Ndr module

Summary: The Ndr (Node Definition Registry) provides a node-domain-agmostic framework for registering and querying information about nodes.

Python bindings for libNdr

Classes:

`DiscoveryPlugin`	Interface for discovery plugins.
`DiscoveryPluginContext`	A context for discovery.
`DiscoveryPluginList`
`DiscoveryUri`	Struct for holding a URI and its resolved URI for a file discovered by NdrFsHelpersDiscoverFiles.
`Node`	Represents an abstract node.
`NodeDiscoveryResult`	Represents the raw data of a node, and some other bits of metadata, that were determined via a `NdrDiscoveryPlugin` .
`NodeList`
`Property`	Represents a property (input or output) that is part of a `NdrNode` instance.
`Registry`	The registry provides access to node information."Discovery Plugins"are responsible for finding the nodes that should be included in the registry.
`Version`
`VersionFilter`

class pxr.Ndr.DiscoveryPlugin

Interface for discovery plugins.

Discovery plugins, like the name implies, find nodes. Where the plugin searches is up to the plugin that implements this interface. Examples of discovery plugins could include plugins that look for nodes on the filesystem, another that finds nodes in a cloud service, and another that searches a local database. Multiple discovery plugins that search the filesystem in specific locations/ways could also be created. All discovery plugins are executed as soon as the registry is instantiated.

These plugins simply report back to the registry what nodes they found in a generic way. The registry doesn’t know much about the innards of the nodes yet, just that the nodes exist. Understanding the nodes is the responsibility of another set of plugins defined by the NdrParserPlugin interface.

Discovery plugins report back to the registry via NdrNodeDiscoveryResult s. These are small, lightweight classes that contain the information for a single node that was found during discovery. The discovery result only includes node information that can be gleaned pre-parse, so the data is fairly limited; to see exactly what’s included, and what is expected to be populated, see the documentation for NdrNodeDiscoveryResult .

How to Create a Discovery Plugin

There are three steps to creating a discovery plugin:

Implement the discovery plugin interface, NdrDiscoveryPlugin

Register your new plugin with the registry. The registration macro must be called in your plugin’s implementation file:

 NDR_REGISTER_DISCOVERY_PLUGIN(YOUR_DISCOVERY_PLUGIN_CLASS_NAME)

This macro is available in discoveryPlugin.h.

  - In the same folder as your plugin, create a ``plugInfo.json``
    file. This file must be formatted like so, substituting
    ``YOUR_LIBRARY_NAME`` , ``YOUR_CLASS_NAME`` , and
    ``YOUR_DISPLAY_NAME`` :

{
    "Plugins": [{
        "Type": "module",
        "Name": "YOUR_LIBRARY_NAME",
        "Root": "@PLUG_INFO_ROOT@",
        "LibraryPath": "@PLUG_INFO_LIBRARY_PATH@",
        "ResourcePath": "@PLUG_INFO_RESOURCE_PATH@",
        "Info": {
            "Types": {
                "YOUR_CLASS_NAME" : {
                    "bases": ["NdrDiscoveryPlugin"],
                    "displayName": "YOUR_DISPLAY_NAME"
                }
            }
        }
    }]
}

The NDR ships with one discovery plugin, the _NdrFilesystemDiscoveryPlugin . Take a look at NDR’s plugInfo.json file for example values for YOUR_LIBRARY_NAME , YOUR_CLASS_NAME , and YOUR_DISPLAY_NAME . If multiple discovery plugins exist in the same folder, you can continue adding additional plugins under the Types key in the JSON. More detailed information about the plugInfo.json format can be found in the documentation for the plug module (in pxr/base).

Methods:

`DiscoverNodes`(arg1)	Finds and returns all nodes that the implementing plugin should be aware of.
`GetSearchURIs`()	Gets the URIs that this plugin is searching for nodes in.

Attributes:

expired

True if this object has expired, False otherwise.

