manager – High-level API — ncclient 0.5.3 documentation

# `manager` – High-level API

This module is a thin layer of abstraction around the library. It exposes all core functionality.

## Customizing

These attributes control what capabilties are exchanged with the NETCONF server and what operations are available through the `Manager` API.

`ncclient.manager.` `OPERATIONS` = {'cancel_commit': <class 'ncclient.operations.edit.CancelCommit'>, 'close_session': <class 'ncclient.operations.session.CloseSession'>, 'commit': <class 'ncclient.operations.edit.Commit'>, 'copy_config': <class 'ncclient.operations.edit.CopyConfig'>, 'create_subscription': <class 'ncclient.operations.subscribe.CreateSubscription'>, 'delete_config': <class 'ncclient.operations.edit.DeleteConfig'>, 'discard_changes': <class 'ncclient.operations.edit.DiscardChanges'>, 'dispatch': <class 'ncclient.operations.retrieve.Dispatch'>, 'edit_config': <class 'ncclient.operations.edit.EditConfig'>, 'get': <class 'ncclient.operations.retrieve.Get'>, 'get_config': <class 'ncclient.operations.retrieve.GetConfig'>, 'get_schema': <class 'ncclient.operations.retrieve.GetSchema'>, 'kill_session': <class 'ncclient.operations.session.KillSession'>, 'lock': <class 'ncclient.operations.lock.Lock'>, 'poweroff_machine': <class 'ncclient.operations.flowmon.PoweroffMachine'>, 'reboot_machine': <class 'ncclient.operations.flowmon.RebootMachine'>, 'unlock': <class 'ncclient.operations.lock.Unlock'>, 'validate': <class 'ncclient.operations.edit.Validate'>}

  Dictionary of base method names and corresponding `RPC` subclasses. It is used to lookup operations, e.g. get_config is mapped to `GetConfig`. It is thus possible to add additional operations to the `Manager` API.

## Factory functions

A `Manager` instance is created using a factory function.

`ncclient.manager.` `connect_ssh`(*args, **kwds)

  Initialize a `Manager` over the SSH transport. For documentation of arguments see `ncclient.transport.SSHSession.connect()`.

  The underlying `ncclient.transport.SSHSession` is created with `CAPABILITIES`. It is first instructed to `load_known_hosts()` and then all the provided arguments are passed directly to its implementation of `connect()`.

  To customize the `Manager`, add a manager_params dictionary in connection parameters (e.g. manager_params={‘timeout’: 60} for a bigger RPC timeout parameter)

  To invoke advanced vendor related operation add device_params={‘name’: ‘<vendor_alias>’} in connection parameters. For the time, ‘junos’ and ‘nexus’ are supported for Juniper and Cisco Nexus respectively.

  A custom device handler can be provided with device_params={‘handler’:<handler class>} in connection parameters.

`ncclient.manager.` `connect` = <function connect>

## Manager

Exposes an API for RPC operations as method calls. The return type of these methods depends on whether we are in `asynchronous or synchronous mode`.

In synchronous mode replies are awaited and the corresponding `RPCReply` object is returned. Depending on the `exception raising mode`, an rpc-error in the reply may be raised as an `RPCError` exception.

However in asynchronous mode, operations return immediately with the corresponding `RPC` object. Error handling and checking for whether a reply has been received must be dealt with manually. See the `RPC` documentation for details.

Note that in case of the `get()` and `get_config()` operations, the reply is an instance of `GetReply` which exposes the additional attributes `data` (as `Element`) and `data_xml` (as a string), which are of primary interest in case of these operations.

Presence of capabilities is verified to the extent possible, and you can expect a `MissingCapabilityError` if something is amiss. In case of transport-layer errors, e.g. unexpected session close, `TransportError` will be raised.

class `ncclient.manager.` `Manager`(session, device_handler, timeout=30)
  For details on the expected behavior of the operations and their

    parameters refer to RFC 4741.

  Manager instances are also context managers so you can use it like this:

      with manager.connect("host") as m:
          # do your stuff

  … or like this:

      m = manager.connect("host")
      try:
          # do your stuff
      finally:
          m.close_session()

  `HUGE_TREE_DEFAULT` = False

    Default for huge_tree support for XML parsing of RPC replies (defaults to False)

  `locked`(target)

    Returns a context manager for a lock on a datastore, where target is the name of the configuration datastore to lock, e.g.:

        with m.locked("running"):
            # do your stuff

    … instead of:

        m.lock("running")
        try:
            # do your stuff
        finally:
            m.unlock("running")

  `take_notification`(block=True, timeout=None)

    Attempt to retrieve one notification from the queue of received notifications.

    If block is True, the call will wait until a notification is received.

    If timeout is a number greater than 0, the call will wait that many seconds to receive a notification before timing out.

    If there is no notification available when block is False or when the timeout has elapse, None will be returned.

    Otherwise a `Notification` object will be returned.

  `async_mode`

    Specify whether operations are executed asynchronously (True) or synchronously (False) (the default).

  `timeout`

    Specify the timeout for synchronous RPC requests.

  `raise_mode`

    Specify which errors are raised as `RPCError` exceptions. Valid values are the constants defined in `RaiseMode`. The default value is `ALL`.

  `client_capabilities`

    `Capabilities` object representing the client’s capabilities.

  `server_capabilities`

    `Capabilities` object representing the server’s capabilities.

  `session_id`

    session-id assigned by the NETCONF server.

  `connected`

    Whether currently connected to the NETCONF server.

  `huge_tree`

    Whether huge_tree support for XML parsing of RPC replies is enabled (default=False) The default value is configurable through `HUGE_TREE_DEFAULT`

## Special kinds of parameters

Some parameters can take on different types to keep the interface simple.

### Source and target parameters

Where an method takes a source or target argument, usually a datastore name or URL is expected. The latter depends on the :url capability and on whether the specific URL scheme is supported. Either must be specified as a string. For example, “running”, “ftp://user:pass@host/config”.

If the source may be a config element, e.g. as allowed for the validate RPC, it can also be specified as an XML string or an `Element` object.

### Filter parameters

Where a method takes a filter argument, it can take on the following types:

- A tuple of (type, criteria).

  > Here type has to be one of “xpath” or “subtree”.

  > - For “xpath” the criteria should be a string containing the XPath expression.

  > - For “subtree” the criteria should be an XML string or an `Element` object containing the criteria.

- A <filter> element as an XML string or an `Element` object.