Network Services Orchestrator (NSO) API v6.4

Latest

Package `_ncs`

NCS Python low level module.

This module and its submodules provide Python bindings for the C APIs, described by the confd_lib(3) man page.

The companion high level module, ncs, provides an abstraction layer on top of this module and may be easier to use.

Sub-modules

_ncs.cdb: Low level module for connecting to NCS built-in XML database (CDB) …
_ncs.dp: Low level callback module for connecting data providers to NCS …
_ncs.error: This module defines new NCS Python API exception classes …
_ncs.events: Low level module for subscribing to NCS event notifications …
_ncs.ha: Low level module for connecting to NCS HA subsystem …
_ncs.maapi: Low level module for connecting to NCS with a read/write interface inside transactions …

Functions

def cs_node_cd(start, path) ‑> Optional[CsNode]

Utility function which finds the resulting CsNode given an (optional) starting node and a (relative or absolute) string keypath.

Keyword arguments:

start – a CsNode instance or None
path – the path

def decrypt(ciphertext) ‑> str

When data is read over the CDB interface, the MAAPI interface or received in event notifications, the data for the builtin types tailf:des3-cbc-encrypted-string, tailf:aes-cfb-128-encrypted-string and tailf:aes-256-cfb-128-encrypted-string is encrypted. This function decrypts ciphertext and returns the clear text as a string.

Keyword arguments:

ciphertext – encrypted string

def expr_op2str(op) ‑> str

Convert confd_expr_op value to a string.

Keyword arguments:

op – confd_expr_op integer value

def fatal(str)

Utility function which formats a string, prints it to stderr and exits with exit code 1. This function will never return.

Keyword arguments:

str – a message string

def find_cs_node(hkeypath, len) ‑> Optional[CsNode]

Utility function which finds the CsNode corresponding to the len first elements of the hashed keypath. To make the search consider the full keypath leave out the len parameter.

Keyword arguments:

hkeypath – a HKeypathRef instance
len – number of elements to return (optional)

def find_cs_node_child(parent, xmltag) ‑> Optional[CsNode]

Utility function which finds the CsNode corresponding to the child node given as xmltag.

See confd_find_cs_node_child() in confd_lib_lib(3).

Keyword arguments:

parent – the parent CsNode
xmltag – the child node

def find_cs_root(ns) ‑> Optional[CsNode]

When schema information is available to the library, this function returns the root of the tree representaton of the namespace given by ns for the (first) toplevel node. For namespaces that are augmented into other namespaces such that they do not have a toplevel node, this function returns None - the nodes of such a namespace are found below the augment target node(s) in other tree(s).

Keyword arguments:

ns – the namespace id

def find_ns_type(nshash, name) ‑> Optional[CsType]

Returns a CsType type definition for the type named name, which is defined in the namespace identified by nshash, or None if the type could not be found. If nshash is 0, the type name will be looked up among the built-in types (i.e. the YANG built-in types, the types defined in the YANG "tailf-common" module, and the types defined in the "confd" and "xs" namespaces).

Keyword arguments:

nshash – a namespace hash or 0 (0 searches for built-in types)
name – the name of the type

def get_leaf_list_type(node) ‑> CsType

For a leaf-list node, the type() method in the CsNodeInfo identifies a "list type" for the leaf-list "itself". This function returns the type of the elements in the leaf-list, i.e. corresponding to the type substatement for the leaf-list in the YANG module.

Keyword arguments:

node – The CsNode of the leaf-list

def get_nslist() ‑> list

Provides a list of the namespaces known to the library as a list of five-tuples. Each tuple contains the the namespace hash (int), the prefix (string), the namespace uri (string), the revision (string), and the module name (string).

If schemas are not loaded an empty list will be returned.

def hash2str(hash) ‑> Optional[str]

Returns a string representing the node name given by hash, or None if the hash value is not found. Requires that schema information has been loaded from the NCS daemon into the library - otherwise it always returns None.

Keyword arguments:

hash – a hash

def hkeypath_dup(hkeypath) ‑> HKeypathRef

Duplicates a HKeypathRef object.

Keyword arguments:

hkeypath – a HKeypathRef instance

def hkeypath_dup_len(hkeypath, len) ‑> HKeypathRef

Duplicates the first len elements of hkeypath.

Keyword arguments:

hkeypath – a HKeypathRef instance
len – number of elements to include in the copy

def hkp_prefix_tagmatch(hkeypath, tags) ‑> bool