DiscoverNodes(arg1) → NdrNodeDiscoveryResultVec

Finds and returns all nodes that the implementing plugin should be aware of.

Parameters: arg1 (Context) –

GetSearchURIs() → NdrStringVec: Gets the URIs that this plugin is searching for nodes in.

property expired: True if this object has expired, False otherwise.

class pxr.Ndr.DiscoveryPluginContext

A context for discovery.

Discovery plugins can use this to get a limited set of non-local information without direct coupling between plugins.

Methods:

GetSourceType(discoveryType)

Returns the source type associated with the discovery type.

Attributes:

expired

True if this object has expired, False otherwise.

GetSourceType(discoveryType) → str

Returns the source type associated with the discovery type.

This may return an empty token if there is no such association.

Parameters: discoveryType (str) –

property expired: True if this object has expired, False otherwise.

class pxr.Ndr.DiscoveryPluginList

Methods:

`append`
`extend`

append()

extend()

class pxr.Ndr.DiscoveryUri

Struct for holding a URI and its resolved URI for a file discovered by NdrFsHelpersDiscoverFiles.

Attributes:

`resolvedUri`
`uri`

property resolvedUri

property uri

class pxr.Ndr.Node

Represents an abstract node. Describes information like the name of the node, what its inputs and outputs are, and any associated metadata.

In almost all cases, this class will not be used directly. More specialized nodes can be created that derive from NdrNode ; those specialized nodes can add their own domain-specific data and methods.

Methods:

`GetContext`()	Gets the context of the node.
`GetFamily`()	Gets the name of the family that the node belongs to.
`GetIdentifier`()	Return the identifier of the node.
`GetInfoString`()	Gets a string with basic information about this node.
`GetInput`(inputName)	Get an input property by name.
`GetInputNames`()	Get an ordered list of all the input names on this node.
`GetMetadata`()	All metadata that came from the parse process.
`GetName`()	Gets the name of the node.
`GetOutput`(outputName)	Get an output property by name.
`GetOutputNames`()	Get an ordered list of all the output names on this node.
`GetResolvedDefinitionURI`()	Gets the URI to the resource that provided this node's definition.
`GetResolvedImplementationURI`()	Gets the URI to the resource that provides this node's implementation.
`GetSourceCode`()	Returns the source code for this node.
`GetSourceType`()	Gets the type of source that this node originated from.
`GetVersion`()	Return the version of the node.
`IsValid`()	Whether or not this node is valid.

GetContext() → str

Gets the context of the node.

The context is the context that the node declares itself as having (or, if a particular node does not declare a context, it will be assigned a default context by the parser).

As a concrete example from the Sdr module, a shader with a specific source type may perform different duties vs. another shader with the same source type. For example, one shader with a source type of SdrArgsParser::SourceType may declare itself as having a context of’pattern’, while another shader of the same source type may say it is used for lighting, and thus has a context of’light’.

GetFamily() → str

Gets the name of the family that the node belongs to.

An empty token will be returned if the node does not belong to a family.

GetIdentifier() → NdrIdentifier: Return the identifier of the node.

GetInfoString() → str

Gets a string with basic information about this node.

Helpful for things like adding this node to a log.

GetInput(inputName) → Property

Get an input property by name.

nullptr is returned if an input with the given name does not exist.

Parameters: inputName (str) –

GetInputNames() → NdrTokenVec: Get an ordered list of all the input names on this node.

GetMetadata() → NdrTokenMap

All metadata that came from the parse process.

Specialized nodes may isolate values in the metadata (with possible manipulations and/or additional parsing) and expose those values in their API.

GetName() → str: Gets the name of the node.

GetOutput(outputName) → Property

Get an output property by name.

nullptr is returned if an output with the given name does not exist.

Parameters: outputName (str) –

GetOutputNames() → NdrTokenVec: Get an ordered list of all the output names on this node.

GetResolvedDefinitionURI() → str

