Module ncs.maapi

MAAPI high level module.

This module defines a high level interface to the low-level maapi functions.

The 'Maapi' class encapsulates a MAAPI connection which upon constructing, sets up a connection towards ConfD/NCS. An example of setting up a transaction and manipulating data:

Copyimport ncs

m = ncs.maapi.Maapi()
m.start_user_session('admin', 'test_context')
t = m.start_write_trans()
t.get_elem('/model/data{one}/str')
t.set_elem('testing', '/model/data{one}/str')
t.apply()

Another way is to use context managers, which will handle all cleanup related to transactions, user sessions and socket connections:

Copywith ncs.maapi.Maapi() as m:
    with ncs.maapi.Session(m, 'admin', 'test_context'):
        with m.start_write_trans() as t:
            t.get_elem('/model/data{one}/str')
            t.set_elem('testing', '/model/data{one}/str')
            t.apply()

Finally, a really compact way of doing this:

Copywith ncs.maapi.single_write_trans('admin', 'test_context') as t:
    t.get_elem('/model/data{one}/str')
    t.set_elem('testing', '/model/data{one}/str')
    t.apply()

Functions

def connect(ip='127.0.0.1', port=4569, path=None)

Convenience function for connecting to ConfD/NCS.

The 'ip' and 'port' arguments are ignored if path is specified.

def single_read_trans(user, context, groups=[], db=2, ip='127.0.0.1', port=4569, path=None, src_ip='127.0.0.1', src_port=0, proto=1, vendor=None, product=None, version=None, client_id=None, load_schemas=True)

Context manager for a single READ transaction.

This function connects to ConfD/NCS, starts a user session and finally starts a new READ transaction.

Signature

def single_read_trans(user, context, groups=[], db=RUNNING, ip=, port=, path=None, src_ip=, src_port=0, proto=PROTO_TCP, vendor=None, product=None, version=None, client_id=_mk_client_id(), load_schemas=LOAD_SCHEMAS_LOAD):

For argument db see Maapi.start_trans(). For arguments user, context, groups, src_ip, src_port, proto, vendor, product, version and client_id see Maapi.start_user_session(). For arguments ip, port and path see connect(). For argument load_schemas see init().

Arguments:

• user - username (str)
• context - context for the session (str)
• groups - groups (list)
• db – database (int)
• ip – ConfD/NCS instance ip address (str)
• port – ConfD/NCS instance port (int)
• path – ConfD/NCS instance location path (str)
• src_ip - source ip address (str)
• src_port - source port (int)
• proto - protocol used by for connecting (i.e. ncs.PROTO_TCP)
• vendor – lock error information (str, optional)
• product – lock error information (str, optional)
• version – lock error information (str, optional)
• client_id – lock error information (str, optional)
• load_schemas - passed on to Maapi.init()

Returns:

• read transaction object (maapi.Transaction)

def single_write_trans(user, context, groups=[], db=2, ip='127.0.0.1', port=4569, path=None, src_ip='127.0.0.1', src_port=0, proto=1, vendor=None, product=None, version=None, client_id=None, load_schemas=True)

Context manager for a single READ/WRITE transaction.

This function connects to ConfD/NCS, starts a user session and finally starts a new READ/WRITE transaction.

Signature

def single_write_trans(user, context, groups=[], db=RUNNING, ip=, port=, path=None, src_ip=, src_port=0, proto=PROTO_TCP, vendor=None, product=None, version=None, client_id=_mk_client_id(), load_schemas=LOAD_SCHEMAS_LOAD):

For argument db see Maapi.start_trans(). For arguments user, context, groups, src_ip, src_port, proto, vendor, product, version and client_id see Maapi.start_user_session(). For arguments ip, port and path see connect(). For argument load_schemas see init().

Arguments:

• user - username (str)
• context - context for the session (str)
• groups - groups (list)
• db – database (int)
• ip – ConfD/NCS instance ip address (str)
• port – ConfD/NCS instance port (int)
• path – ConfD/NCS instance location path (str)
• src_ip - source ip address (str)
• src_port - source port (int)
• proto - protocol used by the client for connecting (int)
• vendor – lock error information (str, optional)
• product – lock error information (str, optional)
• version – lock error information (str, optional)
• client_id – lock error information (str, optional)
• load_schemas - passed on to Maapi.init()

