ShotgridPlugin

ShotgridPlugin

ShotgridPlugin(*args, **kwargs)

              flowchart LR
              task_schema.plugins.shotgrid_plugin.ShotgridPlugin[ShotgridPlugin]
              task_schema.plugins.base_plugin.BasePlugin[BasePlugin]
              task_schema.plugins.base_studio.BaseCPlugin[BaseCPlugin]
              task_schema.plugins.base_studio.BaseComponent[BaseComponent]

                              task_schema.plugins.base_plugin.BasePlugin --> task_schema.plugins.shotgrid_plugin.ShotgridPlugin
                                task_schema.plugins.base_studio.BaseCPlugin --> task_schema.plugins.base_plugin.BasePlugin
                                task_schema.plugins.base_studio.BaseComponent --> task_schema.plugins.base_studio.BaseCPlugin
                




              click task_schema.plugins.shotgrid_plugin.ShotgridPlugin href "" "task_schema.plugins.shotgrid_plugin.ShotgridPlugin"
              click task_schema.plugins.base_plugin.BasePlugin href "" "task_schema.plugins.base_plugin.BasePlugin"
              click task_schema.plugins.base_studio.BaseCPlugin href "" "task_schema.plugins.base_studio.BaseCPlugin"
              click task_schema.plugins.base_studio.BaseComponent href "" "task_schema.plugins.base_studio.BaseComponent"
            

Plugin for integration with Autodesk ShotGrid.

This plugin extends the BasePlugin to support task and version management through ShotGrid. It handles querying tasks, uploading packages, retrieving notes and versions, managing custom artist entities, and other production tracking features within the launcher environment.

Class Attributes

TITLE (str): Plugin title identifier. _server_root (Path): Root path to the project's server-side filesystem. SHOTGRID_URL (str): URL endpoint for the ShotGrid instance. SHOTGRID_SCRIPT_NAME (str): Script name used for authenticating with ShotGrid API. SHOTGRID_API_KEY (str): Script-based API key for ShotGrid access. SG_PROJECT_ID (int): ShotGrid project ID used for scoping queries. SL_SERVER_PATH (Optional[Path]): Optional path used for logging or data sharing. title (str): Human-readable title for the plugin. custom_artist_entities (List[str]): List of custom entity fields used to resolve assignees. _active_entities (List[str]): Entity types used by the plugin (e.g. Shot, Asset). plugin_task_fields (List[str]): Default fields requested from each task. _discarted_task_status (List[str]): List of task statuses to ignore. _discarted_version_status (List[str]): List of version statuses to ignore. asset_task_fields_dict (Optional[Dict]): Optional dictionary for customizing task fields.

Instance Attributes

sg (Shotgun): ShotGrid API instance. _toolbars (List): List of toolbars registered by this plugin. _headers (List[str]): Column headers for task display. plugin_task_filters (List[List]): Filters applied to task queries. timelog_artist_entity_field (Optional[str]): Field used to assign timelogs to artists. publishedfile_artist_entity_field (Optional[str]): Field used to resolve artist from PublishedFiles. version_artist_entity_field (Optional[str]): Field used to assign versions to artists. custom_artist_login_field (Optional[str]): Field used to match the current username to artist. custom_artist_entity_name (Optional[str]): Name of the custom artist entity in ShotGrid. custom_artist_task_field (Optional[str]): Custom field linking tasks and artists. _starting_frame (int): Default starting frame for playblasts or versioning. _task_long_to_short_dict (Dict[str, str]): Mapping of long task names to short aliases. _upload_status (str): Default status to assign when uploading a version. _version_publish_fields (List[str]): Fields to include when publishing a version. _color_status (Dict[str, Tuple[int, int, int]]): Mapping of ShotGrid status codes to RGB colors.

Initializes toolbars, sets up task filters, ShotGrid connection, headers, version fields and task mappings.

Methods:

• after_publish –

  Hook called after publishing process completes.

• async_find –

  Performs asynchronous paged queries on the ShotGrid API.

• browse_note_data –

  This method should be overriden according to each plugin.

• browse_task_data –

  This method should be overriden according to each plugin.

• browse_version_data –

  This method should be overriden according to each plugin.

• cache_data –

  Stores task data in a cache file.

• check_file_is_uploaded –

  Check if a given file name has an associated PublishedFile in ShotGrid.

• check_version_is_published –

  Check if a given version file name has already been published to ShotGrid.

• copy_edl_files_to_server –

  Copy EDL-associated video and audio files to the server location.

• create_assets_from_bdl –

  Receives an standarized dictionary that holds the data for creating assets.

• create_dir_if_missing –

  Create a directory (and its defined subfolders) if it does not exist.

• create_note –

  Create a new Note entity in ShotGrid.

• create_pack –

  Looks for versions that matches the data passed as args,

• create_pack_from_dialog –

  Pack selected version files based on user-selected filters.

• create_shot –

  Create or update a Shot entity and upload an associated version if applicable.

• create_tags –

  Create tags in Shotgrid.

• create_thumbnail –

  Generate and set a thumbnail for the given task.

• dowload_last_file_from_name –

  Download the most recent published file whose code contains the given name.

• dowload_last_file_from_task –

  Download the last file published for a given task.

• download_file –

  Download a PublishedFile from ShotGrid by ID.

• download_last_version_from_entity –

  Download the last uploaded MP4 movie associated with a specific entity.

• download_package –

  Download a package from ShotGrid by task or package name and extract it.

• download_thumbnail_from_sg –

  Download a thumbnail image from a ShotGrid entity.

• download_version –

  Download the movie file from a version.

• download_versions_from_sg –

  Download all version movie files (sg_uploaded_movie) for selected tasks.

• extract_plugin_values –

  Serialize plugin state and write it to a JSON file for debugging or inspection.

• fetch_tasks –

  Fetch raw tasks from the backend using entity type and filters.

• file_added_callback –

  This callback is added in case there is some further functionality to

• file_has_convention –

  Check if a file meets entity and naming regex conventions.

• file_has_entity –

  Check if the task entity is included in the file name (if required).

• filter_local_files –

  Given a path, it will return the files

• generate_environment_for_app –

  Generate environment variables needed to launch an external application.

• generate_package_name –

  Generate a unique package name based on task and current user.

• get_all_tasks_data –

  DEPRECATED: (USE "return_tasks")

• get_plugin_info –

  Return a dictionary with lists of method names and variable names.

• get_task_filesystem –

  Utility function for returning the filesystem of a given task.

• guess_executable_for_file –

  Guess which executable should be used to open a file based on its extension.

• load –

  Load a Component configuration from dict.

• local_to_server –

  Converts the local path to server path.

