Statistics
| Branch: | Tag: | Revision:

root / docs / source / manager.rst @ 4bc8021f

History | View | Annotate | Download (9.7 kB)

1
:mod:`~ncclient.manager` -- High-level API
2
==========================================
3

    
4
.. automodule:: ncclient.manager
5
    :synopsis: High-level API
6

    
7
Module data
8
-----------
9

    
10
These attributes control what capabilties are exchanged with the NETCONF server and what operations
11
are available through the `Manager` API.
12

    
13
.. autodata:: CAPABILITIES
14

    
15
.. autodata:: OPERATIONS
16

    
17
Factory functions
18
-----------------
19

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

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

    
24
.. autodata:: connect
25

    
26
Manager
27
-------
28

    
29
Exposes an API for RPC operations as method calls. The return type of these methods depends on
30
whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`.
31

    
32
In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object
33
is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`,
34
an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
35

    
36
However in asynchronous mode, operations return immediately with an `~ncclient.operations.RPC`
37
object. Error handling and checking for whether a reply has been received must be dealt with
38
manually. See the `~ncclient.operations.RPC` documentation for details.
39

    
40
Note that in case of the *get* and *get-config* operations, the reply is an instance of
41
`~ncclient.operations.GetReply` which exposes the additional attributes
42
:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
43
:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case
44
of these operations.
45

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

    
50
.. class:: Manager
51
    
52
    For details on the expected behavior of the operations and their parameters 
53
    refer to :rfc:`4741`.
54

    
55
    Manager instances are also context managers so you can use it like this::
56

    
57
        with manager.connect("host") as m:
58
            # do your stuff
59
    
60
    ... or like this::
61
    
62
        m = manager.connect("host")
63
        try:
64
            # do your stuff
65
        finally:
66
            m.close()
67
    
68
    .. method:: get_config(source[, filter=None])
69
        
70
        Retrieve all or part of a specified configuration.
71
        
72
        :param source: name of the configuration datastore being queried
73
        :type source: `string`
74
        
75
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
76
        :type filter: :ref:`filter_params`
77
    
78
    .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
79
        
80
        Loads all or part of a specified configuration to the specified target configuration.
81
        
82
        The ``"rollback-on-error"`` *error_option* depends on the ``:rollback-on-error`` capability.
83
        
84
        :param target: name of the configuration datastore being edited
85
        :type target: `string`
86
        
87
        :param config: configuration (must be rooted in *<config> .. </config>*)
88
        :type config: `string` or `~xml.etree.ElementTree.Element`
89
        
90
        :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
91
        :type default_operation: `string`
92
        
93
        :param test_option: one of { ``"test_then_set"``, ``"set"`` }
94
        :type test_option: `string`
95
        
96
        :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
97
        :type error_option: `string`
98
    
99
    .. method:: copy_config(source, target)
100
        
101
        Create or replace an entire configuration datastore with the contents of another complete
102
        configuration datastore. 
103
        
104
        :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
105
        :type source: :ref:`srctarget_params`
106
        
107
        :param target: configuration datastore to use as the destination of the copy operation
108
        :type target: :ref:`srctarget_params`
109
    
110
    .. method:: delete_config(target)
111
        
112
        Delete a configuration datastore.
113
        
114
        :param target: name or URL of configuration datastore to delete
115
        :type: :ref:`srctarget_params`
116
    
117
    .. method:: lock(target)
118
        
119
        Allows the client to lock the configuration system of a device.
120
        
121
        :param target: name of the configuration datastore to lock
122
        :type target: `string`
123
        
124
    .. method:: unlock(target)
125
    
126
        Release a configuration lock, previously obtained with the
127
        :meth:`~ncclient.manager.Manager.lock` operation.
128
        
129
        :param target: name of the configuration datastore to unlock
130
        :type target: `string`
131
    
132
    .. method:: locked(target)
133
        
134
        Returns a context manager for a lock on a datastore, e.g.::
135
        
136
            with m.locked("running"):
137
                # do your stuff
138

    
139
        ... instead of::
140
        
141
            m.lock("running")
142
            try:
143
                # do your stuff
144
            finally:
145
                m.unlock("running")
146
        
147
        :param target: name of configuration datastore to lock
148
        :type target: `string`
149
        
150
        :rtype: `~ncclient.operations.LockContext`
151
    
152
    .. method:: get([filter=None])
153
        
154
        Retrieve running configuration and device state information.
155
        
156
        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
157
        :type filter: :ref:`filter_params`
158
    
159
    .. method:: close_session()
160
        
161
        Request graceful termination of the NETCONF session, and also close the transport.
162
    
163
    .. method:: kill_session(session_id)
164
        
165
        Force the termination of a NETCONF session (not the current one!).
166
        
167
        :param session_id: session identifier of the NETCONF session to be terminated
168
        :type session_id: `string`
169
    
170
    .. method:: commit([confirmed=False, timeout=None])
171
    
172
        Commit the candidate configuration as the device's new current configuration. Depends on the
173
        *:candidate* capability.
174
        
175
        A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
176
        followup commit within the *timeout* interval. If no timeout is specified the confirm
177
        timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
178
        parameter but this is not required. Depends on the *:confirmed-commit* capability.
179
        
180
        :param confirmed: whether this is a confirmed commit
181
        :type confirmed: `bool`
182
        
183
        :param timeout: confirm timeout in seconds
184
        :type timeout: `int`
185
    
186
    .. method:: discard_changes()
187
    
188
        Revert the candidate configuration to the currently running configuration. Any uncommitted
189
        changes are discarded.
190
    
191
    .. method:: validate(source)
192
        
193
        Validate the contents of the specified configuration.
194
        
195
        :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
196
        :type source: :ref:`srctarget_params`
197
    
198
    .. attribute:: async_mode
199
        
200
        Specify whether operations are executed asynchronously (:const:`True`)
201
        or synchronously (:const:`False`) (the default).
202
    
203
    .. attribute:: raise_mode
204
        
205
        Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
206
        Valid values:
207
        
208
        * ``"all"`` -- any kind of *rpc-error* (error or warning)
209
        * ``"errors"`` -- where the *error-type* element says it is an error
210
        * ``"none"`` -- neither
211
        
212
    .. attribute:: client_capabilities
213
    
214
        `~ncclient.capabilities.Capabilities` object representing the client's capabilities.
215
    
216
    .. attribute:: server_capabilities
217
    
218
        `~ncclient.capabilities.Capabilities` object representing the server's capabilities.
219
    
220
    .. attribute:: session_id
221
    
222
        *session-id* assigned by the NETCONF server.
223
    
224
    .. attribute:: connected
225
        
226
        Bolean value indicating whether currently connected to the NETCONF server.
227

    
228

    
229
Special kinds of parameters
230
---------------------------
231

    
232
Some parameters can take on different types to keep the interface simple.
233

    
234
.. _srctarget_params:
235

    
236
Source and target parameters
237
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
238

    
239
Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected.
240
The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported.
241
Either must be specified as a `string`. For example, ``"running"``,
242
``"ftp://user:pass@host/config"``.
243

    
244
If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be
245
specified as an XML string or an `~xml.etree.ElementTree.Element` object.
246

    
247
.. _filter_params:
248

    
249
Filter parameters
250
^^^^^^^^^^^^^^^^^
251

    
252
Where a method takes a *filter* argument, it can take on the following types:
253

    
254
* A ``tuple`` of *(type, criteria)*.
255
    
256
    Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
257
    
258
    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression.
259
    * For ``"subtree"`` the *criteria* should be an XML string or an
260
      `~xml.etree.ElementTree.Element` object containing the criteria.
261

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