Revision fd2db1e1
/dev/null | ||
---|---|---|
1 |
# Makefile for Sphinx documentation |
|
2 |
# |
|
3 |
|
|
4 |
# You can set these variables from the command line. |
|
5 |
SPHINXOPTS = |
|
6 |
SPHINXBUILD = sphinx-build |
|
7 |
PAPER = |
|
8 |
|
|
9 |
# Internal variables. |
|
10 |
PAPEROPT_a4 = -D latex_paper_size=a4 |
|
11 |
PAPEROPT_letter = -D latex_paper_size=letter |
|
12 |
ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source |
|
13 |
|
|
14 |
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest |
|
15 |
|
|
16 |
help: |
|
17 |
@echo "Please use \`make <target>' where <target> is one of" |
|
18 |
@echo " html to make standalone HTML files" |
|
19 |
@echo " dirhtml to make HTML files named index.html in directories" |
|
20 |
@echo " pickle to make pickle files" |
|
21 |
@echo " json to make JSON files" |
|
22 |
@echo " htmlhelp to make HTML files and a HTML help project" |
|
23 |
@echo " qthelp to make HTML files and a qthelp project" |
|
24 |
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
|
25 |
@echo " changes to make an overview of all changed/added/deprecated items" |
|
26 |
@echo " linkcheck to check all external links for integrity" |
|
27 |
@echo " doctest to run all doctests embedded in the documentation (if enabled)" |
|
28 |
|
|
29 |
clean: |
|
30 |
-rm -rf build/* |
|
31 |
|
|
32 |
html: |
|
33 |
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html |
|
34 |
@echo |
|
35 |
@echo "Build finished. The HTML pages are in build/html." |
|
36 |
|
|
37 |
dirhtml: |
|
38 |
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml |
|
39 |
@echo |
|
40 |
@echo "Build finished. The HTML pages are in build/dirhtml." |
|
41 |
|
|
42 |
pickle: |
|
43 |
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle |
|
44 |
@echo |
|
45 |
@echo "Build finished; now you can process the pickle files." |
|
46 |
|
|
47 |
json: |
|
48 |
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json |
|
49 |
@echo |
|
50 |
@echo "Build finished; now you can process the JSON files." |
|
51 |
|
|
52 |
htmlhelp: |
|
53 |
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp |
|
54 |
@echo |
|
55 |
@echo "Build finished; now you can run HTML Help Workshop with the" \ |
|
56 |
".hhp project file in build/htmlhelp." |
|
57 |
|
|
58 |
qthelp: |
|
59 |
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp |
|
60 |
@echo |
|
61 |
@echo "Build finished; now you can run "qcollectiongenerator" with the" \ |
|
62 |
".qhcp project file in build/qthelp, like this:" |
|
63 |
@echo "# qcollectiongenerator build/qthelp/ncclient.qhcp" |
|
64 |
@echo "To view the help file:" |
|
65 |
@echo "# assistant -collectionFile build/qthelp/ncclient.qhc" |
|
66 |
|
|
67 |
latex: |
|
68 |
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex |
|
69 |
@echo |
|
70 |
@echo "Build finished; the LaTeX files are in build/latex." |
|
71 |
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
|
72 |
"run these through (pdf)latex." |
|
73 |
|
|
74 |
changes: |
|
75 |
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes |
|
76 |
@echo |
|
77 |
@echo "The overview file is in build/changes." |
|
78 |
|
|
79 |
linkcheck: |
|
80 |
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck |
|
81 |
@echo |
|
82 |
@echo "Link check complete; look for any errors in the above output " \ |
|
83 |
"or in build/linkcheck/output.txt." |
|
84 |
|
|
85 |
doctest: |
|
86 |
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest |
|
87 |
@echo "Testing of doctests in the sources finished, look at the " \ |
|
88 |
"results in build/doctest/output.txt." |
/dev/null | ||
---|---|---|
1 |
# -*- coding: utf-8 -*- |
|
2 |
# This file is execfile()d with the current directory set to its containing dir. |
|
3 |
# |
|
4 |
# Note that not all possible configuration values are present in this |
|
5 |
# autogenerated file. |
|
6 |
# |
|
7 |
# All configuration values have a default; values that are commented out |
|
8 |
# serve to show the default. |
|
9 |
|
|
10 |
import sys, os |
|
11 |
|
|
12 |
# If extensions (or modules to document with autodoc) are in another directory, |
|
13 |
# add these directories to sys.path here. If the directory is relative to the |
|
14 |
# documentation root, use os.path.abspath to make it absolute, like shown here. |
|
15 |
#sys.path.append(os.path.abspath('.')) |
|
16 |
|
|
17 |
# -- General configuration ----------------------------------------------------- |
|
18 |
|
|
19 |
# Add any Sphinx extension module names here, as strings. They can be extensions |
|
20 |
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
|
21 |
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', |
|
22 |
'sphinx.ext.graphviz', 'sphinx.ext.inheritance_diagram'] |
|
23 |
|
|
24 |
# Add any paths that contain templates here, relative to this directory. |
|
25 |
templates_path = ['_templates'] |
|
26 |
|
|
27 |
# The suffix of source filenames. |
|
28 |
source_suffix = '.rst' |
|
29 |
|
|
30 |
# The encoding of source files. |
|
31 |
#source_encoding = 'utf-8' |
|
32 |
|
|
33 |
# The master toctree document. |
|
34 |
master_doc = 'index' |
|
35 |
|
|
36 |
# General information about the project. |
|
37 |
project = u'ncclient' |
|
38 |
copyright = u'2009, Shikhar Bhushan' |
|
39 |
license = 'APL' |
|
40 |
|
|
41 |
# The version info for the project you're documenting, acts as replacement for |
|
42 |
# |version| and |release|, also used in various other places throughout the |
|
43 |
# built documents. |
|
44 |
# |
|
45 |
# The short X.Y version. |
|
46 |
version = '0.1' |
|
47 |
# The full version, including alpha/beta/rc tags. |
|
48 |
release = '0.1.0' |
|
49 |
|
|
50 |
# The language for content autogenerated by Sphinx. Refer to documentation |
|
51 |
# for a list of supported languages. |
|
52 |
#language = None |
|
53 |
|
|
54 |
# There are two options for replacing |today|: either, you set today to some |
|
55 |
# non-false value, then it is used: |
|
56 |
#today = '' |
|
57 |
# Else, today_fmt is used as the format for a strftime call. |
|
58 |
#today_fmt = '%B %d, %Y' |
|
59 |
|
|
60 |
# List of documents that shouldn't be included in the build. |
|
61 |
#unused_docs = [] |
|
62 |
|
|
63 |
# List of directories, relative to source directory, that shouldn't be searched |
|
64 |
# for source files. |
|
65 |
exclude_trees = [] |
|
66 |
|
|
67 |
# The reST default role (used for this markup: `text`) to use for all documents. |
|
68 |
default_role = 'obj' |
|
69 |
|
|
70 |
# If true, '()' will be appended to :func: etc. cross-reference text. |
|
71 |
#add_function_parentheses = True |
|
72 |
|
|
73 |
# If true, the current module name will be prepended to all description |
|
74 |
# unit titles (such as .. function::). |
|
75 |
#add_module_names = True |
|
76 |
|
|
77 |
# If true, sectionauthor and moduleauthor directives will be shown in the |
|
78 |
# output. They are ignored by default. |
|
79 |
#show_authors = False |
|
80 |
|
|
81 |
# The name of the Pygments (syntax highlighting) style to use. |
|
82 |
pygments_style = 'sphinx' |
|
83 |
|
|
84 |
# A list of ignored prefixes for module index sorting. |
|
85 |
modindex_common_prefix = ['ncclient.'] |
|
86 |
|
|
87 |
|
|
88 |
# -- Options for HTML output --------------------------------------------------- |
|
89 |
|
|
90 |
# The theme to use for HTML and HTML Help pages. Major themes that come with |
|
91 |
# Sphinx are currently 'default' and 'sphinxdoc'. |
|
92 |
html_theme = 'default' |
|
93 |
|
|
94 |
# Theme options are theme-specific and customize the look and feel of a theme |
|
95 |
# further. For a list of options available for each theme, see the |
|
96 |
# documentation. |
|
97 |
#html_theme_options = {} |
|
98 |
|
|
99 |
# Add any paths that contain custom themes here, relative to this directory. |
|
100 |
#html_theme_path = [] |
|
101 |
|
|
102 |
# The name for this set of Sphinx documents. If None, it defaults to |
|
103 |
# "<project> v<release> documentation". |
|
104 |
#html_title = None |
|
105 |
|
|
106 |
# A shorter title for the navigation bar. Default is the same as html_title. |
|
107 |
#html_short_title = None |
|
108 |
|
|
109 |
# The name of an image file (relative to this directory) to place at the top |
|
110 |
# of the sidebar. |
|
111 |
#html_logo = None |
|
112 |
|
|
113 |
# The name of an image file (within the static path) to use as favicon of the |
|
114 |
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
|
115 |
# pixels large. |
|
116 |
#html_favicon = None |
|
117 |
|
|
118 |
# Add any paths that contain custom static files (such as style sheets) here, |
|
119 |
# relative to this directory. They are copied after the builtin static files, |
|
120 |
# so a file named "default.css" will overwrite the builtin "default.css". |
|
121 |
html_static_path = ['_static'] |
|
122 |
|
|
123 |
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
|
124 |
# using the given strftime format. |
|
125 |
#html_last_updated_fmt = '%b %d, %Y' |
|
126 |
|
|
127 |
# If true, SmartyPants will be used to convert quotes and dashes to |
|
128 |
# typographically correct entities. |
|
129 |
#html_use_smartypants = True |
|
130 |
|
|
131 |
# Custom sidebar templates, maps document names to template names. |
|
132 |
#html_sidebars = {} |
|
133 |
|
|
134 |
# Additional templates that should be rendered to pages, maps page names to |
|
135 |
# template names. |
|
136 |
#html_additional_pages = {} |
|
137 |
|
|
138 |
# If false, no module index is generated. |
|
139 |
#html_use_modindex = True |
|
140 |
|
|
141 |
# If false, no index is generated. |
|
142 |
#html_use_index = True |
|
143 |
|
|
144 |
# If true, the index is split into individual pages for each letter. |
|
145 |
#html_split_index = False |
|
146 |
|
|
147 |
# If true, links to the reST sources are added to the pages. |
|
148 |
#html_show_sourcelink = True |
|
149 |
|
|
150 |
# If true, an OpenSearch description file will be output, and all pages will |
|
151 |
# contain a <link> tag referring to it. The value of this option must be the |
|
152 |
# base URL from which the finished HTML is served. |
|
153 |
#html_use_opensearch = '' |
|
154 |
|
|
155 |
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
|
156 |
#html_file_suffix = '' |
|
157 |
|
|
158 |
# Output file base name for HTML help builder. |
|
159 |
htmlhelp_basename = 'ncclientdoc' |
|
160 |
|
|
161 |
|
|
162 |
# -- Options for LaTeX output -------------------------------------------------- |
|
163 |
|
|
164 |
# The paper size ('letter' or 'a4'). |
|
165 |
latex_paper_size = 'a4' |
|
166 |
|
|
167 |
# The font size ('10pt', '11pt' or '12pt'). |
|
168 |
#latex_font_size = '10pt' |
|
169 |
|
|
170 |
# Grouping the document tree into LaTeX files. List of tuples |
|
171 |
# (source start file, target name, title, author, documentclass [howto/manual]). |
|
172 |
latex_documents = [ |
|
173 |
('index', 'ncclient.tex', u'NCClient Documentation', |
|
174 |
u'Shikhar Bhushan', 'manual', True), |
|
175 |
] |
|
176 |
|
|
177 |
# The name of an image file (relative to this directory) to place at the top of |
|
178 |
# the title page. |
|
179 |
#latex_logo = None |
|
180 |
|
|
181 |
# For "manual" documents, if this is true, then toplevel headings are parts, |
|
182 |
# not chapters. |
|
183 |
#latex_use_parts = True |
|
184 |
|
|
185 |
# Additional stuff for the LaTeX preamble. |
|
186 |
latex_preamble = '' |
|
187 |
|
|
188 |
# Documents to append as an appendix to all manuals. |
|
189 |
#latex_appendices = [] |
|
190 |
|
|
191 |
# If false, no module index is generated. |
|
192 |
#latex_use_modindex = True |
|
193 |
|
|
194 |
|
|
195 |
# Example configuration for intersphinx: refer to the Python standard library. |
|
196 |
intersphinx_mapping = {'http://docs.python.org/': None} |
/dev/null | ||
---|---|---|
1 |
.. _extending: |
|
2 |
|
|
3 |
################## |
|
4 |
Extending NCClient |
|
5 |
################## |
|
6 |
|
|
7 |
This is written in a 'how-to' style through code examples. |
|
8 |
|
|
9 |
*Forthcoming* |
/dev/null | ||
---|---|---|
1 |
|
|
2 |
.. toctree:: |
|
3 |
|
|
4 |
intro |
|
5 |
userdoc |
|
6 |
extending |
|
7 |
|
|
8 |
* :ref:`genindex` |
|
9 |
|
/dev/null | ||
---|---|---|
1 |
************* |
|
2 |
Introduction |
|
3 |
************* |
|
4 |
|
|
5 |
NCClient is a Python library for NETCONF clients. NETCONF is a network management protocol defined in :rfc:`4741`. |
|
6 |
|
|
7 |
It is meant for Python 2.6+ (not Python 3 yet, though). |
|
8 |
|
|
9 |
The features of NCClient include: |
|
10 |
|
|
11 |
* Request pipelining. |
|
12 |
* (A)synchronous RPC requests. |
|
13 |
* Keeps XML out of the way unless really needed. |
|
14 |
* Supports all operations and capabilities defined in :rfc:`4741`. |
|
15 |
* Extensible. New transport mappings and capabilities/operations can be easily added. |
|
16 |
|
|
17 |
The best way to introduce is of course, through a simple code example:: |
|
18 |
|
|
19 |
from ncclient import manager |
|
20 |
|
|
21 |
# use ssh-agent or ~/.ssh keys for auth, load known_hosts by default |
|
22 |
with manager.connect_ssh('host', username='username') as m: |
|
23 |
assert(":url" in manager.server_capabilities) |
|
24 |
with m.locked('running'): |
|
25 |
m.copy_config(source="running", target="file://new_checkpoint.conf") |
|
26 |
m.copy_config(source="file://old_checkpoint.conf", target="running") |
|
27 |
|
|
28 |
It is recommended to use the high-level :class:`Manager` API where possible. It exposes all of the functionality except asynchronous RPC requests. |
|
29 |
|
/dev/null | ||
---|---|---|
1 |
.. _userdoc: |
|
2 |
|
|
3 |
################## |
|
4 |
User documentation |
|
5 |
################## |
|
6 |
|
|
7 |
.. toctree:: |
|
8 |
|
|
9 |
userdoc/manager |
|
10 |
userdoc/capabilities |
|
11 |
userdoc/xml |
|
12 |
userdoc/transport |
|
13 |
userdoc/operations |
/dev/null | ||
---|---|---|
1 |
*************************** |
|
2 |
:mod:`capabilities` module |
|
3 |
*************************** |
|
4 |
|
|
5 |
.. automodule:: ncclient.capabilities |
|
6 |
|
|
7 |
.. autodata:: CAPABILITIES |
|
8 |
|
|
9 |
.. autoclass:: Capabilities |
|
10 |
:members: |
/dev/null | ||
---|---|---|
1 |
********************* |
|
2 |
:mod:`manager` module |
|
3 |
********************* |
|
4 |
|
|
5 |
.. module:: ncclient.manager |
|
6 |
|
|
7 |
Dealing with RPC errors |
|
8 |
======================= |
|
9 |
|
|
10 |
These constants define what :class:`Manager` does when an *<rpc-error>* element is encountered in a reply. |
|
11 |
|
|
12 |
.. autodata:: RAISE_ALL |
|
13 |
|
|
14 |
.. autodata:: RAISE_ERR |
|
15 |
|
|
16 |
.. autodata:: RAISE_NONE |
|
17 |
|
|
18 |
|
|
19 |
Manager instances |
|
20 |
================= |
|
21 |
|
|
22 |
:class:`Manager` instances are created by the :meth:`connect` family of factory functions. Currently only :meth:`connect_ssh` is available. |
|
23 |
|
|
24 |
.. autofunction:: connect |
|
25 |
|
|
26 |
.. autofunction:: connect_ssh |
|
27 |
|
|
28 |
|
|
29 |
.. autoclass:: Manager |
|
30 |
:members: set_rpc_error_action, get, get_config, edit_config, copy_config, validate, commit, discard_changes, delete_config, lock, unlock, close_session, kill_session, locked, close, client_capabilities, server_capabilities, session_id, connected |
/dev/null | ||
---|---|---|
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: |
/dev/null | ||
---|---|---|
1 |
:mod:`transport` module |
|
2 |
======================== |
|
3 |
|
|
4 |
.. module:: ncclient.transport |
|
5 |
:synopsis: Transport protocol layer |
|
6 |
.. moduleauthor:: Shikhar Bhushan <shikhar@schmizz.net> |
|
7 |
|
|
8 |
Base types |
|
9 |
----------- |
|
10 |
|
|
11 |
.. autoclass:: Session |
|
12 |
:members: add_listener, remove_listener, get_listener_instance, client_capabilities, server_capabilities, connected, id, can_pipeline |
|
13 |
|
|
14 |
.. autoclass:: SessionListener |
|
15 |
:members: callback, errback |
|
16 |
|
|
17 |
SSH session implementation |
|
18 |
-------------------------- |
|
19 |
|
|
20 |
.. automethod:: ssh.default_unknown_host_cb |
|
21 |
|
|
22 |
.. autoclass:: SSHSession |
|
23 |
:show-inheritance: |
|
24 |
:members: load_known_hosts, close, transport |
|
25 |
|
|
26 |
.. automethod:: connect(host[, port=830, timeout=None, username=None, password=None, key_filename=None, allow_agent=True, look_for_keys=True]) |
|
27 |
|
|
28 |
Errors |
|
29 |
------ |
|
30 |
|
|
31 |
.. autoexception:: TransportError |
|
32 |
:show-inheritance: |
|
33 |
|
|
34 |
.. autoexception:: SessionCloseError |
|
35 |
:show-inheritance: |
|
36 |
|
|
37 |
.. autoexception:: SSHError |
|
38 |
:show-inheritance: |
|
39 |
|
|
40 |
.. autoexception:: AuthenticationError |
|
41 |
:show-inheritance: |
|
42 |
|
|
43 |
.. autoexception:: SSHUnknownHostError |
|
44 |
:show-inheritance: |
|
45 |
|
/dev/null | ||
---|---|---|
1 |
********************** |
|
2 |
:mod:`xml_` module |
|
3 |
********************** |
|
4 |
|
|
5 |
.. automodule:: ncclient.xml_ |
|
6 |
:synopsis: XML facilities |
|
7 |
|
|
8 |
Namespaces |
|
9 |
========== |
|
10 |
|
|
11 |
The following namespace is defined in this module. |
|
12 |
|
|
13 |
.. autodata:: BASE_NS |
|
14 |
|
|
15 |
Namespaces are handled just the same way as :mod:`~xml.etree.ElementTree`. So a qualified name takes the form *{namespace}tag*. There are some utility functions for qualified names: |
|
16 |
|
|
17 |
.. function:: qualify(tag[, ns=BASE_NS]) |
|
18 |
|
|
19 |
:returns: qualified name |
|
20 |
|
|
21 |
.. function:: unqualify(tag) |
|
22 |
|
|
23 |
:returns: unqualified name |
|
24 |
|
|
25 |
.. note:: It is strongly recommended to compare qualified names. |
|
26 |
|
|
27 |
.. _dtree: |
|
28 |
|
|
29 |
DictTree XML representation |
|
30 |
=========================== |
|
31 |
|
|
32 |
.. note:: |
|
33 |
Where this representation is stipulated, an XML literal or :class:`~xml.etree.ElementTree.Element` is just fine as well. |
|
34 |
|
|
35 |
:mod:`ncclient` can make use of a special syntax for XML based on Python dictionaries. It is best illustrated through an example:: |
|
36 |
|
|
37 |
dtree = { |
|
38 |
'tag': qualify('a', 'some_namespace'), |
|
39 |
'attrib': {'attr': 'val'}, |
|
40 |
'subtree': [ { 'tag': 'child1' }, { 'tag': 'child2', 'text': 'some text' } ] |
|
41 |
} |
|
42 |
|
|
43 |
Calling :func:`dtree2xml` on *dtree* would return |
|
44 |
|
|
45 |
.. code-block:: xml |
|
46 |
|
|
47 |
<?xml version="1.0" encoding="UTF-8"?> |
|
48 |
<ns0:a attr="val" xmlns:ns0="some_namespace"> |
|
49 |
<child1 /> |
|
50 |
<child2>some text</child2> |
|
51 |
</ns0:a> |
|
52 |
|
|
53 |
In addition to a 'pure' dictionary representation a DictTree node (including the root) may be an XML literal or an :class:`~xml.etree.ElementTree.Element` instance. The above example could thus be equivalently written as:: |
|
54 |
|
|
55 |
dtree2 = { |
|
56 |
'tag': '{ns}a', |
|
57 |
'attrib': {'attr': 'val'}, |
|
58 |
'subtree': [ ET.Element('child1'), '<child2>some text</child2>' ] |
|
59 |
} |
|
60 |
|
|
61 |
Converting between different representations |
|
62 |
============================================ |
|
63 |
|
|
64 |
Conversions *to* DictTree representation are guaranteed to be entirely dictionaries. In converting *from* DictTree representation, the argument may be any valid representation as specified. |
|
65 |
|
|
66 |
.. autofunction:: dtree2ele(spec) |
|
67 |
|
|
68 |
.. autofunction:: dtree2xml(spec[, encoding="UTF-8"]) |
|
69 |
|
|
70 |
.. autofunction:: ele2dtree(ele) |
|
71 |
|
|
72 |
.. autofunction:: ele2xml(ele) |
|
73 |
|
|
74 |
.. autofunction:: xml2dtree(xml) |
|
75 |
|
|
76 |
.. autofunction:: xml2ele(xml) |
|
77 |
|
|
78 |
Other utility functions |
|
79 |
======================== |
|
80 |
|
|
81 |
.. autofunction:: iselement(obj) |
|
82 |
|
|
83 |
:see: :meth:`xml.etree.ElementTree.iselement` |
|
84 |
|
|
85 |
.. autofunction:: find(ele, tag[, nslist=[]]) |
|
86 |
|
|
87 |
.. autofunction:: parse_root(raw) |
|
88 |
|
|
89 |
.. autofunction:: validated_element(rep, tag=None, attrs=None, text=None) |
|
90 |
|
|
91 |
|
|
92 |
Errors |
|
93 |
====== |
|
94 |
|
|
95 |
.. autoexception:: ContentError |
|
96 |
:show-inheritance: |
|
97 |
:members: |
|
98 |
|
Also available in: Unified diff