• normalize_tasks –

  Convert raw backend task data into internal Task objects.

• on_item_doubleclicked_callback –

  Placeholder for handling item double-click behavior in a GUI context.

• open_app_with_env –

  Launch an application with generated environment variables.

• open_file_with_env –

  Open a file with a specified executable and plugin-defined environment.

• parse_clip_name –

  From a clip name in a XML or in a EDL file, it returns

• parse_edl_file –

  Parse an EDL file and yield shot metadata for creation or update.

• publish_file –

  Upload a file as a PublishedFile entity to ShotGrid.

• publish_last_version –

  Publish the last version file for the specified or last-clicked task.

• publish_timelog –

  Publish a timelog entry in ShotGrid for the given task and duration.

• publish_version –

  Method for creating the logic for publishing, the return

• read_excel –

  Base method for creating the logic for read and return contents of an Excel file.

• receive_config_data_from_app –

  Receives entity-type configuration data from an external application.

• retrieve_cached –

  Attempts to load cached task data for the given link type.

• retrieve_latests_tasks –

  DEPRECATED: (USE "fetch_tasks")

• return_all_assets –

  Retrieve all Asset entities for the configured project.

• return_all_episodes –

  Retrieve all Episode entities for the configured project.

• return_all_packages –

  Retrieve all PublishedFile (package) entities matching optional filters.

• return_all_playlists –

  Retrieve all Playlist entities for the configured project.

• return_all_sequences –

  Retrieve all Sequence entities for the configured project.

• return_all_shots –

  Retrieve all Shot entities, optionally filtered, for the project.

• return_all_tags –

  Retrieve all Tags.

• return_all_versions –

  Retrieve all Version entities matching optional filters.

• return_base_task_with_kwargs –

  Returns a task from current plugin if using kwargs as filters.

• return_base_task_with_path –

  Returns a task from current plugin if using local_path as filters.

• return_custom_artist_entity –

  Return the custom artist entity linked to the current user.

• return_data_to_show –

  Format a ShotGrid task into a list of UI‐ready rows matching headers.

• return_entity_description –

  Fetch the description of the entity linked to a given task.

• return_fields_from_entity_type –

  Generate the list of ShotGrid fields to request based on entity type.

• return_file_by_ext –

  Return a file that matches the given extension and version pattern.

• return_filepack_exceptions –

  This is a function used by the asset packager so that

• return_last_file –

  Returns a tuple with the both the version and the

• return_last_version –

  Returns the latest version associated with a given task.

• return_last_version_by_entity –

  Returns the most recent version associated with a specific entity.

• return_last_version_file –

  Looks at all the files with a given extension in 'path' and returns as

• return_last_version_number –

  Looks at all the files in 'path' and returns as int the highest version

• return_maya_outliner_asset_base_nodes –

  The plugin must send to maya all the parameters so that maya doesn't have

• return_maya_outliner_shot_base_nodes –

  The plugin must send to maya all the parameters so that maya doesn't have

• return_my_tasks_filter –

  Return filters for querying tasks assigned to the currently logged-in user.

• return_next_version_name –

  This method must be overriden according to each plugin.

• return_pack_folder –

  Generate a pack folder name, optionally appending the current date.

• return_playlist_media –

  Retrieve Version entities associated with a Playlist, including notes.

• return_seq_and_shot_from_clipname –

  This method is called when a EDL is parsed for an entire episode,

• return_task_notes –

  Base method to create the note listing logic of a task,

• return_task_versions –

  Base method to create the version listing logic of a task,

• return_tasks –

  Load tasks for the given entity type and store them normalized.

• return_tasks_by_entity –

  DEPRECATED: (USE "normalize_tasks")

• return_thumbnail_url –

  Retrieve the thumbnail image URL for a specific entity.

• return_version_notes –

  Base method to create the note listing logic of a playlist,

• return_version_number –

  Looks at the file and returns as int the version

• return_versions_notes –

  Base method to create the note listing logic of a playlist,

• server_to_local –

  Converts the server path to local path.

• start_task –

  Hook for starting a task. To be overridden as needed.

• stringify_class –

  Return a JSON-friendly representation of a value.

• task_long_to_short –

  Returns the short alias for a given long task name.

• update_asset_task_fields_with_task_entities –

  Update asset task fields based on associated ShotGrid task entities.

• upload_file –

  Upload a local file to ShotGrid as a PublishedFile.

• upload_package –

  Create and upload a zip package containing the specified files and their Maya dependencies.

• validate_last_task_path –

  Ensure the filesystem structure exists for the last-clicked task.

• verify_bdl_excel –

  Validate the naming convention of a BDL Excel file.

Attributes:

• active_entities (list[str]) –

  Returns the list of active entity types the plugin supports.

• app_toolbars (List[BaseToolbar]) –

  List[BaseToolbar]: Instantiated application toolbars.

• apps –

  Supported external applications.

• current_selected_files (List[Path]) –

  Currently selected file paths in the UI.

• current_selected_tasks (List[BaseTask]) –

  Currently selected task objects in the UI.

• headers (List[str]) –

  Column headers for displaying task data in the UI.

• last_file_clicked (Optional[Path]) –

  The most recent file the user clicked.

• last_task_clicked (Optional[BaseTask]) –

  The most recent task the user clicked.

• local_root –

  Path: Local root directory for the project.

• server_root –

  Path: Server root directory for the project.

• task_long_to_short_dict (dict[str, str]) –

  Returns the mapping of long task names to their short aliases.

• tasks (List[BaseTask]) –

  List[BaseTask]: Tasks managed by this plugin.

• toolbars –

  Registered toolbars definitions.

• username –

  str: Username of the plugin user.

• version_includes_entity (bool) –

  Whether the version name must include the entity (e.g., shot or asset) string.

• version_regex (str) –

  Regular expression used to identify version substrings in filenames.

active_entities property

active_entities: list[str]

Returns the list of active entity types the plugin supports.

Returns:

• list[str] –

  list[str]: List of supported entity types.

app_toolbars property

app_toolbars: List[BaseToolbar]

List[BaseToolbar]: Instantiated application toolbars.

apps property

apps

Supported external applications.

current_selected_files property writable

current_selected_files: List[Path]

Currently selected file paths in the UI.

Returns:

• List[Path] –

  List[Path]: The list of file Paths the user has selected.

current_selected_tasks property writable

current_selected_tasks: List[BaseTask]

Currently selected task objects in the UI.

Returns:

• List[BaseTask] –

  List[BaseTask]: The list of tasks the user has selected.

headers property

headers: List[str]

Column headers for displaying task data in the UI.

Returns:

• List[str] –

  List[str]: List of header strings in display order.

last_file_clicked property writable

