documentation in progress

[ncclient] / ncclient / manager.py

diff --git a/ncclient/manager.py b/ncclient/manager.py
index 3ab9317..d305c02 100644 (file)
--- a/ncclient/manager.py
+++ b/ncclient/manager.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"Thin layer of abstraction around NCClient"
+"This module is a thin layer of abstraction around the library. It exposes all core functionality."
 
 import capabilities
 import operations
@@ -22,7 +22,6 @@ import logging
 logger = logging.getLogger('ncclient.manager')
 
 
-#: :class:`Capabilities` object representing the capabilities currently supported by NCClient
 CAPABILITIES = capabilities.Capabilities([
     "urn:ietf:params:netconf:base:1.0",
     "urn:ietf:params:netconf:capability:writable-running:1.0",
@@ -37,7 +36,10 @@ CAPABILITIES = capabilities.Capabilities([
     "urn:ietf:params:netconf:capability:interleave:1.0"
     #'urn:ietf:params:netconf:capability:notification:1.0', # TODO    
 ])
-
+"""`~ncclient.capabilities.Capabilities` object 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.
+"""
 
 OPERATIONS = {
     "get": operations.Get,
@@ -55,17 +57,70 @@ OPERATIONS = {
     "poweroff_machine": operations.PoweroffMachine,
     "reboot_machine": operations.RebootMachine
 }
-
+"""Dictionary of method names and corresponding `~ncclient.operations.RPC` subclasses. `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.
+"""
 
 def connect_ssh(*args, **kwds):
+    """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 -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_unknown_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.
+    
+    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`
+    
+    :param port: port on which to connect
+    :type port: `int`
+    
+    :param timeout: timeout for socket connect
+    :type timeout: `int`
+    
+    :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
+    :type username: `string`
+    
+    :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
+    :type key_filename: `string`
+    
+    :param allow_agent: whether to try connecting to SSH agent for keys
+    :type allow_agent: `bool`
+    
+    :param look_for_keys: whether to look in usual locations for keys
+    :type look_for_keys: `bool`
+    
+    :raises: :exc:`~ncclient.transport.SSHUnknownHostError`
+    :raises: :exc:`~ncclient.transport.AuthenticationError`
+    
+    :rtype: `Manager`
+    """    
     session = transport.SSHSession(CAPABILITIES)
     session.load_known_hosts()
     session.connect(*args, **kwds)
     return Manager(session)
 
-#: Same as :meth:`connect_ssh`
 connect = connect_ssh
-
+"Same as :func:`connect_ssh`, since SSH is the default (and currently, the only) transport."
 
 class Manager(object):