Data Types

The datatype module defines the following classes:

Doctest snippets for this module use the data model from Example 5.

>>> dm = DataModel.from_file('yang-library-ex5.json',
... mod_path=[".", "../../../yang-modules/ietf"])
>>> binary_t = dm.get_data_node('/example-5-a:binary-leaf').type
>>> bits_t = dm.get_data_node('/example-5-a:bits-leaf').type
>>> boolean_t = dm.get_data_node('/example-5-a:boolean-leaf').type
>>> decimal64_t = dm.get_data_node('/example-5-a:decimal64-leaf').type
>>> empty_t = dm.get_data_node('/example-5-a:empty-leaf').type
>>> enumeration_t = dm.get_data_node('/example-5-a:enumeration-leaf').type
>>> identityref_t = dm.get_data_node('/example-5-a:identityref-leaf').type
>>> ii_t = dm.get_data_node('/example-5-a:instance-identifier-leaf').type
>>> leafref_t = dm.get_data_node('/example-5-a:leafref-leaf').type
>>> string_t = dm.get_data_node('/example-5-a:string-leaf').type
>>> union_t = dm.get_data_node('/example-5-a:union-leaf').type

YANG provides a selection of built-in data types, and also supports defining new types that are derived from existing types (built-in or derived) by specifying the base type and zero or more restrictions. See sec. 7.3 of [RFC7950] for details.

Yangson library resolves all derived types so that the base type corresponds to a Python class and restrictions are represented as values of appropriate instance attributes. Instances of subclasses of DataType typically appear as values of type attribute that is common to all TerminalNode instances.

class yangson.datatype.DataType(sctx: SchemaContext, name: YangIdentifier)

This is the abstract superclass for all classes representing YANG data types. The methods described in this class comprise common API for all type, some subclasses then introduce type-specific methods.

The constructor arguments sctx and name initialize values of the instance attributes sctx and name, respectively.

Instance Attributes

sctx

SchemaContext in which the type definition and restrictions are to be interpreted.

>>> string_t.sctx.text_mid
('example-5-a', '2018-10-25')
default

Default value of the type that may be defined by using the default statement inside a typedef.

>>> string_t.default
'xxy'
units

Units of the type’s values may be specified using the units statement inside a typedef.

>>> string_t.units is None
True
name

Name of the type if it is derived, otherwise None.

>>> string_t.name
'my-string'
>>> boolean_t.name is None
True
error_tag

This attribute records the error tag of the most recent type validation that failed.

error_message

This attribute records the error message specified for the most recent type validation that failed.

>>> 'abc' in string_t
False
>>> string_t.error_tag
'invalid-type'
>>> string_t.error_message
'xes and y: abc'

Public Methods

__contains__(val: ScalarValue) → bool

Return True if the argument val contains a valid value of the receiver type, otherwise return False.

This method enables the Python operators in and not in for use with types.

>>> "Dopey" in enumeration_t
True
>>> "SnowWhite" not in enumeration_t
True
__str__()

Return YANG name of the receiver type.

from_raw(raw: RawScalar) → ScalarValue | None

Return cooked value converted from a raw value raw according to the rules of the receiver data type, or None if the value in raw cannot be converted. The argument raw should follow the rules for JSON representation of scalar values as defined in [RFC7951]. Conformance to the receiving type isn’t guaranteed, as long as raw can be correctly converted.

>>> bits_t.from_raw('dos tres')
('dos', 'tres')
>>> bits_t.from_raw(0) is None
True
to_raw(val: ScalarValue) → RawScalar | None

Return a raw value converted from a cooked value val according to the rules of the receiver data type, or None if the conversion fails. This method is essentially inverse to from_raw(). The returned value can be encoded into JSON text by using the standard library functions json.dump() and json.dumps().

>>> bits_t.to_raw(('dos', 'tres'))
'dos tres'
>>> bits_t.to_raw((2,3)) is None
True
parse_value(text: str) → ScalarValue | None