A simplified version of hkp_tagmatch() - it returns True if the tagpath matches a prefix of the hkeypath, i.e. it is equivalent to calling hkp_tagmatch() and checking if the return value includes CONFD_HKP_MATCH_TAGS.

Keyword arguments:

hkeypath – a HKeypathRef instance
tags – a list of XmlTag instances

def hkp_tagmatch(hkeypath, tags) ‑> int

When checking the hkeypaths that get passed into each iteration in e.g. cdb_diff_iterate() we can either explicitly check the paths, or use this function to do the job. The tags list (typically statically initialized) specifies a tagpath to match against the hkeypath. See cdb_diff_match().

Keyword arguments:

hkeypath – a HKeypathRef instance
tags – a list of XmlTag instances

def init(name, file, level)

Initializes the ConfD library. Must be called before any other NCS API functions are called. There should be no need to call this function directly. It is called internally when the Python module is loaded.

Keyword arguments:

name – e
file – (optional)
level – (optional)

def internal_connect(id, sock, ip, port, path)

Internal function used by NCS Python VM.

def list_filter_type2str(op) ‑> str

Convert confd_list_filter_type value to a string.

Keyword arguments:

type – confd_list_filter_type integer value

def max_object_size(object) ‑> int

Utility function which returns the maximum size (i.e. the needed length of the confd_value_t array) for an "object" retrieved by cdb_get_object(), maapi_get_object(), and corresponding multi-object functions.

Keyword arguments:

object – the CsNode

def mmap_schemas(filename)

If shared memory schema support has been enabled, this function will will map a shared memory segment into the current process address space and make it ready for use.

The filename can be obtained by using the get_schema_file_path() function

The filename argument specifies the pathname of the file that is used as backing store.

Keyword arguments:

filename – a filename string

def next_object_node(object, cur, value) ‑> Optional[CsNode]

Utility function to allow navigation of the confd_cs_node schema tree in parallel with the confd_value_t array populated by cdb_get_object(), maapi_get_object(), and corresponding multi-object functions.

The cur parameter is the CsNode for the current value, and the value parameter is the current value in the array. The function returns a CsNode for the next value in the array, or None when the complete object has been traversed. In the initial call for a given traversal, we must pass self.children() for the cur parameter - this always points to the CsNode for the first value in the array.

Keyword arguments:

object – CsNode of the list container node
cur – The CsNode of the current value
value – The current value

def ns2prefix(ns) ‑> Optional[str]

Returns a string giving the namespace prefix for the namespace ns, if the namespace is known to the library - otherwise it returns None.

Keyword arguments:

ns – a namespace hash

def pp_kpath(hkeypath) ‑> str

Utility function which pretty prints a string representation of the path hkeypath. This will use the NCS curly brace notation, i.e. "/servers/server{www}/ip". Requires that schema information is available to the library.

Keyword arguments:

hkeypath – a HKeypathRef instance

def pp_kpath_len(hkeypath, len) ‑> str

A variant of pp_kpath() that prints only the first len elements of hkeypath.

Keyword arguments:

hkeypath – a _lib.HKeypathRef instance
len – number of elements to print

def set_debug(level, file)

Sets the debug level

Keyword arguments:

file – (optional)
level – (optional)

def set_kill_child_on_parent_exit() ‑> bool

Instruct the operating system to kill this process if the parent process exits.

def str2hash(str) ‑> int

Returns the hash value representing the node name given by str, or 0 if the string is not found. Requires that schema information has been loaded from the NCS daemon into the library - otherwise it always returns 0.

Keyword arguments:

str – a name string

def stream_connect(sock, id, flags, ip, port, path)

Connects a stream socket to NCS.

Keyword arguments:

sock – a Python socket instance
id – id
flags – flags
ip – ip address - if sock family is AF_INET or AF_INET6 (optional)
port – port - if sock family is AF_INET or AF_INET6 (optional)
path – a filename - if sock family is AF_UNIX (optional)

def xpath_pp_kpath(hkeypath) ‑> str

Utility function which pretty prints a string representation of the path hkeypath. This will format the path as an XPath, i.e. "/servers/server[name="www"']/ip". Requires that schema information is available to the library.

Keyword arguments:

hkeypath – a HKeypathRef instance

Classes

class AttrValue (attr, v)

This type represents the c-type confd_attr_value_t.

The contructor for this type has the following signature:

AttrValue(attr, v) -> object

Keyword arguments:

attr – attribute type
v – value

Instance variables

