Schema Nodes

The schemanode module implements the following classes:

Doctest snippets for this module use the data model and instance document from Example 4.

>>> dm = DataModel.from_file('yang-library-ex4.json',
... mod_path=['.', '../../../yang-modules/ietf'])
>>> barsn = dm.get_schema_node('/example-4-a:bag/bar')
>>> fsn = dm.get_schema_node('/example-4-a:bag/foo')
>>> qsn = dm.get_data_node('/example-4-b:quux')
>>> rsn = dm.get_schema_node('/example-4-a:bag/opts/example-4-b:fooref/fooref')
>>> with open('example-data.json') as infile:
...     ri = json.load(infile)
>>> inst = dm.from_raw(ri)
class yangson.schemanode.Annotation(type: DataType, description: str)

An object of this class describes a metadata annotation [RFC7952].

Instance Attributes

type

Type of the annotation’s value.

description

Description string of the annotation.

class yangson.schemanode.SchemaNode

This class serves as the top-level abstract superclass for all schema node classes.

Instance Attributes

name

Name of the schema node.

>>> fsn.name
'foo'
ns

Namespace of the schema node, which is the name of the YANG module in which the node is defined.

>>> fsn.ns
'example-4-a'
parent

Parent schema node, if there is any.

>>> type(rsn.parent)
<class 'yangson.schemanode.CaseNode'>
>>> rsn.parent.name
'fooref'
>>> rsn.parent.ns
'example-4-b'
description

Description string for the schema node, or None if the schema node’s definition contains no description.

>>> dm.get_data_node('/example-4-a:bag').description
'Top-level container.'
>>> rsn.description is None
True
must

List of must expressions that are attached to the schema node. Each entry is a tuple consisting of an instance of the Expr class and the corresponding error message (or None if no error message is defined for the must expression). See sec. 7.5.3 in [RFC7950].

when

Optional when expression that makes the schema node conditional. The value is an instance of the Expr class or None if no when expression is defined for the schema node. See sec. 7.21.5 in [RFC7950].

val_count

An integer attribute that counts how many times the schema node been used for validating instances. This can be useful especially for coverage checks. The counter is initialized with a value of zero.

If a sequence of instances is validated, the attribute accumulates the counts for all of them. Validation counters for the entire schema can be reset to zero by using the method clear_val_counters() in the DataModel class.

Properties

qual_name

Qualified name of the schema node.

>>> fsn.qual_name
('foo', 'example-4-a')
config

This boolean property is True if the receiver represents configuration, and False otherwise.

>>> fsn.config
True
mandatory

This boolean property is True if the receiver is a mandatory node in the complete data tree (configuration & state data), and False otherwise.

>>> barsn.mandatory
True
mandatory_config

This boolean property is True if the receiver is a mandatory node in configuration data, and False otherwise.

>>> barsn.mandatory_config
False
status

This property gives the status of the schema node definition represented as a member of the NodeStatus enumeration.

>>> fsn.status
<NodeStatus.deprecated: 'x'>
>>> print(rsn.status)
current

Public Methods

delete() → None

Remove the receiver from the schema.

schema_root() → GroupNode

Return the root node of the receiver’s schema.

>>> rsn.schema_root().parent is None
True
content_type() → ContentType

Return receiver’s content type.

>>> rsn.content_type().name
'config'
data_parent() → InternalNode | None

Return the closest ancestor schema node that is also a data node, or None if there is no such schema node.

>>> bsn = rsn.data_parent()
>>> bsn.qual_name
('bag', 'example-4-a')
iname() → InstanceName

Return instance name corresponding to the receiver.

>>> bsn.iname()
'example-4-a:bag'
>>> fsn.iname()
'foo'
data_path() → DataPath

Return the receiver’s data path.

>>> fsn.data_path()
'/example-4-a:bag/foo'
>>> rsn.data_path()
'/example-4-a:bag/example-4-b:fooref'
state_roots() → List[DataPath]

Return a list of data paths of the roots of all state data subtrees that are descendant to the receiver. If the receiver itself is a state data node, then the returned list contains only its data path. An empty list is returned if the receiver has no descendant state data nodes.

>>> bsn.state_roots()
['/example-4-a:bag/bar']
from_raw(rval: RawValue, jptr: JSONPointer = '') → Value

Return a cooked value transformed from raw value rval as dictated by the receiver and its subtree in the schema. The jptr argument gives the JSON Pointer [RFC6901] of the instance node for the cooked value is intended (if known, otherwise the second argument needn’t be present).

This method raises NonexistentSchemaNode if rval contains a member that is not defined in the schema, and YangTypeError if a scalar value inside rval is of incorrect type.

>>> raw = {'baz': [None]}
>>> type(raw)
<class 'dict'>
>>> cooked = bsn.from_raw(raw, '/example-4-a:bag')
>>> cooked
{'baz': (None,)}
>>> type(cooked)
<class 'yangson.instvalue.ObjectValue'>
class yangson.schemanode.InternalNode

