ncclient:NETCONF Python client

    :members:

default_role = 'class' 

``ncclient`` is a Python library for NETCONF clients. It aims to offer an intuitive API that

sensibly maps the XML-encoded nature of NETCONF to Python constructs and idioms, and make writing

network-management scripts easier. Other key features are:

It is suitable for Python 2.6+ (not Python 3 yet, though), and depends on `paramiko

<http://www.lag.net/paramiko/>`_, an SSH library.

The best way to introduce is of course, through a simple code example::

    extending

Module data

-----------

These attributes control what capabilties are exchanged with the NETCONF server and what operations

are available through the `Manager` API.

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

.. autofunction:: 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])

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* element 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.

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.

* 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.

Base classes

------------

.. autoclass:: RPC(session[, async=False, timeout=None, raise_mode="none"])

    :members: xml, ok, error, errors

*TODO*

The operation classes are currently undocumented. See documentation of `~ncclient.manager.Manager`

for methods that utilize the operation classes. The parameters accepted by :meth:`~RPC.request` for

these classes are the same.

    .. automethod:: connect(host[, port=830, timeout=None, username=None, password=None, key_filename=None, allow_agent=True, look_for_keys=True])

    :show-inheritance:

.. module:: ncclient.xml_

.. function:: register_namespace(prefix, uri)

    ElementTree's namespace map determines the prefixes for namespace URI's when serializing to XML.

    This method allows modifying this map to specify a prefix for a namespace URI.

.. autofunction:: validated_element

.. 

    """Given a URI that has a *scheme* query string (i.e. *:url* capability URI), will return a list

    of supported schemes.

    """

    """Represents the set of capabilities available to a NETCONF client or server. It is initialized

    with a list of capability URI's. These can be iterated over.

    Presence of a capability can be checked with the *in* operation. In addition to the URI, for

    capabilities of the form *urn:ietf:params:netconf:capability:$name:$version* their shorthand can

    be used as a key. For example, for *urn:ietf:params:netconf:capability:candidate:1.0* the

    shorthand would be *:candidate*. If version is significant, use *:candidate:1.0* as key.

    """

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

"A list of URI's 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."

"""Dictionary of method names and corresponding `~ncclient.operations.RPC` subclasses. It is used 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."""

    """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_unknown_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`

    __metaclass__ = OpExecutor

    RAISE_NONE = 0

    RAISE_ERRORS = 1

    RAISE_ALL = 2

    def __init__(self, session):

        self._timeout = None

        self._raise_mode = self.RAISE_ALL

    def set_async_mode(self, mode):

        self._async_mode = mode

    def set_raise_mode(self, mode):

        assert(choice in (self.RAISE_NONE, self.RAISE_ERRORS, self.RAISE_ALL))

        self._raise_mode = mode

    async_mode = property(fget=lambda self: self._async_mode, fset=set_async_mode)

    raise_mode = property(fget=lambda self: self._raise_mode, fset=set_raise_mode)

from rpc import RPC, RPCReply, RPCError

    "*<edit-config>* RPC"

            # TODO: check if it is a valid default-operation

    "*<delete-config>* RPC"

    "*<copy-config>* RPC"

    "*<validate>* RPC. Depends on the *:validate* capability."

    "*<commit>* RPC. Depends on the *:candidate* capability, and the *:confirmed-commit* "

    "*<discard-changes>* RPC. Depends on the *:candidate* capability."

'Locking-related NETCONF operations'

from rpc import RPC

# TODO:

# should have some way to parse session-id from a lock-denied error, and raise

# a tailored exception

    "*<lock>* RPC"

    "*<unlock>* RPC"

    """

    A context manager for the :class:`Lock` / :class:`Unlock` pair of RPC's.

    RPC errors are always raised as exceptions.

    Initialise with (:class:`Session <ncclient.transport.Session>`) instance

    and lock target.

        Lock(self.session).request(self.target)

        Unlock(self.session).request(self.target)

        "*data* element as an `~xml.etree.ElementTree.Element`"

    """Represents an *rpc-error*. It is a type of :exc:`OperationError` and can be raised like any

    other exception."""

        "*rpc-error* element as returned."

        "`string` representing text of *error-type* element."

        "`string` representing text of *error-tag* element."

        "`string` representing text of *error-severity* element."

        "`string` or :const:`None`; representing text of *error-path* element."

        "`string` or :const:`None`; representing text of *error-message* element."

        "`string` (XML) or :const:`None`; representing *error-info* element."

        "Returns the first `RPCError` and :const:`None` if there were no errors."

        """`list` of `RPCError` objects. Will be empty if there were no *rpc-error* elements in

        reply."""

    """Subclasses can specify their dependencies on capabilities. List of URI's or abbreviated

    names, e.g. ':writable-running'. These are verified at the time of instantiation. If the

    capability is not available, a :exc:`MissingCapabilityError` is raised.

    def __init__(self, session, async=False, timeout=None, raise_mode="none"):

        """Implementations of :meth:`request` call this method to send the request and process the

        reply.

        In synchronous mode, blocks until the reply is received and returns `RPCReply`. Depending on

        the :attr:`raise_mode` a *rpc-error* element in the reply may lead to an :exc:`RPCError`

        exception.

        In asynchronous mode, returns immediately, returning *self*. The :attr:`event` attribute

        will be set when the reply has been received (see :attr:`reply`) or an error occured (see

        :attr:`error`).

        :param op: operation to be requested

                    if self._raise_mode == "all":

                    elif (self._raise_mode == "errors" and

                          self._reply.error.type == "error"):

        "`RPCReply` element if reply has been received or :const:`None`"

        """:exc:`Exception` type if an error occured or :const:`None`.

    def set_async(self, async=True):

    def set_raise_mode(self, mode):

    def set_timeout(self, timeout):

    raise_mode = property(fget=lambda self: self._raise_mode, fset=set_raise_mode)

    """Depending on this exception raising mode, an *rpc-error* in the reply may be raised as

    :exc:`RPCError` exceptions. Valid values:

    * ``"all"`` -- any kind of *rpc-error* (error or warning)

    * ``"errors"`` -- when the *error-type* element says it is an error

    * ``"none"`` -- neither

    """

    is_async = property(fget=lambda self: self._async, fset=set_async)

    """Specifies whether this RPC will be / was requested asynchronously. By default RPC's are

    synchronous.

    """

    timeout = property(fget=lambda self: self._timeout, fset=set_timeout)

    """Timeout in seconds for synchronous waiting defining how long the RPC request will block on a

    reply before raising :exc:`TimeoutExpiredError`. By default there is no timeout, represented by

    :const:`None`.