var attr: attribute type (int)
var v: attribute value (Value)

class AuthorizationInfo (...)

This type represents the c-type struct confd_authorization_info.

AuthorizationInfo cannot be directly instantiated from Python.

Instance variables

var groups: authorization groups (list of strings)

class CsCase (...)

This type represents the c-type struct confd_cs_case.

CsCase cannot be directly instantiated from Python.

Methods

def choices() ‑> Optional[CsChoice]: Returns the CsCase choices.
def first() ‑> Optional[CsNode]: Returns the CsCase first.
def last() ‑> Optional[CsNode]: Returns the CsCase last.
def next() ‑> Optional[CsCase]: Returns the CsCase next.
def ns() ‑> int: Returns the CsCase ns hash.
def parent() ‑> Optional[CsChoice]: Returns the CsCase parent.
def tag() ‑> int: Returns the CsCase tag hash.

class CsChoice (...)

This type represents the c-type struct confd_cs_choice.

CsChoice cannot be directly instantiated from Python.

Methods

def case_parent() ‑> Optional[CsCase]: Returns the CsChoice case parent.
def cases() ‑> Optional[CsCase]: Returns the CsChoice cases.
def default_case() ‑> Optional[CsCase]: Returns the CsChoice default case.
def min_occurs() ‑> int: Returns the CsChoice minOccurs.
def next() ‑> Optional[CsChoice]: Returns the CsChoice next.
def ns() ‑> int: Returns the CsChoice ns hash.
def parent() ‑> Optional[CsNode]: Returns the CsChoice parent CsNode.
def tag() ‑> int: Returns the CsChoice tag hash.

class CsNode (...)

This type represents the c-type struct confd_cs_node.

CsNode cannot be directly instantiated from Python.

Methods

def children() ‑> Optional[CsNode]: Returns the children CsNode or None.
def has_display_when() ‑> bool: Returns True if CsNode has YANG 'tailf:display-when' statement(s).
def has_when() ‑> bool: Returns True if CsNode has YANG 'when' statement(s).
def info() ‑> CsNodeInfo: Returns a CsNodeInfo.
def is_action() ‑> bool: Returns True if CsNode is an action.
def is_action_param() ‑> bool: Returns True if CsNode is an action parameter.
def is_action_result() ‑> bool: Returns True if CsNode is an action result.
def is_case() ‑> bool: Returns True if CsNode is a case.
def is_container() ‑> bool: Returns True if CsNode is a container.
def is_empty_leaf() ‑> bool: Returns True if CsNode is a leaf which is empty.
def is_key() ‑> bool: Returns True if CsNode is a key.
def is_leaf() ‑> bool: Returns True if CsNode is a leaf.
def is_leaf_list() ‑> bool: Returns True if CsNode is a leaf-list.
def is_leafref() ‑> bool: Returns True if CsNode is a YANG 'leafref'.
def is_list() ‑> bool: Returns True if CsNode is a list.
def is_mount_point() ‑> bool: Returns True if CsNode is a mount point.
def is_non_empty_leaf() ‑> bool: Returns True if CsNode is a leaf which is not of type empty.
def is_notif() ‑> bool: Returns True if CsNode is a notification.
def is_np_container() ‑> bool: Returns True if CsNode is a non presence container.
def is_oper() ‑> bool: Returns True if CsNode is OPER data.
def is_p_container() ‑> bool: Returns True if CsNode is a presence container.
def is_writable() ‑> bool: Returns True if CsNode is writable.
def next() ‑> Optional[CsNode]: Returns the next CsNode or None.
def ns() ‑> int: Returns the namespace value.
def parent() ‑> Optional[CsNode]: Returns the parent CsNode or None.
def tag() ‑> int: Returns the tag value.

class CsNodeInfo (...)

This type represents the c-type struct confd_cs_node_info.

CsNodeInfo cannot be directly instantiated from Python.

Methods

def choices() ‑> Optional[CsChoice]: Returns CsNodeInfo choices.
def cmp() ‑> int: Returns CsNodeInfo cmp.
def defval() ‑> Value: Returns CsNodeInfo value.
def flags() ‑> int: Returns CsNodeInfo flags.
def keys() ‑> List[int]: Returns a list of hashed key values.
def max_occurs() ‑> int: Returns CsNodeInfo max_occurs.
def meta_data() ‑> Optional[Dict]: Returns CsNodeInfo meta_data.
def min_occurs() ‑> int: Returns CsNodeInfo min_occurs.
def shallow_type() ‑> int: Returns CsNodeInfo shallow_type.
def type() ‑> int: Returns CsNodeInfo type.