This is an abstract superclass for schema nodes that can have children in the schema tree. It is a subclass of SchemaNode.

Instance Attributes

children

The list of the schema node’s children.

>>> [c.name for c in bsn.children]
['foo', 'bar', 'opts']

Public Methods

get_child(name: YangIdentifier, ns: YangIdentifier = None) → SchemaNode | None

Return receiver’s child schema node whose name is name and namespace ns. If the ns argument is None (default), then the receiver’s namespace is used. None is returned if the child isn’t found.

>>> bsn.get_child('bar', 'example-4-a').qual_name
('bar', 'example-4-a')
get_schema_descendant(route: SchemaRoute) → SchemaNode | None

Return the descendant schema node identified by the schema route route, which is interpreted relative to the receiver. None is returned if the node is not found.

>>> bazsn = bsn.get_schema_descendant(
... [('opts','example-4-a'), ('a','example-4-a'), ('baz','example-4-a')])
>>> bazsn.qual_name
('baz', 'example-4-a')
get_data_child(name: YangIdentifier, ns: YangIdentifier = None) → DataNode | None

Return receiver’s data child whose name is name and namespace ns. If the ns argument is None (default), then the receiver’s namespace is used. None is returned if the data child is not found.

Unlike get_child(), this method finds the data node identified by name and ns also if it is separated from the receiver only by non-data nodes (i.e. choice and case nodes), as it is the case in the following example:

>>> bsn.get_data_child('baz', 'example-4-a').qual_name
('baz', 'example-4-a')
filter_children(ctype: ContentType = None) → List[SchemaNode]

Return the list of receiver’s children that are of the content type specified by the argument ctype. If the argument is None, then the returned list contains children of the same content type as the receiver. Children that are instances of either RpcActionNode or NotificationNode are always omitted.

>>> [c.name for c in bsn.filter_children(ContentType.config)]
['foo', 'opts']
>>> [c.name for c in bsn.filter_children(ContentType.nonconfig)]
['bar', 'opts']
data_children() → List[DataNode]

Return the list of receiver’s data children, i.e. descendant data nodes that are either direct children of the receiver, or that have no ancestor data nodes that are also descendants of the receiver. Child nodes that are instances of SchemaTreeNode (i.e. rpc, action, input, output or notification node) are not included. See also get_data_child().

>>> [c.name for c in bsn.data_children()]
['foo', 'bar', 'baz', 'fooref']
class yangson.schemanode.GroupNode

This class is a subclass of InternalNode. Its instances are used as anonymous groups of schema nodes contained in an augment or uses statement if this statement is conditional, i.e. has a when substatement.

class yangson.schemanode.SchemaTreeNode

This class is a subclass of GroupNode. Each instance represents the root node of a schema tree (main tree, RPC operation or action, input or output node, or notification).

Instance Attributes

annotations

Dictionary of annotations that are defined in the modules comprising the data model. The keys are qualified names of the annotations, and the values are objects of the Annotation class.

>>> list(dm.schema.annotations.keys())
[('origin', 'ietf-origin')]
>>> str(dm.schema.annotations[('origin', 'ietf-origin')].type)
'origin-ref(identityref)'
class yangson.schemanode.DataNode

This is an abstract superclass for all data nodes. It is a subclass of SchemaNode.

Instance Attributes

default_deny

Default deny attribute as defined by the NETCONF Access Control Model [RFC6536] and set using YANG extension statements nacm:default-deny-write or nacm:default-deny-all. Permitted values are defined by the DefaultDeny enumeration, the default is DefaultDeny.none.

>>> fsn.default_deny
<DefaultDeny.write: 2>

Public Methods

orphan_instance(rval: RawValue) → ObjectMember

Return an ObjectMember as an isolated instance of the receiver data node, i.e. one that has neither parent instance nor siblings. The rval argument provides the raw value to be cooked and used for the instance.

>>> obag = bsn.orphan_instance({'foo': 54, 'bar': True})
>>> obag.name
'example-4-a:bag'
>>> obag['foo'].value
54
>>> obag.parinst is None
True
>>> obag.siblings
{}
split_instance_route(route: InstanceRoute) → Tuple[InstanceRoute, InstanceRoute] | None

Split route into two InstanceRoutes. The first item of the returned tuple is the part up to the receiver, and the second item is the rest.

>>> irt = dm.parse_resource_id('/example-4-a:bag/foo')
>>> pre, post = bsn.split_instance_route(irt)
>>> str(pre)
'/example-4-a:bag'
>>> str(post)
'/foo'
class yangson.schemanode.TerminalNode

This is the abstract superclass for terminal nodes, i.e. schema nodes that have no children. It is a subclass of SchemaNode.

Instance Attributes

type

A DataType object specifying the type of the instance.

>>> type(rsn.type)
<class 'yangson.datatype.LeafrefType'>

