/docs/source/manager.rst

:mod:`~ncclient.manager` -- High-level API
==========================================

.. module:: ncclient.manager
    :synopsis: High-level API

.. data:: CAPABILITIES

    List of URI strings representing the client's capabilities. This is used during the initial
    capability exchange. Modify this if you need to announce some capability not already included.

.. data:: OPERATIONS
    
    Dictionary of method names and corresponding `~ncclient.operations.RPC` classes. `Manager` uses
    this to lookup operations, e.g. "get_config" is mapped to `ncclient.operations.GetConfig`. It
    is thus possible to add additional operations to the `Manager` API.

Factory functions
-----------------

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

.. function:: connect_ssh(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password, key_filename=None, allow_agent=True, look_for_keys=True])
    
    Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must
    be specified, all the other arguments are optional and depend on the kind of host key
    verification and user authentication you want to complete.
    
    For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts`
    file is automatically considered. The *unknown_host_cb* argument specifies a callback that will
    be invoked when the server's host key cannot be verified. See
    :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
    
    First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it
    will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an
    SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is
    :const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case
    an encrypted key file is encountered, the *password* argument will be used as a decryption
    passphrase.
    
    If ``publickey`` authentication fails and the *password* argument has been supplied,
    ``password`` / ``keyboard-interactive`` SSH authentication will be attempted.
    
    :param host: hostname or address on which to connect
    :type host: `string`
    
    :param port: port on which to connect
    :type port: `int`
    
    :param timeout: timeout for socket connect
    :type timeout: `int`
    
    :param unknown_host_cb: optional; callback that is invoked when host key verification fails
    :type unknown_host_cb: `function`
    
    :param username: username to authenticate with, if not specified the username of the logged-in
                       user is used
    :type username: `string`
    
    :param password: password for ``password`` authentication or passphrase for decrypting
                       private key files
    :type password: `string`
    
    :param key_filename: location of a private key file on the file system
    :type key_filename: `string`
    
    :param allow_agent: whether to try connecting to SSH agent for keys
    :type allow_agent: `bool`
    
    :param look_for_keys: whether to look in usual locations for keys
    :type look_for_keys: `bool`
    
    :raises: :exc:`~ncclient.transport.SSHUnknownHostError`
    :raises: :exc:`~ncclient.transport.AuthenticationError`
    
    :rtype: `Manager`
    
.. function:: connect()

    Same as :func:`connect_ssh`, since SSH is the default (and currently, the
    only) transport.

Manager
-------

Exposes an API for RPC operations as method calls. The return type of these methods depends on
whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`.

In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object
is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`,
an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.

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

Note that in case of the *get* and *get-config* operations, the reply is an instance of
`~ncclient.operations.GetReply` which exposes the additional attributes
:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
:attr:`~ncclient.operations.GetReply.data_xml` (as `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
:exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer
errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised.

.. class:: Manager
    
    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()
    
    .. method:: get_config(source[, filter=None])
        
        Retrieve all or part of a specified configuration.
        
        :param source: name of the configuration datastore being queried
        :type source: `string`
        
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
        :type filter: :ref:`filter_params`
    
    .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
        
        Loads all or part of a specified configuration to the specified target configuration.
        
        The ``"rollback-on-error"`` *error_option* depends on the ``:rollback-on-error`` capability.
        
        :param target: name of the configuration datastore being edited
        :type target: `string`
        
        :param config: configuration (must be rooted in *<config> .. </config>*)
        :type config: `string` or `~xml.etree.ElementTree.Element`
        
        :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
        :type default_operation: `string`
        
        :param test_option: one of { ``"test_then_set"``, ``"set"`` }
        :type test_option: `string`
        
        :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
        :type error_option: `string`
    
    .. method:: copy_config(source, target)
        
        Create or replace an entire configuration datastore with the contents of another complete
        configuration datastore. 
        
        :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
        :type source: :ref:`srctarget_params`
        
        :param target: configuration datastore to use as the destination of the copy operation
        :type target: :ref:`srctarget_params`
    
    .. method:: delete_config(target)
        
        Delete a configuration datastore.
        
        :param target: name or URL of configuration datastore to delete
        :type: :ref:`srctarget_params`
    
    .. method:: lock(target)
        
        Allows the client to lock the configuration system of a device.
        
        :param target: name of the configuration datastore to lock
        :type target: `string`
        
    .. method:: unlock(target)
    
        Release a configuration lock, previously obtained with the
        :meth:`~ncclient.manager.Manager.lock` operation.
        
        :param target: name of the configuration datastore to unlock
        :type target: `string`
    
    .. method:: locked(target)
        
        Returns a context manager for a lock on a datastore, e.g.::
        
            with m.locked("running"):
                # do your stuff

        ... instead of::
        
            m.lock("running")
            try:
                # do your stuff
            finally:
                m.unlock("running")
        
        :param target: name of configuration datastore to lock
        :type target: `string`
        
        :rtype: `~ncclient.operations.LockContext`
    
    .. method:: get([filter=None])
        
        Retrieve running configuration and device state information.
        
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
        :type filter: :ref:`filter_params`
    
    .. method:: close_session()
        
        Request graceful termination of the NETCONF session, and also close the transport.
    
    .. method:: kill_session(session_id)
        
        Force the termination of a NETCONF session (not the current one!).
        
        :param session_id: session identifier of the NETCONF session to be terminated
        :type session_id: `string`
    
    .. method:: commit([confirmed=False, timeout=None])
    
        Commit the candidate configuration as the device's new current configuration. Depends on the
        *:candidate* capability.
        
        A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
        followup commit within the *timeout* interval. If no timeout is specified the confirm
        timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
        parameter but this is not required. Depends on the *:confirmed-commit* capability.
        
        :param confirmed: whether this is a confirmed commit
        :type confirmed: `bool`
        
        :param timeout: confirm timeout in seconds
        :type timeout: `int`
    
    .. method:: discard_changes()
    
        Revert the candidate configuration to the currently running configuration. Any uncommitted
        changes are discarded.
    
    .. method:: validate(source)
        
        Validate the contents of the specified configuration.
        
        :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
        :type source: :ref:`srctarget_params`
    
    .. attribute:: async_mode
        
        Specify whether operations are executed asynchronously (:const:`True`)
        or synchronously (:const:`False`) (the default).
    
    .. attribute:: raise_mode
        
        Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
        Valid values:
        
        * ``"all"`` -- any kind of *rpc-error* (error or warning)
        * ``"errors"`` -- where the *error-type* attribute says it is an error
        * ``"none"`` -- neither
        
    .. attribute:: client_capabilities
    
        `~ncclient.capabilities.Capabilities` object representing the client's capabilities.
    
    .. attribute:: server_capabilities
    
        `~ncclient.capabilities.Capabilities` object representing the server's capabilities.
    
    .. attribute:: session_id
    
        *session-id* assigned by the NETCONF server.
    
    .. attribute:: connected
        
        Bolean value indicating whether currently connected to the NETCONF server.


Special kinds of parameters
---------------------------

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

.. _srctarget_params:

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 `~xml.etree.ElementTree.Element` object.

.. _filter_params:

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
      `~xml.etree.ElementTree.Element` object containing the criteria.

* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` object.