class CsType (...)

This type represents the c-type struct confd_type.

CsType cannot be directly instantiated from Python.

Methods

def bitbig_size() ‑> int: Returns the maximum size needed for the byte array for the BITBIG value when a YANG bits type has a highest position above 63. If this is not a BITBIG value or if the highest position is 63 or less, this function will return 0.
def defval() ‑> Optional[CsType]: Returns the CsType defval.
def parent() ‑> Optional[CsType]: Returns the CsType parent.

class DateTime (year, month, day, hour, min, sec, micro, timezone, timezone_minutes)

This type represents the c-type struct confd_datetime.

The contructor for this type has the following signature:

DateTime(year, month, day, hour, min, sec, micro, timezone, timezone_minutes) -> object

Keyword arguments:

year – the year (int)
month – the month (int)
day – the day (int)
hour – the hour (int)
min – minutes (int)
sec – seconds (int)
micro – micro seconds (int)
timezone – the timezone (int)
timezone_minutes – number of timezone_minutes (int)

Instance variables

var day: the day
var hour: the hour
var micro: micro seconds
var min: minutes
var month: the month
var sec: seconds
var timezone: timezone
var timezone_minutes: timezone minutes
var year: the year

class HKeypathRef (...)

This type represents the c-type confd_hkeypath_t.

HKeypathRef implements some sequence methods which enables indexing, iteration and length checking. There is also support for slicing, e.g:

Lets say the variable hkp is a valid hkeypath pointing to '/foo/bar{a}/baz' and we slice that object like this:

Code Snippet

Copynewhkp = hkp[1:]

In this case newhkp will be a new hkeypath pointing to '/foo/bar{a}'. Note that the last element must always be included, so trying to create a slice with hkp[1:2] will fail.

The example above could also be written using the dup_len() method:

Code Snippet

Copynewhkp = hkp.dup_len(3)

Retrieving an element of the HKeypathRef when the underlying Value is of type C_XMLTAG returns a XmlTag instance. In all other cases a tuple of Values is returned.

When receiving an HKeypathRef object as on argument in a callback method, the underlying object is only borrowed, so this particular instance is only valid inside that callback method. If one, for some reason, would like to keep the HKeypathRef object 'alive' for any longer than that, use dup() or dup_len() to get a copy of it. Slicing also creates a copy.

HKeypathRef cannot be directly instantiated from Python.

Methods

def dup() ‑> HKeypathRef

Duplicates this hkeypath.

def dup_len(len) ‑> HKeypathRef

Duplicates the first len elements of this hkeypath.

Keyword arguments:

len – number of elements to include in the copy

class ProgressLink (...)

This type represents the c-type struct confd_progress_link.

confdProgressLink cannot be directly instantiated from Python.

Instance variables

var span_id: span id (string)
var trace_id: trace id (string)

class QueryResult (...)

This type represents the c-type struct confd_query_result.

QueryResult implements some sequence methods which enables indexing, iteration and length checking.

QueryResult cannot be directly instantiated from Python.

Instance variables

var nelements: number of elements (int)
var nresults: number of results (int)
var offset: the offset (int)
var type: the query result type (int)

class SnmpVarbind (type, val, vartype, name, oid, cr)

This type represents the c-type struct confd_snmp_varbind.

The contructor for this type has the following signature:

SnmpVarbind(type, val, vartype, name, oid, cr) -> object

Keyword arguments:

type – SNMP_VARIABLE, SNMP_OID or SNMP_COL_ROW (int)
val – value (Value)
vartype – snmp type (optional)
name – mandatory if type is SNMP_VARIABLE (string)
oid – mandatory if type is SNMP_OID (list of integers)
cr – mandatory if type is SNMP_COL_ROW (described below)

When type is SNMP_COL_ROW the cr argument must be provided. It is built up as a 2-tuple like this: tuple(string, list(int)).

The first element of the 2-tuple is the column name.

The second element (the row index) is a list of up to 128 integers.

Instance variables

var type: the SnmpVarbind type

class TagValue (xmltag, v, tag, ns)

This type represents the c-type confd_tag_value_t.

In addition to the 'ns' and 'tag' attributes there is an additional attribute 'v' which containes the Value object.

The contructor for this type has the following signature:

TagValue(xmltag, v, tag, ns) -> object

There are two ways to contruct this object. The first one requires that both xmltag and v are specified. The second one requires that both tag and ns are specified.

