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.

clearFields()¶: Clears All current fields 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()¶