Properties

default

Default value of the receiver or None if no default is applicable. Note that the default may also come from receiver’s type.

>>> qsn.default
[Decimal('2.7182')]
units

A string specifying units of receiver’s values or None if no units are specified. Note that units may also be specified in receiver’s type.

>>> fsn.units
'foondela'
class yangson.schemanode.ContainerNode

This class is a subclass of DataNode and InternalNode. Its instances represent YANG container nodes.

The method resolution order for this class is as follows:

ContainerNode ► DataNode ► InternalNode ► SchemaNode

Instance Attributes

presence

A boolean value specifying whether the instance is a container with presence.

>>> bsn.presence
True
class yangson.schemanode.SequenceNode

Abstract superclass for data nodes representing a sequence, i.e. list and leaf-list. It is a subclass of DataNode.

Instance Attributes

min_elements

An integer value specifying the minimum number of list or leaf-list entries set by the min-elements statement. The default is 0.

>>> qsn.min_elements
0
max_elements

An integer value specifying the maximum number of list or leaf-list entries set by the max-elements statement. The default value is None, which means that no maximum is specified.

>>> qsn.max_elements
2
user_ordered

A boolean value specifying whether the list or leaf-list entries are ordered by user. This attribute is set by the ordered-by statement. The value of False (default) means that the (leaf-)list is ordered by system, i.e. the server may rearrange the entries.

>>> qsn.user_ordered
True

Public Methods

entry_from_raw(rval: RawEntry, jptr: JSONPointer = '') → EntryValue

Return a cooked value of an array entry transformed from raw value rval as dictated by the receiver and/or its subtree in the schema. The jptr argument gives the JSON Pointer [RFC6901] of the entry for the cooked value is intended (if known, otherwise the second argument needn’t be present).

This method raises NonexistentSchemaNode if rval contains a member that is not defined in the schema, and YangTypeError if a scalar value inside rval is of incorrect type.

>>> qsn.entry_from_raw('2.7182')
Decimal('2.7182')
class yangson.schemanode.ListNode

This class is a subclass of SequenceNode and InternalNode. Its instances represent YANG list nodes.

The method resolution order for this class is as follows:

ListNode ► SequenceNode ► DataNode ► InternalNode ► SchemaNode

Instance Attributes

keys

List containing qualified names of all keys defined by the key statement.

unique

List of lists of XPath expressions parsed from one or more unique statements ([RFC7950], sec. 7.8.3). The expressions are used to select leaves in all entries of a list instance, and their combinations are then checked for uniqueness.

Public Methods

orphan_entry(rval: RawObject) → ArrayEntry

Return an ArrayEntry as an isolated entry of the receiver list, i.e. one that has neither parent instance nor sibling entries. The rval argument provides the raw value (object) to be cooked and used for the entry.

class yangson.schemanode.ChoiceNode(InternalNode)

This class is a subclass of InternalNode. Its instances represent YANG choice nodes.

Instance Attributes

default_case

Qualified name specifying the default case defined by the default substatement of choice. The value of None (default) means that no case is defined as default.

>>> osn = bsn.get_child('opts', 'example-4-a')
>>> osn.default_case
('a', 'example-4-a')
class yangson.schemanode.CaseNode

This class is a subclass of InternalNode. Its instances represent YANG case nodes.

A CaseNode is present in the internal schema tree even if it is defined as a “shorthand” case in a YANG module (see sec. 7.9.2 of [RFC7950]).

class yangson.schemanode.LeafNode

This class is a subclass of DataNode and TerminalNode. Its instances represent YANG leaf nodes.

The method resolution order for this class is as follows:

LeafNode ► DataNode ► TerminalNode ► SchemaNode

class yangson.schemanode.LeafListNode

This class is a subclass of SequenceNode and TerminalNode. Its instances represent YANG leaf-list nodes.

The method resolution order for this class is as follows:

LeafListNode ► SequenceNode ► DataNode ► TerminalNode ► SchemaNode

class yangson.schemanode.AnyContentNode

This class is an abstract superclass for both anydata and anyxml nodes. It is a subclass od DataNode.

class yangson.schemanode.AnydataNode

This class is a subclass of AnyContentNode. Its instances represent YANG anydata nodes.

class yangson.schemanode.AnyxmlNode

This class is a subclass of AnyContentNode. Its instances represent YANG anyxml nodes.

class yangson.schemanode.RpcActionNode

This class is a subclass of GroupNode. Its instances represent YANG rpc and action nodes.

class yangson.schemanode.InputNode

This class is a subclass of GroupNode. Its instances represent YANG input nodes containing input parameters of an rpc or action.

class yangson.schemanode.OutputNode

This class is a subclass of GroupNode. Its instances represent YANG output nodes containing output parameters of an rpc or action.

class yangson.schemanode.NotificationNode

This class is a subclass of GroupNode. Its instances represent YANG notification nodes.