Merge 95ca16f into 96ba77d

.travis.yml

@@ -2,9 +2,14 @@ language: python
 python:
   - "2.7"
   - "3.7"
+addons:
+  apt:
+    packages:
+      - swig
+      - libusb-1.0-0-dev
 install:
   - pip install .
-  - pip install flake8 pylint coveralls cryptography
+  - pip install flake8 pylint coveralls cryptography libusb1>=1.0.16
   - python --version 2>&1 | grep -q "Python 2" && pip install mock || true
 script:
 - flake8 adb_shell/ && pylint adb_shell/ && coverage run --source adb_shell setup.py test && coverage report -m

README.rst

@@ -27,7 +27,7 @@ Example Usage
 
 .. code-block:: python
 
-   from adb_shell.adb_device import AdbDeviceTcp
+   from adb_shell.adb_device import AdbDeviceTcp, AdbDeviceUsb
    from adb_shell.auth.sign_pythonrsa import PythonRSASigner
 
    # Connect (no authentication necessary)
@@ -41,6 +41,14 @@ Example Usage
    device2 = AdbDeviceTcp('192.168.0.222', 5555, default_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])`
+   with open('path/to/adbkey') as f:
+       priv = f.read()
+   signer = PythonRSASigner('', priv)
+   device3 = AdbDeviceUsb('ab78c6ef')
+   device3.connect(rsa_keys=[signer], auth_timeout_s=0.1)
+
    # Send a shell command
    response1 = device1.shell('echo TEST1')
    response2 = device2.shell('echo TEST2')
+   response3 = device3.shell('echo TEST3')

adb_shell/adb_device.py

@@ -60,6 +60,7 @@
     * :meth:`AdbDevice.streaming_shell`
 
 * :class:`AdbDeviceTcp`
+* :class:`AdbDeviceUsb`
 
 """
 
@@ -79,6 +80,11 @@
 from .handle.base_handle import BaseHandle
 from .handle.tcp_handle import TcpHandle
 
+try:
+    from .handle.usb_handle import UsbHandle
+except ImportError:
+    UsbHandle = None
+
 
 try:
     FILE_TYPES = (file, io.IOBase)
@@ -1287,3 +1293,42 @@ class AdbDeviceTcp(AdbDevice):
     def __init__(self, host, port=5555, default_timeout_s=None, banner=None):
         handle = TcpHandle(host, port, default_timeout_s)
         super(AdbDeviceTcp, self).__init__(handle, banner)
+
+
+class AdbDeviceUsb(AdbDevice):
+    """A class with methods for connecting to a device via USB and executing ADB commands.
+
+    Parameters
+    ----------
+    serial : str, None
+        The USB device serial ID
+    port_path : TODO, None
+        TODO
+    default_timeout_s : float, None
+        Default timeout in seconds for USB packets, or ``None``
+    banner : str, bytes, None
+        The hostname of the machine where the Python interpreter is currently running; if
+        it is not provided, it will be determined via ``socket.gethostname()``
+
+    Raises
+    ------
+    adb_shell.exceptions.InvalidHandleError
+        Raised if package was not installed with the "usb" extras option (``pip install adb-shell[usb]``)
+
+    Attributes
+    ----------
+    _available : bool
+        Whether an ADB connection to the device has been established
+    _banner : bytearray, bytes
+        The hostname of the machine where the Python interpreter is currently running
+    _handle : UsbHandle
+        The handle that is used to connect to the device
+
+    """
+
+    def __init__(self, serial=None, port_path=None, default_timeout_s=None, banner=None):
+        if UsbHandle is None:
+            raise exceptions.InvalidHandleError("To enable USB support you must install this package via `pip install adb-shell[usb]`")
+
+        handle = UsbHandle.find_adb(serial, port_path, default_timeout_s)
+        super(AdbDeviceUsb, self).__init__(handle, banner)

adb_shell/exceptions.py

@@ -91,3 +91,39 @@ class TcpTimeoutException(Exception):
     """TCP connection timed read/write operation exceeded the allowed time.
 
     """
+
+
+class UsbDeviceNotFoundError(Exception):
+    """TODO
+
+    """
+
+
+class UsbReadFailedError(Exception):
+    """TODO
+
+    Parameters
+    ----------
+    msg : str
+        The error message
+    usb_error : libusb1.USBError
+        An exception from ``libusb1``
+
+    Attributes
+    ----------
+    usb_error : libusb1.USBError
+        An exception from ``libusb1``
+
+    """
+    def __init__(self, msg, usb_error):
+        super(UsbReadFailedError, self).__init__(msg)
+        self.usb_error = usb_error
+
+    def __str__(self):
+        return '%s: %s' % (super(UsbReadFailedError, self).__str__(), str(self.usb_error))
+
+
+class UsbWriteFailedError(Exception):
+    """:meth:`adb_shell.handle.usb_handle.UsbHandle.bulk_write` failed.
+
+    """