_ncs Module
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.
Submodules
_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
cs_node_cd
cs_node_cd(start, path) -> Union[CsNode, None]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
decrypt
When data is read over the CDB interface, the MAAPI interface or received in event notifications, the data for the builtin types 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
expr_op2str
Convert confd_expr_op value to a string.
Keyword arguments:
op -- confd_expr_op integer value
fatal
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
find_cs_node
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)
find_cs_node_child
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
find_cs_root
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
find_ns_type
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
get_leaf_list_type
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
get_nslist
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.
hash2str
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
hkeypath_dup
Duplicates a HKeypathRef object.
Keyword arguments:
hkeypath -- a HKeypathRef instance
hkeypath_dup_len
Duplicates the first len elements of hkeypath.
Keyword arguments:
hkeypath -- a HKeypathRef instance
len -- number of elements to include in the copy
hkp_prefix_tagmatch
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
hkp_tagmatch
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
init
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)
internal_connect
Internal function used by NCS Python VM.
list_filter_type2str
Convert confd_list_filter_type value to a string.
Keyword arguments:
type -- confd_list_filter_type integer value
max_object_size
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
mmap_schemas
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
next_object_node
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
ns2prefix
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
pp_kpath
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
pp_kpath_len
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
set_debug
Sets the debug level
Keyword arguments:
file -- (optional)
level -- (optional)
set_kill_child_on_parent_exit
Instruct the operating system to kill this process if the parent process exits.
str2hash
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
stream_connect
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)
xpath_pp_kpath
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
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
Members:
class AuthorizationInfo
This type represents the c-type struct confd_authorization_info.
AuthorizationInfo cannot be directly instantiated from Python.
Members:
class CsCase
This type represents the c-type struct confd_cs_case.
CsCase cannot be directly instantiated from Python.
Members:
class CsChoice
This type represents the c-type struct confd_cs_choice.
CsChoice cannot be directly instantiated from Python.
Members:
class CsNode
This type represents the c-type struct confd_cs_node.
CsNode cannot be directly instantiated from Python.
Members:
class CsNodeInfo
This type represents the c-type struct confd_cs_node_info.
CsNodeInfo cannot be directly instantiated from Python.
Members:
class CsType
This type represents the c-type struct confd_type.
CsType cannot be directly instantiated from Python.
Members:
bitbig_size(...)
Method:
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.
class DateTime
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)
Members:
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:
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:
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.
Members:
dup_len(...)
Method:
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.
Members:
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.
Members:
class SnmpVarbind
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.
Members:
class TagValue
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)
Members:
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.
Members:
None
class UserInfo
This type represents the c-type struct confd_user_info.
UserInfo cannot be directly instantiated from Python.
Members:
class Value
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:
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))
Members:
as_decimal64(...)
Method:
Returns a tuple containing (value, fraction_digits) if this value is of type C_DECIMAL64.
as_pyval(...)
Method:
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())
str2val(...)
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
val2str(...)
Method:
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
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
Members:
Predefined Values
Last updated
Was this helpful?