tokens.tokens#

The module contains interface used to get and modify a bookmark item’s token values.

The default values are stored in DEFAULT_TOKEN_CONFIG but each bookmark item can be configured independently using the tokens.tokens_editor widget. The custom configuration values are stored in the bookmark’s database using TOKENS_DB_KEY column as encoded JSON data.

Use get() to retrieve token config controller instances.

 1from bookmarks.tokens import tokens
 2
 3tokens_config = tokens.get(server, job, root)
 4data = tokens_config.data()
 5
 6# Try to find a description for an item named 'geo'
 7v = tokens_config.get_description('geo')
 8
 9# Expands all tokens using values set in the bookmark database
10s = tokens_config.expand_tokens(
11    '{asset_root}/{scene}/{prefix}_{asset}_{task}_{user}_{version}.{ext}',
12    ext='exr'
13)

Classes:

TokenConfig(server, job, root[, asset, parent])

The class is used to interface with token configuration stored in the bookmark item's database.

Functions:

get(server, job, root[, force])

Returns the TokenConfig of the specified bookmark item.

get_description(token)

Get a description of a token.

get_folder(token)

Find the value an asset folder token based on the bookmark item's token configuration.

get_subfolder(token, name)

Find the value an asset sub-folder based on the bookmark item's token configuration.

get_subfolders(token)

Find all asset sub-folder values based on the bookmark item's token configuration.

Data:

DEFAULT_TOKEN_CONFIG

The default token value configuration

TOKENS_DB_KEY

The database column name

invalid_token

Invalid token marker string
class bookmarks.tokens.tokens.TokenConfig(server, job, root, asset=None, parent=None)[source]#

Bases: QObject

The class is used to interface with token configuration stored in the bookmark item’s database.

As token config data might be used in performance sensitive sections, the instance is uninitialized until data() is called. This will load values from the database and cache it internally. This cached data won’t be updated from the database until data(force=True)() is called.

Methods:

data([force])

Returns the current token config values stored in the bookmark database.

dump_json(destination[, force])

Save the current configuration as a JSON file.

expand_tokens(s[, user, version, host, ...])

Expands all valid tokens of the given string, based on the current database values.

get_asset_folder(k[, force])

Return the name of an asset folder based on the current token config values.

get_asset_subfolder(token, folder[, force])

Returns the value of an asset sub-folder based on the current token config values.

get_asset_subfolders(token[, force])

Returns the value of an asset sub-folder based on the current token config values.

get_description(token[, force])

Utility method used to get the description of a token.

get_extensions(flag[, force])

Returns a list of extensions associated with the given flag.

get_task_extensions(task[, force])

Returns a list of allowed extensions for the given task folder.

get_tokens([force])

Get all available tokens.

set_data(data)

Saves a data dictionary to the bookmark database as an encoded JSON object.
data(force=False)[source]#

Returns the current token config values stored in the bookmark database.

The results fetched from the bookmark database are cached to self._data. To re-query the values from the bookmark database, an optional force=True can be passed.

Parameters:

force (bool, optional) – Force retrieve tokens from the database.

Returns:

dict: Token config values.

dump_json(destination, force=False)[source]#

Save the current configuration as a JSON file.

Parameters:

  • destination (str) – Destination path.

  • force (bool, optional) – Force retrieve tokens from the database.

expand_tokens(s, user=common.get_username(), version='v001', host=socket.gethostname(), task='main', ext=None, prefix=None, **_kwargs)[source]#

Expands all valid tokens of the given string, based on the current database values.

Invalid tokens will be marked invalid_token.

Parameters:

  • s (str) – The string containing tokens to be expanded.

  • user (str, optional) – Username.

  • version (str, optional) – The version string.

  • host (str, optional) – The name of the current machine/host.

  • task (str, optional) – Task folder name.

  • ext (str, optional) – File format extension.

  • prefix (str, optional) – Bookmark item prefix.

  • _kwargs (dict, optional) – Optional token/value pairs.

