% Generated by Sphinx.
\documentclass[a4paper,10pt,english]{manual}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}


\title{NCClient Documentation}
\date{May 17, 2009}
\release{0.1.1a}
\author{Shikhar Bhushan}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex
\makemodindex
\newcommand\PYGZat{@}
\newcommand\PYGZlb{[}
\newcommand\PYGZrb{]}
\newcommand\PYGaz[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}}
\newcommand\PYGax[1]{\textcolor[rgb]{0.84,0.33,0.22}{\textbf{#1}}}
\newcommand\PYGay[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand\PYGar[1]{\textcolor[rgb]{0.73,0.38,0.84}{#1}}
\newcommand\PYGas[1]{\textcolor[rgb]{0.25,0.44,0.63}{\textit{#1}}}
\newcommand\PYGap[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand\PYGaq[1]{\textcolor[rgb]{0.38,0.68,0.84}{#1}}
\newcommand\PYGav[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand\PYGaw[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGat[1]{\textcolor[rgb]{0.73,0.38,0.84}{#1}}
\newcommand\PYGau[1]{\textcolor[rgb]{0.32,0.47,0.09}{#1}}
\newcommand\PYGaj[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand\PYGak[1]{\textcolor[rgb]{0.14,0.33,0.53}{#1}}
\newcommand\PYGah[1]{\textcolor[rgb]{0.00,0.13,0.44}{\textbf{#1}}}
\newcommand\PYGai[1]{\textcolor[rgb]{0.73,0.38,0.84}{#1}}
\newcommand\PYGan[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGao[1]{\textcolor[rgb]{0.25,0.44,0.63}{\textbf{#1}}}
\newcommand\PYGal[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand\PYGam[1]{\textbf{#1}}
\newcommand\PYGab[1]{\textit{#1}}
\newcommand\PYGac[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGaa[1]{\textcolor[rgb]{0.19,0.19,0.19}{#1}}
\newcommand\PYGaf[1]{\textcolor[rgb]{0.25,0.50,0.56}{\textit{#1}}}
\newcommand\PYGag[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGad[1]{\textcolor[rgb]{0.00,0.25,0.82}{#1}}
\newcommand\PYGae[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGaZ[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGbf[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand\PYGaX[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGaY[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand\PYGbc[1]{\textcolor[rgb]{0.78,0.36,0.04}{#1}}
\newcommand\PYGbb[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}}
\newcommand\PYGba[1]{\textcolor[rgb]{0.02,0.16,0.45}{\textbf{#1}}}
\newcommand\PYGaR[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGaS[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGaP[1]{\textcolor[rgb]{0.05,0.52,0.71}{\textbf{#1}}}
\newcommand\PYGaQ[1]{\textcolor[rgb]{0.78,0.36,0.04}{\textbf{#1}}}
\newcommand\PYGaV[1]{\textcolor[rgb]{0.25,0.50,0.56}{\textit{#1}}}
\newcommand\PYGaW[1]{\textcolor[rgb]{0.05,0.52,0.71}{\textbf{#1}}}
\newcommand\PYGaT[1]{\textcolor[rgb]{0.73,0.38,0.84}{#1}}
\newcommand\PYGaU[1]{\textcolor[rgb]{0.13,0.50,0.31}{#1}}
\newcommand\PYGaJ[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}}
\newcommand\PYGaK[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGaH[1]{\textcolor[rgb]{0.50,0.00,0.50}{\textbf{#1}}}
\newcommand\PYGaI[1]{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{#1}}
\newcommand\PYGaN[1]{\textcolor[rgb]{0.73,0.73,0.73}{#1}}
\newcommand\PYGaO[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand\PYGaL[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}}
\newcommand\PYGaM[1]{\colorbox[rgb]{1.00,0.94,0.94}{\textcolor[rgb]{0.25,0.50,0.56}{#1}}}
\newcommand\PYGaB[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGaC[1]{\textcolor[rgb]{0.33,0.33,0.33}{\textbf{#1}}}
\newcommand\PYGaA[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand\PYGaF[1]{\textcolor[rgb]{0.63,0.00,0.00}{#1}}
\newcommand\PYGaG[1]{\textcolor[rgb]{1.00,0.00,0.00}{#1}}
\newcommand\PYGaD[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand\PYGaE[1]{\textcolor[rgb]{0.25,0.50,0.56}{\textit{#1}}}
\newcommand\PYGbg[1]{\textcolor[rgb]{0.44,0.63,0.82}{\textit{#1}}}
\newcommand\PYGbe[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}}
\newcommand\PYGbd[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand\PYGbh[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\begin{document}

\maketitle
\tableofcontents



\resetcurrentobjects
\hypertarget{--doc-intro}{}

\chapter{Introduction}

NCClient is a Python library for NETCONF clients. NETCONF is a network management protocol defined in \index{RFC!RFC 4741}\href{http://tools.ietf.org/html/rfc4741.html}{\textbf{RFC 4741}}.

It is meant for Python 2.6+ (not Python 3 yet, though).

The features of NCClient include:
\begin{itemize}
\item {} 
Request pipelining.

\item {} 
(A)synchronous RPC requests.

\item {} 
Keeps XML out of the way unless really needed.

\item {} 
Supports all operations and capabilities defined in \index{RFC!RFC 4741}\href{http://tools.ietf.org/html/rfc4741.html}{\textbf{RFC 4741}}.

\item {} 
Extensible. New transport mappings and capabilities/operations can be easily added.

\end{itemize}

The best way to introduce is of course, through a simple code example:

\begin{Verbatim}[commandchars=@\[\]]
@PYGal[from] @PYGaW[ncclient] @PYGal[import] manager

@PYGay[with] manager@PYGbe[.]connect@_ssh(@PYGaB[']@PYGaB[host]@PYGaB['], @PYGaB[']@PYGaB[username]@PYGaB[']) @PYGay[as] m:
    @PYGay[assert](@PYGaB["]@PYGaB[:url]@PYGaB["] @PYGav[in] manager@PYGbe[.]server@_capabilities)
    @PYGay[with] m@PYGbe[.]locked(@PYGaB[']@PYGaB[running]@PYGaB[']):
        m@PYGbe[.]copy@_config(source@PYGbe[=]@PYGaB["]@PYGaB[running]@PYGaB["], target@PYGbe[=]@PYGaB["]@PYGaB[file://new@_checkpoint.conf]@PYGaB["])
        m@PYGbe[.]copy@_config(source@PYGbe[=]@PYGaB["]@PYGaB[file://old@_checkpoint.conf]@PYGaB["], target@PYGbe[=]@PYGaB["]@PYGaB[running]@PYGaB["])
\end{Verbatim}

It is recommended to use the high-level \code{Manager} API where possible. It exposes almost all of the functionality.

\resetcurrentobjects
\hypertarget{--doc-userdoc}{}

\hypertarget{userdoc}{}\chapter{User documentation}

\resetcurrentobjects
\hypertarget{--doc-userdoc/manager}{}

\section{\texttt{manager} module}
\index{ncclient.manager (module)}
\hypertarget{module-ncclient.manager}{}
\declaremodule[ncclient.manager]{}{ncclient.manager}
\modulesynopsis{}

\subsection{Dealing with RPC errors}

These constants define what \hyperlink{ncclient.manager.Manager}{\code{Manager}} does when an \emph{\textless{}rpc-error\textgreater{}} element is encountered in a reply.
\index{RAISE\_ALL (in module ncclient.manager)}

\hypertarget{ncclient.manager.RAISE_ALL}{}\begin{datadesc}{RAISE\_ALL}
Raise all \hyperlink{ncclient.operations.rpc.RPCError}{\code{RPCError}}
\end{datadesc}
\index{RAISE\_ERR (in module ncclient.manager)}

\hypertarget{ncclient.manager.RAISE_ERR}{}\begin{datadesc}{RAISE\_ERR}
Only raise when \emph{error-severity} is ``error'' i.e. no warnings
\end{datadesc}
\index{RAISE\_NONE (in module ncclient.manager)}

\hypertarget{ncclient.manager.RAISE_NONE}{}\begin{datadesc}{RAISE\_NONE}
Don't raise any
\end{datadesc}


\subsection{Manager instances}

\hyperlink{ncclient.manager.Manager}{\code{Manager}} instances are created by the \hyperlink{ncclient.manager.connect}{\code{connect()}} family of factory functions. Currently only \hyperlink{ncclient.manager.connect_ssh}{\code{connect\_ssh()}} is available.
\index{connect() (in module ncclient.manager)}

\hypertarget{ncclient.manager.connect}{}\begin{funcdesc}{connect}{*args, **kwds}
Same as \hyperlink{ncclient.manager.connect_ssh}{\code{connect\_ssh()}}
\end{funcdesc}
\index{connect\_ssh() (in module ncclient.manager)}

\hypertarget{ncclient.manager.connect_ssh}{}\begin{funcdesc}{connect\_ssh}{*args, **kwds}
Connect to NETCONF server over SSH. See \hyperlink{ncclient.transport.SSHSession.connect}{\code{SSHSession.connect()}} for function signature.
\end{funcdesc}
\index{Manager (class in ncclient.manager)}

\hypertarget{ncclient.manager.Manager}{}\begin{classdesc}{Manager}{session}
API for NETCONF operations. Currently only supports making synchronous
RPC requests.

It is also a context manager, so a \hyperlink{ncclient.manager.Manager}{\code{Manager}} instance can be used
with the \emph{with} statement. The session is closed when the context ends.
\index{set\_rpc\_error\_action() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.set_rpc_error_action}{}\begin{methoddesc}{set\_rpc\_error\_action}{action}
Specify the action to take when an \emph{\textless{}rpc-error\textgreater{}} element is encountered.
\begin{quote}\begin{description}
\item[Parameter]
\emph{action} -- one of \hyperlink{ncclient.manager.RAISE_ALL}{\code{RAISE\_ALL}}, \hyperlink{ncclient.manager.RAISE_ERR}{\code{RAISE\_ERR}}, \hyperlink{ncclient.manager.RAISE_NONE}{\code{RAISE\_NONE}}

\end{description}\end{quote}
\end{methoddesc}
\index{get() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.get}{}\begin{methoddesc}{get}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.Get.request}{\code{Get.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{get\_config() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.get_config}{}\begin{methoddesc}{get\_config}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.GetConfig.request}{\code{GetConfig.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{edit\_config() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.edit_config}{}\begin{methoddesc}{edit\_config}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.EditConfig.request}{\code{EditConfig.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{copy\_config() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.copy_config}{}\begin{methoddesc}{copy\_config}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.CopyConfig.request}{\code{CopyConfig.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{validate() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.validate}{}\begin{methoddesc}{validate}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.Validate.request}{\code{GetConfig.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{commit() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.commit}{}\begin{methoddesc}{commit}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.Commit.request}{\code{Commit.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{discard\_changes() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.discard_changes}{}\begin{methoddesc}{discard\_changes}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.DiscardChanges.request}{\code{DiscardChanges.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{delete\_config() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.delete_config}{}\begin{methoddesc}{delete\_config}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.DeleteConfig.request}{\code{DeleteConfig.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{lock() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.lock}{}\begin{methoddesc}{lock}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.Lock.request}{\code{Lock.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{unlock() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.unlock}{}\begin{methoddesc}{unlock}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.Unlock.request}{\code{DiscardChanges.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{close\_session() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.close_session}{}\begin{methoddesc}{close\_session}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.CloseSession.request}{\code{CloseSession.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{kill\_session() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.kill_session}{}\begin{methoddesc}{kill\_session}{*args, **kwds}~\begin{quote}\begin{description}
\item[See]
\hyperlink{ncclient.operations.KillSession.request}{\code{KillSession.request()}}

\end{description}\end{quote}
\end{methoddesc}
\index{locked() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.locked}{}\begin{methoddesc}{locked}{target}
Returns a context manager for the \emph{with} statement.
\begin{quote}\begin{description}
\item[Parameter]
\emph{target} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- name of the datastore to lock

\item[Return type]
\hyperlink{ncclient.operations.LockContext}{\code{LockContext}}

\end{description}\end{quote}
\end{methoddesc}
\index{close() (ncclient.manager.Manager method)}

\hypertarget{ncclient.manager.Manager.close}{}\begin{methoddesc}{close}{}
Closes the NETCONF session. First does \emph{\textless{}close-session\textgreater{}} RPC.
\end{methoddesc}
\index{client\_capabilities (ncclient.manager.Manager attribute)}

\hypertarget{ncclient.manager.Manager.client_capabilities}{}\begin{memberdesc}{client\_capabilities}
\hyperlink{ncclient.capabilities.Capabilities}{\code{Capabilities}} object for client
\end{memberdesc}
\index{server\_capabilities (ncclient.manager.Manager attribute)}

\hypertarget{ncclient.manager.Manager.server_capabilities}{}\begin{memberdesc}{server\_capabilities}
\hyperlink{ncclient.capabilities.Capabilities}{\code{Capabilities}} object for server
\end{memberdesc}
\index{session\_id (ncclient.manager.Manager attribute)}

\hypertarget{ncclient.manager.Manager.session_id}{}\begin{memberdesc}{session\_id}
\emph{\textless{}session-id\textgreater{}} as assigned by NETCONF server
\end{memberdesc}
\index{connected (ncclient.manager.Manager attribute)}

\hypertarget{ncclient.manager.Manager.connected}{}\begin{memberdesc}{connected}
Whether currently connected to NETCONF server
\end{memberdesc}
\end{classdesc}

\resetcurrentobjects
\hypertarget{--doc-userdoc/capabilities}{}

\section{\texttt{capabilities} module}
\index{ncclient.capabilities (module)}
\hypertarget{module-ncclient.capabilities}{}
\declaremodule[ncclient.capabilities]{}{ncclient.capabilities}
\modulesynopsis{}\index{CAPABILITIES (in module ncclient.capabilities)}

\hypertarget{ncclient.capabilities.CAPABILITIES}{}\begin{datadesc}{CAPABILITIES}
\hyperlink{ncclient.capabilities.Capabilities}{\code{Capabilities}} object representing the capabilities currently supported by NCClient
\end{datadesc}
\index{Capabilities (class in ncclient.capabilities)}

\hypertarget{ncclient.capabilities.Capabilities}{}\begin{classdesc}{Capabilities}{capabilities}
Represents the set of capabilities for a NETCONF client or server.
Initialised with a list of capability URI's.

Presence of a capability can be checked with the \emph{in} operations. In addition
to the URI, for capabilities of the form
\emph{urn:ietf:params:netconf:capability:\$name:\$version} their shorthand can be
used as a key. For example, for
\emph{urn:ietf:params:netconf:capability:candidate:1.0} the shorthand would be
\emph{:candidate}. If version is significant, use \emph{:candidate:1.0} as key.
\index{add() (ncclient.capabilities.Capabilities method)}

\hypertarget{ncclient.capabilities.Capabilities.add}{}\begin{methoddesc}{add}{uri}
Add a capability
\end{methoddesc}
\index{check() (ncclient.capabilities.Capabilities method)}

\hypertarget{ncclient.capabilities.Capabilities.check}{}\begin{methoddesc}{check}{key}
Whether specified capability is present.
\begin{quote}\begin{description}
\item[Parameter]
\emph{key} -- URI or shorthand

\end{description}\end{quote}
\end{methoddesc}
\index{remove() (ncclient.capabilities.Capabilities method)}

\hypertarget{ncclient.capabilities.Capabilities.remove}{}\begin{methoddesc}{remove}{uri}
Remove a capability
\end{methoddesc}
\end{classdesc}

\resetcurrentobjects
\hypertarget{--doc-userdoc/content}{}

\section{\texttt{content} module}
\index{ncclient.content (module)}
\hypertarget{module-ncclient.content}{}
\declaremodule[ncclient.content]{}{ncclient.content}
\modulesynopsis{Content layer}
The \code{content} module provides methods for creating XML documents, parsing XML, and converting between different XML representations. It uses \href{http://docs.python.org/library/xml.etree.elementtree.html\#module-xml.etree.ElementTree}{\code{ElementTree}} internally.


\subsection{Namespaces}

The following namespace is defined in this module.
\index{BASE\_NS (in module ncclient.content)}

\hypertarget{ncclient.content.BASE_NS}{}\begin{datadesc}{BASE\_NS}
Base NETCONf namespace
\end{datadesc}

Namespaces are handled just the same way as \href{http://docs.python.org/library/xml.etree.elementtree.html\#module-xml.etree.ElementTree}{\code{ElementTree}}. So a qualified name takes the form \emph{\{namespace\}tag}. There are some utility functions for qualified names:
\index{qualify() (in module ncclient.content)}

\hypertarget{ncclient.content.qualify}{}\begin{funcdesc}{qualify}{tag, {[}ns=BASE\_NS{]}}~\begin{quote}\begin{description}
\item[Returns]
qualified name

\end{description}\end{quote}
\end{funcdesc}
\index{unqualify() (in module ncclient.content)}

\hypertarget{ncclient.content.unqualify}{}\begin{funcdesc}{unqualify}{tag}~\begin{quote}\begin{description}
\item[Returns]
unqualified name

\end{description}\end{quote}

\begin{notice}{note}{Note:}
It is strongly recommended to compare qualified names.
\end{notice}
\end{funcdesc}
\hypertarget{dtree}{}

\subsection{DictTree XML representation}

\begin{notice}{note}{Note:}
Where this representation is stipulated, an XML literal or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}} is just fine as well.
\end{notice}

\code{ncclient} can make use of a special syntax for XML based on Python dictionaries. It is best illustrated through an example:

\begin{Verbatim}[commandchars=@\[\]]
dtree @PYGbe[=] {
    @PYGaB[']@PYGaB[tag]@PYGaB[']: qualify(@PYGaB[']@PYGaB[a]@PYGaB['], @PYGaB[']@PYGaB[some@_namespace]@PYGaB[']),
    @PYGaB[']@PYGaB[attrib]@PYGaB[']: {@PYGaB[']@PYGaB[attr]@PYGaB[']: @PYGaB[']@PYGaB[val]@PYGaB[']},
    @PYGaB[']@PYGaB[subtree]@PYGaB[']: @PYGZlb[] { @PYGaB[']@PYGaB[tag]@PYGaB[']: @PYGaB[']@PYGaB[child1]@PYGaB['] }, { @PYGaB[']@PYGaB[tag]@PYGaB[']: @PYGaB[']@PYGaB[child2]@PYGaB['], @PYGaB[']@PYGaB[text]@PYGaB[']: @PYGaB[']@PYGaB[some text]@PYGaB['] } @PYGZrb[]
}
\end{Verbatim}

Calling \hyperlink{ncclient.content.dtree2xml}{\code{dtree2xml()}} on \emph{dtree} would return

\begin{Verbatim}[commandchars=@\[\]]
@PYGaO[@textless[]?xml version="1.0" encoding="UTF-8"?@textgreater[]]
@PYGba[@textless[]ns0:a] @PYGaR[attr=]@PYGaB["val"] @PYGaR[xmlns:ns0=]@PYGaB["some@_namespace"]@PYGba[@textgreater[]]
    @PYGba[@textless[]child1] @PYGba[/@textgreater[]]
    @PYGba[@textless[]child2]@PYGba[@textgreater[]]some text@PYGba[@textless[]/child2@textgreater[]]
@PYGba[@textless[]/ns0:a@textgreater[]]
\end{Verbatim}

In addition to a `pure' dictionary representation a DictTree node (including the root) may be an XML literal or an \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}} instance. The above example could thus be equivalently written as:

\begin{Verbatim}[commandchars=@\[\]]
dtree2 @PYGbe[=] {
    @PYGaB[']@PYGaB[tag]@PYGaB[']: @PYGaB[']@PYGaB[{ns}a]@PYGaB['],
    @PYGaB[']@PYGaB[attrib]@PYGaB[']: {@PYGaB[']@PYGaB[attr]@PYGaB[']: @PYGaB[']@PYGaB[val]@PYGaB[']},
    @PYGaB[']@PYGaB[subtree]@PYGaB[']: @PYGZlb[] ET@PYGbe[.]Element(@PYGaB[']@PYGaB[child1]@PYGaB[']), @PYGaB[']@PYGaB[@textless[]child2@textgreater[]some text@textless[]/child2@textgreater[]]@PYGaB['] @PYGZrb[]
}
\end{Verbatim}


\subsection{Converting between different representations}

Conversions \emph{to} DictTree representation are guaranteed to be entirely dictionaries. In converting \emph{from} DictTree representation, the argument may be any valid representation as specified.
\index{dtree2ele() (in module ncclient.content)}

\hypertarget{ncclient.content.dtree2ele}{}\begin{funcdesc}{dtree2ele}{spec}
DictTree -\textgreater{} Element
\begin{quote}\begin{description}
\item[Return type]
\href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}

\end{description}\end{quote}
\end{funcdesc}
\index{dtree2xml() (in module ncclient.content)}

\hypertarget{ncclient.content.dtree2xml}{}\begin{funcdesc}{dtree2xml}{spec, {[}encoding="UTF-8"{]}}
DictTree -\textgreater{} XML
\begin{quote}\begin{description}
\item[Parameter]
\emph{encoding} -- chraracter encoding

\item[Return type]
string

\end{description}\end{quote}
\end{funcdesc}
\index{ele2dtree() (in module ncclient.content)}

\hypertarget{ncclient.content.ele2dtree}{}\begin{funcdesc}{ele2dtree}{ele}
DictTree -\textgreater{} Element
\begin{quote}\begin{description}
\item[Return type]
\href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}}

\end{description}\end{quote}
\end{funcdesc}
\index{ele2xml() (in module ncclient.content)}

\hypertarget{ncclient.content.ele2xml}{}\begin{funcdesc}{ele2xml}{ele}
Element -\textgreater{} XML
\begin{quote}\begin{description}
\item[Parameter]
\emph{encoding} -- character encoding

\item[Return type]
\href{http://docs.python.org/library/string.html\#string}{\code{string}}

\end{description}\end{quote}
\end{funcdesc}
\index{xml2dtree() (in module ncclient.content)}

\hypertarget{ncclient.content.xml2dtree}{}\begin{funcdesc}{xml2dtree}{xml}
XML -\textgreater{} DictTree
\begin{quote}\begin{description}
\item[Return type]
\href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}}

\end{description}\end{quote}
\end{funcdesc}
\index{xml2ele() (in module ncclient.content)}

\hypertarget{ncclient.content.xml2ele}{}\begin{funcdesc}{xml2ele}{xml}
XML -\textgreater{} Element
\begin{quote}\begin{description}
\item[Return type]
\href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}

\end{description}\end{quote}
\end{funcdesc}


\subsection{Other utility functions}
\index{iselement() (in module ncclient.content)}

\hypertarget{ncclient.content.iselement}{}\begin{funcdesc}{iselement}{obj}~\begin{quote}\begin{description}
\item[See]
\href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.iselement}{\code{xml.etree.ElementTree.iselement()}}

\end{description}\end{quote}
\end{funcdesc}
\index{find() (in module ncclient.content)}

\hypertarget{ncclient.content.find}{}\begin{funcdesc}{find}{ele, tag, {[}nslist=, {[}{]}{]}}
If \emph{nslist} is empty, same as \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element.find}{\code{xml.etree.ElementTree.Element.find()}}. If it is not, \emph{tag} is interpreted as an unqualified name and qualified using each item in \emph{nslist} (with a \href{http://docs.python.org/library/constants.html\#None}{\code{None}} item in \emph{nslit} meaning no qualification is done). The first match is returned.
\begin{quote}\begin{description}
\item[Parameter]
\emph{nslist} -- optional list of namespaces

\end{description}\end{quote}
\end{funcdesc}
\index{parse\_root() (in module ncclient.content)}

\hypertarget{ncclient.content.parse_root}{}\begin{funcdesc}{parse\_root}{raw}
Efficiently parses the root element of an XML document.
\begin{quote}\begin{description}
\item[Parameter]
\emph{raw} (string) -- XML document

\item[Returns]
a tuple of \code{(tag, attributes)}, where \code{tag} is the (qualified) name of the element and \code{attributes} is a dictionary of its attributes.

\item[Return type]
\href{http://docs.python.org/library/functions.html\#tuple}{\code{tuple}}

\end{description}\end{quote}
\end{funcdesc}
\index{validated\_element() (in module ncclient.content)}

\hypertarget{ncclient.content.validated_element}{}\begin{funcdesc}{validated\_element}{rep, tag=None, attrs=None, text=None}
Checks if the root element meets the supplied criteria. Returns a \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}} instance if so, otherwise raises \hyperlink{ncclient.content.ContentError}{\code{ContentError}}.
\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{tag} -- tag name or a list of allowable tag names

\item {} 
\emph{attrs} -- list of required attribute names, each item may be a list of allowable alternatives

\item {} 
\emph{text} -- textual content to match

\end{itemize}

\end{description}\end{quote}
\end{funcdesc}


\subsection{Errors}
\index{ContentError}

\hypertarget{ncclient.content.ContentError}{}\begin{excdesc}{ContentError}
Bases: \code{ncclient.NCClientError}

Raised by methods of the \code{content} module in case of an error.
\end{excdesc}

\resetcurrentobjects
\hypertarget{--doc-userdoc/transport}{}

\section{\texttt{transport} module}
\index{ncclient.transport (module)}
\hypertarget{module-ncclient.transport}{}
\declaremodule[ncclient.transport]{}{ncclient.transport}
\modulesynopsis{Transport protocol layer}

\subsection{Base types}
\index{Session (class in ncclient.transport)}

\hypertarget{ncclient.transport.Session}{}\begin{classdesc}{Session}{capabilities}
Base class for use by transport protocol implementations.
\index{add\_listener() (ncclient.transport.Session method)}

\hypertarget{ncclient.transport.Session.add_listener}{}\begin{methoddesc}{add\_listener}{listener}
Register a listener that will be notified of incoming messages and
errors.
\begin{quote}\begin{description}
\end{description}\end{quote}
\end{methoddesc}
\index{remove\_listener() (ncclient.transport.Session method)}

\hypertarget{ncclient.transport.Session.remove_listener}{}\begin{methoddesc}{remove\_listener}{listener}
Unregister some listener; ignore if the listener was never
registered.
\begin{quote}\begin{description}
\end{description}\end{quote}
\end{methoddesc}
\index{get\_listener\_instance() (ncclient.transport.Session method)}

\hypertarget{ncclient.transport.Session.get_listener_instance}{}\begin{methoddesc}{get\_listener\_instance}{cls}
If a listener of the specified type is registered, returns the
instance.
\begin{quote}\begin{description}
\end{description}\end{quote}
\end{methoddesc}
\index{client\_capabilities (ncclient.transport.Session attribute)}

\hypertarget{ncclient.transport.Session.client_capabilities}{}\begin{memberdesc}{client\_capabilities}
Client's \code{Capabilities}
\end{memberdesc}
\index{server\_capabilities (ncclient.transport.Session attribute)}

\hypertarget{ncclient.transport.Session.server_capabilities}{}\begin{memberdesc}{server\_capabilities}
Server's \code{Capabilities}
\end{memberdesc}
\index{connected (ncclient.transport.Session attribute)}

\hypertarget{ncclient.transport.Session.connected}{}\begin{memberdesc}{connected}
Connection status of the session.
\end{memberdesc}
\index{id (ncclient.transport.Session attribute)}

\hypertarget{ncclient.transport.Session.id}{}\begin{memberdesc}{id}
A \href{http://docs.python.org/library/string.html\#string}{\code{string}} representing the \code{session-id}. If the session has not
been initialized it will be \href{http://docs.python.org/library/constants.html\#None}{\code{None}}
\end{memberdesc}
\index{can\_pipeline (ncclient.transport.Session attribute)}

\hypertarget{ncclient.transport.Session.can_pipeline}{}\begin{memberdesc}{can\_pipeline}
Whether this session supports pipelining
\end{memberdesc}
\end{classdesc}
\index{SessionListener (class in ncclient.transport)}

\hypertarget{ncclient.transport.SessionListener}{}\begin{classdesc}{SessionListener}{}
Base class for \hyperlink{ncclient.transport.Session}{\code{Session}} listeners, which are notified when a new
NETCONF message is received or an error occurs.

\begin{notice}{note}{Note:}
Avoid time-intensive tasks in a callback's context.
\end{notice}
\index{callback() (ncclient.transport.SessionListener method)}

\hypertarget{ncclient.transport.SessionListener.callback}{}\begin{methoddesc}{callback}{root, raw}
Called when a new XML document is received. The \code{root} argument
allows the callback to determine whether it wants to further process the
document.
\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{root} (\href{http://docs.python.org/library/functions.html\#tuple}{\code{tuple}}) -- is a tuple of \code{(tag, attributes)} where \code{tag} is the qualified name of the root element and \code{attributes} is a dictionary of its attributes (also qualified names)

\item {} 
\emph{raw} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- XML document

\end{itemize}

\end{description}\end{quote}
\end{methoddesc}
\index{errback() (ncclient.transport.SessionListener method)}

\hypertarget{ncclient.transport.SessionListener.errback}{}\begin{methoddesc}{errback}{ex}
Called when an error occurs.
\begin{quote}\begin{description}
\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}


\subsection{SSH session implementation}
\index{default\_unknown\_host\_cb() (ncclient.transport.ssh static method)}

\hypertarget{ncclient.transport.ssh.default_unknown_host_cb}{}\begin{staticmethoddesc}[ssh]{default\_unknown\_host\_cb}{host, key}
An \code{unknown host callback} returns \href{http://docs.python.org/library/constants.html\#True}{\code{True}} if it finds the key
acceptable, and \href{http://docs.python.org/library/constants.html\#False}{\code{False}} if not.

This default callback always returns \href{http://docs.python.org/library/constants.html\#False}{\code{False}}, which would lead to
\code{connect()} raising a \code{SSHUnknownHost} exception.

Supply another valid callback if you need to verify the host key
programatically.
\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{host} (string) -- the host for whom key needs to be verified

\item {} 
\emph{key} (string) -- a hex string representing the host key fingerprint

\end{itemize}

\end{description}\end{quote}
\end{staticmethoddesc}
\index{SSHSession (class in ncclient.transport)}

\hypertarget{ncclient.transport.SSHSession}{}\begin{classdesc}{SSHSession}{capabilities}
Bases: \code{ncclient.transport.session.Session}

Implements a \index{RFC!RFC 4742}\href{http://tools.ietf.org/html/rfc4742.html}{\textbf{RFC 4742}} NETCONF session over SSH.
\index{connect() (ncclient.transport.SSHSession method)}

\hypertarget{ncclient.transport.SSHSession.connect}{}\begin{methoddesc}{connect}{host, {[}port=830, timeout=None, username=None, password=None, key\_filename=None, allow\_agent=True, look\_for\_keys=True{]}}
Connect via SSH and initialize the NETCONF session. First attempts
the publickey authentication method and then password authentication.

To disable attemting publickey authentication altogether, call with
\emph{allow\_agent} and \emph{look\_for\_keys} as \href{http://docs.python.org/library/constants.html\#False}{\code{False}}. This may be needed
for Cisco devices which immediately disconnect on an incorrect
authentication attempt.
\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{host} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- the hostname or IP address to connect to

\item {} 
\emph{port} (\href{http://docs.python.org/library/functions.html\#int}{\code{int}}) -- by default 830, but some devices use the default SSH port of 22 so this may need to be specified

\item {} 
\emph{timeout} (\href{http://docs.python.org/library/functions.html\#int}{\code{int}}) -- an optional timeout for the TCP handshake

\item {} 
\emph{unknown\_host\_cb} (see \hyperlink{ncclient.transport.ssh.default_unknown_host_cb}{\code{signature}}) -- called when a host key is not recognized

\item {} 
\emph{username} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- the username to use for SSH authentication

\item {} 
\emph{password} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- the password used if using password authentication, or the passphrase to use for unlocking keys that require it

\item {} 
\emph{key\_filename} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- a filename where a the private key to be used can be found

\item {} 
\emph{allow\_agent} (\href{http://docs.python.org/library/functions.html\#bool}{\code{bool}}) -- enables querying SSH agent (if found) for keys

\item {} 
\emph{look\_for\_keys} (\href{http://docs.python.org/library/functions.html\#bool}{\code{bool}}) -- enables looking in the usual locations for ssh keys (e.g. \code{\textasciitilde{}/.ssh/id\_*})

\end{itemize}

\end{description}\end{quote}
\end{methoddesc}
\index{load\_known\_hosts() (ncclient.transport.SSHSession method)}

\hypertarget{ncclient.transport.SSHSession.load_known_hosts}{}\begin{methoddesc}{load\_known\_hosts}{filename=None}
Load host keys from a \code{known\_hosts}-style file. Can be called multiple
times.

If \emph{filename} is not specified, looks in the default locations i.e.
\code{\textasciitilde{}/.ssh/known\_hosts} and \code{\textasciitilde{}/ssh/known\_hosts} for Windows.
\end{methoddesc}
\index{transport (ncclient.transport.SSHSession attribute)}

\hypertarget{ncclient.transport.SSHSession.transport}{}\begin{memberdesc}{transport}
Underlying \href{http://www.lag.net/paramiko/docs/paramiko.Transport-class.html}{paramiko.Transport}
object. This makes it possible to call methods like set\_keepalive on it.
\end{memberdesc}
\end{classdesc}


\subsection{Errors}
\index{TransportError}

\hypertarget{ncclient.transport.TransportError}{}\begin{excdesc}{TransportError}
Bases: \code{ncclient.NCClientError}
\end{excdesc}
\index{SessionCloseError}

\hypertarget{ncclient.transport.SessionCloseError}{}\begin{excdesc}{SessionCloseError}
Bases: \code{ncclient.transport.errors.TransportError}
\end{excdesc}
\index{SSHError}

\hypertarget{ncclient.transport.SSHError}{}\begin{excdesc}{SSHError}
Bases: \code{ncclient.transport.errors.TransportError}
\end{excdesc}
\index{AuthenticationError}

\hypertarget{ncclient.transport.AuthenticationError}{}\begin{excdesc}{AuthenticationError}
Bases: \code{ncclient.transport.errors.TransportError}
\end{excdesc}
\index{SSHUnknownHostError}

\hypertarget{ncclient.transport.SSHUnknownHostError}{}\begin{excdesc}{SSHUnknownHostError}
Bases: \code{ncclient.transport.errors.SSHError}
\end{excdesc}

\resetcurrentobjects
\hypertarget{--doc-userdoc/operations}{}

\section{\texttt{operations} module}
\index{ncclient.operations (module)}
\hypertarget{module-ncclient.operations}{}
\declaremodule[ncclient.operations]{}{ncclient.operations}
\modulesynopsis{RPC and Operation layers}

\subsection{Base types}
\index{RPC (class in ncclient.operations.rpc)}

\hypertarget{ncclient.operations.rpc.RPC}{}\begin{classdesc}{RPC}{session, {[}async=False, timeout=None{]}}
Base class for all operations.

Directly corresponds to \emph{\textless{}rpc\textgreater{}} requests. Handles making the request, and
taking delivery of the reply.
\index{set\_async() (ncclient.operations.rpc.RPC method)}

\hypertarget{ncclient.operations.rpc.RPC.set_async}{}\begin{methoddesc}{set\_async}{async=True}
Set asynchronous mode for this RPC.
\end{methoddesc}
\index{set\_timeout() (ncclient.operations.rpc.RPC method)}

\hypertarget{ncclient.operations.rpc.RPC.set_timeout}{}\begin{methoddesc}{set\_timeout}{timeout}
Set the timeout for synchronous waiting defining how long the RPC
request will block on a reply before raising an error.
\end{methoddesc}
\index{reply (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.reply}{}\begin{memberdesc}{reply}
\hyperlink{ncclient.operations.rpc.RPCReply}{\code{RPCReply}} element if reply has been received or \href{http://docs.python.org/library/constants.html\#None}{\code{None}}
\end{memberdesc}
\index{error (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.error}{}\begin{memberdesc}{error}
\href{http://docs.python.org/library/exceptions.html\#exceptions.Exception}{\code{Exception}} type if an error occured or \href{http://docs.python.org/library/constants.html\#None}{\code{None}}.

This attribute should be checked if the request was made asynchronously,
so that it can be determined if \hyperlink{ncclient.operations.rpc.RPC.event}{\code{event}} being set is because of a
reply or error.

\begin{notice}{note}{Note:}
This represents an error which prevented a reply from being
received. An \emph{\textless{}rpc-error\textgreater{}} does not fall in that category -- see
\hyperlink{ncclient.operations.rpc.RPCReply}{\code{RPCReply}} for that.
\end{notice}
\end{memberdesc}
\index{event (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.event}{}\begin{memberdesc}{event}
\href{http://docs.python.org/library/threading.html\#threading.Event}{\code{Event}} that is set when reply has been received or
error occured.
\end{memberdesc}
\index{async (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.async}{}\begin{memberdesc}{async}
Whether this RPC is asynchronous
\end{memberdesc}
\index{timeout (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.timeout}{}\begin{memberdesc}{timeout}
Timeout for synchronous waiting
\end{memberdesc}
\index{id (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.id}{}\begin{memberdesc}{id}
The \emph{message-id} for this RPC
\end{memberdesc}
\index{session (ncclient.operations.rpc.RPC attribute)}

\hypertarget{ncclient.operations.rpc.RPC.session}{}\begin{memberdesc}{session}
The \hyperlink{ncclient.transport.Session}{\code{Session}} object associated with this
RPC
\end{memberdesc}
\end{classdesc}
\index{RPCReply (class in ncclient.operations.rpc)}

\hypertarget{ncclient.operations.rpc.RPCReply}{}\begin{classdesc}{RPCReply}{raw}
Represents an \emph{\textless{}rpc-reply\textgreater{}}. Only concerns itself with whether the
operation was successful.

\begin{notice}{note}{Note:}
If the reply has not yet been parsed there is an implicit, one-time
parsing overhead to accessing the attributes defined by this class and
any subclasses.
\end{notice}
\index{ok (ncclient.operations.rpc.RPCReply attribute)}

\hypertarget{ncclient.operations.rpc.RPCReply.ok}{}\begin{memberdesc}{ok}
Boolean value indicating if there were no errors.
\end{memberdesc}
\index{error (ncclient.operations.rpc.RPCReply attribute)}

\hypertarget{ncclient.operations.rpc.RPCReply.error}{}\begin{memberdesc}{error}
Short for \hyperlink{ncclient.operations.rpc.RPCReply.errors}{\code{errors}} {[}0{]}; \href{http://docs.python.org/library/constants.html\#None}{\code{None}} if there were no errors.
\end{memberdesc}
\index{errors (ncclient.operations.rpc.RPCReply attribute)}

\hypertarget{ncclient.operations.rpc.RPCReply.errors}{}\begin{memberdesc}{errors}
\href{http://docs.python.org/library/functions.html\#list}{\code{list}} of \hyperlink{ncclient.operations.rpc.RPCError}{\code{RPCError}} objects. Will be empty if there were no
\emph{\textless{}rpc-error\textgreater{}} elements in reply.
\end{memberdesc}
\end{classdesc}
\index{RPCError (class in ncclient.operations.rpc)}

\hypertarget{ncclient.operations.rpc.RPCError}{}\begin{classdesc}{RPCError}{err\_dict}
Bases: \code{ncclient.operations.errors.OperationError}

Represents an \emph{\textless{}rpc-error\textgreater{}}. It is an instance of \code{OperationError}
so it can be raised like any other exception.
\index{type (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.type}{}\begin{memberdesc}{type}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} represeting \emph{error-type} element
\end{memberdesc}
\index{severity (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.severity}{}\begin{memberdesc}{severity}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} represeting \emph{error-severity} element
\end{memberdesc}
\index{tag (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.tag}{}\begin{memberdesc}{tag}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} represeting \emph{error-tag} element
\end{memberdesc}
\index{path (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.path}{}\begin{memberdesc}{path}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/constants.html\#None}{\code{None}}; represeting \emph{error-path} element
\end{memberdesc}
\index{message (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.message}{}\begin{memberdesc}{message}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/constants.html\#None}{\code{None}}; represeting \emph{error-message} element
\end{memberdesc}
\index{info (ncclient.operations.rpc.RPCError attribute)}

\hypertarget{ncclient.operations.rpc.RPCError.info}{}\begin{memberdesc}{info}
\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/constants.html\#None}{\code{None}}, represeting \emph{error-info} element
\end{memberdesc}
\end{classdesc}


\subsection{NETCONF Operations}


\subsubsection{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 \hyperlink{ncclient.operations.MissingCapabilityError}{\code{MissingCapabilityError}} is raised if the server does not support the relevant capability.
\hypertarget{return}{}

\subsubsection{Return type}

The return type for the \code{request()} method depends of an operation on whether it is synchronous or asynchronous (see base class \code{RPC}).
\begin{itemize}
\item {} 
For synchronous requests, it will block waiting for the reply, and once it has been received an \code{RPCReply} object is returned. If an error occured while waiting for the reply, it will be raised.

\item {} 
For asynchronous requests, it will immediately return an \href{http://docs.python.org/library/threading.html\#threading.Event}{\code{Event}} object. This event is set when a reply is received, or an error occurs that prevents a reply from being received. The \code{reply} and \code{error} attributes can then be accessed to determine which of the two it was :-)

\end{itemize}


\subsubsection{General notes on parameters}


\hypertarget{source-target}{}\paragraph{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 \emph{:url} capability and whether the capability supports the specific schema of the URL. Either must be specified as a \href{http://docs.python.org/library/string.html\#string}{\code{string}}.

If the source may be a \emph{\textless{}config\textgreater{}} element, e.g. for \hyperlink{ncclient.operations.Validate}{\code{Validate}}, specify in \hyperlink{dtree}{\emph{DictTree XML representation}} with the root element as \emph{\textless{}config\textgreater{}}.
\hypertarget{filter}{}

\paragraph{Filter parameters}

Filter parameters, where applicable, can take one of the following types:
\begin{itemize}
\item {} \begin{description}
\item[A \href{http://docs.python.org/library/functions.html\#tuple}{\code{tuple}} of \emph{(type, criteria)}.]
Here type has to be one of ``xpath'' or ``subtree''. For type ``xpath'', the criteria should be a \href{http://docs.python.org/library/string.html\#string}{\code{string}} that is a valid XPath expression. For type ``subtree'', criteria should be in \hyperlink{dtree}{\emph{DictTree XML representation}} representing a valid subtree filter.

\end{description}

\item {} 
A valid \emph{\textless{}filter\textgreater{}} element in \hyperlink{dtree}{\emph{DictTree XML representation}}.

\end{itemize}


\subsubsection{Retrieval operations}

The reply object for these operations will be a \hyperlink{ncclient.operations.GetReply}{\code{GetReply}} instance.
\index{Get (class in ncclient.operations)}

\hypertarget{ncclient.operations.Get}{}\begin{classdesc}{Get}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

The \emph{\textless{}get\textgreater{}} RPC
\index{request() (ncclient.operations.Get method)}

\hypertarget{ncclient.operations.Get.request}{}\begin{methoddesc}{request}{filter=None}~\begin{quote}\begin{description}
\item[Parameter]
\emph{filter} -- optional; see \hyperlink{filter}{\emph{Filter parameters}}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{GetConfig (class in ncclient.operations)}

\hypertarget{ncclient.operations.GetConfig}{}\begin{classdesc}{GetConfig}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

The \emph{\textless{}get-config\textgreater{}} RPC
\index{request() (ncclient.operations.GetConfig method)}

\hypertarget{ncclient.operations.GetConfig.request}{}\begin{methoddesc}{request}{source, filter=None}~\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{source} -- See \hyperlink{source-target}{\emph{Source / target parameters}}

\item {} 
\emph{filter} -- optional; see \hyperlink{filter}{\emph{Filter parameters}}

\end{itemize}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{GetReply (class in ncclient.operations)}

\hypertarget{ncclient.operations.GetReply}{}\begin{classdesc}{GetReply}{raw}
Bases: \hyperlink{ncclient.operations.rpc.RPCReply}{\code{ncclient.operations.rpc.RPCReply}}

Adds attributes for the \emph{\textless{}data\textgreater{}} element to \code{RPCReply}, which
pertains to the \hyperlink{ncclient.operations.Get}{\code{Get}} and \hyperlink{ncclient.operations.GetConfig}{\code{GetConfig}} operations.
\index{data (ncclient.operations.GetReply attribute)}

\hypertarget{ncclient.operations.GetReply.data}{}\begin{memberdesc}{data}
Same as \hyperlink{ncclient.operations.GetReply.data_ele}{\code{data\_ele}}
\end{memberdesc}
\index{data\_xml (ncclient.operations.GetReply attribute)}

\hypertarget{ncclient.operations.GetReply.data_xml}{}\begin{memberdesc}{data\_xml}
\emph{\textless{}data\textgreater{}} element as an XML string
\end{memberdesc}
\index{data\_dtree (ncclient.operations.GetReply attribute)}

\hypertarget{ncclient.operations.GetReply.data_dtree}{}\begin{memberdesc}{data\_dtree}
\emph{\textless{}data\textgreater{}} element in \hyperlink{dtree}{\emph{DictTree XML representation}}
\end{memberdesc}
\index{data\_ele (ncclient.operations.GetReply attribute)}

\hypertarget{ncclient.operations.GetReply.data_ele}{}\begin{memberdesc}{data\_ele}
\emph{\textless{}data\textgreater{}} element as an \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}
\end{memberdesc}
\end{classdesc}


\subsubsection{Locking operations}
\index{Lock (class in ncclient.operations)}

\hypertarget{ncclient.operations.Lock}{}\begin{classdesc}{Lock}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}lock\textgreater{}} RPC
\index{request() (ncclient.operations.Lock method)}

\hypertarget{ncclient.operations.Lock.request}{}\begin{methoddesc}{request}{target}~\begin{quote}\begin{description}
\item[Parameter]
\emph{target} (string) -- see \hyperlink{source-target}{\emph{Source / target parameters}}

\item[Return type]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{Unlock (class in ncclient.operations)}

\hypertarget{ncclient.operations.Unlock}{}\begin{classdesc}{Unlock}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}unlock\textgreater{}} RPC
\index{request() (ncclient.operations.Unlock method)}

\hypertarget{ncclient.operations.Unlock.request}{}\begin{methoddesc}{request}{target}~\begin{quote}\begin{description}
\item[Parameter]
\emph{target} (string) -- see \hyperlink{source-target}{\emph{Source / target parameters}}

\item[Return type]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}


\subsubsection{Configuration operations}
\index{EditConfig (class in ncclient.operations)}

\hypertarget{ncclient.operations.EditConfig}{}\begin{classdesc}{EditConfig}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}edit-config\textgreater{}} RPC
\index{request() (ncclient.operations.EditConfig method)}

\hypertarget{ncclient.operations.EditConfig.request}{}\begin{methoddesc}{request}{target, config, default\_operation=None, test\_option=None, error\_option=None}~\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{target} (string) -- see \hyperlink{source-target}{\emph{Source / target parameters}}

\item {} 
\emph{config} (\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}} or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}) -- a config element in \hyperlink{dtree}{\emph{DictTree XML representation}}

\item {} 
\emph{default\_operation} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- optional; one of \{`merge', `replace', `none'\}

\item {} 
\emph{test\_option} (string) -- optional; one of \{`stop-on-error', `continue-on-error', `rollback-on-error'\}. Last option depends on the \emph{:rollback-on-error} capability

\end{itemize}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{CopyConfig (class in ncclient.operations)}

\hypertarget{ncclient.operations.CopyConfig}{}\begin{classdesc}{CopyConfig}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}copy-config\textgreater{}} RPC
\index{request() (ncclient.operations.CopyConfig method)}

\hypertarget{ncclient.operations.CopyConfig.request}{}\begin{methoddesc}{request}{source, target}~\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{source} (\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}} or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}) -- See \hyperlink{source-target}{\emph{Source / target parameters}}

\item {} 
\emph{target} (\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}} or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}) -- See \hyperlink{source-target}{\emph{Source / target parameters}}

\end{itemize}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{DeleteConfig (class in ncclient.operations)}

\hypertarget{ncclient.operations.DeleteConfig}{}\begin{classdesc}{DeleteConfig}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}delete-config\textgreater{}} RPC
\index{request() (ncclient.operations.DeleteConfig method)}

\hypertarget{ncclient.operations.DeleteConfig.request}{}\begin{methoddesc}{request}{target}~\begin{quote}\begin{description}
\item[Parameter]
\emph{target} (\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}} or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}) -- See \hyperlink{source-target}{\emph{Source / target parameters}}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{Validate (class in ncclient.operations)}

\hypertarget{ncclient.operations.Validate}{}\begin{classdesc}{Validate}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}validate\textgreater{}} RPC. Depends on the \emph{:validate} capability.
\index{request() (ncclient.operations.Validate method)}

\hypertarget{ncclient.operations.Validate.request}{}\begin{methoddesc}{request}{source}~\begin{quote}\begin{description}
\item[Parameter]
\emph{source} (\href{http://docs.python.org/library/string.html\#string}{\code{string}} or \href{http://docs.python.org/library/stdtypes.html\#dict}{\code{dict}} or \href{http://docs.python.org/library/xml.etree.elementtree.html\#xml.etree.ElementTree.Element}{\code{Element}}) -- See \hyperlink{source-target}{\emph{Source / target parameters}}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{Commit (class in ncclient.operations)}

\hypertarget{ncclient.operations.Commit}{}\begin{classdesc}{Commit}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}commit\textgreater{}} RPC. Depends on the \emph{:candidate} capability.
\index{request() (ncclient.operations.Commit method)}

\hypertarget{ncclient.operations.Commit.request}{}\begin{methoddesc}{request}{confirmed=False, timeout=None}
Requires \emph{:confirmed-commit} capability if \emph{confirmed} argument is
\href{http://docs.python.org/library/constants.html\#True}{\code{True}}.
\begin{quote}\begin{description}
\item[Parameters]\begin{itemize}
\item {} 
\emph{confirmed} (\href{http://docs.python.org/library/functions.html\#bool}{\code{bool}}) -- optional; request a confirmed commit

\item {} 
\emph{timeout} (\href{http://docs.python.org/library/functions.html\#int}{\code{int}}) -- specify timeout for confirmed commit

\end{itemize}

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{DiscardChanges (class in ncclient.operations)}

\hypertarget{ncclient.operations.DiscardChanges}{}\begin{classdesc}{DiscardChanges}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}discard-changes\textgreater{}} RPC. Depends on the \emph{:candidate} capability.
\index{request() (ncclient.operations.DiscardChanges method)}

\hypertarget{ncclient.operations.DiscardChanges.request}{}\begin{methoddesc}{request}{}~\begin{quote}\begin{description}
\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}


\subsubsection{Session management operations}
\index{CloseSession (class in ncclient.operations)}

\hypertarget{ncclient.operations.CloseSession}{}\begin{classdesc}{CloseSession}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}close-session\textgreater{}} RPC. The connection to NETCONF server is also closed.
\index{request() (ncclient.operations.CloseSession method)}

\hypertarget{ncclient.operations.CloseSession.request}{}\begin{methoddesc}{request}{}~\begin{quote}\begin{description}
\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}
\index{KillSession (class in ncclient.operations)}

\hypertarget{ncclient.operations.KillSession}{}\begin{classdesc}{KillSession}{session, async=False, timeout=None}
Bases: \hyperlink{ncclient.operations.rpc.RPC}{\code{ncclient.operations.rpc.RPC}}

\emph{\textless{}kill-session\textgreater{}} RPC.
\index{request() (ncclient.operations.KillSession method)}

\hypertarget{ncclient.operations.KillSession.request}{}\begin{methoddesc}{request}{session\_id}~\begin{quote}\begin{description}
\item[Parameter]
\emph{session\_id} (\href{http://docs.python.org/library/string.html\#string}{\code{string}}) -- \emph{session-id} of NETCONF session to kill

\item[Seealso]
\hyperlink{return}{\emph{Return type}}

\end{description}\end{quote}
\end{methoddesc}
\end{classdesc}


\subsubsection{Also useful}
\index{LockContext (class in ncclient.operations)}

\hypertarget{ncclient.operations.LockContext}{}\begin{classdesc}{LockContext}{session, target}
A context manager for the \hyperlink{ncclient.operations.Lock}{\code{Lock}} / \hyperlink{ncclient.operations.Unlock}{\code{Unlock}} pair of RPC's.

Initialise with session instance (\hyperlink{ncclient.transport.Session}{\code{Session}}) and lock target (\hyperlink{source-target}{\emph{Source / target parameters}})
\end{classdesc}


\subsection{Errors}
\index{OperationError}

\hypertarget{ncclient.operations.OperationError}{}\begin{excdesc}{OperationError}
Bases: \code{ncclient.NCClientError}
\end{excdesc}
\index{TimeoutExpiredError}

\hypertarget{ncclient.operations.TimeoutExpiredError}{}\begin{excdesc}{TimeoutExpiredError}
Bases: \code{ncclient.NCClientError}
\end{excdesc}
\index{MissingCapabilityError}

\hypertarget{ncclient.operations.MissingCapabilityError}{}\begin{excdesc}{MissingCapabilityError}
Bases: \code{ncclient.NCClientError}
\end{excdesc}

\resetcurrentobjects
\hypertarget{--doc-extending}{}

\hypertarget{extending}{}\chapter{Extending NCClient}

This is written in a `how-to' style through code examples.

\emph{Forthcoming}


\renewcommand{\indexname}{Module Index}
\printmodindex
\renewcommand{\indexname}{Index}
\printindex
\end{document}