'Session-related NETCONF operations'

    "*<close-session>* RPC. The connection to NETCONF server is also closed."

    "*<kill-session>* RPC."

        """

        :arg session_id: *session-id* of NETCONF session to kill

        :type session_id: `string`

        if not isinstance(session_id, basestring): # make sure

            session_id = str(session_id)

        """Send the supplied *message* to NETCONF server.

        :arg message: an XML document

        :type message: `string`

        """

        """A `string` representing the `session-id`. If the session has not

        been initialized it will be :const:`None`"""

        """Called when a new XML document is received. The `root` argument

        allows the callback to determine whether it wants to further process the

        document.

        :arg root: tuple of `(tag, attributes)` where `tag` is the qualified name of the root element and `attributes` is a dictionary of its attributes (also qualified names)

        :type root: `tuple`

        :arg raw: XML document

        :type raw: `string`

    """An `unknown host callback` returns :const:`True` if it finds the key acceptable, and

    :const:`False` if not.

    This default callback always returns :const:`False`, which would lead to :meth:`connect` raising

    a :exc:`SSHUnknownHost` exception.

    :arg host: the hostname that needs to be verified

    :type host: `string`

    :arg fingerprint: a hex string representing the host key fingerprint, colon-delimited e.g. *4b:69:6c:72:6f:79:20:77:61:73:20:68:65:72:65:21*

    :type fingerprint: `string`

        """Messages ae delimited by MSG_DELIM. The buffer could have grown by a

        maximum of BUF_SIZE bytes everytime this method is called. Retains state

        across method calls and if a byte has been read it will not be

        considered again.

        """

        """Load host keys from a :file:`known_hosts`-style file. Can be called multiple times.

        If *filename* is not specified, looks in the default locations i.e.

        :file:`~/.ssh/known_hosts` and :file:`~/ssh/known_hosts` for Windows.

    def connect(self, host, port=830, timeout=None,

                unknown_host_cb=default_unknown_host_cb,

                username=None, password=None,

                key_filename=None, allow_agent=True, look_for_keys=True):

        """Connect via SSH and initialize the NETCONF session. First attempts the publickey

        authentication method and then password authentication.

        To disable attemting publickey authentication altogether, call with *allow_agent* and

        *look_for_keys* as :const:`False`.

        :type host: `string`

        :type port: `int`

        :type timeout: `int`

        :type unknown_host_cb: see :meth:`signature <ssh.default_unknown_host_cb>`

        :type username: `string`

        :type password: `string`

        :type key_filename: `string`

        :type allow_agent: `bool`

        :type look_for_keys: `bool`

                # select on a paramiko ssh channel object does not ever return

                # it in the writable list, so it channel's don't exactly emulate

                # the socket api

                # will wakeup evey TICK seconds to check if something

                # to send, more if something to read (due to select returning

                # chan in readable list)

        """Underlying `paramiko.Transport

        <http://www.lag.net/paramiko/docs/paramiko.Transport-class.html>`_

        object. This makes it possible to call methods like set_keepalive on it.

        """

"""Qualify a tag name with a namespace, in :mod:`~xml.etree.ElementTree` fashion i.e. *{namespace}tagname*.

:arg tag: name of the tag

:type arg: `string`

:arg ns: namespace to qualify with

:type ns: `string`

"""

    """Convert an `~xml.etree.ElementTree.Element` to XML.

    :arg ele: the `~xml.etree.ElementTree.Element`

    :arg encoding: character encoding

    :rtype: `string`

    """

    """Convert XML to `~xml.etree.ElementTree.Element`. If passed an `~xml.etree.ElementTree.Element` simply returns that.

    :arg x: the XML document or element

    :type x: `string` or `~xml.etree.ElementTree.Element`

    :rtype: `~xml.etree.ElementTree.Element`

    """

    """Efficiently parses the root element of an XML document.

    :arg raw: XML document

    :returns: a tuple of ``(tag, attrib)``, where *tag* is the (qualified) name of the element and *attrib* is a dictionary of its attributes.

    :rtype: `tuple`

    """

    :arg tags: allowable tag name or sequence of allowable alternatives

    :type tags: `string` or sequence of strings

    :arg attrs: list of required attributes, each of which may be a sequence of several allowable alternatives

    :type attrs: sequence of strings or sequence of sequences of strings