From 8bbd15c48244ceb9e11c4fae4afb018620026519 Mon Sep 17 00:00:00 2001 From: Jakub Trllo <43494761+iLLiCiTiT@users.noreply.github.com> Date: Thu, 18 Sep 2025 13:11:46 +0200 Subject: [PATCH] added some docstrings --- client/ayon_core/pipeline/actions/loader.py | 124 +++++++++++++++++++- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/client/ayon_core/pipeline/actions/loader.py b/client/ayon_core/pipeline/actions/loader.py index e04a64b240..2c3ad39c48 100644 --- a/client/ayon_core/pipeline/actions/loader.py +++ b/client/ayon_core/pipeline/actions/loader.py @@ -35,6 +35,17 @@ class LoaderSelectedType(StrEnum): class SelectionEntitiesCache: + """Cache of entities used as helper in the selection wrapper. + + It is possible to get entities based on ids with helper methods to get + entities, their parents or their children's entities. + + The goal is to avoid multiple API calls for the same entity in multiple + action plugins. + + The cache is based on the selected project. Entities are fetched + if are not in cache yet. + """ def __init__( self, project_name: str, @@ -65,6 +76,7 @@ class SelectionEntitiesCache: ) def get_project(self) -> dict[str, Any]: + """Get project entity""" if self._project_entity is None: self._project_entity = ayon_api.get_project(self._project_name) return copy.deepcopy(self._project_entity) @@ -294,6 +306,15 @@ class SelectionEntitiesCache: class LoaderActionSelection: + """Selection of entities for loader actions. + + Selection tells action plugins what exactly is selected in the tool and + which ids. + + Contains entity cache which can be used to get entities by their ids. Or + to get project settings and anatomy. + + """ def __init__( self, project_name: str, @@ -350,9 +371,33 @@ class LoaderActionSelection: @dataclass class LoaderActionItem: + """Item of loader action. + + Action plugins return these items as possible actions to run for a given + context. + + Because the action item can be related to a specific entity + and not the whole selection, they also have to define the entity type + and ids to be executed on. + + Attributes: + identifier (str): Unique action identifier. What is sent to action + plugin when the action is executed. + entity_type (str): Entity type to which the action belongs. + entity_ids (set[str]): Entity ids to which the action belongs. + label (str): Text shown in UI. + order (int): Order of the action in UI. + group_label (Optional[str]): Label of the group to which the action + belongs. + icon (Optional[dict[str, Any]]): Icon definition. + plugin_identifier (Optional[str]): Identifier of the plugin which + created the action item. Is filled automatically. Is not changed + if is filled -> can lead to different plugin. + + """ identifier: str - entity_ids: set[str] entity_type: str + entity_ids: set[str] label: str order: int = 0 group_label: Optional[str] = None @@ -363,6 +408,25 @@ class LoaderActionItem: @dataclass class LoaderActionForm: + """Form for loader action. + + If an action needs to collect information from a user before or during of + the action execution, it can return a response with a form. When the + form is confirmed, a new execution of the action is triggered. + + Attributes: + title (str): Title of the form -> title of the window. + fields (list[AbstractAttrDef]): Fields of the form. + submit_label (Optional[str]): Label of the submit button. Is hidden + if is set to None. + submit_icon (Optional[dict[str, Any]]): Icon definition of the submit + button. + cancel_label (Optional[str]): Label of the cancel button. Is hidden + if is set to None. User can still close the window tho. + cancel_icon (Optional[dict[str, Any]]): Icon definition of the cancel + button. + + """ title: str fields: list[AbstractAttrDef] submit_label: Optional[str] = "Submit" @@ -393,6 +457,18 @@ class LoaderActionForm: @dataclass class LoaderActionResult: + """Result of loader action execution. + + Attributes: + message (Optional[str]): Message to show in UI. + success (bool): If the action was successful. Affects color of + the message. + form (Optional[LoaderActionForm]): Form to show in UI. + form_values (Optional[dict[str, Any]]): Values for the form. Can be + used if the same form is re-shown e.g. because a user forgot to + fill a required field. + + """ message: Optional[str] = None success: bool = True form: Optional[LoaderActionForm] = None @@ -422,7 +498,6 @@ class LoaderActionPlugin(ABC): Plugin is responsible for getting action items and executing actions. - """ _log: Optional[logging.Logger] = None enabled: bool = True @@ -503,6 +578,12 @@ class LoaderActionPlugin(ABC): class LoaderActionsContext: + """Wrapper for loader actions and their logic. + + Takes care about the public api of loader actions and internal logic like + discovery and initialization of plugins. + + """ def __init__( self, studio_settings: Optional[dict[str, Any]] = None, @@ -521,6 +602,15 @@ class LoaderActionsContext: def reset( self, studio_settings: Optional[dict[str, Any]] = None ) -> None: + """Reset context cache. + + Reset plugins and studio settings to reload them. + + Notes: + Does not reset the cache of AddonsManger because there should not + be a reason to do so. + + """ self._studio_settings = studio_settings self._plugins = None @@ -532,6 +622,14 @@ class LoaderActionsContext: return self._addons_manager def get_host(self) -> Optional[AbstractHost]: + """Get current host integration. + + Returns: + Optional[AbstractHost]: Host integration. Can be None if host + integration is not registered -> probably not used in the + host integration process. + + """ if self._host is _PLACEHOLDER: from ayon_core.pipeline import registered_host @@ -552,6 +650,12 @@ class LoaderActionsContext: def get_action_items( self, selection: LoaderActionSelection ) -> list[LoaderActionItem]: + """Collect action items from all plugins for given selection. + + Args: + selection (LoaderActionSelection): Selection wrapper. + + """ output = [] for plugin_id, plugin in self._get_plugins().items(): try: @@ -572,11 +676,25 @@ class LoaderActionsContext: self, plugin_identifier: str, action_identifier: str, + entity_type: str, entity_ids: set[str], - entity_type: LoaderSelectedType, selection: LoaderActionSelection, form_values: dict[str, Any], ) -> Optional[LoaderActionResult]: + """Trigger action execution. + + Args: + plugin_identifier (str): Identifier of the plugin. + action_identifier (str): Identifier of the action. + entity_type (str): Entity type defined on the action item. + entity_ids (set[str]): Entity ids defined on the action item. + selection (LoaderActionSelection): Selection wrapper. Can be used + to get what is selected in UI and to get access to entity + cache. + form_values (dict[str, Any]): Form values related to action. + Usually filled if action returned response with form. + + """ plugins_by_id = self._get_plugins() plugin = plugins_by_id[plugin_identifier] return plugin.execute_action(