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