diff --git a/cura/API/Account.py b/cura/API/Account.py index 4391f730e5..a049b2924f 100644 --- a/cura/API/Account.py +++ b/cura/API/Account.py @@ -16,18 +16,23 @@ if TYPE_CHECKING: i18n_catalog = i18nCatalog("cura") -## The account API provides a version-proof bridge to use Ultimaker Accounts -# -# Usage: -# ``from cura.API import CuraAPI -# api = CuraAPI() -# api.account.login() -# api.account.logout() -# api.account.userProfile # Who is logged in`` -# class Account(QObject): - # Signal emitted when user logged in or out. + """The account API provides a version-proof bridge to use Ultimaker Accounts + + Usage: + + .. code-block:: python + + from cura.API import CuraAPI + api = CuraAPI() + api.account.login() + api.account.logout() + api.account.userProfile Who is logged in`` + """ + loginStateChanged = pyqtSignal(bool) + """Signal emitted when user logged in or out""" + accessTokenChanged = pyqtSignal() def __init__(self, application: "CuraApplication", parent = None) -> None: @@ -65,9 +70,10 @@ class Account(QObject): def _onAccessTokenChanged(self): self.accessTokenChanged.emit() - ## Returns a boolean indicating whether the given authentication is applied against staging or not. @property def is_staging(self) -> bool: + """Indication whether the given authentication is applied against staging or not.""" + return "staging" in self._oauth_root @pyqtProperty(bool, notify=loginStateChanged) @@ -113,10 +119,10 @@ class Account(QObject): def accessToken(self) -> Optional[str]: return self._authorization_service.getAccessToken() - # Get the profile of the logged in user - # @returns None if no user is logged in, a dict containing user_id, username and profile_image_url @pyqtProperty("QVariantMap", notify = loginStateChanged) def userProfile(self) -> Optional[Dict[str, Optional[str]]]: + """None if no user is logged in otherwise the logged in user as a dict containing containing user_id, username and profile_image_url """ + user_profile = self._authorization_service.getUserProfile() if not user_profile: return None diff --git a/cura/API/Backups.py b/cura/API/Backups.py index ef74e74be0..621dec01f2 100644 --- a/cura/API/Backups.py +++ b/cura/API/Backups.py @@ -8,28 +8,37 @@ if TYPE_CHECKING: from cura.CuraApplication import CuraApplication -## The back-ups API provides a version-proof bridge between Cura's -# BackupManager and plug-ins that hook into it. -# -# Usage: -# ``from cura.API import CuraAPI -# api = CuraAPI() -# api.backups.createBackup() -# api.backups.restoreBackup(my_zip_file, {"cura_release": "3.1"})`` class Backups: + """The back-ups API provides a version-proof bridge between Cura's + + BackupManager and plug-ins that hook into it. + + Usage: + + .. code-block:: python + + from cura.API import CuraAPI + api = CuraAPI() + api.backups.createBackup() + api.backups.restoreBackup(my_zip_file, {"cura_release": "3.1"})`` + """ def __init__(self, application: "CuraApplication") -> None: self.manager = BackupsManager(application) - ## Create a new back-up using the BackupsManager. - # \return Tuple containing a ZIP file with the back-up data and a dict - # with metadata about the back-up. def createBackup(self) -> Tuple[Optional[bytes], Optional[Dict[str, Any]]]: + """Create a new back-up using the BackupsManager. + + :return: Tuple containing a ZIP file with the back-up data and a dict with metadata about the back-up. + """ + return self.manager.createBackup() - ## Restore a back-up using the BackupsManager. - # \param zip_file A ZIP file containing the actual back-up data. - # \param meta_data Some metadata needed for restoring a back-up, like the - # Cura version number. def restoreBackup(self, zip_file: bytes, meta_data: Dict[str, Any]) -> None: + """Restore a back-up using the BackupsManager. + + :param zip_file: A ZIP file containing the actual back-up data. + :param meta_data: Some metadata needed for restoring a back-up, like the Cura version number. + """ + return self.manager.restoreBackup(zip_file, meta_data) diff --git a/cura/API/Interface/Settings.py b/cura/API/Interface/Settings.py index 371c40c14c..947b37fc88 100644 --- a/cura/API/Interface/Settings.py +++ b/cura/API/Interface/Settings.py @@ -7,32 +7,43 @@ if TYPE_CHECKING: from cura.CuraApplication import CuraApplication -## The Interface.Settings API provides a version-proof bridge between Cura's -# (currently) sidebar UI and plug-ins that hook into it. -# -# Usage: -# ``from cura.API import CuraAPI -# api = CuraAPI() -# api.interface.settings.getContextMenuItems() -# data = { -# "name": "My Plugin Action", -# "iconName": "my-plugin-icon", -# "actions": my_menu_actions, -# "menu_item": MyPluginAction(self) -# } -# api.interface.settings.addContextMenuItem(data)`` - class Settings: + """The Interface.Settings API provides a version-proof bridge + between Cura's + + (currently) sidebar UI and plug-ins that hook into it. + + Usage: + + .. code-block:: python + + from cura.API import CuraAPI + api = CuraAPI() + api.interface.settings.getContextMenuItems() + data = { + "name": "My Plugin Action", + "iconName": "my-plugin-icon", + "actions": my_menu_actions, + "menu_item": MyPluginAction(self) + } + api.interface.settings.addContextMenuItem(data)`` + """ def __init__(self, application: "CuraApplication") -> None: self.application = application - ## Add items to the sidebar context menu. - # \param menu_item dict containing the menu item to add. def addContextMenuItem(self, menu_item: dict) -> None: + """Add items to the sidebar context menu. + + :param menu_item: dict containing the menu item to add. + """ + self.application.addSidebarCustomMenuItem(menu_item) - ## Get all custom items currently added to the sidebar context menu. - # \return List containing all custom context menu items. def getContextMenuItems(self) -> list: + """Get all custom items currently added to the sidebar context menu. + + :return: List containing all custom context menu items. + """ + return self.application.getSidebarCustomMenuItems() diff --git a/cura/API/Interface/__init__.py b/cura/API/Interface/__init__.py index cec174bf0a..13174070d1 100644 --- a/cura/API/Interface/__init__.py +++ b/cura/API/Interface/__init__.py @@ -9,18 +9,22 @@ if TYPE_CHECKING: from cura.CuraApplication import CuraApplication -## The Interface class serves as a common root for the specific API -# methods for each interface element. -# -# Usage: -# ``from cura.API import CuraAPI -# api = CuraAPI() -# api.interface.settings.addContextMenuItem() -# api.interface.viewport.addOverlay() # Not implemented, just a hypothetical -# api.interface.toolbar.getToolButtonCount() # Not implemented, just a hypothetical -# # etc.`` - class Interface: + """The Interface class serves as a common root for the specific API + + methods for each interface element. + + Usage: + + .. code-block:: python + + from cura.API import CuraAPI + api = CuraAPI() + api.interface.settings.addContextMenuItem() + api.interface.viewport.addOverlay() # Not implemented, just a hypothetical + api.interface.toolbar.getToolButtonCount() # Not implemented, just a hypothetical + # etc + """ def __init__(self, application: "CuraApplication") -> None: # API methods specific to the settings portion of the UI diff --git a/cura/API/__init__.py b/cura/API/__init__.py index 26c9a4c829..97d0797430 100644 --- a/cura/API/__init__.py +++ b/cura/API/__init__.py @@ -12,13 +12,14 @@ if TYPE_CHECKING: from cura.CuraApplication import CuraApplication -## The official Cura API that plug-ins can use to interact with Cura. -# -# Python does not technically prevent talking to other classes as well, but -# this API provides a version-safe interface with proper deprecation warnings -# etc. Usage of any other methods than the ones provided in this API can cause -# plug-ins to be unstable. class CuraAPI(QObject): + """The official Cura API that plug-ins can use to interact with Cura. + + Python does not technically prevent talking to other classes as well, but this API provides a version-safe + interface with proper deprecation warnings etc. Usage of any other methods than the ones provided in this API can + cause plug-ins to be unstable. + """ + # For now we use the same API version to be consistent. __instance = None # type: "CuraAPI" @@ -39,13 +40,10 @@ class CuraAPI(QObject): def __init__(self, application: Optional["CuraApplication"] = None) -> None: super().__init__(parent = CuraAPI._application) - # Accounts API self._account = Account(self._application) - # Backups API self._backups = Backups(self._application) - # Interface API self._interface = Interface(self._application) def initialize(self) -> None: @@ -53,12 +51,18 @@ class CuraAPI(QObject): @pyqtProperty(QObject, constant = True) def account(self) -> "Account": + """Accounts API""" + return self._account @property def backups(self) -> "Backups": + """Backups API""" + return self._backups @property def interface(self) -> "Interface": + """Interface API""" + return self._interface