+++ /dev/null
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
-help:
- @echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
-
-clean:
- -rm -rf build/*
-
-html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
- @echo
- @echo "Build finished. The HTML pages are in build/html."
-
-dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in build/dirhtml."
-
-pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in build/htmlhelp."
-
-qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in build/qthelp, like this:"
- @echo "# qcollectiongenerator build/qthelp/ncclient.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile build/qthelp/ncclient.qhc"
-
-latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
- @echo
- @echo "Build finished; the LaTeX files are in build/latex."
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
- "run these through (pdf)latex."
-
-changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
- @echo
- @echo "The overview file is in build/changes."
-
-linkcheck:
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in build/linkcheck/output.txt."
-
-doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest
- @echo "Testing of doctests in the sources finished, look at the " \
- "results in build/doctest/output.txt."
+++ /dev/null
-# -*- coding: utf-8 -*-
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
-
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
- 'sphinx.ext.graphviz', 'sphinx.ext.inheritance_diagram']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'ncclient'
-copyright = u'2009, Shikhar Bhushan'
-license = 'APL'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.1'
-# The full version, including alpha/beta/rc tags.
-release = '0.1.0'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-default_role = 'obj'
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-modindex_common_prefix = ['ncclient.']
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_use_modindex = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'ncclientdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
- ('index', 'ncclient.tex', u'NCClient Documentation',
- u'Shikhar Bhushan', 'manual', True),
- ]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = True
-
-# Additional stuff for the LaTeX preamble.
-latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+++ /dev/null
-.. _extending:
-
-##################
-Extending NCClient
-##################
-
-This is written in a 'how-to' style through code examples.
-
-*Forthcoming*
+++ /dev/null
-
-.. toctree::
-
- intro
- userdoc
- extending
-
-* :ref:`genindex`
-
+++ /dev/null
-*************
-Introduction
-*************
-
-NCClient is a Python library for NETCONF clients. NETCONF is a network management protocol defined in :rfc:`4741`.
-
-It is meant for Python 2.6+ (not Python 3 yet, though).
-
-The features of NCClient include:
-
-* Request pipelining.
-* (A)synchronous RPC requests.
-* Keeps XML out of the way unless really needed.
-* Supports all operations and capabilities defined in :rfc:`4741`.
-* Extensible. New transport mappings and capabilities/operations can be easily added.
-
-The best way to introduce is of course, through a simple code example::
-
- from ncclient import manager
-
- # use ssh-agent or ~/.ssh keys for auth, load known_hosts by default
- with manager.connect_ssh('host', username='username') as m:
- assert(":url" in manager.server_capabilities)
- with m.locked('running'):
- m.copy_config(source="running", target="file://new_checkpoint.conf")
- m.copy_config(source="file://old_checkpoint.conf", target="running")
-
-It is recommended to use the high-level :class:`Manager` API where possible. It exposes all of the functionality except asynchronous RPC requests.
-
+++ /dev/null
-.. _userdoc:
-
-##################
-User documentation
-##################
-
-.. toctree::
-
- userdoc/manager
- userdoc/capabilities
- userdoc/xml
- userdoc/transport
- userdoc/operations
+++ /dev/null
-***************************
-:mod:`capabilities` module
-***************************
-
-.. automodule:: ncclient.capabilities
-
-.. autodata:: CAPABILITIES
-
-.. autoclass:: Capabilities
- :members:
+++ /dev/null
-*********************
-:mod:`manager` module
-*********************
-
-.. module:: ncclient.manager
-
-Dealing with RPC errors
-=======================
-
-These constants define what :class:`Manager` does when an *<rpc-error>* element is encountered in a reply.
-
-.. autodata:: RAISE_ALL
-
-.. autodata:: RAISE_ERR
-
-.. autodata:: RAISE_NONE
-
-
-Manager instances
-=================
-
-:class:`Manager` instances are created by the :meth:`connect` family of factory functions. Currently only :meth:`connect_ssh` is available.
-
-.. autofunction:: connect
-
-.. autofunction:: connect_ssh
-
-
-.. autoclass:: Manager
- :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
-************************
-:mod:`operations` module
-************************
-
-.. automodule:: ncclient.operations
- :synopsis: RPC and Operation layers
-
-Base types
-==========
-
-.. currentmodule:: ncclient.operations.rpc
-
-.. autoclass:: RPC(session[, async=False, timeout=None])
- :members: set_async, set_timeout, reply, error, event, async, timeout, id, session
-
-.. autoclass:: RPCReply
- :members: ok, error, errors
-
-.. autoclass:: RPCError
- :members: type, severity, tag, path, message, info
- :show-inheritance:
-
-NETCONF Operations
-==================
-
-.. currentmodule:: ncclient.operations
-
-Dependencies
--------------
-
-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.
-
-.. _return:
-
-Return type
------------
-
-The return type for the :meth:`request` method depends of an operation on whether it is synchronous or asynchronous (see base class :class:`RPC`).
-
-* 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.
-
-* 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 :-)
-
-General notes on parameters
-----------------------------
-
-.. _source_target:
-
-Source / target parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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`.
-
-If the source may be a *<config>* element, e.g. for :class:`Validate`, specify in :ref:`dtree` with the root element as *<config>*.
-
-.. _filter:
-
-Filter parameters
-^^^^^^^^^^^^^^^^^^
-
-Filter parameters, where applicable, can take one of the following types:
-
-* A `tuple` of *(type, criteria)*.
- 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.
-* A valid *<filter>* element in :ref:`dtree`.
-
-Retrieval operations
---------------------
-
-The reply object for these operations will be a :class:`GetReply` instance.
-
-.. autoclass:: Get
- :show-inheritance:
- :members: request
-
-.. autoclass:: GetConfig
- :show-inheritance:
- :members: request
-
-.. autoclass:: GetReply
- :show-inheritance:
- :members: data, data_xml, data_dtree, data_ele
-
-Locking operations
-------------------
-
-.. autoclass:: Lock
- :show-inheritance:
- :members: request
-
-.. autoclass:: Unlock
- :show-inheritance:
- :members: request
-
-Configuration operations
--------------------------
-
-.. autoclass:: EditConfig
- :show-inheritance:
- :members: request
-
-.. autoclass:: CopyConfig
- :show-inheritance:
- :members: request
-
-.. autoclass:: DeleteConfig
- :show-inheritance:
- :members: request
-
-.. autoclass:: Validate
- :show-inheritance:
- :members: request
-
-.. autoclass:: Commit
- :show-inheritance:
- :members: request
-
-.. autoclass:: DiscardChanges
- :show-inheritance:
- :members: request
-
-Session management operations
-------------------------------
-
-.. autoclass:: CloseSession
- :show-inheritance:
- :members: request
-
-.. autoclass:: KillSession
- :show-inheritance:
- :members: request
-
-Also useful
------------
-
-.. autoclass:: LockContext
-
-
-Errors
-=======
-
-.. autoexception:: OperationError
- :show-inheritance:
- :members:
-
-.. autoexception:: TimeoutExpiredError
- :show-inheritance:
- :members:
-
-.. autoexception:: MissingCapabilityError
- :show-inheritance:
- :members:
\ No newline at end of file
+++ /dev/null
-:mod:`transport` module
-========================
-
-.. module:: ncclient.transport
- :synopsis: Transport protocol layer
-.. moduleauthor:: Shikhar Bhushan <shikhar@schmizz.net>
-
-Base types
------------
-
-.. autoclass:: Session
- :members: add_listener, remove_listener, get_listener_instance, client_capabilities, server_capabilities, connected, id, can_pipeline
-
-.. autoclass:: SessionListener
- :members: callback, errback
-
-SSH session implementation
---------------------------
-
-.. automethod:: ssh.default_unknown_host_cb
-
-.. autoclass:: SSHSession
- :show-inheritance:
- :members: load_known_hosts, close, transport
-
- .. automethod:: connect(host[, port=830, timeout=None, username=None, password=None, key_filename=None, allow_agent=True, look_for_keys=True])
-
-Errors
-------
-
-.. autoexception:: TransportError
- :show-inheritance:
-
-.. autoexception:: SessionCloseError
- :show-inheritance:
-
-.. autoexception:: SSHError
- :show-inheritance:
-
-.. autoexception:: AuthenticationError
- :show-inheritance:
-
-.. autoexception:: SSHUnknownHostError
- :show-inheritance:
-
+++ /dev/null
-**********************
-:mod:`xml_` module
-**********************
-
-.. automodule:: ncclient.xml_
- :synopsis: XML facilities
-
-Namespaces
-==========
-
-The following namespace is defined in this module.
-
-.. autodata:: BASE_NS
-
-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:
-
-.. function:: qualify(tag[, ns=BASE_NS])
-
- :returns: qualified name
-
-.. function:: unqualify(tag)
-
- :returns: unqualified name
-
- .. note:: It is strongly recommended to compare qualified names.
-
-.. _dtree:
-
-DictTree XML representation
-===========================
-
-.. note::
- Where this representation is stipulated, an XML literal or :class:`~xml.etree.ElementTree.Element` is just fine as well.
-
-:mod:`ncclient` can make use of a special syntax for XML based on Python dictionaries. It is best illustrated through an example::
-
- dtree = {
- 'tag': qualify('a', 'some_namespace'),
- 'attrib': {'attr': 'val'},
- 'subtree': [ { 'tag': 'child1' }, { 'tag': 'child2', 'text': 'some text' } ]
- }
-
-Calling :func:`dtree2xml` on *dtree* would return
-
-.. code-block:: xml
-
- <?xml version="1.0" encoding="UTF-8"?>
- <ns0:a attr="val" xmlns:ns0="some_namespace">
- <child1 />
- <child2>some text</child2>
- </ns0:a>
-
-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::
-
- dtree2 = {
- 'tag': '{ns}a',
- 'attrib': {'attr': 'val'},
- 'subtree': [ ET.Element('child1'), '<child2>some text</child2>' ]
- }
-
-Converting between different representations
-============================================
-
-Conversions *to* DictTree representation are guaranteed to be entirely dictionaries. In converting *from* DictTree representation, the argument may be any valid representation as specified.
-
-.. autofunction:: dtree2ele(spec)
-
-.. autofunction:: dtree2xml(spec[, encoding="UTF-8"])
-
-.. autofunction:: ele2dtree(ele)
-
-.. autofunction:: ele2xml(ele)
-
-.. autofunction:: xml2dtree(xml)
-
-.. autofunction:: xml2ele(xml)
-
-Other utility functions
-========================
-
-.. autofunction:: iselement(obj)
-
- :see: :meth:`xml.etree.ElementTree.iselement`
-
-.. autofunction:: find(ele, tag[, nslist=[]])
-
-.. autofunction:: parse_root(raw)
-
-.. autofunction:: validated_element(rep, tag=None, attrs=None, text=None)
-
-
-Errors
-======
-
-.. autoexception:: ContentError
- :show-inheritance:
- :members:
-
projects / ncclient / commitdiff