Introduction

Yangson is a Python 3 library that offers programmers tools for working with configuration and other data modelled with the YANG data modelling language. Yangson supports only the JSON data encoding as defined in [RFC7951].

This documentation starts with a tutorial and then covers the entire public API of the library. Command-line tools that are included in the yangson package or in the project repository can also serve as examples of how the library is typically used.

Main Features

  • Support for YANG version 1.1 [RFC7950] and YANG library [RFC7895].

  • Instance data are internally represented as a persistent data structure. This makes the code thread-safe, and also allows for copying and updating data trees in a space-efficient way.

  • Parser and evaluator for XPath 1.0 expressions [XPath] and extensions defined for YANG 1.1 (new XPath functions, default namespace, and others).

  • Complete validation of instance data against the data model.

  • Support for RESTCONF data resources [RFC8040] (timestamps and entity-tags) and resource identifiers.

  • Support for NETCONF Access Control Module (NACM) [RFC6536].

Installation

The yangson package is available from PyPI and can be installed using the pip package manager as follows:

python -m pip install yangson

Naming of YANG Modules

In order be able to find the correct revision of each YANG module, Yangson requires that the names of disk files containing modules are of the form specified in [RFC7950], sec. 5.2:

module-or-submodule-name ['@' revision-date] '.yang'

For a (sub)module without a revision statement, the '@' revision-date part must be omitted, otherwise it may or may not be present. Either way, the module name and revision declared in the YANG library must match the corresponding statements in the (sub)module text itself.

Yangson is currently able to parse only the compact syntax of YANG files. Modules written in the alternative XML format (YIN) can be converted to the compact syntax by using the XSLT stylesheet yin2yang.xsl that can be obtained from the YIN Tools project.

Doctest Examples

This documentation uses doctest snippets rather heavily. For this purpose, each Python module uses a specific example data model and/or JSON instance document that have to be loaded first. Python statements that do so are also included as doctest snippets. Other obvious steps, such as necessary Python module imports, are not shown.

The example YANG modules, YANG library specifications and instance documents are included with Yangson documentation, in subdirectories of the examples directory. All the examples are also listed in Example Data Models and Instances.

Doctest snippets embedded in the documentation can also be used as a test suite. To run all Python code contained in those snippets and obtain a summary of the results per Python module, use the following command from the docs directory:

$ make doctest