Return a value of receiver’s type parsed from text, or None if parsing fails. The argument text should follow the rules for lexical representation of scalar values as defined in [RFC7950]. Conformance of the result to the receiving type isn’t guaranteed, as long as text can be correctly parsed.

>>> boolean_t.parse_value('true')
True
>>> boolean_t.parse_value('foo') is None
True
canonical_string(val: ScalarValue) → str | None

Return canonical string representation of val as defined for the receiver type, or None if val is not a valid value of the receiver type. See sec. 9.1 in [RFC7950] for more information about canonical forms.

This method is a partial inverse of parse_value(), the latter method is however able to parse non-canonical string forms, as shown in the next example.

>>> e = decimal64_t.parse_value("002.718281")
>>> e
Decimal('2.7183')
>>> decimal64_t.canonical_string(e)
'2.7183'
from_yang(text: str) → ScalarValue

Return a value of receiver’s type parsed from text that is expected to follow the rules for encoding the argument of the default statement in YANG. Conformance to the receiving type isn’t guaranteed, as long as text can be correctly converted.

This method raises InvalidArgument if the receiver type cannot properly parse text.

>>> sctx = SchemaContext(dm.schema_data, 'example-5-a', ('example-5-a', ''))
>>> identityref_t.from_yang('ex5b:derived-identity')
('derived-identity', 'example-5-b')
yang_type() → YangIdentifier

Return YANG name of the receiver.

>>> ii_t.yang_type()
'instance-identifier'
class yangson.datatype.EmptyType

This class is a subclass of DataType, and represents YANG empty type. It is implemented as a singleton class because the empty type cannot be restricted.

class yangson.datatype.BitsType

This class is a subclass of DataType, and represents YANG bits type.

A cooked value of this type is a tuple of strings – names of the bits that are set.

See documentation of from_raw() for an example.

Instance Attributes

bit

A dictionary that maps bit labels as defined by bit statements to bit positions. The position are either defined explicitly via the position statement, or assigned automatically – see sec. 9.7.4.2 in [RFC7950] for details.

>>> bits_t.bit['un']
1
class yangson.datatype.BooleanType

This class is a subclass of DataType, and represents YANG boolean type.

Both raw value and cooked value of this type is a Python bool value.

See documentation of parse_value() for an example.

class yangson.datatype.StringType

This class is a subclass of DataType, and represents YANG string type.

Instance Attributes

length

Specification of restrictions on the string length. It is a list of two-element lists specifying the lower and upper bounds for the string length. This attribute is compiled from the length type restriction.

>>> string_t.length.intervals
[[2, 4]]
>>> 'xxxxy' in string_t  # too long
False
patterns

List of regular expression patterns with which the type is restricted (those that do not have the invert-match modifier). Each entry is a compiled Python regular expression pattern.

>>> string_t.patterns[0].regex
re.compile('^(?:x*y)$(?!\\n\\Z)')
>>> 'xxxy' in string_t  # match
True
>>> 'xxyy' not in string_t  # no match
True
>>> 'xxy\n' not in string_t  # no match
True
invert_patterns

List of regular expression patterns that have the invert-match modifier, with which the type is restricted. Each entry is a compiled Python regular expression pattern.

class yangson.datatype.BinaryType

This class is a subclass of StringType, and represents YANG binary type. Raw values are strings obtained as output of the Base 64 encoding [RFC4648].

The cooked value is a Python bytes object.

>>> binary_t.to_raw(b'\xFF\xFE')
'//4='

Characters outside the encoding alphabet of Base 64 are not permitted in a raw value:

>>> binary_t.from_raw('u#Q==') is None
True
class yangson.datatype.EnumerationType

This class is a subclass of DataType, and represents YANG enumeration type.

Both raw value and cooked value of this type is a string, and it must must be one of the names specified in the type’s definition via the enum statement.

See documentation of contains() for an example.

Instance Attributes

enum

A dictionary that maps assigned enum names to their values as defined via the value statement or assigned automatically.

>>> enumeration_t.enum['Happy']
4
class yangson.datatype.LinkType