last_file_clicked: Optional[Path]

The most recent file the user clicked.

Returns:

• Optional[Path] –

  Optional[Path]: Path of the last clicked file, or None.

last_task_clicked property writable

last_task_clicked: Optional[BaseTask]

The most recent task the user clicked.

Returns:

• Optional[BaseTask] –

  Optional[BaseTask]: The last clicked task, or None if none selected.

local_root property writable

local_root

Path: Local root directory for the project.

server_root property writable

server_root

Path: Server root directory for the project.

task_long_to_short_dict property

task_long_to_short_dict: dict[str, str]

Returns the mapping of long task names to their short aliases.

Returns:

• dict[str, str] –

  dict[str, str]: Dictionary of task name mappings.

tasks property writable

tasks: List[BaseTask]

List[BaseTask]: Tasks managed by this plugin.

toolbars property

toolbars

Registered toolbars definitions.

username property writable

username

str: Username of the plugin user.

version_includes_entity property writable

version_includes_entity: bool

Whether the version name must include the entity (e.g., shot or asset) string.

Returns:

• bool ( bool ) –

  True if entity inclusion is enforced, False otherwise.

version_regex property writable

version_regex: str

Regular expression used to identify version substrings in filenames.

Returns:

• str ( str ) –

  Current version‐matching regex pattern.

after_publish

after_publish(*args, **kwargs) -> None

Hook called after publishing process completes.

Parameters:

• *args

  (Any, default: () ) –

  Positional arguments.

• **kwargs

  (Any, default: {} ) –

  Keyword arguments.

async_find

async_find(entity: str, filters: list[list[Any]] = [], fields: list[str] = [], page_size: int = 500) -> list[dict[str, Any]]

Performs asynchronous paged queries on the ShotGrid API.

Parameters:

• entity

  (str) –

  Entity type to query (e.g., 'Task').

• filters

  (list[list[Any]], default: [] ) –

  ShotGrid filter list.

• fields

  (list[str], default: [] ) –

  Fields to retrieve.

• page_size

  (int, default: 500 ) –

  Number of results per page.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: Flattened list of all retrieved results.

browse_note_data

browse_note_data(note_id: int) -> None

This method should be overriden according to each plugin. This opens the note in the plugin's database Args: note_id (int): ID of the note to open.

browse_task_data

browse_task_data(task: BaseTask) -> None

This method should be overriden according to each plugin. This opens the task in the plugin's database

Parameters:

• task

  (BaseTask) –

  Task whose ShotGrid detail page should be opened.

browse_version_data

browse_version_data(version_id: int) -> None

This method should be overriden according to each plugin. This opens the version in the plugin's database

Parameters:

• version_id

  (int) –

  ID of the version to open.

cache_data

cache_data(file_name: str, data: list[dict[str, Any]]) -> None

Stores task data in a cache file.

Parameters:

• file_name

  (str) –

  Cache filename identifier.

• data

  (list[dict[str, Any]]) –

  Data to cache.

check_file_is_uploaded

check_file_is_uploaded(file: Path) -> bool

Check if a given file name has an associated PublishedFile in ShotGrid.

Parameters:

• file

  (Path) –

  The local file to check.

Returns:

• bool ( bool ) –

  True if a PublishedFile with the same code exists.

check_version_is_published

check_version_is_published(version: Path) -> bool

Check if a given version file name has already been published to ShotGrid.

Parameters:

• version

  (Path) –

  Path to the version file.

Returns:

• bool ( bool ) –

  True if a Version entity with the same code exists.

copy_edl_files_to_server

copy_edl_files_to_server(shot_data: dict[str, Any]) -> None

Copy EDL-associated video and audio files to the server location.

Parameters:

• shot_data

  (dict[str, Any]) –

  Dictionary containing keys 'video_file' and 'server_path'.

create_assets_from_bdl

create_assets_from_bdl(dict_with_items: dict[str, Any], excel_file: Path) -> None

Receives an standarized dictionary that holds the data for creating assets. It yields assets that were successfully created.

Parameters:

• dict_with_items

  (dict[str, Any]) –

  Structured asset data.

• excel_file

  (Path) –

  Path to original Excel file.

create_dir_if_missing

create_dir_if_missing(path: Path, task: Optional[BaseTask] = None) -> bool

Create a directory (and its defined subfolders) if it does not exist.

Parameters:

• path

  (Path) –

  The directory to ensure exists.

• task

  (BaseTask, default: None ) –

  Task whose task_subfolders define extra subfolders to create. Defaults to self.last_task_clicked.

Returns:

• bool ( bool ) –

  True if creation succeeded or already existed; False on error.

create_note

create_note(links: list[Any] = [], status: str = 'opn', body: str = '', subject: str = '', tasks: list[BaseTask] = [], to: list[Any] = [], author: dict[str, Any] = {}, **kwargs) -> None

Create a new Note entity in ShotGrid.

Parameters:

• links

  (list[Any], default: [] ) –

  List of linked entities.

• status

  (str, default: 'opn' ) –

  Note status.

• body

  (str, default: '' ) –

  Body content.

• subject

  (str, default: '' ) –

  Subject line.

• tasks

  (list[Any], default: [] ) –

  Associated task entities.

• to

  (list[Any], default: [] ) –

  Users addressed in the note.

• author

  (dict[str, Any], default: {} ) –

  User entity of the note author.

• **kwargs

  –

  Additional ShotGrid fields.

create_pack

create_pack(pack_type: str, ep: str) -> Generator[str, None, None]

Looks for versions that matches the data passed as args, and adds them to a given folder.

Parameters:

• pack_type

  (str) –

  Type of pack to create.

• ep

  (str) –

  Episode identifier.

Yields:

• str ( str ) –

  Names of copied files.

create_pack_from_dialog

create_pack_from_dialog(p: Path, versions: list[dict[str, Any]], extensions: list[str]) -> Generator[str, None, None]

Pack selected version files based on user-selected filters.

Parameters:

• p

  (Path) –

  Target folder path for the pack.

• versions

  (list[dict[str, Any]]) –

  List of version dictionaries to pack.

• extensions

  (list[str]) –

  File extensions to include.

Yields:

• str ( str ) –

  File names of the packed assets.

create_shot

create_shot(shot_data: dict[str, Any], task_name: Optional[str] = None) -> dict[str, Any]

Create or update a Shot entity and upload an associated version if applicable.

Parameters:

• shot_data

  (dict[str, Any]) –

  Dictionary with shot data.

• task_name

  (Optional[str], default: None ) –

  Optional name of the task for thumbnail association.

Returns:

• dict[str, Any] –

  dict[str, Any]: The created or updated Shot entity.

create_tags

