commit bfcf8aea7bb6e96b2e33a89c50a11f8e0d8b8c7b
Author: Shikhar Bhushan <shikhar@schmizz.net>
Date:   Mon Oct 26 16:08:08 2009 +0000

    mainly docu
    
    git-svn-id: http://ncclient.googlecode.com/svn/trunk@189 6dbcf712-26ac-11de-a2f3-1373824ab735

diff --git a/docs/source/manager.rst b/docs/source/manager.rst
index 289a92e..2ff31e9 100644
--- a/docs/source/manager.rst
+++ b/docs/source/manager.rst
@@ -4,6 +4,17 @@
 .. module:: ncclient.manager
     :synopsis: High-level API
 
+.. data:: CAPABILITIES
+
+    List of URI strings representing the client's capabilities. This is used during the initial
+    capability exchange. Modify this if you need to announce some capability not already included.
+
+.. data:: OPERATIONS
+    
+    Dictionary of method names and corresponding `~ncclient.operations.RPC` classes. `Manager` uses
+    this to lookup operations, e.g. "get_config" is mapped to `ncclient.operations.GetConfig`. It
+    is thus possible to add additional operations to the `Manager` API.
+
 Factory functions
 -----------------
 
@@ -11,28 +22,24 @@ A `Manager` instance is created using a factory function.
 
 .. function:: connect_ssh(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password, key_filename=None, allow_agent=True, look_for_keys=True])
     
-    Initializes a NETCONF session over SSH, and creates a connected `Manager`
-    instance. *host* must be specified, all the other arguments are optional and
-    depend on the kind of host key verification and user authentication you want
-    to complete.
+    Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must
+    be specified, all the other arguments are optional and depend on the kind of host key
+    verification and user authentication you want to complete.
     
-    For the purpose of host key verification, on POSIX systems a user's
-    :file:`~/.ssh/known_hosts` file is automatically considered. The
-    *unknown_host_cb* argument specifies a callback that will be invoked when
-    the server's host key cannot be verified. See
+    For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts`
+    file is automatically considered. The *unknown_host_cb* argument specifies a callback that will
+    be invoked when the server's host key cannot be verified. See
     :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
     
-    First, ``publickey`` authentication is attempted. If a specific
-    *key_filename* is specified, it will be loaded and authentication attempted
-    using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys
-    provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in
-    the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an
-    encrypted key file is encountered, the *password* argument will be used as a
-    decryption passphrase.
+    First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it
+    will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an
+    SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is
+    :const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case
+    an encrypted key file is encountered, the *password* argument will be used as a decryption
+    passphrase.
     
-    If ``publickey`` authentication fails and the *password* argument has been
-    supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be
-    attempted.
+    If ``publickey`` authentication fails and the *password* argument has been supplied,
+    ``password`` / ``keyboard-interactive`` SSH authentication will be attempted.
     
     :param host: hostname or address on which to connect
     :type host: `string`
@@ -43,16 +50,15 @@ A `Manager` instance is created using a factory function.
     :param timeout: timeout for socket connect
     :type timeout: `int`
     
-    :param unknown_host_cb: optional; callback that is invoked when host key
-                            verification fails
+    :param unknown_host_cb: optional; callback that is invoked when host key verification fails
     :type unknown_host_cb: `function`
     
-    :param username: username to authenticate with, if not specified the
-                        username of the logged-in user is used
+    :param username: username to authenticate with, if not specified the username of the logged-in
+                       user is used
     :type username: `string`
     
-    :param password: password for ``password`` authentication or passphrase for
-                        decrypting private key files
+    :param password: password for ``password`` authentication or passphrase for decrypting
+                       private key files
     :type password: `string`
     
     :param key_filename: location of a private key file on the file system
@@ -77,31 +83,26 @@ A `Manager` instance is created using a factory function.
 Manager
 -------
 
-Exposes an API for RPC operations as method calls. The return type of these
-methods depends on whether we are is in :attr:`asynchronous or synchronous
-mode <ncclient.manager.Manager.async_mode>`.
+Exposes an API for RPC operations as method calls. The return type of these methods depends on
+whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`.
 
