:mod:`~ncclient.operations` -- Everything RPC
=============================================
-
.. module:: ncclient.operations
:synopsis: Everything RPC
Base classes
------------
-.. autoclass:: RPC(session, async=False, timeout=None, raise_mode="none")
+.. autoclass:: RPC
:members: DEPENDS, REPLY_CLS, _assert, _request, request, event, error, reply, raise_mode, is_async, timeout
.. autoclass:: RPCReply
Operations
----------
-The operation classes are currently undocumented. See documentation of :class:`~ncclient.manager.Manager` for methods that utilize the operation classes. The parameters accepted by :meth:`~RPC.request` for these classes are the same.
+Retrieval
+..........
+
+.. autoclass:: Get
+ :members: request
+ :show-inheritance:
+
+ .. autoattribute:: REPLY_CLS
-Replies with data
------------------
+.. autoclass:: GetConfig
+ :members: request
+ :show-inheritance:
+
+ .. autoattribute:: REPLY_CLS
.. autoclass:: GetReply
:show-inheritance:
:members: data, data_ele, data_xml
+Editing
+........
+
+.. autoclass:: EditConfig
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: DeleteConfig
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: CopyConfig
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: Validate
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: Commit
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: DiscardChanges
+ :members: request
+ :show-inheritance:
+
+Locking
+........
+
+.. autoclass:: Lock
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: Unlock
+ :members: request
+ :show-inheritance:
+
+Session
+........
+
+.. autoclass:: CloseSession
+ :members: request
+ :show-inheritance:
+
+.. autoclass:: KillSession
+ :members: request
+ :show-inheritance:
+
Exceptions
----------
class GetReply(RPCReply):
- """Adds attributes for the *data* element to `RPCReply`. This pertains to the `Get` and
- `GetConfig` operations."""
+ """Adds attributes for the *data* element to `RPCReply`."""
def _parsing_hook(self, root):
self._data = None
"The *get* RPC."
REPLY_CLS = GetReply
+ "See :class:`GetReply`."
def request(self, filter=None):
"""Retrieve running configuration and device state information.
"The *get-config* RPC."
REPLY_CLS = GetReply
+ "See :class:`GetReply`."
def request(self, source, filter=None):
"""Retrieve all or part of a specified configuration.
.. 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.
+ accessing some of the attributes defined by this class.
"""
ERROR_CLS = RPCError
self._parsed = True
def _parsing_hook(self, root):
- "No-op by default. Gets given the *root* element."
+ "No-op by default. Gets passed the *root* element for the reply."
pass
@property
class RPC(object):
- """Base class for all operations, directly corresponding to *rpc* requests. Handles making the
- request, and taking delivery of the reply."""
+ """Base class for all operations, directly corresponding to *rpc* requests. Handles making the request, and taking delivery of the reply."""
DEPENDS = []
- """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 their dependencies on capabilities as a 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, :exc:`MissingCapabilityError` is raised."""
REPLY_CLS = RPCReply
- "Subclasses can specify a different reply class, but it should be a subclass of `RPCReply`."
+ "By default :class:`RPCReply`. Subclasses can specify a :class:`RPCReply` subclass."
def __init__(self, session, async=False, timeout=30, raise_mode=RaiseMode.NONE):
+ """
+ *session* is the :class:`~ncclient.transport.Session` instance
+
+ *async* specifies whether the request is to be made asynchronously, see :attr:`is_async`
+
+ *timeout* is the timeout for a synchronous request, see :attr:`timeout`
+
+ *raise_mode* specifies the exception raising mode, see :attr:`raise_mode`
+ """
self._session = session
try:
for cap in self.DEPENDS:
In synchronous mode, blocks until the reply is received and returns :class:`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`).
-
- *op* operation to be requested as an `~xml.etree.ElementTree.Element`
+ 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`).
- Returns :class:`RPCReply` (sync) or :class:`RPC` (async)
+ *op* is the operation to be requested as an :class:`~xml.etree.ElementTree.Element`
"""
logger.info('Requesting %r' % self.__class__.__name__)
req = self._wrap(op)
def request(self):
"""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
+ :class:`~xml.etree.ElementTree.Element` and everything else can be handed off to
:meth:`_request`."""
pass
@property
def event(self):
- """`~threading.Event` that is set when reply has been received or when an error preventing
+ """:class:`~threading.Event` that is set when reply has been received or when an error preventing
delivery of the reply occurs.
"""
return self._event
"""Depending on this exception raising mode, an `rpc-error` in the reply may be raised as an :exc:`RPCError` exception. Valid values are the constants defined in :class:`RaiseMode`. """
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. """
+ """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`.