pyangext package

Submodules

pyangext.cli module

Extension for the pyang command line interface.

This module includes tools for augmenting PYANG_PLUGINPATH with the location of auto-discovered pyang plugins.

Pyang do not use the setuptools to register plugins. Instead it requires that the paths of all directories containing plugins to be present in the PYANG_PLUGINPATH environment variable.

pyangext reads all entry points under yang.plugins, detect the path to the file that contains the function registered, and builds a list with the containing directories.

In this sense, pyangext run command can be used as a bridge to the pyang command, but using the auto-discovery feature.

Note

Including non pyang-plugin python files alongside pyang-plugins python files (in the same directory) will result in a pyang CLI crash.

It is recommended that the function registered as entry-point follows the proprietary pyang plugin convention, or in other words:

  • it should be named pyang_plugin_init
  • it should call pyang.plugin.register_plugin with an instance of pyang.plugin.PyangPlugin as argument.

Command Line Interface

Usage:
pyangext [OPTIONS] COMMAND [ARGS]
Options:
-h, --help Show this message and exit.
-v, --version Show the version and exit.
--path Prints the auto discovered plugin path. Python packages that register an entry-point inside yang.plugins will be auto-detected.
--init, --export-path
 

Prints an export shell statement with the auto discovered plugin path.

This may be used by shell script to configure PYANG_PLUGINPATH environment variable.

Example:

eval $(pyangext --export-path)

--help Show this message and exit.
Commands:
call:invoke pyang script with plugin path adjusted using auto-discovery.
pyangext.cli.export_path(ctx, _, value)[source]

Prints an export shell statement with the auto discovered plugin path.

This may be used by shell script to configure PYANG_PLUGINPATH environment variable.

Example

eval $(pyangext --export-path)
pyangext.cli.print_path(ctx, _, value)[source]

Prints the auto discovered plugin path.

Packages that register an yang.plugins entry-point will be auto-detected.

pyangext.definitions module

Meta information about YANG modeling language.

pyangext.definitions.BUILT_IN_TYPES = ['binary', 'bits', 'boolean', 'decimal64', 'empty', 'enumeration', 'identityref', 'instance-identifier', 'int16', 'int32', 'int64', 'int8', 'leafref', 'string', 'uint16', 'uint32', 'uint64', 'uint8', 'union']

Types supported by default in the YANG language.

pyangext.definitions.DATA_STATEMENTS = ['container', 'leaf', 'leaf-list', 'list', 'anyxml']

Statements that denote a data node in the abstract tree.

pyangext.definitions.HEADER_STATEMENTS = ['organization', 'contact', 'revision', 'yang-version']

Descriptive statements used in the header of a module or submodule.

pyangext.definitions.ID_STATEMENTS = ['namespace', 'prefix']

Statements used to identify the module.

pyangext.definitions.PREFIX_SEPARATOR = ':'

Character used to denote prefix in YANG language.

pyangext.definitions.YANG_KEYWORDS = ['action', 'anydata', 'anyxml', 'argument', 'augment', 'base', 'belongs-to', 'bit', 'case', 'choice', 'config', 'contact', 'container', 'default', 'description', 'deviate', 'deviation', 'enum', 'error-app-tag', 'error-message', 'extension', 'feature', 'fraction-digits', 'grouping', 'identity', 'if-feature', 'import', 'include', 'input', 'key', 'leaf', 'leaf-list', 'length', 'list', 'mandatory', 'max-elements', 'min-elements', 'modifier', 'module', 'must', 'namespace', 'notification', 'ordered-by', 'organization', 'output', 'path', 'pattern', 'position', 'prefix', 'presence', 'range', 'reference', 'refine', 'require-instance', 'revision', 'revision-date', 'rpc', 'status', 'submodule', 'type', 'typedef', 'unique', 'units', 'uses', 'value', 'when', 'yang-version', 'yin-element']

YANG language Keywords.

pyangext.paths module

Automatically discover pyang plugins by reading setuptools entry-points.

pyangext.paths.discover()[source]

Discovers pyang plugins registered using setuptools entry points.

Collects the path for all python modules that have functions registered as an entry point inside yang.plugins group.

Ideally the function registered should be named pyang_plugin_init. It is also important to not include non-pyang-plugin python modules in the same directory of this module.

Returns:Array of paths that contains python modules with pyang plugins.
Reference:
https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
pyangext.paths.expanded()[source]

Combines the auto-discovered plugin paths with env PYANG_PLUGINPATH.

This function appends paths discovered using discover function to the list provided by PYANG_PLUGINPATH environment variable. It also removes duplicated entries from the resulting list.

Returns:Array of paths that contains python modules with pyang plugins.

pyangext.utils module

Utility belt for working with pyang and pyangext.

pyangext.utils.create_context(path='.', *options, **kwargs)[source]

Generates a pyang context.

The dict options and keyword arguments are similar to the command line options for pyang. For plugindir use env var PYANG_PLUGINPATH. For path option use the argument with the same name, or PYANG_MODPATH env var.

Parameters:
  • path (str) – location of YANG modules. (Join string with os.pathsep for multiple locations). Default is the current working dir.
  • *options – list of dicts, with options to be passed to context. See bellow.
  • **kwargs – similar to options but have a higher precedence. See bellow.
Keyword Arguments:
 
  • print_error_code (bool) – On errors, print the error code instead of the error message. Default False.
  • warnings (list) – If contains error, treat all warnings as errors, except any other error code in the list. If contains none, do not report any warning.
  • errors (list) – Treat each error code container as an error.
  • ignore_error_tags (list) – Ignore error code. (For a list of error codes see pyang --list-errors).
  • ignore_errors (bool) – Ignore all errors. Default False.
  • canonical (bool) – Validate the module(s) according to the canonical YANG order. Default False.
  • yang_canonical (bool) – Print YANG statements according to the canonical order. Default False.
  • yang_remove_unused_imports (bool) – Remove unused import statements when printing YANG. Default False.
  • trim_yin (bool) – In YIN input modules, trim whitespace in textual arguments. Default False.
  • lax_xpath_checks (bool) – Lax check of XPath expressions. Default False.
  • strict (bool) – Force strict YANG compliance. Default False.
  • max_line_len (int) – Maximum line length allowed. Disabled by default.
  • max_identifier_len (int) – Maximum identifier length allowed. Disabled by default.
  • features (list) – Features to support, default all. Format <modname>:[<feature>,]*.
  • keep_comments (bool) – Do not discard comments. Default True.
  • no_path_recurse (bool) – Do not recurse into directories in the yang path. Default False.
Returns:

Context object for pyang usage

Return type:

pyang.Context

pyangext.utils.compare_prefixed(arg1, arg2, prefix_sep=':', ignore_prefix=False)[source]

Compare 2 arguments : prefixed strings or tuple (prefix, string)

Parameters:
  • arg1 (str or tuple) – first argument
  • arg2 (str or tuple) – first argument
  • prefix_sep (str) – prefix string separator (default: ':')
Returns:

bool

pyangext.utils.qualify_str(arg, prefix_sep=':')[source]

Transform prefixed strings in tuple (prefix, string)

pyangext.utils.select(statements, keyword=None, arg=None, ignore_prefix=False)[source]

Given a list of statements filter by keyword, or argument or both.

Parameters:
  • statements (list of pyang.statements.Statement) – list of statements to be filtered.
  • keyword (str) – if specified the statements should have this keyword
  • arg (str) – if specified the statements should have this argument

keyword and arg can be also used as keyword arguments.

Returns:nodes that matches the conditions
Return type:list
pyangext.utils.find(parent, keyword=None, arg=None, ignore_prefix=False)[source]

Select all sub-statements by keyword, or argument or both.

See also

function select()

pyangext.utils.dump(node, file_obj=None, prev_indent='', indent_string=' ', ctx=None)[source]

Generate a string representation of an abstract syntax tree.

Parameters:
  • node (pyang.statements.Statement) – object to be represented
  • file_obj (file) – file-like object where the representation will be dumped. If nothing is passed, the method returns a string
Keyword Arguments:
 
  • prev_indent (str) – string to be added to the produced indentation
  • indent_string (str) – string to be used as indentation
  • ctx (pyang.Context) – context object used to generate string representation. If no context is passed, a dummy object is used with default configuration
Returns:

text content if file_obj is not specified

Return type:

str

pyangext.utils.check(ctx, rescue=False)[source]

Check existence of errors or warnings in context.

Code mostly borrowed from pyang script.

Parameters:ctx (pyang.Context) – pyang context to be checked.
Keyword Arguments:
 rescue (bool) – if True, no exception/warning will be raised.
Raises:SyntaxError – if errors detected
Warns:SyntaxWarning – if warnings detected
Returns:(list of errors, list of warnings), if rescue is True
Return type:tuple
pyangext.utils.parse(text, ctx=None)[source]

Parse a YANG statement into an Abstract Syntax subtree.

Parameters:
  • text (str) – file name for a YANG module or text
  • ctx (optional pyang.Context) – context used to validate text
Returns:

Abstract syntax subtree

Return type:

pyang.statements.Statement

Note

The parse function can be used to parse small amounts of text. If yout plan to parse an entire YANG (sub)module, please use instead:

ast = ctx.add_module(module_name, text_contet)

It is also well known that parse function cannot solve YANG deviations yet.

pyangext.utils.walk(parent, select=<function <lambda>>, apply=<function <lambda>>, key='substmts')[source]

Recursivelly find nodes and/or apply a function to them.

Parameters:
  • parent (pyang.statements.Statement) – root of the subtree were the search will take place.
  • select – optional callable that receives a node and returns a bool (True if the node matches the criteria)
  • apply – optional callable that are going to be applied to the node if it matches the criteria
  • key (str) – property where the children nodes are stored, default is substmts
Returns:

results collected from the apply function

Return type:

list

Module contents

Critical missing features for pyang plugin users and authors.