-In synchronous mode replies are awaited and the corresponding
-`~ncclient.operations.RPCReply` object is returned. Depending on the
-:attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, an
-*rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
+In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object
+is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`,
+an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
 
-However in asynchronous mode, operations return immediately with an
-`~ncclient.operations.RPC` object. Error handling and checking for whether a
-reply has been received must be dealt with manually. See the
-`~ncclient.operations.RPC` documentation for details.
+However in asynchronous mode, operations return immediately with an `~ncclient.operations.RPC`
+object. Error handling and checking for whether a reply has been received must be dealt with
+manually. See the `~ncclient.operations.RPC` documentation for details.
 
-Note that in case of the *get* and *get-config* operations, the reply is an
-instance of `~ncclient.operations.GetReply` which exposes the additional
-attributes :attr:`~ncclient.operations.GetReply.data`
-(as `~xml.etree.ElementTree.Element`) and
-:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary
-interest in case of these operations.
+Note that in case of the *get* and *get-config* operations, the reply is an instance of
+`~ncclient.operations.GetReply` which exposes the additional attributes
+:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
+:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case
+of these operations.
 
-Presence of capabilities is verified to the extent possible, and you can expect
-a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In
-case of transport-layer errors, e.g. unexpected session close,
-:exc:`~ncclient.transport.TransportError` will be raised.
+Presence of capabilities is verified to the extent possible, and you can expect a
+:exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer
+errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised.
 
 .. class:: Manager
     
@@ -128,7 +129,8 @@ case of transport-layer errors, e.g. unexpected session close,
         :param source: name of the configuration datastore being queried
         :type source: `string`
         
-        :param filter: see :ref:`filter_params`
+        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
+        :type filter: :ref:`filter_params`
     
     .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
         
@@ -139,6 +141,9 @@ case of transport-layer errors, e.g. unexpected session close,
         :param target: name of the configuration datastore being edited
         :type target: `string`
         
+        :param config: configuration (must be rooted in *<config> .. </config>*)
+        :type config: `string` or `~xml.etree.ElementTree.Element`
+        
         :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
         :type default_operation: `string`
         
@@ -147,23 +152,24 @@ case of transport-layer errors, e.g. unexpected session close,
         
         :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
         :type error_option: `string`
-        
-        :param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object
     
     .. method:: copy_config(source, target)
         
-        Create or replace an entire configuration datastore with the contents of
-        another complete configuration datastore. 
+        Create or replace an entire configuration datastore with the contents of another complete
+        configuration datastore. 
         
-        :param source: see :ref:`srctarget_params`
+        :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
+        :type source: :ref:`srctarget_params`
         
-        :param target: see :ref:`srctarget_params`
+        :param target: configuration datastore to use as the destination of the copy operation
+        :type target: :ref:`srctarget_params`
     
     .. method:: delete_config(target)
         
         Delete a configuration datastore.
         
-        :param target: see :ref:`srctarget_params`
+        :param target: name or URL of configuration datastore to delete
+        :type: :ref:`srctarget_params`
     
     .. method:: lock(target)
         
@@ -195,7 +201,8 @@ case of transport-layer errors, e.g. unexpected session close,
             finally:
                 m.unlock("running")
         
-        :param target: datastore name. See :ref:`srctarget_params`
+        :param target: name of configuration datastore to lock
+        :type target: `string`
         
         :rtype: `~ncclient.operations.LockContext`
     
@@ -203,21 +210,48 @@ case of transport-layer errors, e.g. unexpected session close,
         
         Retrieve running configuration and device state information.
         
-        :param filter: see :ref:`filter_params`
+        :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
+        :type filter: :ref:`filter_params`
     
     .. method:: close_session()
         
-        Request graceful termination of the NETCONF session, and also close the
-        transport.
+        Request graceful termination of the NETCONF session, and also close the transport.
     
     .. method:: kill_session(session_id)
         
         Force the termination of a NETCONF session (not the current one!).
         
-        :param session_id: session identifier of the NETCONF session to be
-                            terminated
+        :param session_id: session identifier of the NETCONF session to be terminated
         :type session_id: `string`
     
+    .. method:: commit([confirmed=False, timeout=None])
+    
+        Commit the candidate configuration as the device's new current configuration. Depends on the
+        *:candidate* capability.
+        
+        A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
+        followup commit within the *timeout* interval. If no timeout is specified the confirm
+        timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
+        parameter but this is not required. Depends on the *:confirmed-commit* capability.
+        
+        :param confirmed: whether this is a confirmed commit
+        :type confirmed: `bool`
+        
+        :param timeout: confirm timeout in seconds
+        :type timeout: `int`
+    
+    .. method:: discard_changes()
+    
+        Revert the candidate configuration to the currently running configuration. Any uncommitted
+        changes are discarded.
+    
+    .. method:: validate(source)
+        
+        Validate the contents of the specified configuration.
+        
+        :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
+        :type source: :ref:`srctarget_params`
+    
     .. attribute:: async_mode
         
         Specify whether operations are executed asynchronously (:const:`True`)
@@ -225,8 +259,8 @@ case of transport-layer errors, e.g. unexpected session close,
     
     .. attribute:: raise_mode
         
-        The raise *mode* affects what errors are raised as
-        :exc:`~ncclient.operations.RPCError` exceptions.
+        Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
+        Valid values:
         
         * ``"all"`` -- any kind of *rpc-error* (error or warning)
         * ``"errors"`` -- where the *error-type* attribute says it is an error
@@ -234,47 +268,43 @@ case of transport-layer errors, e.g. unexpected session close,
         
     .. attribute:: client_capabilities
     
-        `~ncclient.capabilities.Capabilities` object representing the client's
-        capabilities.
+        `~ncclient.capabilities.Capabilities` object representing the client's capabilities.
     
     .. attribute:: server_capabilities
     
-        `~ncclient.capabilities.Capabilities` object representing the server's
-        capabilities.
+        `~ncclient.capabilities.Capabilities` object representing the server's capabilities.
     
     .. attribute:: session_id
     
-        The *session-id* assigned by the NETCONF server.
+        *session-id* assigned by the NETCONF server.
     
     .. attribute:: connected
         
-        A boolean value indicating whether currently connected to the NETCONF
-        server.
+        Bolean value indicating whether currently connected to the NETCONF server.
 
 
 Special kinds of parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
-To keep the API clean, some parameters can take on different types.
+Some parameters can take on different types to keep the interface simple.
 
 .. _srctarget_params:
 
 Source and target parameters
-""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Where an method takes a *source* or *target* argument, usually a datastore name
-or URL is expected. The latter depends on the ``:url`` capability and on whether
-the specific URL scheme is supported. Either must be specified as a `string`.
-For example, ``"running"``, ``"ftp://user:pass@host/config"``.
+Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected.
+The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported.
+Either must be specified as a `string`. For example, ``"running"``,
+``"ftp://user:pass@host/config"``.
 
-If the source may be a *<config>* element, e.g. as allowed for the *validate*
-RPC, it can be specified either as an XML string or an
-`~xml.etree.ElementTree.Element` object rooted in the *<config>* element.
+If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be
+specified as an XML string or an `~xml.etree.ElementTree.Element` object.
 
 .. _filter_params:
 
 Filter parameters
-"""""""""""""""""
+^^^^^^^^^^^^^^^^^
 
 Where a method takes a *filter* argument, it can take on the following types:
 
@@ -282,10 +312,8 @@ Where a method takes a *filter* argument, it can take on the following types:
     
     Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
     
-    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath
-      expression.
+    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression.
     * For ``"subtree"`` the *criteria* should be an XML string or an
       `~xml.etree.ElementTree.Element` object containing the criteria.
 
-* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element`
-  object.
+* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` object.
