Skip to content

BasePlugin

BasePlugin 

BasePlugin(username: str = None, *args, **kwargs)


              flowchart LR
              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_studio.BaseCPlugin --> task_schema.plugins.base_plugin.BasePlugin
                                task_schema.plugins.base_studio.BaseComponent --> task_schema.plugins.base_studio.BaseCPlugin
                



              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"

Core plugin class providing shared launcher functionality.

Class Attributes

PROJECT_UUID (Optional[str]): Unique identifier. super_user (str): Username for elevated operations. env_handler (EnviromentHandlerCore): Environment manager for environment variables. TEMPLATES_FOLDER (Path): Path to templates folder. BDLS_PATH (Path): Path for BDLs files. SL_SERVER_PATH (Path): Path for session logs on server. GWAIO_DEADLINE_REPO_PATH (str): Path for Deadline repository. OCIO_FILE (Optional[Path]): Filepath for OCIO configuration. CUSTOM_MAYA_TOOLS (Optional[Path]): Path for custom Maya tools. CUSTOM_NUKE_TOOLS (Optional[Path]): Path for custom Nuke tools. CUSTOM_HOUDINI_TOOLS (Optional[Path]): Path for custom Houdini tools. GWAIO_MAYA_LIGHT_TEMPLATE (Path): Default Maya light rig template. title (str): Human-readable title of the plugin. uses_deadline (bool): Flag indicating Deadline integration. create_file_ext (List[str]): Default file extensions for creation. task_subfolders (Dict[str, List[str]]): Default subfolders for each task.

Methods:

Attributes:

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.

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.

__del__ 

__del__() -> None

This method should be called before unmounting this plugin. This method should be overriden to close up connections, like shotgun or maya instances.

after_publish 

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

Hook called after publishing process completes.

Parameters:

  • *args

    (Any, default: () ) –

    Positional arguments.

  • **kwargs

    (Any, default: {} ) –

    Keyword arguments.

browse_note_data 

browse_note_data() -> None

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

browse_task_data 

browse_task_data() -> None

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

browse_version_data 

browse_version_data() -> None

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

check_version_is_published 

check_version_is_published(version: Path) -> bool

Determine whether a given version file has already been published.

Parameters:

  • version

    (Path) –

    File path of the version to check.

Returns:

  • bool ( bool ) –

    True if published; False otherwise.

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_shot 

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

Create a shot using parsed shot data.

Parameters:

  • shot_data

    (dict[str, Any]) –

    Dictionary of shot attributes.

Raises:

  • NotImplementedError –

    Must be implemented in subclass.

create_thumbnail classmethod 

create_thumbnail(task: BaseTask) -> bool

This method may be overriden and it is called when the thumbnail for a task cannot be synced because it is not in the server yet. Returns True on success

Parameters:

  • task

    (BaseTask) –

    Task for which to create the thumbnail.

Returns:

  • bool ( bool ) –

    True if creation and resizing succeeded, False otherwise.

extract_plugin_values 

extract_plugin_values() -> None

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

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.

get_all_tasks_data 

get_all_tasks_data(return_object: dict, callback: Callable = None) -> None

This method should be overriden. It fills the return_object so that it can be accesed when threaded and runs a callback

Parameters:

  • return_object

    (Dict) –

    A container that will be filled with the retrieved task data.

  • callback

    (Callable, default: None ) –

    A function to call once data retrieval is complete.

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.

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) -> Iterator[dict[Any, Any]]

Parse an EDL file to extract shot data.

Parameters:

  • source_edl

    (Path) –

    Path to the EDL file.

  • source_video

    (Path) –

    Path to the reference video.

Yields:

  • dict[Any, Any] –

    dict[Any, Any]: A dictionary representing each shot.

Raises:

  • NotImplementedError –

    Must be implemented in subclass.

publish_version 

publish_version(task: BaseTask, version: Path) -> dict

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

Parameters:

  • task

    (BaseTask) –

    The task being published.

  • version

    (Path) –

    Path to the version file.

Returns:

  • dict –

    Dict[str, Any]: A result dict with: { "success": bool, "message": str, "error": Optional[str] }

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

Because the user data may be passed on to the plugin on initialization, we have this function that will handle in a per plugin basis the logic.

Parameters:

  • *args

    (Any, default: () ) –

    Positional arguments.

  • **kwargs

    (Any, default: {} ) –

    Configuration data passed by the app.

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_entity_description 

return_entity_description(task: BaseTask, force_stop: Callable[[], bool]) -> Optional[str]

Return a string description of the entity (e.g., asset or shot).

Parameters:

  • task

    (BaseTask) –

    The task associated with the entity.

  • force_stop

    (Callable[[], bool]) –

    Callback to interrupt processing.

Returns:

  • Optional[str] –

    Optional[str]: The entity description, if any.

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_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_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_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]) -> 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" : list[dict["url_open":str,"url_image":str,"bytes":str,"path":str],] "url" : str }]

Parameters:

  • task

    (BaseTask) –

    The task to retrieve notes for.

  • force_stop

    (Callable[[], bool]) –

    Callback to interrupt processing.

Returns:

  • list[dict[str, Any]] –

    list[dict[str, Any]]: A list of note dictionaries.

return_task_versions 

return_task_versions(task: BaseTask) -> list[dict[str, 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 to retrieve versions for.

Returns:

  • list[dict[str, Any]] –

    list[dict[str, Any]]: A list of version dictionaries.

return_thumbnail_url 

return_thumbnail_url() -> Optional[str]

This method should be overriden according to each plugin. This refresh the url thumbnail in the plugin's database

Returns:

  • Optional[str] –

    Optional[str]: URL string if available.

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.

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.

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.