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:
- 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.
- fieldCount(recursive=False)¶
Returns the count field count on the config.
- rules(recursive=True)¶
Returns all the currently active rules
- hasRule(name, recursive=True)¶
Whether the config has the given rule by name.
- 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.
- ruleFromExpression(expression, recursive=True)¶
Given the expression return the matching expression name.
- deleteRule(rule)¶
Deletes the given rule from the config, ignoring the parent hierarchy.
- deleteRuleByName(name)¶
Deletes the given rule by name from the config, ignoring the parent hierarchy.
- 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.
- fields(recursive=True)¶
Generator function which returns all fields on the config.
- addField(name, fields)¶
Adds the token with the value and sets the default.
- hasField(name, recursive=True)¶
Checks if the token exists in the config.
- hasFieldKey(name, value, recursive=True)¶
Checks if the value exists with in the token table.
- 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.
- 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.
- 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:
- 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)¶
- 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:
- class Field(name, description, permissions, keyValues)¶
Bases:
object
- classmethod fromDict(data)¶
- hasKey(key)¶
Whether the KeyValue by it’s name exists.
- add(name, value, protected=False)¶
Adds a new KeyValue to the field.
- 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.
- serialize()¶
- valueForKey(key)¶
Returns the field value for the key within the table
- keyForValue(value)¶
Returns the field key from the table based on the compare.
- 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:
- property name¶
- serialize()¶