Gets the URI to the resource that provided this node’s definition.

Could be a path to a file, or some other resource identifier. This URI should be fully resolved.

NdrNode::GetResolvedImplementationURI()

GetResolvedImplementationURI() → str

Gets the URI to the resource that provides this node’s implementation.

Could be a path to a file, or some other resource identifier. This URI should be fully resolved.

NdrNode::GetResolvedDefinitionURI()

GetSourceCode() → str

Returns the source code for this node.

This will be empty for most nodes. It will be non-empty only for the nodes that are constructed using NdrRegistry::GetNodeFromSourceCode() , in which case, the source code has not been parsed (or even compiled) yet.

An unparsed node with non-empty source-code but no properties is considered to be invalid. Once the node is parsed and the relevant properties and metadata are extracted from the source code, the node becomes valid.

NdrNode::IsValid

GetSourceType() → str

Gets the type of source that this node originated from.

Note that this is distinct from GetContext() , which is the type that the node declares itself as having.

As a concrete example from the Sdr module, several shader parsers exist and operate on different types of shaders. In this scenario, each distinct type of shader (OSL, Args, etc) is considered a different source, even though they are all shaders. In addition, the shaders under each source type may declare themselves as having a specific context (shaders can serve different roles). See GetContext() for more information on this.

GetVersion() → Version: Return the version of the node.

IsValid() → bool

Whether or not this node is valid.

A node that is valid indicates that the parser plugin was able to successfully parse the contents of this node.

Note that if a node is not valid, some data like its name, URI, source code etc. could still be available (data that was obtained during the discovery process). However, other data that must be gathered from the parsing process will NOT be available (eg, inputs and outputs).

class pxr.Ndr.NodeDiscoveryResult

Represents the raw data of a node, and some other bits of metadata, that were determined via a NdrDiscoveryPlugin .

Attributes:

`blindData`
`discoveryType`
`family`
`identifier`
`metadata`
`name`
`resolvedUri`
`sourceCode`
`sourceType`
`subIdentifier`
`uri`
`version`

property blindData

property discoveryType

property family

property identifier

property metadata

property name

property resolvedUri

property sourceCode

property sourceType

property subIdentifier

property uri

property version

class pxr.Ndr.NodeList

Methods:

`append`
`extend`

append()

extend()

class pxr.Ndr.Property

Represents a property (input or output) that is part of a NdrNode instance.

A property must have a name and type, but may also specify a host of additional metadata. Instances can also be queried to determine if another NdrProperty instance can be connected to it.

In almost all cases, this class will not be used directly. More specialized properties can be created that derive from NdrProperty ; those specialized properties can add their own domain-specific data and methods.

Methods:

`CanConnectTo`(other)	Determines if this property can be connected to the specified property.
`GetArraySize`()	Gets this property's array size.
`GetDefaultValue`()	Gets this property's default value associated with the type of the property.
`GetInfoString`()	Gets a string with basic information about this property.
`GetMetadata`()	All of the metadata that came from the parse process.
`GetName`()	Gets the name of the property.
`GetType`()	Gets the type of the property.
`GetTypeAsSdfType`()	Converts the property's type from `GetType()` into a `SdfValueTypeName` .
`IsArray`()	Whether this property's type is an array type.
`IsConnectable`()	Whether this property can be connected to other properties.
`IsDynamicArray`()	Whether this property's array type is dynamically-sized.
`IsOutput`()	Whether this property is an output.

CanConnectTo(other) → bool

Determines if this property can be connected to the specified property.

Parameters: other (Property) –

GetArraySize() → int

Gets this property’s array size.

If this property is a fixed-size array type, the array size is returned. In the case of a dynamically-sized array, this method returns the array size that the parser reports, and should not be relied upon to be accurate. A parser may report -1 for the array size, for example, to indicate a dynamically-sized array. For types that are not a fixed-size array or dynamic array, this returns 0.

