Rename handles and timeouts, add timeouts to 'shell' and 'root' (#103)

* Rename files: 'handle' -> 'transport'

* Use sed to replace 'handle' with 'transport'

* Rename the *Handle classes

* Rebuild documentation

* 'InvalidHandleError' -> 'InvalidTransportError'

* 'PATCH_TCP_HANDLE' -> 'PATCH_TCP_TRANSPORT'

* Rename 'timeout_s' -> 'transport_timeout_s' and 'default_timeout_s' -> 'default_transport_timeout_s'

* Alphabetize attributes

* Documentation

* 'total_timeout_s' -> 'read_timeout_s'

* 'DEFAULT_TOTAL_TIMEOUT_S' -> 'DEFAULT_READ_TIMEOUT_S'

* Alphabetize attributes

* Working on a better timeout

* String formatting

* Change 'setblocking(0)' to 'setblocking(False)'

* Add a timeout for shell commands

* Fail async tests when a warning is raised

* Add 'async_patch' function

* Renaming, documentation, and cleanup

* Text alignment

* Documentation

* 'transportd' -> 'handled'

Author: JeffLIrion

.travis.yml

@@ -15,7 +15,7 @@ install:
   - pip install flake8 pylint coveralls cryptography libusb1>=1.0.16 pycryptodome
   - python --version 2>&1 | grep -q "Python 2" && pip install mock || true
 script:
-  - if python --version 2>&1 | grep -q "Python 2" || python --version 2>&1 | grep -q "Python 3.5"; then flake8 adb_shell/ --exclude="adb_shell/adb_device_async.py,adb_shell/handle/base_handle_async.py,adb_shell/handle/tcp_handle_async.py" && pylint --ignore="adb_device_async.py,base_handle_async.py,tcp_handle_async.py" adb_shell/; fi
+  - if python --version 2>&1 | grep -q "Python 2" || python --version 2>&1 | grep -q "Python 3.5"; then flake8 adb_shell/ --exclude="adb_shell/adb_device_async.py,adb_shell/transport/base_transport_async.py,adb_shell/transport/tcp_transport_async.py" && pylint --ignore="adb_device_async.py,base_transport_async.py,tcp_transport_async.py" adb_shell/; fi
   - if python --version 2>&1 | grep -q "Python 3.6" || python --version 2>&1 | grep -q "Python 3.7" || python --version 2>&1 | grep -q "Python 3.8"; then flake8 adb_shell/ && pylint adb_shell/; fi
   - if python --version 2>&1 | grep -q "Python 2" || python --version 2>&1 | grep -q "Python 3.5"; then for synctest in $(cd tests && ls test*.py | grep -v async); do python -m unittest discover -s tests/ -t . -p "$synctest" || exit 1; done; fi
   - if python --version 2>&1 | grep -q "Python 3.6" || python --version 2>&1 | grep -q "Python 3.7" || python --version 2>&1 | grep -q "Python 3.8"; then coverage run --source adb_shell -m unittest discover -s tests/ -t . && coverage report -m; fi

Makefile

@@ -28,7 +28,7 @@ tdd:
 
 .PHONY: lint
 lint:
-	python --version 2>&1 | grep -q "Python 2" && (flake8 adb_shell/ --exclude="adb_shell/adb_device_async.py,adb_shell/handle/base_handle_async.py,adb_shell/handle/tcp_handle_async.py" && pylint --ignore="adb_device_async.py,base_handle_async.py,tcp_handle_async.py" adb_shell/) || (flake8 adb_shell/ && pylint adb_shell/)
+	python --version 2>&1 | grep -q "Python 2" && (flake8 adb_shell/ --exclude="adb_shell/adb_device_async.py,adb_shell/transport/base_transport_async.py,adb_shell/transport/tcp_transport_async.py" && pylint --ignore="adb_device_async.py,base_transport_async.py,tcp_transport_async.py" adb_shell/) || (flake8 adb_shell/ && pylint adb_shell/)
 
 .PHONY: alltests
 alltests:

README.rst

@@ -47,14 +47,14 @@ Example Usage
    from adb_shell.auth.sign_pythonrsa import PythonRSASigner
 
    # Connect (no authentication necessary)
-   device1 = AdbDeviceTcp('192.168.0.111', 5555, default_timeout_s=9.)
+   device1 = AdbDeviceTcp('192.168.0.111', 5555, default_transport_timeout_s=9.)
    device1.connect(auth_timeout_s=0.1)
 
    # Connect (authentication required)
    with open('path/to/adbkey') as f:
        priv = f.read()
    signer = PythonRSASigner('', priv)
-   device2 = AdbDeviceTcp('192.168.0.222', 5555, default_timeout_s=9.)
+   device2 = AdbDeviceTcp('192.168.0.222', 5555, default_transport_timeout_s=9.)
    device2.connect(rsa_keys=[signer], auth_timeout_s=0.1)
 
    # Connect via USB (package must be installed via `pip install adb-shell[usb])`

adb_shell/adb_device.py

@@ -88,7 +88,7 @@ def unpack(message):
     arg1 : int
         TODO
     data_length : int
-        The length of the data sent by the device (used by :meth:`adb_shell.adb_device._read`)
+        The length of the data sent by the device (used by :meth:`adb_shell.adb_device.AdbDevice._read` and :meth:`adb_shell.adb_device_async.AdbDeviceAsync._read`)
     data_checksum : int
         The checksum of the data sent by the device
 
@@ -114,18 +114,18 @@ class AdbMessage(object):
     command : bytes
         A command; examples used in this package include :const:`adb_shell.constants.AUTH`, :const:`adb_shell.constants.CNXN`, :const:`adb_shell.constants.CLSE`, :const:`adb_shell.constants.OPEN`, and :const:`adb_shell.constants.OKAY`
     arg0 : int
-        Usually the local ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` provides :const:`adb_shell.constants.VERSION`, :const:`adb_shell.constants.AUTH_SIGNATURE`, and :const:`adb_shell.constants.AUTH_RSAPUBLICKEY`
+        Usually the local ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` and :meth:`~adb_shell.adb_device_async.AdbDeviceAsync.connect` provide :const:`adb_shell.constants.VERSION`, :const:`adb_shell.constants.AUTH_SIGNATURE`, and :const:`adb_shell.constants.AUTH_RSAPUBLICKEY`
     arg1 : int
-        Usually the remote ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` provides :const:`adb_shell.constants.MAX_ADB_DATA`
+        Usually the remote ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` and :meth:`~adb_shell.adb_device_async.AdbDeviceAsync.connect` provide :const:`adb_shell.constants.MAX_ADB_DATA`
     data : bytes
         The data that will be sent
 
     Attributes
     ----------
     arg0 : int
-        Usually the local ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` provides :const:`adb_shell.constants.VERSION`, :const:`adb_shell.constants.AUTH_SIGNATURE`, and :const:`adb_shell.constants.AUTH_RSAPUBLICKEY`
+        Usually the local ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` and :meth:`~adb_shell.adb_device_async.AdbDeviceAsync.connect` provide :const:`adb_shell.constants.VERSION`, :const:`adb_shell.constants.AUTH_SIGNATURE`, and :const:`adb_shell.constants.AUTH_RSAPUBLICKEY`
     arg1 : int
-        Usually the remote ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` provides :const:`adb_shell.constants.MAX_ADB_DATA`
+        Usually the remote ID, but :meth:`~adb_shell.adb_device.AdbDevice.connect` and :meth:`~adb_shell.adb_device_async.AdbDeviceAsync.connect` provide :const:`adb_shell.constants.MAX_ADB_DATA`
     command : int
         The input parameter ``command`` converted to an integer via :const:`adb_shell.constants.ID_TO_WIRE`
     data : bytes

adb_shell/adb_device_async.py

@@ -75,7 +75,7 @@
 SEND = b'SEND'
 STAT = b'STAT'
 
-#: Commands that are recognized by :meth:`adb_shell.adb_device.AdbDevice._read`
+#: Commands that are recognized by :meth:`adb_shell.adb_device.AdbDevice._read` and :meth:`adb_shell.adb_device_async.AdbDeviceAsync._read`
 IDS = (AUTH, CLSE, CNXN, OKAY, OPEN, SYNC, WRTE)
 
 #: A dictionary where the keys are the commands in :const:`IDS` and the values are the keys converted to integers
@@ -84,7 +84,7 @@
 #: A dictionary where the keys are integers and the values are their corresponding commands (type = bytes) from :const:`IDS`
 WIRE_TO_ID = {wire: cmd_id for cmd_id, wire in ID_TO_WIRE.items()}
 
-#: Commands that are recognized by :meth:`adb_shell.adb_device.AdbDevice._filesync_read`
+#: Commands that are recognized by :meth:`adb_shell.adb_device.AdbDevice._filesync_read` and :meth:`adb_shell.adb_device_async.AdbDeviceAsync._filesync_read`
 FILESYNC_IDS = (DATA, DENT, DONE, FAIL, LIST, OKAY, QUIT, RECV, SEND, STAT)
 
 #: A dictionary where the keys are the commands in :const:`FILESYNC_IDS` and the values are the keys converted to integers
@@ -111,8 +111,8 @@
 #: The size of an ADB message
 MESSAGE_SIZE = struct.calcsize(MESSAGE_FORMAT)
 
-#: Default authentication timeout (in s) for :meth:`adb_shell.tcp_handle.TcpHandle.connect`
+#: Default authentication timeout (in s) for :meth:`adb_shell.adb_device.AdbDevice.connect` and :meth:`adb_shell.adb_device_async.AdbDeviceAsync.connect`
 DEFAULT_AUTH_TIMEOUT_S = 10.
 
-#: Default total timeout (in s) for :meth:`adb_shell.adb_device.AdbDevice._read`
-DEFAULT_TOTAL_TIMEOUT_S = 10.
+#: Default total timeout (in s) for :meth:`adb_shell.adb_device.AdbDevice._read`, :meth:`adb_shell.adb_device.AdbDevice._read_until`, :meth:`adb_shell.adb_device_async.AdbDeviceAsync._read`, and :meth:`adb_shell.adb_device_async.AdbDeviceAsync._read_until`
+DEFAULT_READ_TIMEOUT_S = 10.

adb_shell/adb_message.py

@@ -38,6 +38,12 @@ class AdbConnectionError(Exception):
     """
 
 
+class AdbTimeoutError(Exception):
+    """ADB command did not complete within the specified time.
+
+    """
+
+
 class DeviceAuthError(Exception):
     """Device authentication failed.
 
@@ -69,8 +75,8 @@ def __init__(self, message, response_header, response_data):
         super(InvalidCommandError, self).__init__(message, response_header, response_data)
 
 
-class InvalidHandleError(Exception):
-    """The provided handle does not implement the necessary methods: ``close``, ``connect``, ``bulk_read``, and ``bulk_write``.
+class InvalidTransportError(Exception):
+    """The provided transport does not implement the necessary methods: ``close``, ``connect``, ``bulk_read``, and ``bulk_write``.
 
     """
 
@@ -124,6 +130,6 @@ def __str__(self):
 
 
 class UsbWriteFailedError(Exception):
-    """:meth:`adb_shell.handle.usb_handle.UsbHandle.bulk_write` failed.
+    """:meth:`adb_shell.transport.usb_transport.UsbTransport.bulk_write` failed.
 
     """

adb_shell/constants.py

@@ -81,36 +81,54 @@ def _open(name, mode='r'):
 class _AdbTransactionInfo(object):  # pylint: disable=too-few-public-methods
     """A class for storing info and settings used during a single ADB "transaction."
 
+    Note that if ``timeout_s`` is not ``None``, then:
+
+    ::
+
+       self.transport_timeout_s <= self.read_timeout_s <= self.timeout_s
+
+    If ``timeout_s`` is ``None``, the first inequality still applies.
+
+
     Parameters
     ----------
     local_id : int
         The ID for the sender (i.e., the device running this code)
     remote_id : int
         The ID for the recipient
+    transport_timeout_s : float, None
+        Timeout in seconds for sending and receiving packets, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`,
+        :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`,
+        :meth:`BaseTransportAsync.bulk_read() <adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_read>`, and
+        :meth:`BaseTransportAsync.bulk_write() <adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_write>`
+    read_timeout_s : float
+        The total time in seconds to wait for a command in ``expected_cmds`` in :meth:`AdbDevice._read` and :meth:`AdbDeviceAsync._read`
     timeout_s : float, None
-        Timeout in seconds for sending and receiving packets, or ``None``; see :meth:`BaseHandle.bulk_read() <adb_shell.handle.base_handle.BaseHandle.bulk_read>`
-        and :meth:`BaseHandle.bulk_write() <adb_shell.handle.base_handle.BaseHandle.bulk_write>`
-    total_timeout_s : float
-        The total time in seconds to wait for a command in ``expected_cmds`` in :meth:`AdbDevice._read`
+        The total time in seconds to wait for the ADB command to finish
 
     Attributes
     ----------
     local_id : int
         The ID for the sender (i.e., the device running this code)
+    read_timeout_s : float
+        The total time in seconds to wait for a command in ``expected_cmds`` in :meth:`AdbDevice._read` and :meth:`AdbDeviceAsync._read`
     remote_id : int
         The ID for the recipient
     timeout_s : float, None
-        Timeout in seconds for sending and receiving packets, or ``None``; see :meth:`BaseHandle.bulk_read() <adb_shell.handle.base_handle.BaseHandle.bulk_read>`
-        and :meth:`BaseHandle.bulk_write() <adb_shell.handle.base_handle.BaseHandle.bulk_write>`
-    total_timeout_s : float
-        The total time in seconds to wait for a command in ``expected_cmds`` in :meth:`AdbDevice._read`
+        The total time in seconds to wait for the ADB command to finish
+    transport_timeout_s : float, None
+        Timeout in seconds for sending and receiving packets, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`,
+        :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`,
+        :meth:`BaseTransportAsync.bulk_read() <adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_read>`, and
+        :meth:`BaseTransportAsync.bulk_write() <adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_write>`
 
     """
-    def __init__(self, local_id, remote_id, timeout_s=None, total_timeout_s=constants.DEFAULT_TOTAL_TIMEOUT_S):
+    def __init__(self, local_id, remote_id, transport_timeout_s=None, read_timeout_s=constants.DEFAULT_READ_TIMEOUT_S, timeout_s=None):
         self.local_id = local_id
         self.remote_id = remote_id
         self.timeout_s = timeout_s
-        self.total_timeout_s = total_timeout_s
+        self.read_timeout_s = read_timeout_s if self.timeout_s is None else min(read_timeout_s, self.timeout_s)
+        self.transport_timeout_s = self.read_timeout_s if transport_timeout_s is None else min(transport_timeout_s, self.read_timeout_s)
 
 
 class _FileSyncTransactionInfo(object):  # pylint: disable=too-few-public-methods