ncclient:NETCONF Python client

  <a href="http://schmizz.net/ncclient">

:mod:`~ncclient.capabilities` -- NETCONF Capabilities

=====================================================

.. module:: ncclient.capabilities

.. autofunction:: schemes

.. autoclass:: Capabilities

    :members:

.. automodule:: ncclient.manager

Module data

-----------

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

are available through the `Manager` API.

.. autodata:: CAPABILITIES

.. autodata:: OPERATIONS

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

.. autodata:: connect

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

:mod:`~ncclient.operations` -- Everything RPC

=============================================

Base classes

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

.. module:: ncclient.operations

    :synopsis: Everything RPC

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

    :members: DEPENDS, REPLY_CLS, _assert, _request, request, event, error, reply, raise_mode, is_async, timeout

.. autoclass:: RPCReply

    :members: xml, ok, error, errors

.. autoexception:: RPCError

    :show-inheritance:

    :members: type, severity, tag, path, message, info

Operations

----------

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

Replies with data

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

.. autoclass:: GetReply

    :show-inheritance:

    :members: data, data_ele, data_xml

Exceptions

----------

.. autoexception:: OperationError

    :show-inheritance:

.. autoexception:: MissingCapabilityError

    :show-inheritance:

.. autoexception:: TimeoutExpiredError

    :show-inheritance:

:mod:`~ncclient.transport` -- Transport / Session layer

=======================================================

.. module:: ncclient.transport

    :synopsis: Transport / Session layer

Base types

-----------

.. autoclass:: Session

    :members: add_listener, remove_listener, get_listener_instance, client_capabilities, server_capabilities, connected, id

.. autoclass:: SessionListener

    :members: callback, errback

SSH session implementation

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

.. automethod:: ssh.default_unknown_host_cb

.. autoclass:: SSHSession

    :show-inheritance:

    :members: load_known_hosts, close, transport

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

Errors

------

.. autoexception:: TransportError

    :show-inheritance:

.. autoexception:: SessionCloseError

    :show-inheritance:

.. autoexception:: SSHError

    :show-inheritance:

.. autoexception:: AuthenticationError

    :show-inheritance:

.. autoexception:: SSHUnknownHostError

    :show-inheritance:

:mod:`~ncclient.xml_` -- XML Handling

=====================================

*TODO*

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

        "Add a capability."

        "Remove a capability."

    #def get_uri(self, shorthand):

    #    "Returns the URI that is inferred for a given shorthand."

    #    for uri, abbrs in self._dict.items():

    #        if shorthand in abbrs:

    #            return uri

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

"""`~ncclient.capabilities.Capabilities` object 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. `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.

"""

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

    """    

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

    """Adds attributes for the *data* element to `RPCReply`. This pertains to the `Get` and

    `GetConfig` operations."""

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

        "*data* element as an XML string"

    "Same as :attr:`data_ele`"

    "The *get* RPC."

    "The *get-config* RPC."

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

    other exception."""

    def __init__(self, raw):

        self._raw = raw

        for subele in raw:

    "*rpc-error* element as returned."

    @property

    def xml(self):

        return self._raw

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

class RPCReply:

    """Represents an *rpc-reply*. Only concerns itself with whether the operation was successful.

    .. note::

        If the reply has not yet been parsed there is an implicit, one-time parsing overhead to

        accessing the attributes defined by this class and any subclasses.

    """

    ERROR_CLS = RPCError

    "Subclasses can specify a different error class, but it should be a subclass of `RPCError`."

    def __init__(self, raw):

        self._raw = raw

        self._parsed = False

        self._root = None

        self._errors = []

    def __repr__(self):

        return self._raw

    def parse(self):

        "Parses the *rpc-reply*."

        if self._parsed: return

        root = self._root = to_ele(self._raw) # The <rpc-reply> element

        # Per RFC 4741 an <ok/> tag is sent when there are no errors or warnings

        ok = root.find(qualify("ok"))

        if ok is None:

            # Create RPCError objects from <rpc-error> elements

            error = root.find(qualify("rpc-error"))

            if error is not None:

                for err in root.getiterator(error.tag):

                    # Process a particular <rpc-error>

                    self._errors.append(ERROR_CLS(err))

        self._parsed = True

    @property

    def xml(self):

        "*rpc-reply* element as returned."

        return self._raw

    @property

    def ok(self):

        "Boolean value indicating if there were no errors."

        return not self.errors # empty list => false

    @property

    def error(self):

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

        self.parse()

        if self._errors:

            return self._errors[0]

        else:

            return None

    @property

    def errors(self):

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

        reply."""

        self.parse()

        return self._errors

    """Base class for all operations, directly corresponding to *rpc* requests. Handles making the

    request, and taking delivery of the 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.

    """

    "Subclasses can specify a different reply class, but it should be a subclass of `RPCReply`."

        self._id = uuid1().urn # Keeps things simple instead of having a class attr with running ID that has to be locked

    def _wrap(self, subele):

        # internal use

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

        :type ops: `~xml.etree.ElementTree.Element`

        :rtype: `RPCReply` (sync) or `RPC` (async)

        req = self._wrap(op)

        """Subclasses must implement this method. Typically only the request needs to be built as an

        `~xml.etree.ElementTree.Element` and everything else can be handed off to

        :meth:`_request`."""

        pass

        """Subclasses can use this method to verify that a capability is available with the NETCONF

        server, before making a request that requires it. A :exc:`MissingCapabilityError` will be

        raised if the capability is not available."""

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

            This represents an error which prevented a reply from being received. An *rpc-error*

            does not fall in that category -- see `RPCReply` for that.

        "The *message-id* for this RPC."

        "The `~ncclient.transport.Session` object associated with this RPC."

        """`~threading.Event` that is set when reply has been received or when an error preventing

        delivery of the reply occurs.

        """

    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

    """

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

    synchronous.

    """

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

    Irrelevant for asynchronous usage.

    """

logger = logging.getLogger("ncclient.transport.ssh")

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

    Supply another valid callback if you need to verify the host key programatically.

    :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

        considered again.

        """

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

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

        :arg timeout: an optional timeout for socket connect

        :arg unknown_host_cb: called when the server host key is not recognized