create_tags(tags: list[str]) -> list[dict[str]]

Create tags in Shotgrid.

Parameters:

• tags

  (list[str]) –

  List of tags name.

create_thumbnail

create_thumbnail(task: BaseTask) -> Optional[Path]

Generate and set a thumbnail for the given task.

Attempts to generate a thumbnail from the latest .jpg file in the task directory. If not found, it falls back to downloading from ShotGrid.

Parameters:

• task

  (BaseTask) –

  The task for which to create the thumbnail.

Returns:

• Optional[Path] –

  Optional[Path]: Path to the generated thumbnail or None if failed.

dowload_last_file_from_name

dowload_last_file_from_name(name: str, path: str) -> Optional[Path]

Download the most recent published file whose code contains the given name.

Parameters:

• name

  (str) –

  Name substring to match against the PublishedFile code.

• path

  (str) –

  Destination folder path where the file will be downloaded.

Returns:

• Optional[Path] –

  Optional[Path]: Local path of the downloaded file if successful, otherwise None.

dowload_last_file_from_task

dowload_last_file_from_task(task: BaseTask, path: Optional[Union[str, Path]] = None) -> Optional[Path]

Download the last file published for a given task.

Parameters:

• task

  (BaseTask) –

  Task to query.

• path

  (Optional[Union[str, Path]], default: None ) –

  Destination path.

Returns:

• Optional[Path] –

  Optional[Path]: File path if downloaded, else None.

download_file

download_file(id: int, path: Path) -> Union[Path, bool]

Download a PublishedFile from ShotGrid by ID.

Parameters:

• id

  (int) –

  ShotGrid PublishedFile ID.

• path

  (Path) –

  Directory to save the file to.

Returns:

• Union[Path, bool] –

  Union[Path, bool]: Local path to the file, or False if failed.

download_last_version_from_entity

download_last_version_from_entity(task: str, id: int, path: Path) -> bool

Download the last uploaded MP4 movie associated with a specific entity.

Parameters:

• task

  (str) –

  Unused placeholder argument.

• id

  (int) –

  Entity ID.

• path

  (Path) –

  Destination file path.

Returns:

• bool ( bool ) –

  True if download was successful, otherwise False.

download_package

download_package(package: Union[str, BaseTask]) -> Optional[list[Path]]

Download a package from ShotGrid by task or package name and extract it.

Parameters:

• package

  (Union[str, BaseTask]) –

  Task or package name to download.

Returns:

• Optional[list[Path]] –

  Optional[list[Path]]: List of extracted files or None.

download_thumbnail_from_sg

download_thumbnail_from_sg(entity_type: str, id: int, path: Path) -> bool

Download a thumbnail image from a ShotGrid entity.

Parameters:

• entity_type

  (str) –

  Type of entity (e.g., 'Task').

• id

  (int) –

  ID of the entity.

• path

  (Path) –

  Path where the image should be saved.

Returns:

• bool ( bool ) –

  True if successful, False otherwise.

download_version

download_version(id: int, path: Path) -> Union[Path, bool]

Download the movie file from a version.

Parameters:

• id

  (int) –

  ShotGrid Version ID.

• path

  (Path) –

  Directory to store the downloaded file.

Returns:

• Union[Path, bool] –

  Union[Path, bool]: Path to downloaded file or False if unsuccessful.

download_versions_from_sg

download_versions_from_sg() -> None

Download all version movie files (sg_uploaded_movie) for selected tasks.

For each version in each selected task, this function saves the movie to the preview location if it doesn't already exist.

extract_plugin_values

extract_plugin_values() -> None

Serialize plugin state and write it to a JSON file for debugging or inspection.

fetch_tasks

fetch_tasks(link_type: str, filters=None, use_cache: bool = True) -> list[dict[str, Any]]

Fetch raw tasks from the backend using entity type and filters.

Parameters:

• link_type

  (str) –

  Entity type.

• filters

  (list[list[Any]], default: None ) –

  Query filters.

• use_cache

  (bool, default: True ) –

  Active use cache.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: Raw task records.

file_added_callback

file_added_callback() -> None

This callback is added in case there is some further functionality to add in a per plugin level. Originally requested for a change in the DB in the Grisu plugin. File added -> task updated to IP.

file_has_convention

file_has_convention(file: Path, task: Optional[BaseTask] = None) -> bool

Check if a file meets entity and naming regex conventions.

Parameters:

• file

  (Path) –

  File to validate.

• task

  (Optional[BaseTask], default: None ) –

  Task context. Defaults to last clicked.

Returns:

• bool ( bool ) –

  True if file meets convention; otherwise False.

file_has_entity

file_has_entity(file: Path, task: Optional[BaseTask] = None) -> bool

Check if the task entity is included in the file name (if required).

Parameters:

• file

  (Path) –

  File to check.

• task

  (Optional[BaseTask], default: None ) –

  Task context. Defaults to last clicked.

Returns:

• bool ( bool ) –

  True if the entity name is found or not required.

filter_local_files

filter_local_files(local_path: Path, ext: str | Iterable[str] = [''], task: Optional[BaseTask] = None) -> list[Path]

Given a path, it will return the files that follow the stablished conventions

Parameters:

• local_path

  (Path) –

  The directory to search in.

• ext

  (Union[str, Iterable[str]], default: [''] ) –

  Valid file extensions to include.

• task

  (BaseTask, default: None ) –

  Task context to validate conventions. Defaults to last clicked task.

Returns:

• list[Path] –

  list[Path]: List of files matching conventions and extensions.

generate_environment_for_app

generate_environment_for_app(task: Optional[BaseTask] = None) -> dict[str, str]

Generate environment variables needed to launch an external application.

Parameters:

• task

  (Optional[BaseTask], default: None ) –

  Task context to embed into environment. Defaults to None.

Returns:

• dict[str, str] –

  dict[str, str]: Dictionary of environment variables.

generate_package_name

generate_package_name(task: BaseTask) -> str

Generate a unique package name based on task and current user.

Parameters:

• task

  (BaseTask) –

  The task to generate the package name for.

Returns:

• str ( str ) –

  A filename-safe package name.

get_all_tasks_data

get_all_tasks_data(return_object: dict[str, Any], callback: Optional[Callable[[], None]] = None, force_no_cache: bool = False, cache_data: bool = True, *args: Any, **kwargs: Any) -> None

DEPRECATED: (USE "return_tasks") Retrieve all tasks for the specified entity type, handle caching, and invoke callback.

Parameters:

• return_object

  (dict[str, Any]) –

  Dict to populate with return_object["results"] = (tasks, headers).

• callback

  (Optional[Callable[[], None]], default: None ) –

  Function to call once tasks are loaded.

