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: NamedTuple

Which sources to show and compare.

label: str

Alias for field number 0

columns: Tuple[int, ...]

Alias for field number 1

pairs: List[Tuple[int, int]]

Alias for field number 2

layerAccepts(layer, key)

True when a top level definition key passes a LAYER_FILTERS filter.

Parameters:
  • layer (str) – One of LAYER_FILTERS.

  • key (str) – Top level key, e.g. node.path[0].

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.dag path, or None.

Parameters:

path (Sequence[str]) – DiffNode.path.

class DiffSession(ignoreRules=None, mode='normalized', tolerance=0.0001, hideIgnored=True, hideMissing=())

Bases: object

Snapshots 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_NORMALIZED or definitionsources.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, see hideMissing.

property tolerance: float

The absolute tolerance used to compare numbers, never negative.

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 by hiddenDifferenceCount().

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 when hideIgnored is 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.errors and returns None.

Parameters:

columns (Iterable[int] | None) – The sources shown or compared, e.g. CompareMode.columns. hideMissing and “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.

Parameters:

columns (Iterable[int] | None) – The sources shown, see tree(), defaults to the sources of the pairs.

hiddenDifferenceCount(snapshots, pairs, reason=None, columns=None)

Number of hidden differences over the components.

Parameters:
  • reason (str | None) – definitiondiff.HIDDEN_BY_RULE for ignore rules, definitiondiff.HIDDEN_MISSING for hideMissing, 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 .definition file 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._setConstructDefinition does 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: object

The 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
name: str = ''
side: str = ''
componentType: str = ''
hasGuide: bool = False
hasRig: bool = False
sceneIsCache: bool = False
errors: List[str]
base: dict | None = None
definition: dict | None = None
scene: dict | None = None
rawBase: dict | None = None
rawCache: dict | None = None
rawScene: dict | None = 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_NORMALIZED or MODE_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 ComponentSnapshot for a component meta node without modifying the scene.

Each source is built on its own, so a failure ends up in snapshot.errors and leaves that source as None instead of raising.

Parameters:
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 name and a Type or value) 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:

Any

copyJson(data)

A deep copy of JSON data, several times faster than copy.deepcopy which 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 ComponentDefinition so 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 errors and 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.serializeFromScene without 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.

Parameters:

tolerance (float) – Absolute tolerance used to compare numbers.

Returns:

{path: origin} for leaf keys of the normalized definition, see definitiondiff.valueOrigin.

Return type:

Dict[Tuple[str, …], str]

class FrozenState(snapshots, label='')

Bases: object

Snapshots 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’s visibleSources are checked.

Parameters:

labels (str) – Source labels, see buildDiffTree’s labels.

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_SIDED and ignoreMissingIn() modes.

class DiffStatus

Bases: object

Status 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: object

One 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.

  • kind (str) – DICT, LIST or VALUE.

  • values (Tuple[Any, ...]) – One value per source, MISSING when the source doesn’t contain this key.

  • tolerance (float) – Absolute tolerance used to compare numbers.

  • ignoreMode (str | None) – None, IGNORE_ALWAYS or IGNORE_ONE_SIDED, from the first matching rule.

  • labels (Tuple[str, ...]) – Display label per source, only set on the root.

  • suppressedBy (str | None) – HIDDEN_MISSING or HIDDEN_BY_RULE when the node is hidden for every pair because it’s missing from a source, see buildDiffTree’s suppressMissing and ignoreMissingIn(). Set on the whole subtree.

DICT = 'dict'
LIST = 'list'
VALUE = 'value'
key: str
path: Tuple[str, ...]
kind: str
values: Tuple[Any, ...]
tolerance: float = 0.0001
ignoreMode: str | None = None
labels: Tuple[str, ...] = ()
suppressedBy: str | None = None
children: List[DiffNode]
parent: DiffNode | None = None
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 DiffStatus of this node between source a and source b.

Parameters:
  • a (int) – Index of the first source.

  • b (int) – Index of the second source.

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.

hiddenReason(a, b)

Why a difference of this node between a and b is hidden, HIDDEN_MISSING or HIDDEN_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 ignoreMode of 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 is IGNORE_ALWAYS, IGNORE_ONE_SIDED or an ignoreMissingIn() mode. Patterns are matched with fnmatch against the dotted path, * also matches dots. Paths are also matched with a leading dot, so *.key covers a top level key. The first matching IGNORE_ALWAYS or IGNORE_ONE_SIDED rule wins, every matching ignoreMissingIn() 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.suppressedBy and hiddenDifferenceCount().

  • visibleSources (Iterable[int] | None) – Sources which are shown or compared, suppressMissing and ignoreMissingIn() 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().

Returns:

{(a, b): {"changed": int, "added": int, "removed": int}}

Return type:

Dict[Tuple[int, int], Dict[str, int]]

hiddenDifferenceCount(root, pairs, reason=None)

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_RULE or HIDDEN_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 count sources, 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.

Parameters:
  • base (int) – Source index of the base.

  • merged (int) – Source index of the merged result.

  • cache (int) – Source index of the cache.

Returns:

The origin or None for containers and values missing from the merged result.

Return type:

str | None

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: ABC

Where IgnoreRules persists 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: object

A list of ignore rules. A pattern has at most one MODES rule and one definitiondiff.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 MODES rule replaces the pattern’s existing MODES rule. A definitiondiff.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_SIDED or a definitiondiff.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_LENGTH characters.

Parameters:

kind (str) – The DiffNode kind.

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_SYMBOLS symbol per pair, space separated.

pairLabel(labels, pair, separator=' → ')

"Base → Definition" for a source pair.

Parameters:

labels (Sequence[str]) – Display label per source.

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.

Parameters:

sources (Iterable[int]) – Source indices whose values are included.

differingLines(textA, textB)

Line numbers which differ between two multi line texts, e.g. two prettyValue() results.

Returns:

(lines of textA, lines of textB).

Return type:

Tuple[Set[int], Set[int]]

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.

docForPath(path)

Returns a description for the last key of a definition path, or an empty string.

Parameters:

path (Sequence[str]) – Keys from the definition root, see DiffNode.path.