root / docs / source / manager.rst @ bfcf8aea
History | View | Annotate | Download (12.5 kB)
1 | 09e50473 | Shikhar Bhushan | :mod:`~ncclient.manager` -- High-level API |
---|---|---|---|
2 | 09e50473 | Shikhar Bhushan | ========================================== |
3 | 84e0f4f2 | Shikhar Bhushan | |
4 | 09e50473 | Shikhar Bhushan | .. module:: ncclient.manager |
5 | 09e50473 | Shikhar Bhushan | :synopsis: High-level API |
6 | 09e50473 | Shikhar Bhushan | |
7 | bfcf8aea | Shikhar Bhushan | .. data:: CAPABILITIES |
8 | bfcf8aea | Shikhar Bhushan | |
9 | bfcf8aea | Shikhar Bhushan | List of URI strings representing the client's capabilities. This is used during the initial |
10 | bfcf8aea | Shikhar Bhushan | capability exchange. Modify this if you need to announce some capability not already included. |
11 | bfcf8aea | Shikhar Bhushan | |
12 | bfcf8aea | Shikhar Bhushan | .. data:: OPERATIONS |
13 | bfcf8aea | Shikhar Bhushan | |
14 | bfcf8aea | Shikhar Bhushan | Dictionary of method names and corresponding `~ncclient.operations.RPC` classes. `Manager` uses |
15 | bfcf8aea | Shikhar Bhushan | this to lookup operations, e.g. "get_config" is mapped to `ncclient.operations.GetConfig`. It |
16 | bfcf8aea | Shikhar Bhushan | is thus possible to add additional operations to the `Manager` API. |
17 | bfcf8aea | Shikhar Bhushan | |
18 | 09e50473 | Shikhar Bhushan | Factory functions |
19 | 09e50473 | Shikhar Bhushan | ----------------- |
20 | 09e50473 | Shikhar Bhushan | |
21 | 09e50473 | Shikhar Bhushan | A `Manager` instance is created using a factory function. |
22 | 09e50473 | Shikhar Bhushan | |
23 | 09e50473 | Shikhar Bhushan | .. 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]) |
24 | 09e50473 | Shikhar Bhushan | |
25 | bfcf8aea | Shikhar Bhushan | Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must |
26 | bfcf8aea | Shikhar Bhushan | be specified, all the other arguments are optional and depend on the kind of host key |
27 | bfcf8aea | Shikhar Bhushan | verification and user authentication you want to complete. |
28 | 09e50473 | Shikhar Bhushan | |
29 | bfcf8aea | Shikhar Bhushan | For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts` |
30 | bfcf8aea | Shikhar Bhushan | file is automatically considered. The *unknown_host_cb* argument specifies a callback that will |
31 | bfcf8aea | Shikhar Bhushan | be invoked when the server's host key cannot be verified. See |
32 | 09e50473 | Shikhar Bhushan | :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature. |
33 | 09e50473 | Shikhar Bhushan | |
34 | bfcf8aea | Shikhar Bhushan | First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it |
35 | bfcf8aea | Shikhar Bhushan | will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an |
36 | bfcf8aea | Shikhar Bhushan | SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is |
37 | bfcf8aea | Shikhar Bhushan | :const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case |
38 | bfcf8aea | Shikhar Bhushan | an encrypted key file is encountered, the *password* argument will be used as a decryption |
39 | bfcf8aea | Shikhar Bhushan | passphrase. |
40 | 09e50473 | Shikhar Bhushan | |
41 | bfcf8aea | Shikhar Bhushan | If ``publickey`` authentication fails and the *password* argument has been supplied, |
42 | bfcf8aea | Shikhar Bhushan | ``password`` / ``keyboard-interactive`` SSH authentication will be attempted. |
43 | 09e50473 | Shikhar Bhushan | |
44 | 09e50473 | Shikhar Bhushan | :param host: hostname or address on which to connect |
45 | 09e50473 | Shikhar Bhushan | :type host: `string` |
46 | 09e50473 | Shikhar Bhushan | |
47 | 09e50473 | Shikhar Bhushan | :param port: port on which to connect |
48 | 09e50473 | Shikhar Bhushan | :type port: `int` |
49 | 09e50473 | Shikhar Bhushan | |
50 | 09e50473 | Shikhar Bhushan | :param timeout: timeout for socket connect |
51 | 09e50473 | Shikhar Bhushan | :type timeout: `int` |
52 | 09e50473 | Shikhar Bhushan | |
53 | bfcf8aea | Shikhar Bhushan | :param unknown_host_cb: optional; callback that is invoked when host key verification fails |
54 | 09e50473 | Shikhar Bhushan | :type unknown_host_cb: `function` |
55 | 09e50473 | Shikhar Bhushan | |
56 | bfcf8aea | Shikhar Bhushan | :param username: username to authenticate with, if not specified the username of the logged-in |
57 | bfcf8aea | Shikhar Bhushan | user is used |
58 | 09e50473 | Shikhar Bhushan | :type username: `string` |
59 | 09e50473 | Shikhar Bhushan | |
60 | bfcf8aea | Shikhar Bhushan | :param password: password for ``password`` authentication or passphrase for decrypting |
61 | bfcf8aea | Shikhar Bhushan | private key files |
62 | 09e50473 | Shikhar Bhushan | :type password: `string` |
63 | 09e50473 | Shikhar Bhushan | |
64 | 09e50473 | Shikhar Bhushan | :param key_filename: location of a private key file on the file system |
65 | 09e50473 | Shikhar Bhushan | :type key_filename: `string` |
66 | 09e50473 | Shikhar Bhushan | |
67 | 09e50473 | Shikhar Bhushan | :param allow_agent: whether to try connecting to SSH agent for keys |
68 | 09e50473 | Shikhar Bhushan | :type allow_agent: `bool` |
69 | 09e50473 | Shikhar Bhushan | |
70 | 09e50473 | Shikhar Bhushan | :param look_for_keys: whether to look in usual locations for keys |
71 | 09e50473 | Shikhar Bhushan | :type look_for_keys: `bool` |
72 | 09e50473 | Shikhar Bhushan | |
73 | 09e50473 | Shikhar Bhushan | :raises: :exc:`~ncclient.transport.SSHUnknownHostError` |
74 | 09e50473 | Shikhar Bhushan | :raises: :exc:`~ncclient.transport.AuthenticationError` |
75 | 09e50473 | Shikhar Bhushan | |
76 | 09e50473 | Shikhar Bhushan | :rtype: `Manager` |
77 | 09e50473 | Shikhar Bhushan | |
78 | 09e50473 | Shikhar Bhushan | .. function:: connect() |
79 | 09e50473 | Shikhar Bhushan | |
80 | 09e50473 | Shikhar Bhushan | Same as :func:`connect_ssh`, since SSH is the default (and currently, the |
81 | 09e50473 | Shikhar Bhushan | only) transport. |
82 | 09e50473 | Shikhar Bhushan | |
83 | 09e50473 | Shikhar Bhushan | Manager |
84 | 09e50473 | Shikhar Bhushan | ------- |
85 | 09e50473 | Shikhar Bhushan | |
86 | bfcf8aea | Shikhar Bhushan | Exposes an API for RPC operations as method calls. The return type of these methods depends on |
87 | bfcf8aea | Shikhar Bhushan | whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`. |
88 | 09e50473 | Shikhar Bhushan | |
89 | bfcf8aea | Shikhar Bhushan | In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object |
90 | bfcf8aea | Shikhar Bhushan | is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, |
91 | bfcf8aea | Shikhar Bhushan | an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions. |
92 | 09e50473 | Shikhar Bhushan | |
93 | bfcf8aea | Shikhar Bhushan | However in asynchronous mode, operations return immediately with an `~ncclient.operations.RPC` |
94 | bfcf8aea | Shikhar Bhushan | object. Error handling and checking for whether a reply has been received must be dealt with |
95 | bfcf8aea | Shikhar Bhushan | manually. See the `~ncclient.operations.RPC` documentation for details. |
96 | 09e50473 | Shikhar Bhushan | |
97 | bfcf8aea | Shikhar Bhushan | Note that in case of the *get* and *get-config* operations, the reply is an instance of |
98 | bfcf8aea | Shikhar Bhushan | `~ncclient.operations.GetReply` which exposes the additional attributes |
99 | bfcf8aea | Shikhar Bhushan | :attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and |
100 | bfcf8aea | Shikhar Bhushan | :attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case |
101 | bfcf8aea | Shikhar Bhushan | of these operations. |
102 | 09e50473 | Shikhar Bhushan | |
103 | bfcf8aea | Shikhar Bhushan | Presence of capabilities is verified to the extent possible, and you can expect a |
104 | bfcf8aea | Shikhar Bhushan | :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer |
105 | bfcf8aea | Shikhar Bhushan | errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised. |
106 | 09e50473 | Shikhar Bhushan | |
107 | 09e50473 | Shikhar Bhushan | .. class:: Manager |
108 | 09e50473 | Shikhar Bhushan | |
109 | 09e50473 | Shikhar Bhushan | For details on the expected behavior of the operations and their parameters |
110 | 09e50473 | Shikhar Bhushan | refer to :rfc:`4741`. |
111 | 09e50473 | Shikhar Bhushan | |
112 | 09e50473 | Shikhar Bhushan | Manager instances are also context managers so you can use it like this:: |
113 | 09e50473 | Shikhar Bhushan | |
114 | 09e50473 | Shikhar Bhushan | with manager.connect("host") as m: |
115 | 09e50473 | Shikhar Bhushan | # do your stuff |
116 | 09e50473 | Shikhar Bhushan | |
117 | 09e50473 | Shikhar Bhushan | ... or like this:: |
118 | 09e50473 | Shikhar Bhushan | |
119 | 09e50473 | Shikhar Bhushan | m = manager.connect("host") |
120 | 09e50473 | Shikhar Bhushan | try: |
121 | 09e50473 | Shikhar Bhushan | # do your stuff |
122 | 09e50473 | Shikhar Bhushan | finally: |
123 | 09e50473 | Shikhar Bhushan | m.close() |
124 | 09e50473 | Shikhar Bhushan | |
125 | 09e50473 | Shikhar Bhushan | .. method:: get_config(source[, filter=None]) |
126 | 09e50473 | Shikhar Bhushan | |
127 | 09e50473 | Shikhar Bhushan | Retrieve all or part of a specified configuration. |
128 | 09e50473 | Shikhar Bhushan | |
129 | 09e50473 | Shikhar Bhushan | :param source: name of the configuration datastore being queried |
130 | 09e50473 | Shikhar Bhushan | :type source: `string` |
131 | 09e50473 | Shikhar Bhushan | |
132 | bfcf8aea | Shikhar Bhushan | :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved) |
133 | bfcf8aea | Shikhar Bhushan | :type filter: :ref:`filter_params` |
134 | 09e50473 | Shikhar Bhushan | |
135 | 09e50473 | Shikhar Bhushan | .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None]) |
136 | 09e50473 | Shikhar Bhushan | |
137 | 09e50473 | Shikhar Bhushan | Loads all or part of a specified configuration to the specified target configuration. |
138 | 09e50473 | Shikhar Bhushan | |
139 | 09e50473 | Shikhar Bhushan | The ``"rollback-on-error"`` *error_option* depends on the ``:rollback-on-error`` capability. |
140 | 09e50473 | Shikhar Bhushan | |
141 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore being edited |
142 | 09e50473 | Shikhar Bhushan | :type target: `string` |
143 | 09e50473 | Shikhar Bhushan | |
144 | bfcf8aea | Shikhar Bhushan | :param config: configuration (must be rooted in *<config> .. </config>*) |
145 | bfcf8aea | Shikhar Bhushan | :type config: `string` or `~xml.etree.ElementTree.Element` |
146 | bfcf8aea | Shikhar Bhushan | |
147 | 09e50473 | Shikhar Bhushan | :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` } |
148 | 09e50473 | Shikhar Bhushan | :type default_operation: `string` |
149 | 09e50473 | Shikhar Bhushan | |
150 | 09e50473 | Shikhar Bhushan | :param test_option: one of { ``"test_then_set"``, ``"set"`` } |
151 | 09e50473 | Shikhar Bhushan | :type test_option: `string` |
152 | 09e50473 | Shikhar Bhushan | |
153 | 09e50473 | Shikhar Bhushan | :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` } |
154 | 09e50473 | Shikhar Bhushan | :type error_option: `string` |
155 | 09e50473 | Shikhar Bhushan | |
156 | 09e50473 | Shikhar Bhushan | .. method:: copy_config(source, target) |
157 | 09e50473 | Shikhar Bhushan | |
158 | bfcf8aea | Shikhar Bhushan | Create or replace an entire configuration datastore with the contents of another complete |
159 | bfcf8aea | Shikhar Bhushan | configuration datastore. |
160 | 09e50473 | Shikhar Bhushan | |
161 | bfcf8aea | Shikhar Bhushan | :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy |
162 | bfcf8aea | Shikhar Bhushan | :type source: :ref:`srctarget_params` |
163 | 09e50473 | Shikhar Bhushan | |
164 | bfcf8aea | Shikhar Bhushan | :param target: configuration datastore to use as the destination of the copy operation |
165 | bfcf8aea | Shikhar Bhushan | :type target: :ref:`srctarget_params` |
166 | 09e50473 | Shikhar Bhushan | |
167 | 09e50473 | Shikhar Bhushan | .. method:: delete_config(target) |
168 | 09e50473 | Shikhar Bhushan | |
169 | 09e50473 | Shikhar Bhushan | Delete a configuration datastore. |
170 | 09e50473 | Shikhar Bhushan | |
171 | bfcf8aea | Shikhar Bhushan | :param target: name or URL of configuration datastore to delete |
172 | bfcf8aea | Shikhar Bhushan | :type: :ref:`srctarget_params` |
173 | 09e50473 | Shikhar Bhushan | |
174 | 09e50473 | Shikhar Bhushan | .. method:: lock(target) |
175 | 09e50473 | Shikhar Bhushan | |
176 | 09e50473 | Shikhar Bhushan | Allows the client to lock the configuration system of a device. |
177 | 09e50473 | Shikhar Bhushan | |
178 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore to lock |
179 | 09e50473 | Shikhar Bhushan | :type target: `string` |
180 | 09e50473 | Shikhar Bhushan | |
181 | 09e50473 | Shikhar Bhushan | .. method:: unlock(target) |
182 | 09e50473 | Shikhar Bhushan | |
183 | 09e50473 | Shikhar Bhushan | Release a configuration lock, previously obtained with the |
184 | 09e50473 | Shikhar Bhushan | :meth:`~ncclient.manager.Manager.lock` operation. |
185 | 09e50473 | Shikhar Bhushan | |
186 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore to unlock |
187 | 09e50473 | Shikhar Bhushan | :type target: `string` |
188 | 09e50473 | Shikhar Bhushan | |
189 | 09e50473 | Shikhar Bhushan | .. method:: locked(target) |
190 | 09e50473 | Shikhar Bhushan | |
191 | 09e50473 | Shikhar Bhushan | Returns a context manager for a lock on a datastore, e.g.:: |
192 | 09e50473 | Shikhar Bhushan | |
193 | 09e50473 | Shikhar Bhushan | with m.locked("running"): |
194 | 09e50473 | Shikhar Bhushan | # do your stuff |
195 | 09e50473 | Shikhar Bhushan | |
196 | 09e50473 | Shikhar Bhushan | ... instead of:: |
197 | 09e50473 | Shikhar Bhushan | |
198 | 09e50473 | Shikhar Bhushan | m.lock("running") |
199 | 09e50473 | Shikhar Bhushan | try: |
200 | 09e50473 | Shikhar Bhushan | # do your stuff |
201 | 09e50473 | Shikhar Bhushan | finally: |
202 | 09e50473 | Shikhar Bhushan | m.unlock("running") |
203 | 09e50473 | Shikhar Bhushan | |
204 | bfcf8aea | Shikhar Bhushan | :param target: name of configuration datastore to lock |
205 | bfcf8aea | Shikhar Bhushan | :type target: `string` |
206 | 09e50473 | Shikhar Bhushan | |
207 | 09e50473 | Shikhar Bhushan | :rtype: `~ncclient.operations.LockContext` |
208 | 09e50473 | Shikhar Bhushan | |
209 | 09e50473 | Shikhar Bhushan | .. method:: get([filter=None]) |
210 | 09e50473 | Shikhar Bhushan | |
211 | 09e50473 | Shikhar Bhushan | Retrieve running configuration and device state information. |
212 | 09e50473 | Shikhar Bhushan | |
213 | bfcf8aea | Shikhar Bhushan | :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved) |
214 | bfcf8aea | Shikhar Bhushan | :type filter: :ref:`filter_params` |
215 | 09e50473 | Shikhar Bhushan | |
216 | 09e50473 | Shikhar Bhushan | .. method:: close_session() |
217 | 09e50473 | Shikhar Bhushan | |
218 | bfcf8aea | Shikhar Bhushan | Request graceful termination of the NETCONF session, and also close the transport. |
219 | 09e50473 | Shikhar Bhushan | |
220 | 09e50473 | Shikhar Bhushan | .. method:: kill_session(session_id) |
221 | 09e50473 | Shikhar Bhushan | |
222 | 09e50473 | Shikhar Bhushan | Force the termination of a NETCONF session (not the current one!). |
223 | 09e50473 | Shikhar Bhushan | |
224 | bfcf8aea | Shikhar Bhushan | :param session_id: session identifier of the NETCONF session to be terminated |
225 | 09e50473 | Shikhar Bhushan | :type session_id: `string` |
226 | 09e50473 | Shikhar Bhushan | |
227 | bfcf8aea | Shikhar Bhushan | .. method:: commit([confirmed=False, timeout=None]) |
228 | bfcf8aea | Shikhar Bhushan | |
229 | bfcf8aea | Shikhar Bhushan | Commit the candidate configuration as the device's new current configuration. Depends on the |
230 | bfcf8aea | Shikhar Bhushan | *:candidate* capability. |
231 | bfcf8aea | Shikhar Bhushan | |
232 | bfcf8aea | Shikhar Bhushan | A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no |
233 | bfcf8aea | Shikhar Bhushan | followup commit within the *timeout* interval. If no timeout is specified the confirm |
234 | bfcf8aea | Shikhar Bhushan | timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed* |
235 | bfcf8aea | Shikhar Bhushan | parameter but this is not required. Depends on the *:confirmed-commit* capability. |
236 | bfcf8aea | Shikhar Bhushan | |
237 | bfcf8aea | Shikhar Bhushan | :param confirmed: whether this is a confirmed commit |
238 | bfcf8aea | Shikhar Bhushan | :type confirmed: `bool` |
239 | bfcf8aea | Shikhar Bhushan | |
240 | bfcf8aea | Shikhar Bhushan | :param timeout: confirm timeout in seconds |
241 | bfcf8aea | Shikhar Bhushan | :type timeout: `int` |
242 | bfcf8aea | Shikhar Bhushan | |
243 | bfcf8aea | Shikhar Bhushan | .. method:: discard_changes() |
244 | bfcf8aea | Shikhar Bhushan | |
245 | bfcf8aea | Shikhar Bhushan | Revert the candidate configuration to the currently running configuration. Any uncommitted |
246 | bfcf8aea | Shikhar Bhushan | changes are discarded. |
247 | bfcf8aea | Shikhar Bhushan | |
248 | bfcf8aea | Shikhar Bhushan | .. method:: validate(source) |
249 | bfcf8aea | Shikhar Bhushan | |
250 | bfcf8aea | Shikhar Bhushan | Validate the contents of the specified configuration. |
251 | bfcf8aea | Shikhar Bhushan | |
252 | bfcf8aea | Shikhar Bhushan | :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated |
253 | bfcf8aea | Shikhar Bhushan | :type source: :ref:`srctarget_params` |
254 | bfcf8aea | Shikhar Bhushan | |
255 | 09e50473 | Shikhar Bhushan | .. attribute:: async_mode |
256 | 09e50473 | Shikhar Bhushan | |
257 | 09e50473 | Shikhar Bhushan | Specify whether operations are executed asynchronously (:const:`True`) |
258 | 09e50473 | Shikhar Bhushan | or synchronously (:const:`False`) (the default). |
259 | 09e50473 | Shikhar Bhushan | |
260 | 09e50473 | Shikhar Bhushan | .. attribute:: raise_mode |
261 | 09e50473 | Shikhar Bhushan | |
262 | bfcf8aea | Shikhar Bhushan | Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions. |
263 | bfcf8aea | Shikhar Bhushan | Valid values: |
264 | 09e50473 | Shikhar Bhushan | |
265 | 09e50473 | Shikhar Bhushan | * ``"all"`` -- any kind of *rpc-error* (error or warning) |
266 | 09e50473 | Shikhar Bhushan | * ``"errors"`` -- where the *error-type* attribute says it is an error |
267 | 09e50473 | Shikhar Bhushan | * ``"none"`` -- neither |
268 | 09e50473 | Shikhar Bhushan | |
269 | 09e50473 | Shikhar Bhushan | .. attribute:: client_capabilities |
270 | 09e50473 | Shikhar Bhushan | |
271 | bfcf8aea | Shikhar Bhushan | `~ncclient.capabilities.Capabilities` object representing the client's capabilities. |
272 | 09e50473 | Shikhar Bhushan | |
273 | 09e50473 | Shikhar Bhushan | .. attribute:: server_capabilities |
274 | 09e50473 | Shikhar Bhushan | |
275 | bfcf8aea | Shikhar Bhushan | `~ncclient.capabilities.Capabilities` object representing the server's capabilities. |
276 | 09e50473 | Shikhar Bhushan | |
277 | 09e50473 | Shikhar Bhushan | .. attribute:: session_id |
278 | 09e50473 | Shikhar Bhushan | |
279 | bfcf8aea | Shikhar Bhushan | *session-id* assigned by the NETCONF server. |
280 | 09e50473 | Shikhar Bhushan | |
281 | 09e50473 | Shikhar Bhushan | .. attribute:: connected |
282 | 09e50473 | Shikhar Bhushan | |
283 | bfcf8aea | Shikhar Bhushan | Bolean value indicating whether currently connected to the NETCONF server. |
284 | 09e50473 | Shikhar Bhushan | |
285 | 09e50473 | Shikhar Bhushan | |
286 | 09e50473 | Shikhar Bhushan | Special kinds of parameters |
287 | bfcf8aea | Shikhar Bhushan | --------------------------- |
288 | 09e50473 | Shikhar Bhushan | |
289 | bfcf8aea | Shikhar Bhushan | Some parameters can take on different types to keep the interface simple. |
290 | 09e50473 | Shikhar Bhushan | |
291 | 09e50473 | Shikhar Bhushan | .. _srctarget_params: |
292 | 09e50473 | Shikhar Bhushan | |
293 | 09e50473 | Shikhar Bhushan | Source and target parameters |
294 | bfcf8aea | Shikhar Bhushan | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
295 | 09e50473 | Shikhar Bhushan | |
296 | bfcf8aea | Shikhar Bhushan | Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected. |
297 | bfcf8aea | Shikhar Bhushan | The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported. |
298 | bfcf8aea | Shikhar Bhushan | Either must be specified as a `string`. For example, ``"running"``, |
299 | bfcf8aea | Shikhar Bhushan | ``"ftp://user:pass@host/config"``. |
300 | 09e50473 | Shikhar Bhushan | |
301 | bfcf8aea | Shikhar Bhushan | If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be |
302 | bfcf8aea | Shikhar Bhushan | specified as an XML string or an `~xml.etree.ElementTree.Element` object. |
303 | 09e50473 | Shikhar Bhushan | |
304 | 09e50473 | Shikhar Bhushan | .. _filter_params: |
305 | 09e50473 | Shikhar Bhushan | |
306 | 09e50473 | Shikhar Bhushan | Filter parameters |
307 | bfcf8aea | Shikhar Bhushan | ^^^^^^^^^^^^^^^^^ |
308 | 09e50473 | Shikhar Bhushan | |
309 | 09e50473 | Shikhar Bhushan | Where a method takes a *filter* argument, it can take on the following types: |
310 | 09e50473 | Shikhar Bhushan | |
311 | 09e50473 | Shikhar Bhushan | * A ``tuple`` of *(type, criteria)*. |
312 | 09e50473 | Shikhar Bhushan | |
313 | 09e50473 | Shikhar Bhushan | Here *type* has to be one of ``"xpath"`` or ``"subtree"``. |
314 | 09e50473 | Shikhar Bhushan | |
315 | bfcf8aea | Shikhar Bhushan | * For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression. |
316 | 09e50473 | Shikhar Bhushan | * For ``"subtree"`` the *criteria* should be an XML string or an |
317 | 09e50473 | Shikhar Bhushan | `~xml.etree.ElementTree.Element` object containing the criteria. |
318 | 09e50473 | Shikhar Bhushan | |
319 | bfcf8aea | Shikhar Bhushan | * A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` object. |