Naming

Generic naming configuration handling

Naming works off a json based configuration which contains rules and tokens. see config.json under the test folder formatting example.

Naming management provides a useful way to provide strict rules over how a name is formatted and generated. A rule contain to important pieces a Name i.e. myRule and an expression ie. “{area}_{side}_noToken”. See NameManager for working with the config.

class NameManager(config=None, configPath=None)

Bases: object

The name manager deals with the manipulation of a string based on an expression allowing for a formalised naming convention, we use the terms ‘rule’ and ‘tokens’ throughout the class to describe the logic. rules are just a basic expression like so ‘{side}_{area}_{counter}_{type}’, the ‘_’ isn’t necessary for any logic. the characters within the curly brackets are tokens which will be replaced when it’s resolved.

You can add tokens and values in memory per instance, or you can add it to the config JSON file.

Parameters
  • config (dict or None) – The config to load if required.

  • configPath (str or None) – The json absolute json file path containing rules and tokens.

classmethod fromPath(configPath)

Loads the provided configPath and resets this instance with said paths.

Parameters

configPath (str) – The absolute config path to a valid json file to load.

classmethod flatten(configuration)
Parameters

configuration (NameManager) –

Returns

Return type

changes(target=None)
ruleCount(recursive=False)

Returns the count rule count on the config.

Parameters

recursive (bool) – Whether to recursively search the parent config hierarchy if the parent is valid.

Returns

The total rule count.

Return type

int

fieldCount(recursive=False)

Returns the count field count on the config.

Parameters

recursive (bool) – Whether to recursively search the parent config hierarchy if the parent is valid.

Returns

The total field count.

Return type

int

rules(recursive=True)

Returns all the currently active rules

Parameters

recursive (bool) – Whether to recursively search the parent config hierarchy if the parent is valid.

Returns

a list of active rule names

Return type

list[Rule]

hasRule(name, recursive=True)

Whether the config has the given rule by name.

Parameters
  • name (str) – The rule name.

  • recursive (bool) – If True then the parent config will be searched as the fallback.

Return type

bool

addRule(name, expression, description, exampleFields, creator=None, recursive=True)

Adds the provided rule to the config. If the rule already exists then it will be updated.

Parameters
  • name (str) – The rule name to add or update.

  • expression (str) – The new expression string.

  • description (str) – The rule description

  • exampleFields (dict) – A dict containing an example KeyValues for the expression fields.

  • creator (str) – The rule creator name

  • recursive (bool) – If True then the parent config will be searched as the fallback.

rule(name, recursive=True)

Returns the rule info data for the given Rule.

Parameters
  • name (str) – The rule name ie. “object”

  • recursive (bool) – If True then the parent config will be searched as the fallback.

Returns

The Rule Instance or None if not found

Return type

Rule or None

ruleFromExpression(expression, recursive=True)

Given the expression return the matching expression name.

Parameters
  • recursive (bool) – If True then the parent config will be searched as the fallback.

  • expression (str) – The expression format ie. “{my}_{expression}”

Returns

The rule name which matches the expression.

Return type

Rule

deleteRule(rule)

Deletes the given rule from the config, ignoring the parent hierarchy.

Parameters

rule (Rule) – The rule to delete from the config

Returns

Whether the rule was deleted successfully.

Return type

bool

deleteRuleByName(name)

Deletes the given rule by name from the config, ignoring the parent hierarchy.

Parameters

name (str) – The rule name ie. “object”

Returns

Whether the rule was deleted successfully.

Return type

bool

updateRules(rules)

Updates the configs rule list with the provided rules. Rules are stored as a set, so we use set.update.

Parameters

rules (list[Rule]) – A list of rules to add to the configs rules.

clearRules()

Clears All current rules for the config.

setRules(rules)

Overrides the current rules with the provided ones.

Parameters

rules (set[Rule]) – The Rules to set for the config.

field(name, recursive=True)

Returns the field table for the given name.

If recursive id true then if the current config doesn’t contain the token then the parent config if specified will be searched.

Parameters
  • name (str) – The token name to query.

  • recursive (bool) – If True then the parent config will be searched as the fallback.

Returns

The token table.

Return type

Field

fields(recursive=True)

Generator function which returns all fields on the config.

Parameters

recursive (bool) – If True then the parent config will be searched as well

Return type

list[Field]

addField(name, fields)

Adds the token with the value and sets the default.

Parameters
  • name (str) – The new token name.

  • fields (dict[str,str]) – the dict of key value pairs.

Return type

Field

hasField(name, recursive=True)

Checks if the token exists in the config.

Parameters
  • name (str) – The field name to query

  • recursive (bool) – If True then the parent config will be searched as the fallback