GetDefaultValue() → VtValue

Gets this property’s default value associated with the type of the property.

GetType()

GetInfoString() → str

Gets a string with basic information about this property.

Helpful for things like adding this property to a log.

GetMetadata() → NdrTokenMap: All of the metadata that came from the parse process.

GetName() → str: Gets the name of the property.

GetType() → str: Gets the type of the property.

GetTypeAsSdfType() → NdrSdfTypeIndicator

Converts the property’s type from GetType() into a SdfValueTypeName .

Two scenarios can result: an exact mapping from property type to Sdf type, and an inexact mapping. In the first scenario, the first element in the pair will be the cleanly-mapped Sdf type, and the second element, a TfToken, will be empty. In the second scenario, the Sdf type will be set to Token to indicate an unclean mapping, and the second element will be set to the original type returned by GetType() .

GetDefaultValueAsSdfType

IsArray() → bool: Whether this property’s type is an array type.

IsConnectable() → bool

Whether this property can be connected to other properties.

If this returns true , connectability to a specific property can be tested via CanConnectTo() .

IsDynamicArray() → bool: Whether this property’s array type is dynamically-sized.

IsOutput() → bool: Whether this property is an output.

class pxr.Ndr.Registry

The registry provides access to node information.”Discovery Plugins”are responsible for finding the nodes that should be included in the registry.

Discovery plugins are found through the plugin system. If additional discovery plugins need to be specified, a client can pass them to SetExtraDiscoveryPlugins() .

When the registry is first told about the discovery plugins, the plugins will be asked to discover nodes. These plugins will generate NdrNodeDiscoveryResult instances, which only contain basic metadata. Once the client asks for information that would require the node’s contents to be parsed (eg, what its inputs and outputs are), the registry will begin the parsing process on an as-needed basis. See NdrNodeDiscoveryResult for the information that can be retrieved without triggering a parse.

Some methods in this module may allow for a”family”to be provided. A family is simply a generic grouping which is optional.

Methods:

`GetAllNodeSourceTypes`()	Get a sorted list of all node source types that may be present on the nodes in the registry.
`GetNodeByIdentifier`(identifier, ...)	Get the node with the specified `identifier` , and an optional `sourceTypePriority` list specifying the set of node SOURCE types (see `NdrNode::GetSourceType()` ) that should be searched.
`GetNodeByIdentifierAndType`(identifier, ...)	Get the node with the specified `identifier` and `sourceType` .
`GetNodeByName`(name, sourceTypePriority, filter)	Get the node with the specified name.
`GetNodeByNameAndType`(name, sourceType, filter)	A convenience wrapper around `GetNodeByName()` .
`GetNodeFromAsset`(asset, metadata, ...)	Parses the given `asset` , constructs a NdrNode from it and adds it to the registry.
`GetNodeFromSourceCode`(sourceCode, ...)	Parses the given `sourceCode` string, constructs a NdrNode from it and adds it to the registry.
`GetNodeIdentifiers`(family, filter)	Get the identifiers of all the nodes that the registry is aware of.
`GetNodeNames`(family)	Get the names of all the nodes that the registry is aware of.
`GetNodesByFamily`(family, filter)	Get all nodes from the registry, optionally restricted to the nodes that fall under a specified family and/or the default version.
`GetNodesByIdentifier`(identifier)	Get all nodes matching the specified identifier (multiple nodes of the same identifier, but different source types, may exist).
`GetNodesByName`(name, filter)	Get all nodes matching the specified name.
`GetSearchURIs`()	Get the locations where the registry is searching for nodes.
`SetExtraDiscoveryPlugins`(plugins)	Allows the client to set any additional discovery plugins that would otherwise NOT be found through the plugin system.
`SetExtraParserPlugins`(pluginTypes)	Allows the client to set any additional parser plugins that would otherwise NOT be found through the plugin system.

GetAllNodeSourceTypes() → NdrTokenVec

