Tokens module

Tokens are the meaningful parts of a template. A token can be required, meaning fully typed by the user, or can have a set of options preconfigured.

If options are present, then one of them is the default one. Each option follows a {full_name:abbreviation} schema, so that names can be short but meaning can be recovered easily. The default option might be passed explicitly by the user by passing a default argument (it must match one of the options in the Token). If no default options is explicitly passed, the Token will sort options alphabetically and pick the first one. Please notice if you pass the default option explicitly, you can use the abbreviation or the full option name.

n.add_token('whatAffects')
n.add_token_number('digits')
n.add_token('category', natural='nat',
            practical='pra', dramatic='dra',
            volumetric='vol', default='nat')

In line 1 we’re creating a Required Token. This means that for solving the user must provide a value. This is a explicit solve.

In line 2 we’re creating a Number Token. This is a special Token really useful for working with version like or counting parts of a name. It’s always required.

In line 3 we’re creating an Optional Token, which means that for solving the user can pass one of the options in the Token or simply ignore passing a value and the Token will solve to it’s default option. This is an implicit solve, which helps to greatly reduce the amount of info that needs to be passed to solve for certain cases.

For more information on implicit and explicit solving please check Solving

vfxnaming.tokens.add_token(name, **kwargs)

Add token to current naming session. If ‘default’ keyword argument is found, set it as default for the token instance.

Args:

name (str): Name that best describes the token, this will be used as a way to invoke the Token object.

kwargs: Each argument following the name is treated as an option for the new Token.

Raises:

TokenError: If explicitly passed default does not match with any of the options.

Returns:

Token: The Token object instance created for given name and fields.

vfxnaming.tokens.add_token_number(name, prefix='', suffix='', padding=3)

Add token number to current naming session.

Args:

name (str): Name that best describes the token, this will be used as a way to invoke the TokenNumber object.

prefix (str, optional): Prefix for token number. Useful if you have to use ‘v’ as prefix for versioning for example.

suffix (str, optional): Suffix for token number.

padding (int, optional): Padding a numeric value with this leading number of zeroes. e.g.: 25 with padding 4 would be 0025

Returns:

TokenNumber: The TokenNumber object instance created for given name and fields.

vfxnaming.tokens.get_token(name)

Gets Token or TokenNumber object with given name.

Args:

name (str): The name of the token to query.

Returns:

Rule: Token object instance for given name.

vfxnaming.tokens.get_tokens()

Get all Token and TokenNumber objects for current session.

Returns:

dict: {token_name:token_object}

vfxnaming.tokens.has_token(name)

Test if current session has a token with given name.

Args:

name (str): The name of the token to be looked for.

Returns:

bool: True if rule with given name exists in current session, False otherwise.

vfxnaming.tokens.load_token(filepath)

Load token from given location and create Token or TokenNumber object in memory to work with it.

Args:

filepath (str): Path to existing .token file location

Returns:

bool: True if successful, False if .token wasn’t found.

vfxnaming.tokens.remove_token(name)

Remove Token or TokenNumber from current session.

Args:

name (str): The name of the token to be removed.

Returns:

bool: True if successful, False if a rule name was not found.

vfxnaming.tokens.reset_tokens()

Clears all rules created for current session.

Returns:

bool: True if clearing was successful.

vfxnaming.tokens.save_token(name, directory)

Saves given token serialized to specified location.

Args:

name (str): The name of the token to be saved. filepath (str): Path location to save the token.

Returns:

bool: True if successful, False if rule wasn’t found in current session.