Returns:

• write transaction object (maapi.Transaction)

Classes

class CommitParams (result=None)

Class representing NSO commit parameters.

Start with creating an empty instance of this class and set commit parameters using helper methods.

Methods

def commit_queue_async(self)

Set commit queue asynchronous mode of operation.

def commit_queue_atomic(self)

Make the commit queue item atomic.

def commit_queue_block_others(self)

Make the commit queue item block other commit queue items for this device.

def commit_queue_bypass(self)

Make the commit transactional even if commit queue is configured by default.

def commit_queue_error_option(self, error_option)

Set commit queue item behaviour on error.

def commit_queue_lock(self)

Make the commit queue item locked.

def commit_queue_non_atomic(self)

Make the commit queue item non-atomic.

def commit_queue_sync(self, timeout=None)

Set commit queue synchronous mode of operation.

def commit_queue_tag(self, tag)

Set commit-queue tag. Implicitly enabled commit queue commit.

def dry_run_cli(self)

Dry-run commit outformat CLI.

def dry_run_cli_c(self)

Dry-run commit outformat cli-c.

def dry_run_cli_c_reverse(self)

Dry-run commit outformat cli-c reverse.

def dry_run_native(self)

Dry-run commit outformat native.

def dry_run_native_reverse(self)

Dry-run commit outformat native reverse.

def dry_run_xml(self)

Dry-run commit outformat XML.

def get_commit_queue_error_option(self)

Get commit queue item behaviour on error.

def get_commit_queue_sync_timeout(self)

Get commit queue synchronous mode of operation timeout.

def get_commit_queue_tag(self)

Get commit-queue tag.

def get_dry_run_outformat(self)

Get dry-run outformat

def get_trace_id(self)

Get trace id.

def get_wait_devices(self)

Get the devices that the transaction should wait for a device lock for before entering the transactions critical section.

def is_commit_queue_async(self)

Get commit queue asynchronous mode of operation.

def is_commit_queue_atomic(self)

Check if the commit queue item should be atomic.

def is_commit_queue_block_others(self)

Check if the the commit queue item should block other commit queue items for this device.

def is_commit_queue_bypass(self)

Check if the commit is transactional even if commit queue is configured by default.

def is_commit_queue_lock(self)

Check if the commit queue item should be locked.

def is_commit_queue_non_atomic(self)

Check if the commit queue item should be non-atomic.

def is_commit_queue_sync(self)

Get commit queue synchronous mode of operation.

def is_dry_run(self)

Is dry-run enabled

def is_dry_run_reverse(self)

Is dry-run reverse enabled.

def is_no_deploy(self)

Should service create method be invoked or not.

def is_no_lsa(self)

Get no-lsa commit parameter.

def is_no_networking(self)

Check if the the configuration should only be written to CDB and not actually pushed to the device.

def is_no_out_of_sync_check(self)

Do not check device sync state before pushing the configuration change.

def is_no_overwrite(self)

Should a check be done that the parts of the device configuration to be modified are are up-to-date in CDB before pushing the configuration change to the device.

def is_no_revision_drop(self)

Get no-revision-drop commit parameter.

def is_reconcile_discard_non_service_config(self)

Get reconcile commit parameter with discard-non-service-config behaviour.

def is_reconcile_keep_non_service_config(self)

Get reconcile commit parameter with keep-non-service-config behaviour.

def is_use_lsa(self)

Get use-lsa commit parameter.

def no_deploy(self)

Do not invoke service's create method.

def no_lsa(self)

Set no-lsa commit parameter.

def no_networking(self)

Only write the configuration to CDB, do not actually push it to the device.

def no_out_of_sync_check(self)

Do not check device sync state before pushing the configuration change.

def no_overwrite(self)

Check that the parts of the device configuration to be modified are are up-to-date in CDB before pushing the configuration change to the device.

def no_revision_drop(self)

Set no-revision-drop commit parameter.

def reconcile_discard_non_service_config(self)

Set reconcile commit parameter with discard-non-service-config behaviour.

def reconcile_keep_non_service_config(self)

Set reconcile commit parameter with keep-non-service-config behaviour.

def set_dry_run_outformat(self, outformat)

Set dry-run outformat

