Codec Services

Codec Service

YDK CodecService class provides API for encoding and decoding of payload strings in XML or JSON format to/from instances of Entity, which represent containers in the device supported YANG models.

class ydk.services.CodecService
encode(provider, entity, pretty=True, subtree=False)

Encodes Entity into payload string in XML or JSON format.

Parameters:
  • provider – CodecServiceProvider - Codec Provider instance.
  • entity – Entity instance or collection of Entity instances of type list or dict or EntityCollection.
  • pretty – bool flag, which specifies if resulting string must be in human readable way with indentation.
  • subtree – bool flag, which directs to encode entity to XML or JSON subtree. When set to true, the XmlSubtreeCodec or JsonSubtreeCodec is called accordingly.
Returns:

Type of returned object corresponds to the type of entity: single payload str, or list of str, or a dictionary of str.
Raises:

YServiceError, if error has occurred.
decode(provider, payload, subtree=False)

Decodes payload string in XML or JSON format to instances of Entity class.

Parameters:
  • provider – CodecServiceProvider - Codec Provider instance.
  • payload – str or collection of str Either a single encoded payload or a collection of payloads encapsulated to list or dict.
  • subtree – bool flag, which directs to encode entity to XML or JSON subtree. When set to true, the XmlSubtreeCodec or JsonSubtreeCodec is called accordingly.
Returns:

Type of returned object corresponds to the type of payload. It is either an instance of Entity, or a collection of Entity instances of type list or dict.
Raises:

YServiceError, if error has occurred.

XmlSubtreeCodec

class ydk.entity_utils.XmlSubtreeCodec

XmlSubtreeCodec class designed to provide encoding and decoding Python model API objects of type Entity to/from XML encoded string. Compared to CodecService the class does not validate encoded data for their types and values. It is also can be used to encode/decode non-top level entities.

XmlSubtreeCodec()

Constructs an instance of XmlSubtreeCodec class.

encode(entity, root_schema)

Performs encoding of Python model API objects of type Entity to well formatted XML encoded string.

Parameters:
  • entity – An instance of Entity class defined under a bundle.
  • root_schema – An instance of RootSchemaNode, which includes the model bundle.
Returns:

str, encoded well formatted multi-line XML payload string.
Raises:

YServiceError, if an error has occurred; usually appears when model is not present in the bundle.
decode(payload, entity)

Decodes the XML encoded string to produce corresponding instance of Entity.

Parameters:
  • payload – str, XML encoded string to be decoded.
  • entity – Entity, instance of shared pointer to expected top level Entity class.
Returns:

Entity, shared pointer to the decoded Entity.
Raises:

YInvalidArgumentError, if an error has occurred; usually appears when payload does not correspond to Entity model.

JsonSubtreeCodec

class ydk.entity_utils.JsonSubtreeCodec

JsonSubtreeCodec class designed to provide encoding and decoding Python model API objects of type Entity to/from JSON encoded string. Compared to CodecService the class does not validate encoded data for their types and values. It is also can be used to encode/decode non-top level entities.

JsonSubtreeCodec()

Constructs an instance of JsonSubtreeCodec class.

encode(entity, root_schema, pretty)

Performs encoding of Python model API objects of type Entity to JSON encoded string.

Parameters:
  • entity – An instance of Entity class defined under a bundle.
  • root_schema – An instance of RootSchemaNode, which includes the model bundle.
  • pretty – bool. If set to True, the function produces well formatted multi-line JSON string. If set to False - one line string.
Returns:

str, encoded JSON payload string.
Raises:

YServiceError, if an error has occurred; usually appears when model is not present in the bundle.
decode(payload, entity)

Decodes the JSON encoded string to produce corresponding instance of Entity.

Parameters:
  • payload – str, JSON encoded string to be decoded.
  • entity – Entity, instance of shared pointer to expected top level Entity class.
Returns:

Entity, shared pointer to the decoded Entity.
Raises:

YServiceError, if an error has occurred; usually appears when payload does not correspond to Entity model;

YInvalidArgumentError, if invalid JSON string is specified.
convert_string(json, pretty)

Utility function to convert JSON formatted string to a well formatted multiline indented string or to a single line string with no spaces.

Parameters:
  • json – str A JSON encoded string.
  • pretty – bool. If set to True, the function produces well formatted multiline JSON string. If set to False - one line string.
Returns:

str A JSON encoded string with specified formatting.
Raises:

YInvalidArgumentError if invalid JSON string is specified.

Example of JsonSubtreeCodec usage

In this example we use gNMIServiceProvider and CRUDService to get interface configuration from IOS XR device and then print it using JsonSubtreeCodec:

from ydk.services import CRUDService
from ydk.path import Repository
from ydk.gnmi.providers import gNMIServiceProvider

from ydk.models.cisco_ios_xr import Cisco_IOS_XR_ifmgr_cfg as ifmgr

# Create gNMI service provider
repo = Repository("/home/yan/ydk-gen/scripts/repository/10.30.110.84")
provider = gNMIServiceProvider(repo=repo,
                           address=10.20.30.40,
                           port=57400,
                           username='admin',
                           password='admin')
# Create CRUD service
crud = CRUDService()

# Build filter for interface configuration
ifc_filter = ifmgr.InterfaceConfigurations()
ifc = ifmgr.InterfaceConfigurations.InterfaceConfiguration()
ifc.active = '"act"'
ifc.interface_name = '"Loopback0"'
ifc_filter.interface_configuration.append(ifc)

# Read interface configuration
ifc_read = crud.read(provider, ifc_filter)

# Print interface configuration
if ifc_read:
    from ydk.entity_utils import JsonSubtreeCodec
    jcodec = JsonSubtreeCodec()
    payload = jcodec.encode(ifc_read, provider.get_session().get_root_schema(), True)
    print('CREATED INTERFACE CONFIGURATION:')
    print(payload)