Returns:

The expanded string. It might contain invalid_token markers if a token does not have a corresponding value.

Return type:

str

get_asset_folder(k, force=False)[source]#

Return the name of an asset folder based on the current token config values.

get_asset_subfolder(token, folder, force=False)[source]#

Returns the value of an asset sub-folder based on the current token config values.

Parameters:

  • token (str) – An asset folder name (not value!), e.g.`config.ExportFolder`.

  • folder (str) – A sub folder name, e.g. abc.

  • force (bool, optional) – Force reload data from the database.

Returns:

A custom value set in config settings, or None.

Return type:

str

get_asset_subfolders(token, force=False)[source]#

Returns the value of an asset sub-folder based on the current token config values.

Parameters:

  • token (str) – An asset folder name (not value!), e.g.`tokens.ExportFolder`.

  • force (bool, optional) – Force reload data from the database.

Returns:

A tuple of folder names.

Return type:

list

get_description(token, force=False)[source]#

Utility method used to get the description of a token.

Parameters:

  • token (str) – A file-format or a folder name, e.g. ‘anim’.

  • force (bool, optional) – Force retrieve tokens from the database.

Returns:

The description of the token.

Return type:

str

get_extensions(flag, force=False)[source]#

Returns a list of extensions associated with the given flag.

Parameters:

  • flag (int) – A format filter flag.

  • force (bool, optional) – Force retrieve tokens from the database.

Returns:

A tuple of file format extensions.

Return type:

tuple

get_task_extensions(task, force=False)[source]#

Returns a list of allowed extensions for the given task folder.

Parameters:

  • task (str) – The name of a task folder.

  • force (bool, optional) – Force retrieve tokens from the database.

Returns:

A set of file format extensions.

Return type:

set

get_tokens(force=False, **kwargs)[source]#

Get all available tokens.

Parameters:

force (bool, optional) – Force retrieve tokens from the database.

Returns:

A dictionary of token/value pairs.

Return type:

dict

set_data(data)[source]#

Saves a data dictionary to the bookmark database as an encoded JSON object.

Parameters:

data (dict) – The token config data to save.

bookmarks.tokens.tokens.get(server, job, root, force=False)[source]#

Returns the TokenConfig of the specified bookmark item.

Parameters:

  • server (str) – server path segment.

  • job (str) – job path segment.

  • root (str) – root path segment.

  • force (bool, optional) – Force retrieve tokens from the database.

Returns:

The token config controller instance.

Return type:

TokenConfig

bookmarks.tokens.tokens.get_description(token)[source]#

Get a description of a token.

Parameters:

token (str) – A token, e.g. tokens.SceneFormat.

Returns:

Description of the item.

Return type:

str

bookmarks.tokens.tokens.get_folder(token)[source]#

Find the value an asset folder token based on the bookmark item’s token configuration.

Returns:

The current folder value.

Return type:

str

bookmarks.tokens.tokens.get_subfolder(token, name)[source]#

Find the value an asset sub-folder based on the bookmark item’s token configuration.

Parameters:

  • token (str) – Asset folder token, e.g. tokens.CacheFolder.

  • name (str) – Sub-folder token.

Returns:

The value of the current asset sub-folder.

Return type:

str

bookmarks.tokens.tokens.get_subfolders(token)[source]#

Find all asset sub-folder values based on the bookmark item’s token configuration.

Parameters:

token (str) – Asset folder token, e.g. tokens.CacheFolder.

Returns:

A list of current asset sub-folder values.

Return type:

list

