# `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'>, 'rpc': <class 'ncclient.operations.rpc.GenericRPC'>, '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 6241.

  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)

  get_config(source, filter=None, with_defaults=None)

    get_config is mapped to `GetConfig`

  get_schema(identifier, version=None, format=None)

    get_schema is mapped to `GetSchema`

  edit_config(config, format='xml', target='candidate', default_operation=None, test_option=None, error_option=None)

    edit_config is mapped to `EditConfig`

  copy_config(source, target)

    copy_config is mapped to `CopyConfig`

  delete_config(target)

    delete_config is mapped to `DeleteConfig`

  dispatch(rpc_command, source=None, filter=None)

    dispatch is mapped to `Dispatch`

  lock(target='candidate')

    lock is mapped to `Lock`

  unlock(target='candidate')

    unlock is mapped to `Unlock`

  get(filter=None, with_defaults=None)

    get is mapped to `Get`

  close_session()

    close_session is mapped to `CloseSession`

  kill_session(session_id)

    kill_session is mapped to `KillSession`

  commit(confirmed=False, timeout=None, persist=None, persist_id=None)

    commit is mapped to `Commit`

  cancel_commit(persist_id=None)

    cancel_commit is mapped to `CancelCommit`

  discard_changes()

    discard_changes is mapped to `DiscardChanges`

  validate(source='candidate')

    validate is mapped to `Validate`

  create_subscription(filter=None, stream_name=None, start_time=None, stop_time=None)

    create_subscription is mapped to `CreateSubscription`

  reboot_machine()

    reboot_machine is mapped to `RebootMachine`

  poweroff_machine()

    poweroff_machine is mapped to `PoweroffMachine`

  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 or a tuple containing a dict of namespace mapping and the XPath expression.

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

- A list of spec

  > Here type has to be “subtree”.

  > - the spec should be a list containing multiple XML string or multiple `Element` objects.

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