Keyword arguments:

xmltag – a XmlTag instance (optional)
v – a Value instance (optional)
tag – tag hash (optional)
ns – namespace hash (optional)

Instance variables

var ns: namespace hash
var tag: tag hash

class TransCtxRef (...)

This type represents the c-type struct confd_trans_ctx.

Available attributes:

fd – worker socket (int)
th – transaction handle (int)
secondary_index – secondary index number for list traversal (int)
username – from user session (string) DEPRECATED, see uinfo
context – from user session (string) DEPRECATED, see uinfo
uinfo – user session (UserInfo)
accumulated – if the data provider is using the accumulate functionality this attribute will contain the first dp.TrItemRef object in the linked list, otherwise if will be None
traversal_id – unique id for the get_next* invocation

TransCtxRef cannot be directly instantiated from Python.

class UserInfo (...)

This type represents the c-type struct confd_user_info.

UserInfo cannot be directly instantiated from Python.

Instance variables

var actx_thandle: actx_thandle – action context transaction handle
var addr: addr – ip address (string)
var af: af – address family AF_INIT or AF_INET6 (int)
var clearpass: clearpass – password if available (string)
var context: context – the context (string)
var flags: flags – CONFD_USESS_FLAG_… (int)
var lmode: lmode – the lock we have (int)
var logintime: logintime – time for login (long)
var port: port – source port (int)
var proto: proto – protocol (int)
var snmp_v3_ctx: snmp_v3_ctx – SNMP context (string)
var username: username – the username (string)
var usid: usid – user session id (int)

class Value (init, type)

This type represents the c-type confd_value_t.

The contructor for this type has the following signature:

Value(init, type) -> object

If type is not provided it will be automatically set by inspecting the type of argument init according to this table:

Python type	Value type
bool	C_BOOL
int	C_INT32
long	C_INT64
float	C_DOUBLE
string	C_BUF

If any other type is provided for the init argument, the type will be set to C_BUF and the value will be the string representation of init.

For types C_XMLTAG, C_XMLBEGIN and C_XMLEND the init argument must be a 2-tuple which specifies the ns and tag values like this: (ns, tag).

For type C_IDENTITYREF the init argument must be a 2-tuple which specifies the ns and id values like this: (ns, id).

For types C_IPV4, C_IPV6, C_DATETIME, C_DATE, C_TIME, C_DURATION, C_OID, C_IPV4PREFIX and C_IPV6PREFIX, the init argument must be a string.

For type C_DECIMAL64 the init argument must be a string, or a 2-tuple which specifies value and fraction digits like this: (value, fraction_digits).

For type C_BINARY the init argument must be a bytes instance.

Keyword arguments:

init – the initial value
type – type (optional, see confd_types(3))

Methods

def as_decimal64() ‑> Tuple[int, int]

Returns a tuple containing (value, fraction_digits) if this value is of type C_DECIMAL64.

def as_list() ‑> list

Returns a list of Value's if this value is of type C_LIST.

def as_pyval() ‑> Any

Tries to convert a Value to a native Python type. If possible the object returned will be of the same type as used when initializing a Value object. If the type cannot be represented as something useful in Python a string will be returned. Note that not all Value types are supported.

E.g. assuming you already have a value object, this should be possible in most cases:

newvalue = Value(value.as_pyval(), value.confd_type())

def as_xmltag() ‑> XmlTag

Returns a XmlTag instance if this value is of type C_XMLTAG.

def confd_type() ‑> int

Returns the confd type.

def confd_type_str() ‑> str

Returns a string representation for the Value type.

def str2val(value, schema_type) ‑> Value

(class method)

Create and return a Value from a string. The schema_type argument must be either a 2-tuple with namespace and keypath, a CsNode instance or a CsType instance.

Keyword arguments:

value – string value
schema_type – either (ns, keypath), a CsNode or a CsType

def val2str(schema_type) ‑> str

Return a string representation of Value. The schema_type argument must be either a 2-tuple with namespace and keypath, a CsNode instance or a CsType instance.

Keyword arguments:

schema_type – either (ns, keypath), a CsNode or a CsType

class XmlTag (ns, tag)

This type represent the c-type struct xml_tag.

The contructor for this type has the following signature:

XmlTag(ns, tag) -> object

Keyword arguments:

ns – namespace hash
tag – tag hash

Instance variables

var ns: namespace hash value (unsigned int)
var tag: tag hash value (unsigned int)