doc: documeting connections

doc/connection.rst

@@ -0,0 +1,157 @@
+Connection
+==========
+
+A :class:`Connection` abstracts an actual physical connection to a device. The
+first connection is created when :func:`Target.connect` method is called. If a
+:class:`Target` is used in a multi-threaded environment, it will maintain a
+connection for each thread in which it is invoked. This allows the same target
+object to be used in parallel in multiple threads.
+
+:class:`Connection`\ s will be automatically created and managed by
+:class:`Target`\ s, so there is usually no reason to create one manually.
+Instead, configuration for a :class:`Connection` is passed as
+`connection_settings` parameter when creating a :class:`Target`. The connection
+to be used target is also specified on instantiation by `conn_cls` parameter,
+though all concrete :class:`Target` implementations will set an appropriate
+default, so there is typically no need to specify this explicitly.
+
+:class:`Connection` classes are not a part of an inheritance hierarchy, i.e.
+they do not derive from a common base. Instead, a :class:`Connection` is any
+class that implements the following methods.
+
+
+.. method:: push(self, source, dest, timeout=None)
+
+   Transfer a file from the host machine to the connected device.
+
+   :param source: path of to the file on the host
+   :param dest: path of to the file on the connected
+   :param timeout: timeout (in seconds) for the transfer; if the transfer does
+       not  complete within this period, an exception will be raised.
+
+.. method:: pull(self, source, dest, timeout=None)
+
+   Transfer a file from the connected device to the host machine.
+
+   :param source: path of to the file on the connected device
+   :param dest: path of to the file on the host
+   :param timeout: timeout (in seconds) for the transfer; if the transfer does
+       not  complete within this period, an exception will be raised.
+
+.. method:: execute(self, command, timeout=None, check_exit_code=False, as_root=False)
+
+   Execute the specified command on the connected device and return its output.
+
+   :param command: The command to be executed.
+   :param timeout: Timeout (in seconds) for the execution of the command. If
+       specified, an exception will be raised if execution does not complete
+       with the specified period.
+   :param check_exit_code: If ``True`` the exit code (on connected device) 
+       from execution of the command will be checked, and an exception will be
+       raised if it is not ``0``.
+   :param as_root: The command will be executed as root. This will fail on
+       unrooted connected devices.
+
+.. method:: background(self, command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, as_root=False)
+
+   Execute the command on the connected device, invoking it via subprocess on the host.
+   This will return :class:`subprocess.Popen` instance for the command.
+
+   :param command: The command to be executed.
+   :param stdout: By default, standard output will be piped from the subprocess;
+      this may be used to redirect it to an alternative file handle.
+   :param stderr: By default, standard error will be piped from the subprocess;
+      this may be used to redirect it to an alternative file handle.
+   :param as_root: The command will be executed as root. This will fail on
+       unrooted connected devices.
+
+   .. note:: This **will block the connection** until the command completes.
+   
+.. note:: The above methods are directly wrapped by :class:`Target` methods,
+          however note that some of the defaults are different. 
+
+.. method:: cancel_running_command(self)
+
+   Cancel a running command (previously started with :func:`background`) and free up the connection.
+   It is valid to call this if the command has already terminated (or if no
+   command was issued), in which case this is a no-op.
+
+.. method:: close(self)
+
+   Close the connection to the device. The :class:`Connection` object should not
+   be used after this method is called. There is no way to reopen a previously
+   closed connection, a new connection object should be created instead.
+
+.. note:: There is no :func:`open` method, as the connection is assumed to be
+          opened on instantiation.
+
+
+.. _connection-types:
+
+Connection Types
+----------------
+
+.. class:: AdbConnection(device=None, timeout=None)
+
+    A connection to an android device via ``adb`` (Android Debug Bridge).
+    ``adb`` is part of the Android SDK (though stand-alone versions are also
+    available).
+
+    :param device: The name of the adb divice. This is usually a unique hex
+                   string for USB-connected devices, or an ip address/port
+                   combination. To see connected devices, you can run ``adb
+                   devices`` on the host.
+    :param timeout: Connection timeout in seconds. If a connection to the device
+                    is not esblished within this period, :class:`HostError` 
+                    is raised.
+
+
+.. class:: SshConnection(host, username, password=None, keyfile=None, port=None,\
+                         timeout=None, telnet=False, password_prompt=None,\
+                         original_prompt=None)
+
+    A connectioned to a device on the network over SSH or Telnet.
+
+    :param host: SSH host to which to connect
+    :param username: username for SSH login
+    :param password: password for the SSH connection
+
+                     .. note:: In order to user password-based authentication,
+                               ``sshpass`` utility must be installed on the
+                               system.
+    
+    :param keyfile: Path to the SSH private key to be used for the connection.
+
+                    .. note:: ``keyfile`` and ``password`` can't be specified 
+                              at the same time.
+
+    :param port: TCP port on which SSH server is litening on the remoted device.
+                 Omit to use the default port.
+    :param timeout: Timeout for the connection in seconds. If a connection
+                    cannot be established within this time, an error will be
+                    raised.
+    :param telnet: If ``True``, Telenet will be used instead of SSH. In this
+                   case, all other parameters apart from "original_prompt" will
+                   be ignored.
+    :param password_prompt: A string with the password prompt used by
+                            ``sshpass``. Set this if your version of ``sshpass``
+                            uses somethin other than ``"[sudo] password"``.
+    :param original_prompt: A regex for the shell prompted presented in the Telenet
+                            connection (the prompt will be reset to a
+                            randomly-generated pattern for the duration of the
+                            connection to reduce the possibility of clashes).
+                            This paramer is ignored for SSH connections.
+
+
+.. class:: LocalConnection(keep_password=True, unrooted=False, password=None)
+
+    A connection to the local host allowing it to be treated as a Target.
+
+
+    :param keep_password: If this is ``True`` (the default) user's password will
+                          be cached in memory after it is first requested. 
+    :param unrooted: If set to ``True``, the platform will be assumed to be
+                     unrooted without testing for root. This is useful to avoid
+                     blocking on password request in scripts.
+    :param password: Specify password on connection creation rather than
+                     prompting for it.

doc/index.rst

@@ -19,8 +19,7 @@ Contents:
    target
    modules
    instrumentation
-
+   connection
-
 
 Indices and tables
 ==================

doc/target.rst

@@ -10,8 +10,8 @@ Target
     :class:`Instrument`).
 
     :param connection_settings: A ``dict`` that specifies how to connect to the remote 
-       device. Its contents depend on the specific :class:`Target` type used (e.g.
+       device. Its contents depend on the specific :class:`Target` type (used see
-       :class:`AndroidTarget` expects the adb ``device`` name).
+       :ref:`connection-types`\ ).
 
     :param platform: A :class:`Target` defines interactions at Operating System level. A 
         :class:`Platform` describes the underlying hardware (such as CPUs