This is an abstract superclass for types that refer to other instance nodes (leafref and instance-identifier). It is a subclass of DataType.

Instance Attributes

require_instance

Boolean flag that indicates whether an instance node being referred to is required to exist. This property is set by the require-instance statement in type’s definition, see sec. 9.9.3 in [RFC7950].

>>> leafref_t.require_instance
True
class yangson.datatype.LeafrefType

This class is a subclass of LinkType, and represents YANG leafref type.

The type of a cooked value of this type is dictated by the type of the leaf node that is being referred to via the path statement.

Instance Attributes

path

An Expr object (XPath abstract syntax tree) parsed from the argument of the path statement.

>>> print(leafref_t.path.syntax_tree(), end='')
LocationPath
  Root
  Step (child ('string-leaf', 'example-5-a'))
ref_type

Type of the leaf being referred to.

>>> type(leafref_t.ref_type)
<class 'yangson.datatype.StringType'>
>>> 'abc' in leafref_t
False
class yangson.datatype.InstanceIdentifierType

This class is a subclass of LinkType, and represents YANG instance-identifier type.

A cooked value of this type is an InstanceRoute object parsed from a raw value as defined in sec. 9.13 of [RFC7950].

>>> type(ii_t.from_raw('/example-5-a:boolean-leaf'))
<class 'yangson.instance.InstanceRoute'>
>>> str(ii_t.from_raw('/example-5-a:boolean-leaf'))
'/example-5-a:boolean-leaf'
class yangson.datatype.IdentityrefType

This class is a subclass of DataType, and represents YANG identityref type.

A cooked value of this type is a qualified name of an identity defined by the data model.

See documentation of from_yang() for an example.

Instance Attributes

bases

List of qualified names of identities that are defined as bases for this type via the base statement.

>>> identityref_t.bases
[('base-identity', 'example-5-b')]
class yangson.datatype.NumericType

This class is an abstract superclass for all classes representing numeric types. It is subclass of DataType.

class yangson.datatype.Decimal64Type

This class is a subclass of NumericType, and represents YANG decimal64 type.

A cooked value of this type is a decimal.Decimal number.

See documentation of canonical_string() for an example.

class yangson.datatype.IntegralType

This class is an abstract superclass for all classes representing integral numbers. It is subclass of NumericType, and represents YANG integral type.

Python unlimited precision integers (int) are use for cooked values of all integral types, and restrictions on ranges are enforced explicitly for specific types such as uint32.

class yangson.datatype.Int8Type

This class is a subclass of IntegralType, and represents YANG int8 type.

class yangson.datatype.Int16Type

This class is a subclass of IntegralType, and represents YANG int16 type.

class yangson.datatype.Int32Type

This class is a subclass of IntegralType, and represents YANG int32 type.

class yangson.datatype.Int64Type

This class is a subclass of IntegralType, and represents YANG int64 type.

class yangson.datatype.Uint8Type

This class is a subclass of IntegralType, and represents YANG uint8 type.

class yangson.datatype.Uint16Type

This class is a subclass of IntegralType, and represents YANG uint16 type.

class yangson.datatype.Uint32Type

This class is a subclass of IntegralType, and represents YANG uint32 type.

class yangson.datatype.Uint64Type

This class is a subclass of IntegralType, and represents YANG uint64 type.

class yangson.datatype.UnionType

This class is a subclass of DataType, and represents YANG union type.

A cooked value of this type must be a valid cooked value of a union’s member type. Methods in this class are implemented so that they iterate through the member types in the order in which they are specified in the union type definition, and try the same method from their classes. If the method fails, next member class is tried in turn. The result of the first method implementation that succeeds is used as the result of the implementation in the UnionType. If the method does not succeed for any of the member classes, then the UnionType method fails, too.

>>> union_t.parse_value('true')  # result is bool, not string
True

Instance Attributes

types

List of member types.

>>> len(union_t.types)
2
>>> type(union_t.types[0])
<class 'yangson.datatype.StringType'>