def trace_id(self, trace_id)

Set trace id.

def use_lsa(self)

Set use-lsa commit parameter.

def wait_device(self, devices)

Wait for device locks before entering transaction critical state.

Arguments:

• devices – list or string which represents multiple device names or a device name respectively

class DryRunOutformat (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enumeration.

Ancestors

• enum.Enum

Class variables

var CLI

var CLI_C

var NATIVE

var XML

class Key (key, enum_cs_nodes=None)

Key string encapsulation and helper.

Initialize a key.

'key' may be a string or a list of strings.

class Maapi (ip='127.0.0.1', port=4569, path=None, load_schemas=True, msock=None)

Class encapsulating a MAAPI connection.

Create a Maapi instance.

Arguments:

• ip – ConfD/NCS instance ip address (str, optional)
• port – ConfD/NCS instance port (int, optional)
• path – ConfD/NCS instance location path (str, optional)
• msock – already connected MAAPI socket (socket.socket, optional) (ip, port and path ignored)
• load_schemas – whether schemas should be loaded/reloaded or not LOAD_SCHEMAS_LOAD = load schemas unless already loaded LOAD_SCHEMAS_SKIP = do not load schemas LOAD_SCHEMAS_RELOAD = force reload of schemas

The option LOAD_SCHEMAS_RELOAD can be used to force a reload of schemas, for example when connecting to a different ConfD/NSO node. Note that previously constructed maagic objects will be invalid and using them will lead to undefined behavior. Use this option with care, for example in a small script querying a list of running nodes.

Instance variables

var ip

Return address to connect to the IPC port

var path

Return path to connect to the IPC port

var port

Return port to connect to the IPC port

Methods

def apply_template(self, th, name, path, vars=None, flags=0)

Apply a template.

def attach(self, ctx_or_th, hashed_ns=0, usid=0)

Attach to an existing transaction.

'ctx_or_th' may be either a TransCtxRef or a transaction handle. The 'hashed_ns' argument is basically just there to save a call to set_namespace(). 'usid' is only used if 'ctx_or_th' is a transaction handle and if set to 0 the user session id that is the owner of the transaction will be used.

A new Transaction object will be returned.

def attach_init(self)

Attach to phase0 for CDB initialization and upgrade.

def authenticate(self, user, password, n, src_addr=None, src_port=None, context=None, prot=None)

Authenticate a user using the AAA configuration.

def close(self)

Ends session and closes socket.

def cursor(self, th, path, enum_cs_nodes=None, want_values=False, secondary_index=None, xpath_expr=None)

Get an iterable list cursor.

def destroy_cursor(self, mc)

Destroy cursor.

def detach(self, ctx_or_th)

Detach the underlying MAAPI socket.

def do_display(self, th, path)

Do display.

If the data model uses the YANG when or tailf:display-when statement, this function can be used to determine if the item given by the path should be displayed or not.

def exists(self, th, path)

Check if path exists.

def find_next(self, mc, type, inkeys)

Find next.

Update the cursor 'mc' with the key(s) for the list entry designated by the 'type' and 'inkeys' arguments. This function may be used to start a traversal from an arbitrary entry in a list. Keys for subsequent entries may be retrieved with the get_next() function. When no more keys are found, False is returned.

The strategy to use is defined by 'type':

Code Snippet

CopyFIND_NEXT - The keys for the first list entry after the one
            indicated by the 'inkeys' argument.
FIND_SAME_OR_NEXT - If the values in the 'inkeys' array completely
            identifies an actual existing list entry, the keys for
            this entry are requested. Otherwise the same logic as
            for FIND_NEXT above.

def get_next(self, mc)

Iterate and get the keys for the next entry in a list.

When no more keys are found, False is returned.

def get_objects(self, mc, n, nobj)

Get objects.

Read at most n values from each nobj lists starting at cursor mc. Returns a list of Value's.

def get_running_db_status(self)

Get running db status.

Gets the status of the running db. Returns True if consistent and False otherwise.

def load_schemas(self, use_maapi_socket=False)

Load the schemas to Python (using shared memory if enabled).

If 'use_maapi_socket' is set to True, the schmeas are loaded through the NSO daemon via a MAAPI socket.

def netconf_ssh_call_home(self, host, port=4334)

Initiate NETCONF SSH Call Home.

def netconf_ssh_call_home_opaque(self, host, opaque, port=4334)

Initiate NETCONF SSH Call Home w. opaque data.

def query_free_result(self, qrs)

Deallocate QueryResult memory.

Deallocated memory inside the QueryResult object 'qrs' returned from query_result(). It is not necessary to call this method as deallocation will be done when the Python library garbage collects the QueryResult object.

def report_progress(self, th, verbosity, msg, package=None)

Report transaction/action progress.

The 'package' argument is only available to NCS.

def report_progress_start(self, th, verbosity, msg, package=None)

Report transaction/action progress.

Used for calculation of the duration between two events. The method returns a _Progress object to be passed to report_progress_stop() once the event has finished.

The 'package' argument is only available to NCS.

def report_progress_stop(self, th, progress, annotation=None)

Report transaction/action progress.

Used for calculation of the duration between two events. The method takes a _Progress object returned from report_progress_start().

def report_service_progress(self, th, verbosity, msg, path, package=None)

Report transaction progress for a FASTMAP service.

def report_service_progress_start(self, th, verbosity, msg, path, package=None)

Report transaction progress for a FASTMAP service.

Used for calculation of the duration between two events. The method returns a _Progress object to be passed to report_service_progress_stop() once the event has finished.

def report_service_progress_stop(self, th, progress, annotation=None)

Report transaction progress for a FASTMAP service.

Used for calculation of the duration between two events. The method takes a _Progress object returned from report_service_progress_start().

def safe_create(self, th, path)

Safe version of create.

Create a new list entry, a presence container, or a leaf of type empty in the data tree - if it doesn't already exist.

def safe_delete(self, th, path)

Safe version of delete.

Delete an existing list entry, a presence container, or an optional leaf and all its children (if any) from the data tree. If it exists.

def safe_get_elem(self, th, path)

Safe version of get_elem.

Read the element at 'path', returns 'None' if it doesn't exist.

def safe_get_object(self, th, n, path)

Safe version of get_object.

This function reads at most 'n' values from the list entry or container specified by the 'path'. Returns 'None' the path is empty.

def set_elem(self, th, value, path)

Set the node at 'path' to 'value'.

If 'value' is not of type Value it will be converted to a string before calling set_elem2() under the hood.

def shared_apply_template(self, th, name, path, vars=None, flags=0)

FASTMAP version of apply_template().

def shared_copy_tree(self, th, from_path, to_path, flags=0)

FASTMAP version of copy_tree().

def shared_create(self, th, path, flags=0)

FASTMAP version of create().

def shared_insert(self, th, path, flags=0)

FASTMAP version of insert().

def shared_set_elem(self, th, value, path, flags=0)

FASTMAP version of set_elem().

If 'value' is not of type Value it will be converted to a string before calling shared_set_elem2() under the hood.

def shared_set_values(self, th, values, path, flags=0)

FASTMAP version of set_values().

def start_read_trans(self, db=2, usid=0, flags=0, vendor=None, product=None, version=None, client_id=None)

Start a read transaction.

For details see start_trans().

def start_trans(self, rw, db=2, usid=0, flags=0, vendor=None, product=None, version=None, client_id=None)

Start a transaction towards the 'db'.

This function starts a new a new transaction towards the given data store.

A new Transaction object will be returned.

def start_trans_in_trans(self, th, readwrite, usid=0)

Start a new transaction within a transaction.

This function makes it possible to start a transaction with another transaction as backend, instead of an actual data store. This can be useful if we want to make a set of related changes, and then either apply or discard them all based on some criterion, while other changes remain unaffected. The thandle identifies the backend transaction to use. If 'usid' is 0, the transaction will be started within the user session associated with the MAAPI socket, otherwise it will be started within the user session given by usid. If we call apply() on this "transaction in a transaction" object, the changes (if any) will be applied to the backend transaction. To discard the changes, call finish() without calling apply() first.

A new Transaction object will be returned.

def start_user_session(self, user, context, groups=[], src_ip='127.0.0.1', src_port=0, proto=1, vendor=None, product=None, version=None, client_id=None)

Start a new user session.

This method gives some resonable defaults.

def start_write_trans(self, db=2, usid=0, flags=0, vendor=None, product=None, version=None, client_id=None)

Start a write transaction.

For details see start_trans().

def write_service_log_entry(self, path, msg, type, level)

Write service log entries.

This function makes it possible to write service log entries from FASTMAP code.

class Session (maapi, user, context, groups=[], src_ip='127.0.0.1', src_port=0, proto=1, vendor=None, product=None, version=None, client_id=None)

Encapsulate a MAAPI user session.

Context manager for user sessions. This class makes it easy to use a single Maapi connection and switch user session along the way. For example:

Code Snippet

Copywith Maapi() as m:
    for user, context, device in devlist:
        with Session(m, user, context):
            with m.start_write_trans() as t:
                # ...
                # do something using the correct user session
                # ...
                t.apply()

Initialize a Session object.

'maapi' should be a Maapi object. For all other arguments see Maapi.start_user_session().

Methods

def close(self)

Close the user session.

class Transaction (maapi, th=None, rw=None, db=2, vendor=None, product=None, version=None, client_id=None)

Class that corresponds to a single MAAPI transaction.

Initialize a Transaction object.

When created one may access the maapi and th arguments like this:

Code Snippet

Copytrans = Transaction(mymaapi, th=myth)
trans.maapi # the Maapi object
trans.th # the transaction handle

An instance of this class is also a context manager:

Code Snippet

Copywith Transaction(mymaapi, th=myth) as trans:
    # do something here...

When exiting the with statement, finish() will be called.

If 'th' is left out (or None) a new transaction is started using the 'db' and 'rw' arguments, otherwise 'db' and 'rw' are ignored.

Arguments:

• maapi – a Maapi object
• th – a transaction handle or None
• db – database
• rw – mode (READ or READ_WRITE)
• vendor – lock error information (optional)
• product – lock error information (optional)
• version – lock error information (optional)
• client_id – lock error information (optional)

Methods

def abort(self)

Abort the transaction.

def apply(self, keep_open=True, flags=0)

Apply the transaction.

Validates, prepares and eventually commits or aborts the transaction. If the validation fails and the 'keep_open' argument is set to True (default), the transaction is left open and the developer can react upon the validation errors.

def apply_params(self, keep_open=True, params=None)

Apply the transaction and return the result in form of dict().

Validates, prepares and eventually commits or aborts the transaction. If the validation fails and the 'keep_open' argument is set to True (default), the transaction is left open and the developer can react upon the validation errors.

The 'params' argument represent commit parameters. See CommitParams class for available commit parameters.

The result is a dictionary representing the result of applying transaction. If dry-run was requested, then the resulting dictionary will have 'dry-run' key set along with the actual results. If commit through commit queue was requested, then the resulting dictionary will have 'commit-queue' key set. Otherwise the dictionary will be empty.

def commit(self)

Commit the transaction.

def finish(self)

Finish the transaction.

This will finish the transaction. If the transaction is implemented by an external database, this will invoke the finish() callback.

def get_params(self)

Get the current commit parameters for the transaction.

The result is an instance of the CommitParams class.

def prepare(self, flags=0)

Prepare transaction.

This function must be called as first part of two-phase commit. After this function has been called, commit() or abort() must be called.

It will invoke the prepare callback in all participants in the transaction. If all participants reply with OK, the second phase of the two-phase commit procedure is commenced.

def validate(self, unlock, forcevalidation=False)

Validate the transaction.

This function validates all data written in the transaction. This includes all data model constraints and all defined semantic validation, i.e. user programs that have registered functions under validation points.

If 'unlock' is True, the transaction is open for further editing even if validation succeeds. If 'unlock' is False and the function succeeds next function to be called MUST be prepare() or finish().

'unlock = True' can be used to implement a 'validate' command which can be given in the middle of an editing session. The first thing that happens is that a lock is set. If 'unlock' == False, the lock is released on success. The lock is always released on failure.

The 'forcevalidation' argument should normally be False. It has no effect for a transaction towards the running or startup data stores, validation is always performed. For a transaction towards the candidate data store, validation will not be done unless 'forcevalidation' is True. Avoiding this validation is preferable if we are going to commit the candidate to running, since otherwise the validation will be done twice. However if we are implementing a 'validate' command, we should give a True value for 'forcevalidation'.