code.grnet.gr Git - ncclient/blob - docs/source/userdoc/operations.rst

   1 ************************
   2 :mod:`operations` module
   3 ************************
   4
   5 .. automodule:: ncclient.operations
   6     :synopsis: RPC and Operation layers
   7
   8 Base types
   9 ==========
  10
  11 .. currentmodule:: ncclient.operations.rpc
  12
  13 .. autoclass:: RPC(session[, async=False, timeout=None])
  14     :members: set_async, set_timeout, reply, error, event, async, timeout, id, session
  15
  16 .. autoclass:: RPCReply
  17     :members: ok, error, errors
  18
  19 .. autoclass:: RPCError
  20     :members: type, severity, tag, path, message, info
  21     :show-inheritance:
  22
  23 NETCONF Operations
  24 ==================
  25
  26 .. currentmodule:: ncclient.operations
  27
  28 Dependencies
  29 -------------
  30
  31 Operations may have a hard dependency on some capability, or the dependency may arise at request-time due to an optional argument. In any case, a :exc:`MissingCapabilityError` is raised if the server does not support the relevant capability.
  32
  33 .. _return:
  34
  35 Return type
  36 -----------
  37
  38 The return type for the :meth:`request` method depends of an operation on whether it is synchronous or asynchronous (see base class :class:`RPC`).
  39
  40 * For synchronous requests, it will block waiting for the reply, and once it has been received an :class:`RPCReply` object is returned. If an error occured while waiting for the reply, it will be raised.
  41
  42 * For asynchronous requests, it will immediately return an :class:`~threading.Event` object. This event is set when a reply is received, or an error occurs that prevents a reply from being received. The :attr:`~RPC.reply` and :attr:`~RPC.error` attributes can then be accessed to determine which of the two it was :-)
  43
  44 General notes on parameters
  45 ----------------------------
  46
  47 .. _source_target:
  48
  49 Source / target parameters
  50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  51
  52 Where an operation takes a source or target parameter, it is mainly the case that it can be a datastore name or a URL. The latter, of course, depends on the *:url* capability and whether the capability supports the specific schema of the URL. Either must be specified as a `string`.
  53
  54 If the source may be a *<config>* element, e.g. for :class:`Validate`, specify in :ref:`dtree` with the root element as *<config>*.
  55
  56 .. _filter:
  57
  58 Filter parameters
  59 ^^^^^^^^^^^^^^^^^^
  60
  61 Filter parameters, where applicable, can take one of the following types:
  62
  63 * A `tuple` of *(type, criteria)*.
  64     Here type has to be one of "xpath" or "subtree". For type "xpath", the criteria should be a `string` that is a valid XPath expression. For type "subtree", criteria should be in :ref:`dtree` representing a valid subtree filter.
  65 * A valid *<filter>* element in :ref:`dtree`.
  66
  67 Retrieval operations
  68 --------------------
  69
  70 The reply object for these operations will be a :class:`GetReply` instance.
  71
  72 .. autoclass:: Get
  73     :show-inheritance:
  74     :members: request
  75
  76 .. autoclass:: GetConfig
  77     :show-inheritance:
  78     :members: request
  79
  80 .. autoclass:: GetReply
  81     :show-inheritance:
  82     :members: data, data_xml, data_dtree, data_ele
  83
  84 Locking operations
  85 ------------------
  86
  87 .. autoclass:: Lock
  88     :show-inheritance:
  89     :members: request
  90
  91 .. autoclass:: Unlock
  92     :show-inheritance:
  93     :members: request
  94
  95 Configuration operations
  96 -------------------------
  97
  98 .. autoclass:: EditConfig
  99     :show-inheritance:
 100     :members: request
 101
 102 .. autoclass:: CopyConfig
 103     :show-inheritance:
 104     :members: request
 105
 106 .. autoclass:: DeleteConfig
 107     :show-inheritance:
 108     :members: request
 109
 110 .. autoclass:: Validate
 111     :show-inheritance:
 112     :members: request
 113
 114 .. autoclass:: Commit
 115     :show-inheritance:
 116     :members: request
 117
 118 .. autoclass:: DiscardChanges
 119     :show-inheritance:
 120     :members: request
 121
 122 Session management operations
 123 ------------------------------
 124
 125 .. autoclass:: CloseSession
 126     :show-inheritance:
 127     :members: request
 128
 129 .. autoclass:: KillSession
 130     :show-inheritance:
 131     :members: request
 132
 133 Also useful
 134 -----------
 135
 136 .. autoclass:: LockContext
 137
 138
 139 Errors
 140 =======
 141
 142 .. autoexception:: OperationError
 143     :show-inheritance:
 144     :members:
 145
 146 .. autoexception:: TimeoutExpiredError
 147     :show-inheritance:
 148     :members:
 149
 150 .. autoexception:: MissingCapabilityError
 151     :show-inheritance:
 152     :members: