Skip to content

GrisuPlugin

GrisuPlugin 

GrisuPlugin(*args, **kwargs)


              flowchart LR
              task_schema.plugins.grisu_plugin.GrisuPlugin[GrisuPlugin]
              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.shotgrid_plugin.ShotgridPlugin --> task_schema.plugins.grisu_plugin.GrisuPlugin
                                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.grisu_plugin.GrisuPlugin href "" "task_schema.plugins.grisu_plugin.GrisuPlugin"
              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"

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.

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_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.

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_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.