Hive Definition Diff¶
Read-only diff of a component’s base definition, the definition cached on the meta node and what is built
in the scene. zoo.libs.hive.definitiondebug.session.DiffSession is the entry point, the Hive Artist UI
Definition Debugger is built on it. For a guide with examples see Hive Definition Diff.
from zoo.libs.hive import api
from zoo.libs.hive.definitiondebug import session as diffsession
rig = api.rootByRigName("biped")
session = diffsession.DiffSession()
session.loadRig(rig.meta)
pairs = [(diffsession.DEFINITION, diffsession.SCENE)]
for snap in session.snapshots:
print(snap.label(), session.differenceCount(snap, pairs))
print(diffsession.reportToMarkdown(session.report(compareMode=diffsession.COMPARE_MODES[1])))
High level, read-only definition diff of every component of a Hive rig.
A DiffSession reads the components of a rig into definitionsources.ComponentSnapshot objects,
builds and caches their diff trees for the current mode, tolerance and ignore rules, can freeze the current state
to compare against later, and exports the differences as a dict or Markdown.
Sources are indexed by BASE, DEFINITION, SCENE, FROZEN_DEFINITION and
FROZEN_SCENE, the frozen ones are missing until DiffSession.freeze() is called.
from zoo.libs.hive.definitiondebug import session as diffsession
session = diffsession.DiffSession()
session.loadRig(rig.meta)
for snap in session.snapshots:
print(snap.label(), session.differenceCount(snap, [(diffsession.DEFINITION, diffsession.SCENE)]))
print(diffsession.reportToMarkdown(session.report()))
session.freeze()
# ... build, mirror, save and reopen ...
session.loadRig(rig.meta)
data = session.report(compareMode=diffsession.FROZEN_COMPARE_MODES[0])
- class CompareMode(label, columns, pairs)¶
Bases:
NamedTupleWhich sources to show and compare.
- layerAccepts(layer, key)¶
True when a top level definition key passes a
LAYER_FILTERSfilter.
- pairColumns(pairs)¶
The sources of the pairs, in order, e.g.
[(0, 1), (1, 2)]gives(0, 1, 2).
- guideIdFromPath(path)¶
Returns the deepest guide id in a
guideLayer.dagpath, or None.
- class DiffSession(ignoreRules=None, mode='normalized', tolerance=0.0001, hideIgnored=True, hideMissing=())¶
Bases:
objectSnapshots of a rig’s components with cached diff trees for the current settings. Read-only, nothing here modifies the scene.
Changing the mode, tolerance, ignore rules, hidden missing sources or freeze doesn’t need any invalidation, trees are cached per setting. Call
loadRig()again to re-read the scene.- Parameters:
ignoreRules (Optional[ignorerules.IgnoreRules]) – The user’s ignore rules, defaults to empty in-memory rules.
mode (str) –
definitionsources.MODE_NORMALIZEDordefinitionsources.MODE_RAW.tolerance (float) – Absolute tolerance used to compare numbers, clamped to 0.
hideIgnored (bool) – Apply the ignore rules, see
activeIgnoreRules().hideMissing (Iterable[int]) – Sources where a missing key hides the row, e.g.
{SCENE}for keys the scene intentionally doesn’t have, seehideMissing.
- property hideMissing: FrozenSet[int]¶
Source indices where a missing key hides the row and everything below it, whatever the other sources hold, overriding the ignore rules. Only sources being shown or compared are checked, e.g. Scene doesn’t affect Base ↔ Definition. Independent of
hideIgnored, the hidden differences are counted byhiddenDifferenceCount().
- loadRig(rigMeta)¶
Re-reads every component of the rig from the scene. The freeze is kept.
A rig whose configuration fails to load is logged and gives no snapshots.
- Parameters:
rigMeta (Optional[HiveRig]) – The rig meta node, None clears the snapshots.
- Returns:
The new snapshots.
- Return type:
List[ComponentSnapshot]
- rigLabel()¶
Label of the loaded rig including its namespace, or an empty string.
- snapshot(label)¶
The snapshot with the label, e.g.
"arm_L", or None.
- invalidate()¶
Forgets the cached trees and origins.
- freeze(label=None)¶
Keeps the current snapshots so they can be compared with the scene after the next
loadRig().- Parameters:
label (str | None) – Description of the freeze, defaults to the current time.
- clearFreeze()¶
- compareModes()¶
The compare modes available, the frozen ones only after a freeze.
- activeIgnoreRules()¶
The ignore rules used to build the trees, user rules first then, in normalized mode,
definitionsources.SERIALIZER_NOISE_RULES. Empty whenhideIgnoredis off.
- sources(snap)¶
(base, definition, scene, frozen definition, frozen scene)for the current mode, any can be None.
- tree(snap, columns=None)¶
The diff tree of the component’s
sources()for the current settings, cached.A failure is logged, added to
snap.errorsand returns None.- Parameters:
columns (Iterable[int] | None) – The sources shown or compared, e.g.
CompareMode.columns.hideMissingand “missing in” ignore rules only check these. None means every source.
- origins(snap)¶
Where each definition value came from, cached, see
definitionsources.definitionOrigins(). A failure is logged and returns an empty dict.
- showsOrigins(columns)¶
True when definition origins apply to the shown source columns: the definition is shown in normalized mode.
- differenceCount(snap, pairs, columns=None)¶
Total number of differences of the component over the pairs, or None when the diff failed.
Number of hidden differences over the components.
- Parameters:
reason (str | None) –
definitiondiff.HIDDEN_BY_RULEfor ignore rules,definitiondiff.HIDDEN_MISSINGforhideMissing, None for both.columns (Iterable[int] | None) – The sources shown, see
tree(), defaults to the sources of the pairs.
- report(snapshots=None, compareMode=None, statuses=('changed', 'added', 'removed'), layer='All', rigLabel=None, sceneName=None)¶
The differences of the components as a JSON compatible dict, see
reportToMarkdown().- Parameters:
snapshots (Iterable[ComponentSnapshot] | None) – The components, defaults to all of them.
compareMode (CompareMode | None) – One of
compareModes(), defaults to the first.statuses (Iterable[str]) – Only differences with one of these statuses for a pair are included.
layer (str) – One of
LAYER_FILTERS.rigLabel (str | None) – Defaults to
rigLabel().sceneName (str | None) – Defaults to the open Maya scene.
- reportToMarkdown(data)¶
A
DiffSession.report()as Markdown, for bug reports.
Read-only snapshots of the data sources of a Hive component, the inputs of a definition diff.
A component’s data lives in several places which can drift apart:
Base - the shipped
.definitionfile for the component type.Definition - what Hive thinks the component is: the base merged with the definition cached on the component meta node. This repeats what
Component._setConstructDefinitiondoes when a component is loaded from the scene, without the save.Raw cache - the exact JSON stored in the
zooDefCache*attributes of the meta node.Scene - what is built in the scene, serialized from the guides, settings nodes and constraints.
Everything here is strictly read-only. Component instances are never created because loading a
component, or calling Component.serializeFromScene, can write the definition back to the meta node.
Snapshots are built from the meta nodes and the component registry only.
- class ComponentSnapshot(metaNode, name='', side='', componentType='', hasGuide=False, hasRig=False, sceneIsCache=False, errors=<factory>, base=None, definition=None, scene=None, rawBase=None, rawCache=None, rawScene=None, inheritedScenePaths=<factory>)¶
Bases:
objectThe data sources of one component at the time of the snapshot, as plain dicts. Built by
snapshotComponent(), never changed afterwards.- Parameters:
metaNode (Optional[HiveComponent]) – The component meta node.
- metaNode: HiveComponent | None¶
- inheritedScenePaths: Set[DefinitionPath]¶
- label()¶
- sources(mode='normalized')¶
Returns
(base, definition, scene)dicts for the mode, any of which can be None.- Parameters:
mode (str) –
MODE_NORMALIZEDorMODE_RAW.
- exists()¶
- iterSceneRigs()¶
Yields
(label, rigMeta)for every Hive rig in the scene, the label includes the namespace.
- rigLabel(rigMeta)¶
The rig name including its namespace, e.g.
"char:biped".
- configurationForRig(rigMeta)¶
Returns the hive configuration of a rig in the scene. Starting a session on an existing rig only reads the rig, it doesn’t create anything.
- iterRigComponentMetas(rigMeta)¶
Yields the component meta nodes of the rig.
- componentMetaFromNode(node)¶
Returns the component meta node for any node of a component, or None.
- selectedComponentMetas()¶
Returns the unique component meta nodes for the current Maya selection.
- rigMetaForComponentMeta(meta)¶
Returns the rig meta node which owns the component meta node, or None.
- snapshotComponent(meta, configuration)¶
Builds a
ComponentSnapshotfor a component meta node without modifying the scene.Each source is built on its own, so a failure ends up in
snapshot.errorsand leaves that source as None instead of raising.- Parameters:
meta (HiveComponent) – The component meta node.
configuration (Configuration) – The rig configuration, see
configurationForRig().
- serializeFull(definition)¶
Serializes a definition with every driver in full, rather than as a difference from the base, then canonicalizes it, see
canonicalize().
- canonicalize(data)¶
Removes attribute keys which only differ because of how a source was written, in place.
Attribute dicts (dicts with a
nameand aTypeorvalue) lose the Maya plug flags (ATTR_PLUG_FLAG_KEYS), keys set to None and lock/keyable/channelBox flags which are off. The scene serializers leave these out while the definition files write them explicitly.- Returns:
The same object.
- Return type:
- copyJson(data)¶
A deep copy of JSON data, several times faster than
copy.deepcopywhich matters for whole definitions.- Parameters:
data (Any) – Only dicts, lists, strings, numbers, bools and None, like the definition dicts the sources hold.
- normalize(data)¶
Puts a raw definition dict through
ComponentDefinitionso formatting differences (missing keys, hard coded guide defaults) don’t show as differences.
- readRawCache(meta, errors)¶
Decodes the definition cached on the meta node. Attributes with invalid JSON are reported in
errorsand skipped instead of failing the whole decode.- Parameters:
errors (List[str]) – List which receives error messages.
- serializeScene(meta, errors)¶
Serializes the component from the scene, read-only.
This is
Component.serializeFromScenewithout writing the result back to the meta node: the meta node layer serializers, plus the guide root constraints and the parent component.- Parameters:
errors (List[str]) – List which receives error messages.
- serializeGuideConnections(meta)¶
Read-only copy of
Component.serializeComponentGuideConnections. Returns None when there’s nothing to serialize, in which case Hive keeps the cached connections.
- parentComponentName(meta)¶
Returns
"name:side"of the parent component, or an empty string.
- guideNodeFromId(meta, guideId)¶
Returns the scene guide for a guide id of the component, or None.
- definitionOrigins(snap, tolerance=0.0001)¶
Where each Definition value came from: the base, the meta node cache, both, or Hive’s merge.
- class FrozenState(snapshots, label='')¶
Bases:
objectSnapshots kept from an earlier point in time, to compare against the current scene.
Snapshots are never changed once built, a refresh creates new ones, so the frozen ones are kept by reference.
- Parameters:
snapshots (Sequence[ComponentSnapshot]) – The snapshots to keep.
label (str) – Description, e.g. the time it was frozen.
- match(snap)¶
Returns the frozen snapshot of the same component, matched by meta node then by name and side.
- missingFrom(snapshots)¶
Labels of frozen components which no longer exist in the given snapshots.
N-way structural diff for Hive component definition dicts.
Pure python, no Maya imports, so it can be unit tested with plain python.
The engine takes N plain (JSON compatible) dicts, typically (base, definition, scene), and returns
a DiffNode tree. Each node holds one value per source and can report its status between any two
sources.
Lists of dicts are matched by identity rather than by index, because Hive lists are identity keyed
(guides by id, attributes by name, drivers by label). Without this, one inserted guide would
show every guide after it as changed.
root = buildDiffTree([base, definition, scene], ("Base", "Definition", "Scene"))
for node in iterDifferences(root, [(1, 2)]):
print(node.pathString(), node.status(1, 2))
- ignoreMissingIn(*labels)¶
Ignore mode which hides a node, and everything below it, when it’s missing from any of the sources with these labels, e.g.
ignoreMissingIn("Scene")for keys the scene intentionally doesn’t have.The node is hidden for every source pair, whatever the other sources hold, and this wins over the other ignore modes. Only sources in
buildDiffTree’svisibleSourcesare checked.- Parameters:
labels (str) – Source labels, see
buildDiffTree’slabels.- Raises:
ValueError – Without labels or for a label containing a comma.
- missingInLabels(mode)¶
The source labels of an
ignoreMissingIn()mode, None for any other mode.
- isIgnoreMode(mode)¶
True for
IGNORE_ALWAYS,IGNORE_ONE_SIDEDandignoreMissingIn()modes.
- class DiffStatus¶
Bases:
objectStatus of a node between two sources.
- SAME = 'same'¶
- CHANGED = 'changed'¶
- ADDED = 'added'¶
- REMOVED = 'removed'¶
- ABSENT = 'absent'¶
- DIFFERENT = ('changed', 'added', 'removed')¶
- class DiffNode(key, path, kind, values, tolerance=0.0001, ignoreMode=None, labels=(), suppressedBy=None, children=<factory>, parent=None, _statusCache=<factory>, _pathString=None)¶
Bases:
objectOne key in the diff tree with a value per source.
Nodes compare by identity, status results are cached per source pair.
- Parameters:
key (str) – Display key, e.g.
"guideLayer", a guide id or"[2]"for index matched list items.path (Tuple[str, ...]) – Keys from the root down to this node.
values (Tuple[Any, ...]) – One value per source,
MISSINGwhen the source doesn’t contain this key.tolerance (float) – Absolute tolerance used to compare numbers.
ignoreMode (str | None) – None,
IGNORE_ALWAYSorIGNORE_ONE_SIDED, from the first matching rule.labels (Tuple[str, ...]) – Display label per source, only set on the root.
suppressedBy (str | None) –
HIDDEN_MISSINGorHIDDEN_BY_RULEwhen the node is hidden for every pair because it’s missing from a source, seebuildDiffTree’ssuppressMissingandignoreMissingIn(). Set on the whole subtree.
- DICT = 'dict'¶
- LIST = 'list'¶
- VALUE = 'value'¶
- addChild(child)¶
- isLeaf()¶
- child(key)¶
Returns the direct child with the given key or None.
- find(*keys)¶
Returns the descendant at the given key path or None.
root.find("guideLayer", "dag", "root", "translate")
- pathString()¶
Dotted path from the root, e.g.
guideLayer.dag.root.translate.
- status(a, b)¶
Returns the
DiffStatusof this node between sourceaand sourceb.
- rawStatus(a, b)¶
Like
status()but without applying ignore rules or suppression, anywhere in the subtree.
- isSuppressed()¶
True when the node is hidden for every pair because it’s missing from a source, see
suppressedBy.
- isHiddenDifference(a, b)¶
True when this node differs between a and b but suppression or an ignore rule hides that.
Why a difference of this node between a and b is hidden,
HIDDEN_MISSINGorHIDDEN_BY_RULE, None when it isn’t hidden or there is no difference. Suppression wins.
- isIgnored(a, b)¶
True when suppression or an ignore rule makes this node compare as the same between source a and b.
- isRuleIgnored(a, b)¶
True when the
ignoreModeof this node makes it compare as the same between source a and b.
- hasDifferences(pairs)¶
Returns True when this node differs for any of the given source pairs.
- walk()¶
Depth first iterator over this node and all descendants.
- isNumber(value)¶
True for ints and floats, but not bools.
- valuesEqual(a, b, tolerance=0.0001)¶
Compares two JSON compatible values. Numbers (and lists of numbers at any depth, like vectors, matrices and curve cvs) are compared with an absolute tolerance. Bools are never equal to numbers.
- Parameters:
tolerance (float) – Absolute tolerance for numbers.
- buildDiffTree(sources, labels=None, rules=(('connections.constraints', 'type'),), tolerance=0.0001, ignore=(), suppressMissing=(), visibleSources=None)¶
Builds the diff tree for N sources.
- Parameters:
sources (Sequence[dict | None]) – The dicts to compare, None is treated as a missing source.
labels (Sequence[str] | None) – Display label per source, stored on the root node as
labels.rules (Iterable[Tuple[str, str | None]]) –
(path pattern, identity key)overrides for matching list items.tolerance (float) – Absolute tolerance used to compare numbers.
ignore (Iterable[Tuple[str, str]]) –
(path pattern, mode)rules, mode isIGNORE_ALWAYS,IGNORE_ONE_SIDEDor anignoreMissingIn()mode. Patterns are matched with fnmatch against the dotted path,*also matches dots. Paths are also matched with a leading dot, so*.keycovers a top levelkey. The first matchingIGNORE_ALWAYSorIGNORE_ONE_SIDEDrule wins, every matchingignoreMissingIn()rule applies.suppressMissing (Iterable[int]) – Indices of the sources where a missing value hides the node, and everything below it, for every pair whatever the other sources hold, e.g. keys the scene intentionally doesn’t have. Wins over the ignore rules, see
DiffNode.suppressedByandhiddenDifferenceCount().visibleSources (Iterable[int] | None) – Sources which are shown or compared,
suppressMissingandignoreMissingIn()rules only check these. None means every source.
- iterDifferences(root, pairs)¶
Yields the nodes which explain the differences for the given pairs.
An added or removed subtree is yielded once, not per descendant. For changed containers the changed descendants are yielded instead of the container.
- summarize(root, pairs)¶
Counts the differences per pair, using the same rules as
iterDifferences().
Number of nodes whose differences for any of the pairs are hidden by suppression or an ignore rule on the node itself. Like
iterDifferences(), a hidden subtree counts once.- Parameters:
reason (str | None) – Only count
HIDDEN_BY_RULEorHIDDEN_MISSING, None counts both. A node hidden for different reasons on different pairs counts for the first pair’s reason.
- ignorePatternForKey(key)¶
fnmatch pattern which matches a key anywhere in a path, with fnmatch special characters escaped.
- escapePattern(text)¶
Escapes fnmatch special characters so text only matches itself.
- differenceCount(root, pair)¶
Total number of differences between two sources.
- sourcePairs(count)¶
All ordered neighbour and end pairs for
countsources, e.g. 3 gives[(0, 1), (1, 2), (0, 2)].
- valueOrigin(node, base, merged, cache)¶
Where a merged value came from, for leaf nodes of a tree built from (at least) the three sources.
ORIGIN_BASE- equal to the base and not set by the cache.ORIGIN_CACHE- set by the cache and different from the base.ORIGIN_BOTH- the base and the cache hold the same value.ORIGIN_MERGED- equal to neither, the merge or hard coded defaults produced it.
User ignore rules for definition diffs.
Rules are (path pattern, mode) pairs, see definitiondiff.buildDiffTree(). Rules are kept in memory
unless an IgnoreRulesStorage is given.
rules = IgnoreRules()
rules.add("*.name", definitiondiff.IGNORE_ALWAYS)
tree = definitiondiff.buildDiffTree(sources, ignore=rules.rules())
- modeLabel(mode)¶
Short readable description of an ignore mode.
- isMissingInMode(mode)¶
True for a
definitiondiff.ignoreMissingIn()mode.
- class IgnoreRulesStorage¶
Bases:
ABCWhere
IgnoreRulespersists its rules, e.g. a preference file.- abstractmethod load()¶
Returns the stored
(pattern, mode)rules.
- abstractmethod save(rules)¶
Stores the rules.
- class IgnoreRules(rules=(), storage=None)¶
Bases:
objectA list of ignore rules. A pattern has at most one
MODESrule and onedefinitiondiff.ignoreMissingIn()rule.- Parameters:
rules (Iterable[Sequence[str]]) – Initial rules, replaced by the stored rules when a storage is given.
storage (Optional[IgnoreRulesStorage]) – Used to persist the rules, None keeps them in memory only.
- rules()¶
- add(pattern, mode)¶
Adds a rule. Returns True when the rules changed.
A
MODESrule replaces the pattern’s existingMODESrule. Adefinitiondiff.ignoreMissingIn()rule is merged into the pattern’s existing one, so adding “missing in Base” to “missing in Scene” gives “missing in Scene, Base”.- Parameters:
mode (str) –
definitiondiff.IGNORE_ALWAYS,definitiondiff.IGNORE_ONE_SIDEDor adefinitiondiff.ignoreMissingIn()mode.- Raises:
ValueError – When the mode is unknown.
- remove(pattern, mode=None)¶
Removes the rules with the pattern, only the one with the mode when given. Returns True when a rule was removed.
- clear()¶
- storage()¶
The storage used to persist the rules, or None.
- load()¶
Replaces the rules with the stored ones, rules with an unknown mode are skipped.
- save()¶
Text formatting of definition diff nodes and values, for views, reports and logs.
- formatValue(value, kind='value')¶
Short single line text for a value, cut to
MAX_DISPLAY_LENGTHcharacters.- Parameters:
kind (str) – The
DiffNodekind.
- prettyValue(value)¶
Multi line JSON text for a value.
- rowStatus(node, pairs)¶
Returns the most significant status of a node across pairs, or SAME.
- statusSymbols(node, pairs)¶
One
STATUS_SYMBOLSsymbol per pair, space separated.
- pairLabel(labels, pair, separator=' → ')¶
"Base → Definition"for a source pair.
- initials(label)¶
"Frozen Scene"->"FS".
- searchText(node, sources)¶
Lower case text a search should match: the path and, for values, the formatted values of the sources.
- differingLines(textA, textB)¶
Line numbers which differ between two multi line texts, e.g. two
prettyValue()results.
Short descriptions of definition keys, e.g. for tooltips or reports of a definition diff.
Node keys (guides, joints, inputs, outputs, controls) are read from the comments above the dataclass fields in
zoo.libs.hive.base.definition.definitionnodes, so they stay in step with the code. Layer, top level and
attribute keys are described here.
- fieldComments(cls)¶
Returns
{fieldName: comment}from the comment lines directly above each field of a dataclass. A leading underscore is removed from the name, matching the serialized key.