Return type

bool

hasFieldKey(name, value, recursive=True)

Checks if the value exists with in the token table.

Parameters
  • name (str) – The field name to query.

  • value (str) – The token table value.

  • recursive (bool) – If True then the parent config will be searched as the fallback

Return type

bool

setFields(fields)

Overrides the current fields with the provided ones.

Parameters

fields (set[Field]) – The fields to set for the config.

expressionFromString(name)

Returns the expression from the name, if the name cannot be resolved then we raise ValueError, If we resolve to multiple expressions then we raise ValueError. Only one expression is possible. To resolve a name, all tokens must exist within the config, and we must be able to resolve more than 50% for an expression for it to be viable.

Parameters

name (str) – the string the resolve.

Returns

the config expression eg. {side}_{type}{section}.

Return type

str

resolve(rule, fields)

Resolves the given rule expression using the provided fields as values. Each field value will be converted via the config’s field table if a field or field key doesn’t exist then the provided value will be used instead.

Parameters
  • rule (str) – The rule Name.

  • fields (dict) – The fields key and values to set for the expression.

Returns

The formatted string. tokenAValue_tokenBValue_anim.

Return type

str

serialize()
refresh()

Loads a fresh version of the config based on the original config paths.

class NamingChanges(source, target)

Bases: object

NamingChanges handles creating a new naming config based on the changes in the source config vs the target config.

Parameters
  • source (NameManager) – The source config where it’s local rules/fields are diffed against the target.

  • target (NameManager) – Commonly the parent config of the source, used to check changes for the source.

hasChanges()

Whether There’s any changes made on the source compared to the target.

Return type

bool

serialize()

Returns the changes for the source based on the target.

Return type

dict

compute()
class Rule(name, creator, description, expression, exampleFields)

Bases: object

Encapsulates a rule expression.

Parameters
  • name (str) – The Rule name.

  • creator (str) – The person who created the rule

  • description (str) – The description of what the expression represents, should include example.

  • expression (str) – The Expression to use which can contain fields using the format, “{myField}_{anotherField}”

  • exampleFields (dict) – example fields for the expression which is used in UIs for generating examples.

classmethod fromDict(data)
fields()

Returns all the fields within the current expression.

Return type

list[str]

serialize()

Returns the raw data for the rule.

myRule = myRule.fromData({'name': 'componentName',
                        'creator': 'ZooToolsPro',
                        'description': 'Some description',
                        'expression': '{componentName}_{side}',
                        'exampleFields': {'componentName': 'arm', 'side': 'L'}})
data = myRule.serialize()
# {'name': 'componentName',
# 'creator': 'ZooToolsPro',
# 'description': 'Some description',
# 'expression': '{componentName}_{side}',
# 'exampleFields': {'componentName': 'arm', 'side': 'L'}}
Return type

dict

class Field(name, description, permissions, keyValues)

Bases: object

classmethod fromDict(data)
count()

Returns the number of KeyValue instances for the field.

Return type

int

hasKey(key)

Whether the KeyValue by it’s name exists.

Parameters

key (str) – The key to check for.

Return type

bool

add(name, value, protected=False)

Adds a new KeyValue to the field.

Parameters
  • name (str) – The new keyValue name.

  • value (str) – The new KeyValue Value. Should be a string.

  • protected (bool) – Whether this KeyValue is protected from deletion and renaming.

Returns

Returns the newly created KeyValue Instance

Return type

KeyValue

update(field)

Updates(merge) the provided field KeyValues with this field instance KeyValues.

Parameters

field (Field) – The Field instance to update this field.

remove(key)

Removes the KeyValue instance from the field by the key.

Parameters

key (str) – The KeyValue name to remove.

Returns

Whether removal was successful

Return type

bool

serialize()
valueForKey(key)

Returns the field value for the key within the table

Parameters

key (str) – The key to search for

Return type

str

keyForValue(value)

Returns the field key from the table based on the compare.

Parameters

value (str) – The value to search from the table.

Return type

str

keyValues()

Generator Function which returns each keyValue object in the table.

Return type

Iterable[KeyValue]

keyValue(key)

Returns the KeyValue object for the given key.

Parameters

key (str) – The key within the table to return.

Return type

KeyValue

class KeyValue(name, value, protected=False)

Bases: object

KeyValue class is Responsible for a single key/value pair within a naming field.

The Key Value can also be marked as protected in which case the value can still change but can’t be renamed or deleted.

Parameters
  • name (str) – The name for the KeyValue.

  • value (str) – The value for the keyValue.

  • protected (bool) – if Protected Than this KeyValue can’t be deleted or renamed, but it’s value can change.

property name
serialize()