Utilities

The publisher provides some utility methods that are generally useful for writing publish plugins that aren’t driven by templates. These methods are used by the basic Shotgun integration to infer information from file paths when templates are not available. This includes version and frame number identification, publish display name, image sequence paths, etc.

Note

These utility methods are exposed via the publisher’s util module, but the implementation for most of them lives within the app’s path_info hook. Studios can override these path processing methods to account for their own naming conventions and path structures.

The utilty method are documented below:

tk_multi_publish2.util.get_version_path(path, version)[source]

Given a path without a version number, return the path with the supplied version number.

If a version number is detected in the supplied path, the path will be returned as-is.

Parameters:

path – The path to inject a version number.
version – The version number to inject.

Returns:

The modified path with the supplied version number inserted.

tk_multi_publish2.util.get_next_version_path(path)[source]

Given a file path, return a path to the next version.

This is typically used by auto-versioning logic in plugins that need to save the current work file to the next version number.

If no version can be identified in the supplied path, None will be returned, indicating that the next version path can’t be determined.

Parameters:: path – The path to a file, likely one to be published.
Returns:: The path to the next version of the supplied path.

tk_multi_publish2.util.get_file_path_components(path)[source]

Convenience method for determining file components for a given path.

Parameters:: path (str) – The path to the file to componentize.

Returns file path components in the form:

# path="/path/to/the/file/my_file.v001.ext"

{
    "path": "/path/to/the/file/my_file.v001.ext",
    "folder": "/path/to/the/file" ,
    "filename": "my_file.v001.ext",
    "extension": "ext",
}

# path="/path/to/the/folder"

{
    "path": "/path/to/the/folder",
    "folder": "/path/to/the" ,
    "filename": "folder",
    "extension": None,
}

tk_multi_publish2.util.get_frame_sequence_path(path, frame_spec=None)[source]

Given a path with a frame number, return the sequence path where the frame number is replaced with a given frame specification such as {FRAME} or %04d or $F.

Parameters:

path – The input path with a frame number
frame_spec – The frame specification to replace the frame number with.

Returns:

The full frame sequence path

tk_multi_publish2.util.get_frame_sequences(folder, extensions=None, frame_spec=None)[source]

Given a folder, inspect the contained files to find what appear to be files with frame numbers.

Parameters:

folder – The path to a folder potentially containing a sequence of files.
extensions – A list of file extensions to retrieve paths for. If not supplied, the extension will be ignored.
frame_spec – A string to use to represent the frame number in the return sequence path.

Returns:

A list of tuples for each identified frame sequence. The first item in the tuple is a sequence path with the frame number replaced with the supplied frame specification. If no frame spec is supplied, a python string format spec will be returned with the padding found in the file.

Example:

get_frame_sequences(
    "/path/to/the/folder",
    ["exr", "jpg"],
    frame_spec="{FRAME}"
)

[
    (
        "/path/to/the/supplied/folder/key_light1.{FRAME}.exr",
        [<frame_1_path>, <frame_2_path>, ...]
    ),
    (
        "/path/to/the/supplied/folder/fill_light1.{FRAME}.jpg",
        [<frame_1_path>, <frame_2_path>, ...]
    )
]

tk_multi_publish2.util.get_publish_name(path, sequence=False)[source]

Given a file path, return the display name to use for publishing.

Typically, this is a name where the path and any version number are removed in order to keep the publish name consistent as subsequent versions are published.

Example:

in: /path/to/the/file/my_file.v001.jpg
out: my_file.jpg

Parameters:

path – The path to a file, likely one to be published.
sequence – If True, treat the path as a sequence name and replace the frame number with placeholder

Returns:

A publish display name for the provided path.

tk_multi_publish2.util.get_version_number(path)[source]

Extract a version number from the supplied path.

This is used by plugins that need to know what version number to associate with the file when publishing.

Example:

in: /path/to/the/file/my_file.v001.jpg
out: 1

Parameters:: path – The path to a file, likely one to be published.
Returns:: An integer representing the version number in the supplied path. If no version found, None will be returned.

tk_multi_publish2.util.get_thumbnail(path, context)[source]

Given a path and context, attempt to automatically generate a thumbnail.

Parameters:

path – The path to generate a thumbnail from.
context – The context to help determine engine software locations in order to discover thumbnail extraction tools.

Returns:

The generated thumbnail.

Return type:

QtGui.QPixmap