Revision bfcf8aea docs/source/manager.rst

b/docs/source/manager.rst
4 4
.. module:: ncclient.manager
5 5
    :synopsis: High-level API
6 6

  
7
.. data:: CAPABILITIES
8

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

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

  
7 18
Factory functions
8 19
-----------------
9 20

  
......
11 22

  
12 23
.. 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])
13 24
    
14
    Initializes a NETCONF session over SSH, and creates a connected `Manager`
15
    instance. *host* must be specified, all the other arguments are optional and
16
    depend on the kind of host key verification and user authentication you want
17
    to complete.
25
    Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must
26
    be specified, all the other arguments are optional and depend on the kind of host key
27
    verification and user authentication you want to complete.
18 28
    
19
    For the purpose of host key verification, on POSIX systems a user's
20
    :file:`~/.ssh/known_hosts` file is automatically considered. The
21
    *unknown_host_cb* argument specifies a callback that will be invoked when
22
    the server's host key cannot be verified. See
29
    For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts`
30
    file is automatically considered. The *unknown_host_cb* argument specifies a callback that will
31
    be invoked when the server's host key cannot be verified. See
23 32
    :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
24 33
    
25
    First, ``publickey`` authentication is attempted. If a specific
26
    *key_filename* is specified, it will be loaded and authentication attempted
27
    using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys
28
    provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in
29
    the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an
30
    encrypted key file is encountered, the *password* argument will be used as a
31
    decryption passphrase.
34
    First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it
35
    will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an
36
    SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is
37
    :const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case
38
    an encrypted key file is encountered, the *password* argument will be used as a decryption
39
    passphrase.
32 40
    
33
    If ``publickey`` authentication fails and the *password* argument has been
34
    supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be
35
    attempted.
41
    If ``publickey`` authentication fails and the *password* argument has been supplied,
42
    ``password`` / ``keyboard-interactive`` SSH authentication will be attempted.
36 43
    
37 44
    :param host: hostname or address on which to connect
38 45
    :type host: `string`
......
43 50
    :param timeout: timeout for socket connect
44 51
    :type timeout: `int`
45 52
    
46
    :param unknown_host_cb: optional; callback that is invoked when host key
47
                            verification fails
53
    :param unknown_host_cb: optional; callback that is invoked when host key verification fails
48 54
    :type unknown_host_cb: `function`
49 55
    
50
    :param username: username to authenticate with, if not specified the
51
                        username of the logged-in user is used
56
    :param username: username to authenticate with, if not specified the username of the logged-in
57
                       user is used
52 58
    :type username: `string`
53 59
    
54
    :param password: password for ``password`` authentication or passphrase for
55
                        decrypting private key files
60
    :param password: password for ``password`` authentication or passphrase for decrypting
61
                       private key files
56 62
    :type password: `string`
57 63
    
58 64
    :param key_filename: location of a private key file on the file system
......
77 83
Manager
78 84
-------
79 85

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

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

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

  
94
Note that in case of the *get* and *get-config* operations, the reply is an
95
instance of `~ncclient.operations.GetReply` which exposes the additional
96
attributes :attr:`~ncclient.operations.GetReply.data`
97
(as `~xml.etree.ElementTree.Element`) and
98
:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary
99
interest in case of these operations.
97
Note that in case of the *get* and *get-config* operations, the reply is an instance of
98
`~ncclient.operations.GetReply` which exposes the additional attributes
99
:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
100
:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case
101
of these operations.
100 102

  
101
Presence of capabilities is verified to the extent possible, and you can expect
102
a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In
103
case of transport-layer errors, e.g. unexpected session close,
104
:exc:`~ncclient.transport.TransportError` will be raised.
103
Presence of capabilities is verified to the extent possible, and you can expect a
104
:exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer
105
errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised.
105 106

  
106 107
.. class:: Manager
107 108
    
......
128 129
        :param source: name of the configuration datastore being queried
129 130
        :type source: `string`
130 131
        
131
        :param filter: see :ref:`filter_params`
132
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
133
        :type filter: :ref:`filter_params`
132 134
    
133 135
    .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
134 136
        
......
139 141
        :param target: name of the configuration datastore being edited
140 142
        :type target: `string`
141 143
        
144
        :param config: configuration (must be rooted in *<config> .. </config>*)
145
        :type config: `string` or `~xml.etree.ElementTree.Element`
146
        
142 147
        :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
143 148
        :type default_operation: `string`
144 149
        
......
147 152
        
148 153
        :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
149 154
        :type error_option: `string`
150
        
151
        :param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object
152 155
    
153 156
    .. method:: copy_config(source, target)
154 157
        
155
        Create or replace an entire configuration datastore with the contents of
156
        another complete configuration datastore. 
158
        Create or replace an entire configuration datastore with the contents of another complete
159
        configuration datastore. 
157 160
        
158
        :param source: see :ref:`srctarget_params`
161
        :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
162
        :type source: :ref:`srctarget_params`
159 163
        
160
        :param target: see :ref:`srctarget_params`
164
        :param target: configuration datastore to use as the destination of the copy operation
165
        :type target: :ref:`srctarget_params`
161 166
    
162 167
    .. method:: delete_config(target)
163 168
        
164 169
        Delete a configuration datastore.
165 170
        
166
        :param target: see :ref:`srctarget_params`
171
        :param target: name or URL of configuration datastore to delete
172
        :type: :ref:`srctarget_params`
167 173
    
168 174
    .. method:: lock(target)
169 175
        
......
195 201
            finally:
196 202
                m.unlock("running")
197 203
        
198
        :param target: datastore name. See :ref:`srctarget_params`
204
        :param target: name of configuration datastore to lock
205
        :type target: `string`
199 206
        
200 207
        :rtype: `~ncclient.operations.LockContext`
201 208
    
......
203 210
        
204 211
        Retrieve running configuration and device state information.
205 212
        
206
        :param filter: see :ref:`filter_params`
213
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
214
        :type filter: :ref:`filter_params`
207 215
    
208 216
    .. method:: close_session()
209 217
        
210
        Request graceful termination of the NETCONF session, and also close the
211
        transport.
218
        Request graceful termination of the NETCONF session, and also close the transport.
212 219
    
213 220
    .. method:: kill_session(session_id)
214 221
        
215 222
        Force the termination of a NETCONF session (not the current one!).
216 223
        
217
        :param session_id: session identifier of the NETCONF session to be
218
                            terminated
224
        :param session_id: session identifier of the NETCONF session to be terminated
219 225
        :type session_id: `string`
220 226
    
227
    .. method:: commit([confirmed=False, timeout=None])
228
    
229
        Commit the candidate configuration as the device's new current configuration. Depends on the
230
        *:candidate* capability.
231
        
232
        A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
233
        followup commit within the *timeout* interval. If no timeout is specified the confirm
234
        timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
235
        parameter but this is not required. Depends on the *:confirmed-commit* capability.
236
        
237
        :param confirmed: whether this is a confirmed commit
238
        :type confirmed: `bool`
239
        
240
        :param timeout: confirm timeout in seconds
241
        :type timeout: `int`
242
    
243
    .. method:: discard_changes()
244
    
245
        Revert the candidate configuration to the currently running configuration. Any uncommitted
246
        changes are discarded.
247
    
248
    .. method:: validate(source)
249
        
250
        Validate the contents of the specified configuration.
251
        
252
        :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
253
        :type source: :ref:`srctarget_params`
254
    
221 255
    .. attribute:: async_mode
222 256
        
223 257
        Specify whether operations are executed asynchronously (:const:`True`)
......
225 259
    
226 260
    .. attribute:: raise_mode
227 261
        
228
        The raise *mode* affects what errors are raised as
229
        :exc:`~ncclient.operations.RPCError` exceptions.
262
        Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
263
        Valid values:
230 264
        
231 265
        * ``"all"`` -- any kind of *rpc-error* (error or warning)
232 266
        * ``"errors"`` -- where the *error-type* attribute says it is an error
......
234 268
        
235 269
    .. attribute:: client_capabilities
236 270
    
237
        `~ncclient.capabilities.Capabilities` object representing the client's
238
        capabilities.
271
        `~ncclient.capabilities.Capabilities` object representing the client's capabilities.
239 272
    
240 273
    .. attribute:: server_capabilities
241 274
    
242
        `~ncclient.capabilities.Capabilities` object representing the server's
243
        capabilities.
275
        `~ncclient.capabilities.Capabilities` object representing the server's capabilities.
244 276
    
245 277
    .. attribute:: session_id
246 278
    
247
        The *session-id* assigned by the NETCONF server.
279
        *session-id* assigned by the NETCONF server.
248 280
    
249 281
    .. attribute:: connected
250 282
        
251
        A boolean value indicating whether currently connected to the NETCONF
252
        server.
283
        Bolean value indicating whether currently connected to the NETCONF server.
253 284

  
254 285

  
255 286
Special kinds of parameters
256
^^^^^^^^^^^^^^^^^^^^^^^^^^^
287
---------------------------
257 288

  
258
To keep the API clean, some parameters can take on different types.
289
Some parameters can take on different types to keep the interface simple.
259 290

  
260 291
.. _srctarget_params:
261 292

  
262 293
Source and target parameters
263
""""""""""""""""""""""""""""
294
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
264 295

  
265
Where an method takes a *source* or *target* argument, usually a datastore name
266
or URL is expected. The latter depends on the ``:url`` capability and on whether
267
the specific URL scheme is supported. Either must be specified as a `string`.
268
For example, ``"running"``, ``"ftp://user:pass@host/config"``.
296
Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected.
297
The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported.
298
Either must be specified as a `string`. For example, ``"running"``,
299
``"ftp://user:pass@host/config"``.
269 300

  
270
If the source may be a *<config>* element, e.g. as allowed for the *validate*
271
RPC, it can be specified either as an XML string or an
272
`~xml.etree.ElementTree.Element` object rooted in the *<config>* element.
301
If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be
302
specified as an XML string or an `~xml.etree.ElementTree.Element` object.
273 303

  
274 304
.. _filter_params:
275 305

  
276 306
Filter parameters
277
"""""""""""""""""
307
^^^^^^^^^^^^^^^^^
278 308

  
279 309
Where a method takes a *filter* argument, it can take on the following types:
280 310

  
......
282 312
    
283 313
    Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
284 314
    
285
    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath
286
      expression.
315
    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression.
287 316
    * For ``"subtree"`` the *criteria* should be an XML string or an
288 317
      `~xml.etree.ElementTree.Element` object containing the criteria.
289 318

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

Also available in: Unified diff