Get a sorted list of all node source types that may be present on the nodes in the registry.

Source types originate from the discovery process, but there is no guarantee that the discovered source types will also have a registered parser plugin. The actual supported source types here depend on the parsers that are available. Also note that some parser plugins may not advertise a source type.

See the documentation for NdrParserPlugin and NdrNode::GetSourceType() for more information.

GetNodeByIdentifier(identifier, sourceTypePriority) → Node

Get the node with the specified identifier , and an optional sourceTypePriority list specifying the set of node SOURCE types (see NdrNode::GetSourceType() ) that should be searched.

If no sourceTypePriority is specified, the first encountered node with the specified identifier will be returned (first is arbitrary) if found.

If a sourceTypePriority list is specified, then this will iterate through each source type and try to find a node matching by identifier. This is equivalent to calling NdrRegistry::GetNodeByIdentifierAndType for each source type until a node is found.

Nodes of the same identifier but different source type can exist in the registry. If a node’Foo’with source types’abc’and’xyz’exist in the registry, and you want to make sure the’abc’version is fetched before the’xyz’version, the priority list would be specified as [‘abc’,’xyz’]. If the’abc’version did not exist in the registry, then the’xyz’version would be returned.

Returns nullptr if a node matching the arguments can’t be found.

Parameters

identifier (NdrIdentifier) –
sourceTypePriority (NdrTokenVec) –

GetNodeByIdentifierAndType(identifier, sourceType) → Node

Get the node with the specified identifier and sourceType .

If there is no matching node for the sourceType, nullptr is returned.

Parameters

identifier (NdrIdentifier) –
sourceType (str) –

GetNodeByName(name, sourceTypePriority, filter) → Node

Get the node with the specified name.

An optional priority list specifies the set of node SOURCE types (

NdrNode::GetSourceType() ) that should be searched and in what order. Optionally, a filter can be specified to consider just the default versions of nodes matching name (the default) or all versions of the nodes.

GetNodeByIdentifier() .

Parameters

name (str) –
sourceTypePriority (NdrTokenVec) –
filter (VersionFilter) –

GetNodeByNameAndType(name, sourceType, filter) → Node

A convenience wrapper around GetNodeByName() .

Instead of providing a priority list, an exact type is specified, and nullptr is returned if a node with the exact identifier and type does not exist.

Optionally, a filter can be specified to consider just the default versions of nodes matching name (the default) or all versions of the nodes.

Parameters

name (str) –
sourceType (str) –
filter (VersionFilter) –

GetNodeFromAsset(asset, metadata, subIdentifier, sourceType) → Node

Parses the given asset , constructs a NdrNode from it and adds it to the registry.

Nodes created from an asset using this API can be looked up by the unique identifier and sourceType of the returned node, or by URI, which will be set to the unresolved asset path value.

metadata contains additional metadata needed for parsing and compiling the source code in the file pointed to by asset correctly. This metadata supplements the metadata available in the asset and overrides it in cases where there are key collisions.

subidentifier is optional, and it would be used to indicate a particular definition in the asset file if the asset contains multiple node definitions.

sourceType is optional, and it is only needed to indicate a particular type if the asset file is capable of representing a node definition of multiple source types.

Returns a valid node if the asset is parsed successfully using one of the registered parser plugins.

Parameters

asset (AssetPath) –
metadata (NdrTokenMap) –
subIdentifier (str) –
sourceType (str) –

GetNodeFromSourceCode(sourceCode, sourceType, metadata) → Node

Parses the given sourceCode string, constructs a NdrNode from it and adds it to the registry.

The parser to be used is determined by the specified sourceType .

Nodes created from source code using this API can be looked up by the unique identifier and sourceType of the returned node.

metadata contains additional metadata needed for parsing and compiling the source code correctly. This metadata supplements the metadata available in sourceCode and overrides it cases where there are key collisions.

Returns a valid node if the given source code is parsed successfully using the parser plugins that is registered for the specified sourceType .

Parameters

sourceCode (str) –
sourceType (str) –
metadata (NdrTokenMap) –

GetNodeIdentifiers(family, filter) → NdrIdentifierVec

Get the identifiers of all the nodes that the registry is aware of.

This will not run the parsing plugins on the nodes that have been discovered, so this method is relatively quick. Optionally, a”family”name can be specified to only get the identifiers of nodes that belong to that family and a filter can be specified to get just the default version (the default) or all versions of the node.

Parameters

family (str) –
filter (VersionFilter) –

GetNodeNames(family) → NdrStringVec

Get the names of all the nodes that the registry is aware of.

This will not run the parsing plugins on the nodes that have been discovered, so this method is relatively quick. Optionally, a”family”name can be specified to only get the names of nodes that belong to that family.

Parameters: family (str) –

GetNodesByFamily(family, filter) → NdrNodeConstPtrVec

Get all nodes from the registry, optionally restricted to the nodes that fall under a specified family and/or the default version.

Note that this will parse all nodes that the registry is aware of (unless a family is specified), so this may take some time to run the first time it is called.

Parameters

family (str) –
filter (VersionFilter) –

GetNodesByIdentifier(identifier) → NdrNodeConstPtrVec

Get all nodes matching the specified identifier (multiple nodes of the same identifier, but different source types, may exist).

If no nodes match the identifier, an empty vector is returned.

Parameters: identifier (NdrIdentifier) –

GetNodesByName(name, filter) → NdrNodeConstPtrVec

Get all nodes matching the specified name.

Only nodes matching the specified name will be parsed. Optionally, a filter can be specified to get just the default version (the default) or all versions of the node. If no nodes match an empty vector is returned.

Parameters

name (str) –
filter (VersionFilter) –

GetSearchURIs() → NdrStringVec

Get the locations where the registry is searching for nodes.

Depending on which discovery plugins were used, this may include non- filesystem paths.

SetExtraDiscoveryPlugins(plugins) → None

Allows the client to set any additional discovery plugins that would otherwise NOT be found through the plugin system.

Runs the discovery process for the specified plugins immediately.

Note that this method cannot be called after any nodes in the registry have been parsed (eg, through GetNode*()), otherwise an error will result.

Parameters: plugins (DiscoveryPluginRefPtrVec) –

SetExtraDiscoveryPlugins(pluginTypes) -> None

Allows the client to set any additional discovery plugins that would otherwise NOT be found through the plugin system.

Runs the discovery process for the specified plugins immediately.

Note that this method cannot be called after any nodes in the registry have been parsed (eg, through GetNode*()), otherwise an error will result.

Parameters: pluginTypes (list[Type]) –

SetExtraParserPlugins(pluginTypes) → None

Allows the client to set any additional parser plugins that would otherwise NOT be found through the plugin system.

Note that this method cannot be called after any nodes in the registry have been parsed (eg, through GetNode*()), otherwise an error will result.

Parameters: pluginTypes (list[Type]) –

class pxr.Ndr.Version

Methods:

`GetAsDefault`()	Return an equal version marked as default.
`GetMajor`()	Return the major version number or zero for an invalid version.
`GetMinor`()	Return the minor version number or zero for an invalid version.
`GetStringSuffix`()	Return the version as a identifier suffix.
`IsDefault`()	Return true iff this version is marked as default.

GetAsDefault() → Version

Return an equal version marked as default.

It’s permitted to mark an invalid version as the default.

GetMajor() → int: Return the major version number or zero for an invalid version.

GetMinor() → int: Return the minor version number or zero for an invalid version.

GetStringSuffix() → str: Return the version as a identifier suffix.

IsDefault() → bool: Return true iff this version is marked as default.

class pxr.Ndr.VersionFilter

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()

allValues = (Ndr.VersionFilterDefaultOnly, Ndr.VersionFilterAllVersions)