• force_no_cache

  (bool, default: False ) –

  If True, ignore existing cache.

• cache_data

  (bool, default: True ) –

  If True, update the local cache with new results.

• *args

  (Any, default: () ) –

  Additional positional arguments.

• **kwargs

  (Any, default: {} ) –

  Keyword args, expects 'sg_entity_type' key.

get_plugin_info

get_plugin_info() -> dict[str, list[str]]

Return a dictionary with lists of method names and variable names.

Returns:

• dict[str, list[str]] –

  dict[str, list[str]]: Dictionary with 'methods' and 'variables' as keys.

get_task_filesystem

get_task_filesystem() -> tuple[Path, Path]

Utility function for returning the filesystem of a given task. Retrieve the local and server filesystem roots for the current task.

Parameters:

• *args

  –

  Positional arguments for filesystem resolution.

• **kwargs

  –

  Keyword arguments for filesystem resolution.

Returns:

• tuple[Path, Path] –

  tuple[Path, Path]: (local_path, server_path) for the task.

guess_executable_for_file

guess_executable_for_file(path: str | Path) -> Optional[str]

Guess which executable should be used to open a file based on its extension.

Parameters:

• path

  (str | Path) –

  Path to the file to analyze.

Returns:

• Optional[str] –

  Optional[str]: Path to the executable, or None if no match found.

load

load(cfg: dict[str, Any]) -> None

Load a Component configuration from dict.

Parameters:

• cfg

  (dict[str, Any]) –

  dict from JSON configuration .

Returns:

• BaseConfig ( None ) –

  Instance initialized with the loaded configuration.

local_to_server

local_to_server(path: Path) -> Path

Converts the local path to server path.

normalize_tasks

normalize_tasks(link_type: str, raw_tasks: dict)

Convert raw backend task data into internal Task objects.

Parameters:

• link_type

  (str) –

  Entity link type.

• raw_tasks

  (dict) –

  Raw task records.

Returns:

• –

  list[BaseTask]: Normalized tasks.

on_item_doubleclicked_callback

on_item_doubleclicked_callback() -> None

Placeholder for handling item double-click behavior in a GUI context.

Intended to be overridden by subclasses or externally bound.

open_app_with_env

open_app_with_env(executable: Optional[str] = None, environ: Optional[str] = None) -> None

Launch an application with generated environment variables.

Parameters:

• executable

  (Optional[str], default: None ) –

  Executable path. Overridden by environ if provided.

• environ

  (Optional[str], default: None ) –

  Environment variable key to retrieve executable from.

open_file_with_env

open_file_with_env(path: str | Path, executable: str) -> None

Open a file with a specified executable and plugin-defined environment.

Parameters:

• path

  (str | Path) –

  File path to open.

• executable

  (str) –

  Path to the application executable.

parse_clip_name

parse_clip_name(clip_name: str) -> Any

From a clip name in a XML or in a EDL file, it returns the number of the episode, sequence and shot

Parameters:

• clip_name

  (str) –

  The input clip name.

Returns:

• Any ( Any ) –

  Expected to return episode, sequence, and shot identifiers.

Raises:

• NotImplementedError –

  Must be implemented in subclass.

parse_edl_file

parse_edl_file(source_edl: Path, source_video: Path, episode_name: Optional[str] = None, edl_target_task: Optional[str] = None, task: Optional[BaseTask] = None) -> Generator[dict[str, Any], None, None]

Parse an EDL file and yield shot metadata for creation or update.

Parameters:

• source_edl

  (Path) –

  Path to the source EDL file.

• source_video

  (Path) –

  Path to the source video file.

• episode_name

  (Optional[str], default: None ) –

  Name of the episode to associate with the EDL.

• edl_target_task

  (Optional[str], default: None ) –

  Name of the EDL-related task.

• task

  (Optional[BaseTask], default: None ) –

  Optional BaseTask context fallback.

Yields:

• dict[str, Any] –

  Generator[dict[str, Any], None, None]: Metadata for each parsed shot.

publish_file

publish_file(file: Path, version: Optional[dict[str, Any]] = None, task: Optional[BaseTask] = None, description: str = '') -> dict[str, Union[bool, str, None]]

Upload a file as a PublishedFile entity to ShotGrid.

Parameters:

• file

  (Path) –

  The local file path to upload.

• version

  (Optional[dict[str, Any]], default: None ) –

  Version entity to link with this PublishedFile.

• task

  (Optional[BaseTask], default: None ) –

  Task associated with the file.

• description

  (str, default: '' ) –

  Description of the upload.

Returns:

• dict[str, Union[bool, str, None]] –

  dict[str, Union[bool, str, None]]: Dictionary containing upload status, message and any error.

publish_last_version

publish_last_version(task: Optional[BaseTask] = None) -> bool

Publish the last version file for the specified or last-clicked task.

Parameters:

• task

  (Optional[BaseTask], default: None ) –

  Task to publish. Defaults to last clicked.

Returns:

• bool ( bool ) –

  True if publishing succeeds, otherwise False.

publish_timelog

publish_timelog(task: BaseTask, duration: int) -> dict[str, Union[bool, str, None]]

Publish a timelog entry in ShotGrid for the given task and duration.

Parameters:

• task

  (BaseTask) –

  The task for which the timelog will be created.

• duration

  (int) –

  Duration in minutes to be logged.

Returns:

• dict[str, Union[bool, str, None]] –

  dict[str, Union[bool, str, None]]: A result dict with status, message, and error.

publish_version

publish_version(task: BaseTask, version: Path, description: str = '') -> dict[str, Union[bool, str, None, dict[str, Any]]]

Method for creating the logic for publishing, the return object should be a dictionary with the following structure:

{ "success" : bool, "message" : str, "error" : str |None # Exception like error "entity" : dict |None }

Parameters:

• task

  (BaseTask) –

  Task associated with the version.

• version

  (Path) –

  Local path to the video file to upload.

• description

  (str, default: '' ) –

  Optional description of the version.

Returns:

• dict[str, Union[bool, str, None, dict[str, Any]]] –

  dict[str, Union[bool, str, None, dict[str, Any]]]: A result dict with status, message, error (if any), and version entity.

read_excel

read_excel(excel: Path) -> tuple[list[Any], dict[Any, Any]]

Base method for creating the logic for read and return contents of an Excel file.

Parameters:

• excel

  (Path) –

  Path to the Excel file.

Returns:

• tuple[list[Any], dict[Any, Any]] –

  tuple[list[Any], dict[str, Any]]: A list of rows and a dictionary of parsed data.

receive_config_data_from_app

receive_config_data_from_app(*args, **kwargs) -> None

Receives entity-type configuration data from an external application.

Parameters:

• *args

  –

  Positional arguments (unused).

• **kwargs

  –

  Keyword arguments containing 'sg_active_entity'.

retrieve_cached

retrieve_cached(link_type: str) -> tuple[list[dict[str, Any]], Optional[datetime], bool]

Attempts to load cached task data for the given link type.

Parameters:

• link_type

  (str) –

  The ShotGrid entity type.

Returns:

• tuple[list[dict[str, Any]], Optional[datetime], bool] –

  tuple[list[dict[str, Any]], Optional[datetime], bool]: Cached data, last modified date, and success flag.

retrieve_latests_tasks

retrieve_latests_tasks(link_type: str, sg_filters: list[list[Any]], force_no_cache: bool) -> list[dict[str, Any]]

DEPRECATED: (USE "fetch_tasks") Uses the cache to get its date so that only the tasks that were updated after the last cache are retrieved. These tasks are merged with the cache.

Parameters:

• link_type

  (str) –

  The entity type to query (e.g., "Shot").

• sg_filters

  (list[list[Any]]) –

  ShotGrid filter definitions.

• force_no_cache

  (bool) –

  If True, bypass local cache entirely.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: Combined list of new and (if not forced) cached task dicts.

return_all_assets

return_all_assets(filters: list[list[Any]] = [], fields: list[str] = []) -> dict[str, dict[str, Any]]

Retrieve all Asset entities for the configured project.

Returns:

• dict[str, dict[str, Any]] –

  dict[str, dict[str, Any]]: Mapping asset code to its SG entity dict.

return_all_episodes

return_all_episodes() -> dict[str, dict[str, Any]]

Retrieve all Episode entities for the configured project.

Returns:

• dict[str, dict[str, Any]] –

  dict[str, dict[str, Any]]: Mapping episode code to its SG entity dict.

return_all_packages

return_all_packages(filters: Optional[list[list[Any]]] = None, fields: Optional[list[str]] = None) -> list[dict[str, Any]]

Retrieve all PublishedFile (package) entities matching optional filters.

Parameters:

• filters

  (Optional[list[list[Any]]], default: None ) –

  ShotGrid filters to apply.

• fields

  (Optional[list[str]], default: None ) –

  Fields to include in results.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of PublishedFile entity dicts.

return_all_playlists

return_all_playlists() -> list[dict[str, Any]]

Retrieve all Playlist entities for the configured project.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of Playlist entity dicts.

return_all_sequences

return_all_sequences() -> dict[str, dict[str, Any]]

Retrieve all Sequence entities for the configured project.

Returns:

• dict[str, dict[str, Any]] –

  dict[str, dict[str, Any]]: Mapping sequence code to its SG entity dict.

return_all_shots

return_all_shots(filters: list[list[Any]] = []) -> dict[str, dict[str, Any]]

Retrieve all Shot entities, optionally filtered, for the project.

Parameters:

• filters

  (list[list[Any]], default: [] ) –

  Additional filter rules.

Returns:

• dict[str, dict[str, Any]] –

  dict[str, dict[str, Any]]: Mapping shot code to its SG entity dict.

return_all_tags

return_all_tags() -> dict[str, dict[str, Any]]

Retrieve all Tags.

Returns:

• dict[str, dict[str, Any]] –

  dict[str, dict[str, Any]]

return_all_versions

return_all_versions(filters: Optional[list[list[Any]]] = None, fields: Optional[list[str]] = None) -> list[dict[str, Any]]

Retrieve all Version entities matching optional filters.

Parameters:

• filters

  (Optional[list[list[Any]]], default: None ) –

  ShotGrid filters to apply.

• fields

  (Optional[list[str]], default: None ) –

  Fields to include in results.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of Version entity dicts.

return_base_task_with_kwargs

return_base_task_with_kwargs(**kwargs) -> Optional[BaseTask]

Returns a task from current plugin if using kwargs as filters.

Parameters:

• **kwargs

  (Any, default: {} ) –

  Attribute-value pairs to match against BaseTask attributes.

Returns:

• Optional[BaseTask] –

  Optional[BaseTask]: Matching task or None.

return_base_task_with_path

return_base_task_with_path(local_path: Path) -> Optional[BaseTask]

Returns a task from current plugin if using local_path as filters.

Parameters:

• local_path

  (Path) –

  Path to match against task local paths.

Returns:

• Optional[BaseTask] –

  Optional[BaseTask]: The matching BaseTask, if any.

return_custom_artist_entity

return_custom_artist_entity() -> Union[dict[str, Any], bool]

Return the custom artist entity linked to the current user.

Returns:

• Union[dict[str, Any], bool] –

  Union[dict[str, Any], bool]: ShotGrid entity dict or False if not found/configured.

return_data_to_show

return_data_to_show(sg_task: dict[str, Any], link_type: str, thumbnail: BaseThumbnail, assignees: list[str], tags: str, asset_type: str, episodes: str, created_for_episode: Optional[str], cut_in: Any, cut_out: Any, cut_duration: Any, sequence: Any, episode: Any) -> list[dict[str, Any]]

Format a ShotGrid task into a list of UI‐ready rows matching headers.

Parameters:

• sg_task

  (dict[str, Any]) –

  Raw ShotGrid Task entity.

• link_type

  (str) –

  Entity type of the task (e.g., "Shot").

• thumbnail

  (BaseThumbnail) –

  Thumbnail object for display.

• assignees

  (list[str]) –

  Names of assigned artists.

• tags

  (str) –

  Space‐separated tag names.

• asset_type

  (str) –

  Asset type code.

• episodes

  (str) –

  Episode codes.

• created_for_episode

  (Optional[str]) –

  Original episode code.

• cut_in

  (Any) –

  Cut in frame or None.

• cut_out

  (Any) –

  Cut out frame or None.

• cut_duration

  (Any) –

  Duration in frames or None.

• sequence

  (Any) –

  Sequence code or None.

• episode

  (Any) –

  Episode code or None.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of dicts with keys "text", "icon", "thumbnail", "background_color".

return_entity_description

return_entity_description(task: BaseTask, force_stop: Callable[[], bool] = lambda: False) -> str

Fetch the description of the entity linked to a given task.

Parameters:

• task

  (BaseTask) –

  Task whose parent entity description to retrieve.

• force_stop

  (Callable[[], bool], default: lambda: False ) –

  If True at any point, aborts and returns empty string.

Returns:

• str ( str ) –

  The entity's description, or empty string if not found/aborted.

return_fields_from_entity_type

return_fields_from_entity_type(entity_type: str) -> list[str]

Generate the list of ShotGrid fields to request based on entity type.

Parameters:

• entity_type

  (str) –

  The ShotGrid entity type (e.g., "Shot" or "Asset").

Returns:

• list[str] –

  list[str]: Unique list of field names to retrieve for the given entity.

return_file_by_ext

return_file_by_ext(file: Path, ext: str) -> Path

Return a file that matches the given extension and version pattern.

Parameters:

• file

  (Path) –

  Input file path.

• ext

  (str) –

  Target extension to match.

Returns:

• Path ( Path ) –

  Matching file or fallback template path.

return_filepack_exceptions

return_filepack_exceptions() -> list[str]

This is a function used by the asset packager so that each plugin can define how to return an exception of files to be packed.

Returns:

• list[str] –

  list[str]: A list of exception file names or patterns.

return_last_file

return_last_file(ext: Iterable[str], subdir: Path = Path(), template_failed: bool = True, task: Optional[BaseTask] = None) -> tuple[int, Path]

Returns a tuple with the both the version and the last file of a given task. Defaults to the task's localpath, but can receive a path (generaly a subpath of the local path).

Parameters:

• ext

  (Iterable[str]) –

  Valid file extensions.

• subdir

  (Path, default: Path() ) –

  Subdirectory to look inside. Defaults to Path().

• template_failed

  (bool, default: True ) –

  If True and no file is found, try template. Defaults to True.

• task

  (Optional[BaseTask], default: None ) –

  Task context. Defaults to last clicked.

Returns:

• tuple[int, Path] –

  tuple[int, Path]: Tuple of version number and file path.

return_last_version

return_last_version(task_id: int) -> Optional[dict[str, Any]]

Returns the latest version associated with a given task.

Parameters:

• task_id

  (int) –

  ID of the task.

Returns:

• Optional[dict[str, Any]] –

  Optional[dict[str, Any]]: Latest version dictionary or None.

return_last_version_by_entity

return_last_version_by_entity(entity: dict[str, Any], fields: list[str] = []) -> Optional[dict[str, Any]]

Returns the most recent version associated with a specific entity.

Parameters:

• entity

  (dict[str, Any]) –

  ShotGrid entity dictionary.

• fields

  (list[str], default: [] ) –

  Additional fields to include in the query.

Returns:

• Optional[dict[str, Any]] –

  Optional[dict[str, Any]]: Latest version dictionary or None.

return_last_version_file

return_last_version_file(path: Path, ext: Iterable[str]) -> Optional[Path]

Looks at all the files with a given extension in 'path' and returns as Path the file that has the highest version number that matches the version_regex.

Parameters:

• path

  (Path) –

  Directory to search.

• ext

  (Iterable[str]) –

  File extensions to match.

Returns:

• Optional[Path] –

  Optional[Path]: Path to highest-versioned file, or None.

return_last_version_number

return_last_version_number(path: Path) -> int

Looks at all the files in 'path' and returns as int the highest version number that matches the version_regex.

Parameters:

• path

  (Path) –

  Directory to search for versioned files.

Returns:

• int ( int ) –

  The maximum version number found. Returns 0 if none.

return_maya_outliner_asset_base_nodes

return_maya_outliner_asset_base_nodes(*args, **kwargs) -> Optional[list[str]]

The plugin must send to maya all the parameters so that maya doesn't have to query any database to get the required values. All not-default nodes must be under one of these nodes.

Parameters:

• *args

  (Any, default: () ) –

  Positional arguments.

• **kwargs

  (Any, default: {} ) –

  Keyword arguments, expects 'link_name' to identify asset group.

Returns:

• Optional[list[str]] –

  Optional[list[str]]: List of node strings to be used as parents in Maya's outliner.

return_maya_outliner_shot_base_nodes

return_maya_outliner_shot_base_nodes(*args, **kwargs) -> list[str]

The plugin must send to maya all the parameters so that maya doesn't have to query any database to get the required values.

Parameters:

• *args

  (Any, default: () ) –

  Positional arguments.

• **kwargs

  (Any, default: {} ) –

  Keyword arguments.

Returns:

• list[str] –

  list[str]: Top-level node names used in Maya for organizing shots.

return_my_tasks_filter

return_my_tasks_filter() -> list[list[Any]]

Return filters for querying tasks assigned to the currently logged-in user.

Returns:

• list[list[Any]] –

  list[list[Any]]: ShotGrid filter for user's tasks.

return_next_version_name

return_next_version_name(ext: Iterable, task: BaseTask = None) -> dict

This method must be overriden according to each plugin. it should return a dictionary like so: { "local_path": "path there the file goes", "file_name": "name without extension", "previous_file": "copy the previous version" }

If there is no previous version, it should return a path where the templates are so that the user can choose a template form a QFileDialog. If the path is None, the QFileDialog will pop up in the root.

Parameters:

• ext

  (Iterable[str]) –

  Allowed file extensions.

• task

  (BaseTask, default: None ) –

  Task context. Defaults to last clicked.

Returns:

• dict –

  Dict[str, Any]: Mapping with keys described above, or None

• dict –

  if default logic is not applicable.

return_pack_folder staticmethod

return_pack_folder(folder_name: str, add_date: bool = False) -> str

Generate a pack folder name, optionally appending the current date.

Parameters:

• folder_name

  (str) –

  Base name of the folder.

• add_date

  (bool, default: False ) –

  If True, appends current date in YYYYMMDD format.

Returns:

• str ( str ) –

  Final folder name.

return_playlist_media

return_playlist_media(playlist_id: int, fields: Optional[list[str]] = None) -> list[dict[str, Any]]

Retrieve Version entities associated with a Playlist, including notes.

Parameters:

• playlist_id

  (int) –

  ID of the Playlist entity.

• fields

  (Optional[list[str]], default: None ) –

  Additional fields to include.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of Version entity dicts in the playlist.

return_seq_and_shot_from_clipname

return_seq_and_shot_from_clipname(clip_name: str) -> Any

This method is called when a EDL is parsed for an entire episode, where the info about which sequence and shot lives in the name of the clip name, for a edl file. This method is called when self._episode_edl_workflow is True.

Parameters:

• clip_name

  (str) –

  The clip name from which to extract episode data.

Returns:

• None ( Any ) –

  Override expected to return values.

return_task_notes

return_task_notes(task: BaseTask, force_stop: Callable[[], bool] = lambda: False) -> list[dict[str, Any]]

Base method to create the note listing logic of a task, the returned object must be a list with the following structure:

[{ "content" : str, "created_by" : str or None, "created_at" : str or None, "attachments" : dict["url","bytes" or "url"], "url" : str "reply" : list[dict] }]

Parameters:

• task

  (BaseTask) –

  The task for which to retrieve notes.

• force_stop

  (Callable[[], bool], default: lambda: False ) –

  If True, aborts and returns empty list.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: List of notes including content, author, timestamp,

• list[dict[str, Any]] –

  attachments, replies, and direct ShotGrid URLs.

return_task_versions

return_task_versions(task: BaseTask) -> list[list[Any]]

Base method to create the version listing logic of a task, the returned object must be a list with the following structure:

[{ "content" : str, "created_by" : str or None, "created_at" : str or None, "attachments" : dict["url","bytes" or "url"], "url" : str "reply" : list[dict] }]

Parameters:

• task

  (BaseTask) –

  The task entity to query versions for.

Returns:

• list[list[Any]] –

  list[list[Any]]: A list of version details, each item containing: [version_id, thumbnail_url, version_code, user_name, status_code]

return_tasks

return_tasks(*args: Any, **kwargs: Any) -> None

Load tasks for the given entity type and store them normalized.

Parameters:

• **kwargs

  (Any, default: {} ) –

  Must include sg_entity_type to choose which tasks to load.

return_tasks_by_entity

return_tasks_by_entity(link_type: str, force_no_cache: bool = False, filters: list[list[Any]] = [], cache_data: bool = True) -> Optional[list[BaseTask]]

DEPRECATED: (USE "normalize_tasks") Query ShotGrid for all tasks of a given entity type and wrap them as BaseTask objects.

Parameters:

• link_type

  (str) –

  The entity type code (e.g., "Asset", "Shot").

• force_no_cache

  (bool, default: False ) –

  If True, bypass the cache layer.

• filters

  (list[list[Any]], default: [] ) –

  Additional ShotGrid filters.

• cache_data

  (bool, default: True ) –

  If True, save the raw SG results to cache.

Returns:

• Optional[list[BaseTask]] –

  Optional[list[BaseTask]]: A list of BaseTask instances, or None on failure.

return_thumbnail_url

return_thumbnail_url(entity_type: str, id: int) -> Optional[str]

Retrieve the thumbnail image URL for a specific entity.

Parameters:

• entity_type

  (str) –

  The type of entity (e.g., 'Task', 'Asset').

• id

  (int) –

  ID of the entity.

Returns:

• Optional[str] –

  Optional[str]: URL of the thumbnail image or None if not found.

return_version_notes

return_version_notes(version: dict[str, Any], download_attachments: Union[Path, bool] = False) -> list[dict[str, Any]]

Base method to create the note listing logic of a playlist, the returned object must be a list with the following structure:

[{ "content" : str, "created_by" : str or None, "created_at" : str or None, "attachments" : dict["url","bytes"], "url" : str }]

Parameters:

• version

  (dict[str, Any]) –

  A ShotGrid version dictionary.

• download_attachments

  (Union[Path, bool], default: False ) –

  Path to download files to.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: The same version dict with 'attachments' populated.

return_version_number

return_version_number(file: Path) -> int

Looks at the file and returns as int the version number that matches the version_regex.

Parameters:

• file

  (Path) –

  version file.

Returns:

• int ( int ) –

  The maximum version number found. Returns -1 if none.

return_versions_notes

return_versions_notes(list_version: list[dict[str, Any]], download_attachments: Union[Path, bool] = False) -> list[dict[str, Any]]

Base method to create the note listing logic of a playlist, the returned object must be a list with the following structure:

[{ "content" : str, "created_by" : str or None, "created_at" : str or None, "attachments" : dict["url","bytes"], "url" : str }]

Parameters:

• list_version

  (list[dict[str, Any]]) –

  Versions to extract notes from.

• download_attachments

  (Union[Path, bool], default: False ) –

  Destination path to download attachments or False.

Returns:

• list[dict[str, Any]] –

  list[dict[str, Any]]: Updated version dictionaries with note attachments.

server_to_local

server_to_local(path: Path) -> Path

Converts the server path to local path.

start_task

start_task() -> None

Hook for starting a task. To be overridden as needed.

stringify_class classmethod

stringify_class(value: Any) -> Any

Return a JSON-friendly representation of a value.

Parameters:

• value

  (Any) –

  Object to convert.

Returns:

• Any –

  A value that can be serialized by :mod:json.

task_long_to_short

task_long_to_short(task_name: str) -> str

Returns the short alias for a given long task name.

Parameters:

• task_name

  (str) –

  Full name of the task.

Returns:

• str ( str ) –

  Shortened task name.

Raises:

• Exception –

  If task name is not found in the dictionary.

update_asset_task_fields_with_task_entities

update_asset_task_fields_with_task_entities(additional_filters: Optional[list[Any]] = None) -> None

Update asset task fields based on associated ShotGrid task entities.

Parameters:

• additional_filters

  (Optional[list[Any]], default: None ) –

  Additional filters for the ShotGrid query.

upload_file

upload_file(file: Path, task: Optional[BaseTask] = None, description: str = '') -> dict[str, Any]

Upload a local file to ShotGrid as a PublishedFile.

Parameters:

• file

  (Path) –

  The file to upload.

• task

  (Optional[BaseTask], default: None ) –

  The task associated with the file.

• description

  (str, default: '' ) –

  Optional description for the upload.

Returns:

• dict[str, Any] –

  dict[str, Any]: A result dictionary indicating success, message, and error if any.

upload_package

upload_package(list_files: list[Path], package_name: str, task: Optional[BaseTask] = None) -> Iterator[tuple[int, str]]

Create and upload a zip package containing the specified files and their Maya dependencies.

This function yields progress updates at different stages of packaging and uploading: - 0–10%: Preparing files - 10–50%: Resolving Maya dependencies - 70–99%: Uploading the package to ShotGrid

Parameters:

• list_files

  (list[Path]) –

  List of files to include in the package.

• package_name

  (str) –

  The name for the zip archive to be created.

• task

  (Optional[BaseTask], default: None ) –

  Optional task context to associate the upload with.

Yields:

• tuple[int, str] –

  Iterator[tuple[int, str]]: Tuples of (progress percentage, status message).

validate_last_task_path

validate_last_task_path(task: Optional[BaseTask] = None) -> Path

Ensure the filesystem structure exists for the last-clicked task.

If necessary, creates missing directories (including any subfolders defined in task_subfolders).

Parameters:

• task

  (BaseTask, default: None ) –

  Task to validate. Defaults to self.last_task_clicked.

Returns:

• Path ( Path ) –

  The validated (and possibly newly created) task path.

verify_bdl_excel classmethod

verify_bdl_excel(excel: Path) -> tuple[bool, str]

Validate the naming convention of a BDL Excel file.

Parameters:

• excel

  (Path) –

  The Excel file to verify.

Returns:

• tuple[bool, str] –

  tuple[bool, str]: True and code string if valid; False and reason otherwise.