Skip to content

shotgrid_plugin

shotgrid_plugin

Classes:

ShotgridInstance 

ShotgridInstance(plugin: ShotgridPlugin)

Context manager for handling a Shotgun API session.

This helper class is designed to manage the lifecycle of a Shotgun API instance within a with-statement. It ensures the connection is properly closed after use.

Parameters:

Methods:

  • __enter__ –

    Instantiate and return a Shotgun API instance.

  • __exit__ –

    Clean up the Shotgun API instance.

__enter__ 

__enter__() -> Shotgun

Instantiate and return a Shotgun API instance.

Returns:

  • Shotgun ( Shotgun ) –

    Shotgun API instance.

__exit__ 

__exit__(exc_type: Optional[type], exc_value: Optional[BaseException], exc_tb: Optional[object]) -> None

Clean up the Shotgun API instance.

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:

Attributes:

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:

  • (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:

  • (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:

  • (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:

  • (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.

  • (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:

  • (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.