diff --git a/doc/connection.rst b/doc/connection.rst new file mode 100644 index 0000000..8b7f4c5 --- /dev/null +++ b/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. diff --git a/doc/index.rst b/doc/index.rst index 6ebafb1..482eeb8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,8 +19,7 @@ Contents: target modules instrumentation - - + connection Indices and tables ================== diff --git a/doc/target.rst b/doc/target.rst index e24cd09..7ee8d44 100644 --- a/doc/target.rst +++ b/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. - :class:`AndroidTarget` expects the adb ``device`` name). + device. Its contents depend on the specific :class:`Target` type (used see + :ref:`connection-types`\ ). :param platform: A :class:`Target` defines interactions at Operating System level. A :class:`Platform` describes the underlying hardware (such as CPUs