mirror of
https://github.com/Ultimaker/Cura.git
synced 2025-07-09 15:57:52 -06:00
Converted comments in dir Cura/cura/API to rst style
Converted doxygen style comments to reStructuredText style in the files found in Cura/cura/API directory recursively using the script dox_2_rst.py (provided in the Uranium repo). Comments were manually checked and changed if needed. Comments from the hidden attributes in the class CuraAPI (_acount, _backups, _interface) were moved to the public property getters, so they docstrings are exposed to the user.
This commit is contained in:
parent
6aedab78dc
commit
68318d20fd
5 changed files with 101 additions and 67 deletions
|
@ -16,18 +16,23 @@ if TYPE_CHECKING:
|
||||||
i18n_catalog = i18nCatalog("cura")
|
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):
|
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)
|
loginStateChanged = pyqtSignal(bool)
|
||||||
|
"""Signal emitted when user logged in or out"""
|
||||||
|
|
||||||
accessTokenChanged = pyqtSignal()
|
accessTokenChanged = pyqtSignal()
|
||||||
|
|
||||||
def __init__(self, application: "CuraApplication", parent = None) -> None:
|
def __init__(self, application: "CuraApplication", parent = None) -> None:
|
||||||
|
@ -65,9 +70,10 @@ class Account(QObject):
|
||||||
def _onAccessTokenChanged(self):
|
def _onAccessTokenChanged(self):
|
||||||
self.accessTokenChanged.emit()
|
self.accessTokenChanged.emit()
|
||||||
|
|
||||||
## Returns a boolean indicating whether the given authentication is applied against staging or not.
|
|
||||||
@property
|
@property
|
||||||
def is_staging(self) -> bool:
|
def is_staging(self) -> bool:
|
||||||
|
"""Indication whether the given authentication is applied against staging or not."""
|
||||||
|
|
||||||
return "staging" in self._oauth_root
|
return "staging" in self._oauth_root
|
||||||
|
|
||||||
@pyqtProperty(bool, notify=loginStateChanged)
|
@pyqtProperty(bool, notify=loginStateChanged)
|
||||||
|
@ -113,10 +119,10 @@ class Account(QObject):
|
||||||
def accessToken(self) -> Optional[str]:
|
def accessToken(self) -> Optional[str]:
|
||||||
return self._authorization_service.getAccessToken()
|
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)
|
@pyqtProperty("QVariantMap", notify = loginStateChanged)
|
||||||
def userProfile(self) -> Optional[Dict[str, Optional[str]]]:
|
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()
|
user_profile = self._authorization_service.getUserProfile()
|
||||||
if not user_profile:
|
if not user_profile:
|
||||||
return None
|
return None
|
||||||
|
|
|
@ -8,28 +8,37 @@ if TYPE_CHECKING:
|
||||||
from cura.CuraApplication import CuraApplication
|
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:
|
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:
|
def __init__(self, application: "CuraApplication") -> None:
|
||||||
self.manager = BackupsManager(application)
|
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]]]:
|
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()
|
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:
|
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)
|
return self.manager.restoreBackup(zip_file, meta_data)
|
||||||
|
|
|
@ -7,32 +7,43 @@ if TYPE_CHECKING:
|
||||||
from cura.CuraApplication import CuraApplication
|
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:
|
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:
|
def __init__(self, application: "CuraApplication") -> None:
|
||||||
self.application = application
|
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:
|
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)
|
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:
|
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()
|
return self.application.getSidebarCustomMenuItems()
|
||||||
|
|
|
@ -9,18 +9,22 @@ if TYPE_CHECKING:
|
||||||
from cura.CuraApplication import CuraApplication
|
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:
|
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:
|
def __init__(self, application: "CuraApplication") -> None:
|
||||||
# API methods specific to the settings portion of the UI
|
# API methods specific to the settings portion of the UI
|
||||||
|
|
|
@ -12,13 +12,14 @@ if TYPE_CHECKING:
|
||||||
from cura.CuraApplication import CuraApplication
|
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):
|
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.
|
# For now we use the same API version to be consistent.
|
||||||
__instance = None # type: "CuraAPI"
|
__instance = None # type: "CuraAPI"
|
||||||
|
@ -39,13 +40,10 @@ class CuraAPI(QObject):
|
||||||
def __init__(self, application: Optional["CuraApplication"] = None) -> None:
|
def __init__(self, application: Optional["CuraApplication"] = None) -> None:
|
||||||
super().__init__(parent = CuraAPI._application)
|
super().__init__(parent = CuraAPI._application)
|
||||||
|
|
||||||
# Accounts API
|
|
||||||
self._account = Account(self._application)
|
self._account = Account(self._application)
|
||||||
|
|
||||||
# Backups API
|
|
||||||
self._backups = Backups(self._application)
|
self._backups = Backups(self._application)
|
||||||
|
|
||||||
# Interface API
|
|
||||||
self._interface = Interface(self._application)
|
self._interface = Interface(self._application)
|
||||||
|
|
||||||
def initialize(self) -> None:
|
def initialize(self) -> None:
|
||||||
|
@ -53,12 +51,18 @@ class CuraAPI(QObject):
|
||||||
|
|
||||||
@pyqtProperty(QObject, constant = True)
|
@pyqtProperty(QObject, constant = True)
|
||||||
def account(self) -> "Account":
|
def account(self) -> "Account":
|
||||||
|
"""Accounts API"""
|
||||||
|
|
||||||
return self._account
|
return self._account
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def backups(self) -> "Backups":
|
def backups(self) -> "Backups":
|
||||||
|
"""Backups API"""
|
||||||
|
|
||||||
return self._backups
|
return self._backups
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def interface(self) -> "Interface":
|
def interface(self) -> "Interface":
|
||||||
|
"""Interface API"""
|
||||||
|
|
||||||
return self._interface
|
return self._interface
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue