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 ofpyang.plugin.PyangPlugin
as argument.
See also
https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
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.definitions module¶
Meta information about YANG modeling language.
See also
-
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.
-
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 byPYANG_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
. Forplugindir
use env varPYANG_PLUGINPATH
. Forpath
option use the argument with the same name, orPYANG_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 containsnone
, 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
usageReturn type: pyang.Context
- path (str) – location of YANG modules.
(Join string with
-
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: keyword
andarg
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 specifiedReturn type:
-
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 detectedWarns: SyntaxWarning – if warnings detected Returns: (list of errors, list of warnings), if rescue
isTrue
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:
Module contents¶
Critical missing features for pyang
plugin users and authors.