bookmarks.tokens.tokens.DEFAULT_TOKEN_CONFIG = {'AssetFolderConfig': {0: {'description': 'Alembic, FBX, OBJ and other CG caches', 'filter': 31, 'name': 'cache', 'subfolders': {0: {'description': 'Alembic (*.abc) cache files', 'name': 'abc', 'value': 'alembic'}, 1: {'description': 'OBJ cache files', 'name': 'obj', 'value': 'obj'}, 2: {'description': 'FBX cache files', 'name': 'fbx', 'value': 'fbx'}, 3: {'description': 'Arnold (*.ass) cache files', 'name': 'ass', 'value': 'arnold'}, 4: {'description': 'USD stage and cache files', 'name': 'usd', 'value': 'usd'}, 5: {'description': 'USD stage and cache files', 'name': 'usda', 'value': 'usd'}, 6: {'description': 'USD stage and cache files', 'name': 'usdc', 'value': 'usd'}, 7: {'description': 'USD stage and cache files', 'name': 'usdz', 'value': 'usd'}, 8: {'description': 'Houdini cache files', 'name': 'geo', 'value': 'geo'}, 9: {'description': 'Houdini cache files', 'name': 'bgeo', 'value': 'geo'}, 10: {'description': 'Volume caches', 'name': 'vdb', 'value': 'vdb'}, 11: {'description': 'Maya scene exports', 'name': 'ma', 'value': 'maya'}, 12: {'description': 'Maya scene exports', 'name': 'mb', 'value': 'maya'}}, 'value': 'cache'}, 1: {'description': 'Temporary data files, or content generated by applications', 'filter': 255, 'name': 'data', 'subfolders': {}, 'value': 'data'}, 2: {'description': 'References, e.g., images, videos or sound files', 'filter': 58, 'name': 'reference', 'subfolders': {}, 'value': 'reference'}, 3: {'description': 'Render layer outputs', 'filter': 26, 'name': 'render', 'subfolders': {}, 'value': 'images'}, 4: {'description': 'Project and scene files', 'filter': 1, 'name': 'scene', 'subfolders': {0: {'description': 'Layout, blockomatic & animatics scenes', 'name': 'layout', 'value': 'layout'}, 1: {'description': 'Modeling & sculpting scenes', 'name': 'model', 'value': 'model'}, 2: {'description': 'Character rigging scenes', 'name': 'rig', 'value': 'rig'}, 3: {'description': 'Render and lighting projects', 'name': 'render', 'value': 'render'}, 4: {'description': 'Animation scenes', 'name': 'anim', 'value': 'anim'}, 5: {'description': 'FX project files', 'name': 'fx', 'value': 'fx'}, 6: {'description': 'Compositing project files', 'name': 'comp', 'value': 'comp'}, 7: {'description': 'Audio and SFX project files', 'name': 'audio', 'value': 'audio'}, 8: {'description': 'Motion tracking projects', 'name': 'tracking', 'value': 'tracking'}}, 'value': 'scenes'}, 5: {'description': 'Asset publish files', 'filter': 26, 'name': 'publish', 'value': 'publish'}, 6: {'description': '2D and 3D texture files', 'filter': 26, 'name': 'textures', 'subfolders': {}, 'value': 'sourceimages'}, 7: {'description': 'Miscellaneous asset files', 'filter': 255, 'name': 'other', 'subfolders': {}, 'value': 'other'}}, 'FileFormatConfig': {0: {'description': 'Scene file formats', 'flag': 1, 'name': 'Scene Formats', 'value': 'aep, ai, blend, c4d, eps, fla, hip, hiplc, hipnc, hud, ma, mb, mocha, nk, nk, ppj, prproj, psb, psd, psq, rv, spm, tvpp, xfl, zprj'}, 1: {'description': 'Image file formats', 'flag': 2, 'name': 'Image Formats', 'value': '3g2, 3gp, avi, bmp, bmp, bw, cin, cineon, dds, dds, dib, dpx, dpx, env, exr, ffmpeg, fits, fits, gif, gif, hdr, hdr, ico, ico, iff, iff, int, inta, j2c, j2k, jfi, jfif, jif, jp2, jpe, jpeg, jpeg, jpeg2000, jpg, m4a, m4v, mj2, mov, mp4, mpg, mxr, nul, null, null, openexr, pbm, pdd, pfm, pgm, pic, png, png, pnm, pnm, ppm, psb, psd, psd, qt, rgb, rgba, rgbe, rla, rla, sgi, sgi, sm, softimage, sxr, targa, term, term, tga, tif, tiff, tiff, tpic, tx, vsm, webp, webp, z, zfile, zfile'}, 2: {'description': 'CG cache formats', 'flag': 4, 'name': 'Cache Formats', 'value': 'abc, ass, bgeo, fbx, geo, ifd, obj, rs, sc, sim, usd, usda, usdc, usdz, vdb'}, 3: {'description': 'Movie file formats', 'flag': 8, 'name': 'Movie Formats', 'value': 'avi, m4v, mov, mp4'}, 4: {'description': 'Audio file formats', 'flag': 16, 'name': 'Audio Formats', 'value': 'aac, m4a, mp3, wav'}, 5: {'description': 'Audio file formats', 'flag': 32, 'name': 'Document Formats', 'value': 'doc, docx, pdf, ppt, pptx, rtf, txt'}, 6: {'description': 'Various script file formats', 'flag': 64, 'name': 'Script Formats', 'value': 'bash, bat, env, js, json, jsx, mel, py, pyc, pyd, pyo, vex, xml'}, 7: {'description': 'Miscellaneous file formats', 'flag': 128, 'name': 'Miscellaneous Formats', 'value': '7z, app, bz2, exe, gz, rar, tar, zip, zipx'}}, 'FileNameConfig': {0: {'description': 'Uses the project prefix, asset, task, element, user and version names', 'name': 'Asset Scene Task', 'value': '{prefix}_{asset}_{mode}_{element}_{user}_{version}.{ext}'}, 1: {'description': 'Uses the project prefix, asset, user and version names', 'name': 'Asset Scene File (without task and element)', 'value': '{prefix}_{asset}_{user}_{version}.{ext}'}, 2: {'description': 'Uses the project prefix, sequence, shot, mode, element, user and version names', 'name': 'Shot Scene Task', 'value': '{prefix}_{seq}_{shot}_{mode}_{element}_{user}_{version}.{ext}'}, 3: {'description': 'Uses the project prefix, sequence, shot, user and version names', 'name': 'Shot Scene Task (without task and element)', 'value': '{prefix}_{seq}_{shot}_{user}_{version}.{ext}'}, 4: {'description': 'File name with an element and version name', 'name': 'Versioned Element', 'value': '{element}_{version}.{ext}'}, 5: {'description': 'A non-versioned element file', 'name': 'Non-Versioned Element', 'value': '{element}.{ext}'}}, 'PublishConfig': {0: {'description': 'Publish a shot task element', 'filter': 15, 'name': 'Shot Task', 'value': '{server}/{job}/publish/{sequence}_{shot}/{task}/{element}/{prefix}_{sequence}_{shot}_{task}_{element}.{ext}'}, 1: {'description': 'Publish an asset task element', 'filter': 15, 'name': 'Asset Task', 'value': '{server}/{job}/publish/asset_{asset}/{task}/{element}/{prefix}_{asset}_{task}_{element}.{ext}'}, 3: {'description': 'Publish an shot thumbnail', 'filter': 2, 'name': 'Shot Thumbnail', 'value': '{server}/{job}/publish/{sequence}_{shot}/thumbnail.{ext}'}, 4: {'description': 'Publish an asset thumbnail', 'filter': 2, 'name': 'Asset Thumbnail', 'value': '{server}/{job}/publish/asset_{asset}/thumbnail.{ext}'}}}#

The default token value configuration

bookmarks.tokens.tokens.TOKENS_DB_KEY = 'tokens'#

The database column name

bookmarks.tokens.tokens.invalid_token = '{invalid_token}'#

Invalid token marker string