Skip to content

Commit

Permalink
Documentation fixes (#179)
Browse files Browse the repository at this point in the history 
* Document `_AdbTransactionInfo.args_match`

* Fix documentation of read() methods

* Remove duplicate documentation

* Add link to _AdbIOManager.connect / _AdbIOManagerAsync.connect

* Remove InterleavedDataError exception

* Bunch of documentation fixes
  • Loading branch information
@JeffLIrion
JeffLIrion committed Jul 16, 2021
1 parent fc06c25 commit 9824574
Show file tree
Hide file tree
Showing 6 changed files with 87 additions and 166 deletions.
104 changes: 33 additions & 71 deletions adb_shell/adb_device.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,12 +244,12 @@ def connect(self, banner, rsa_keys, auth_timeout_s, auth_callback, adb_info):
def read(self, expected_cmds, adb_info, allow_zeros=False):
"""Read packets from the device until we get an expected packet type.
1. While the time limit has not been exceeded:
1. See if the expected packet is in the packet store
2. While the time limit has not been exceeded:
1. See if the expected packet is in the packet store
2. Read a packet from the device. If it matches what we are looking for, we are done. If it corresponds to a different stream, add it to the store.
2. After time has expired, check the store again. If the expected packet is found, return it.
3. Raise a timeout exception
Expand Down Expand Up @@ -335,10 +335,6 @@ def read(self, expected_cmds, adb_info, allow_zeros=False):
def send(self, msg, adb_info):
"""Send a message to the device.
1. Send the message header (:meth:`adb_shell.adb_message.AdbMessage.pack <AdbMessage.pack>`)
2. Send the message data
Parameters
----------
msg : AdbMessage
Expand Down Expand Up @@ -529,7 +525,7 @@ class AdbDevice(object):
Used for handling all ADB I/O
_local_id : int
The local ID that is used for ADB transactions; the value is incremented each time and is always in the range ``[1, 2^32)``
_local_id_lock : Lock
_local_id_lock : Lock
A lock for protecting ``_local_id``; this is never held for long
_maxdata: int
Maximum amount of data in an ADB packet
Expand Down Expand Up @@ -613,33 +609,20 @@ def close(self):
def connect(self, rsa_keys=None, transport_timeout_s=None, auth_timeout_s=constants.DEFAULT_AUTH_TIMEOUT_S, read_timeout_s=constants.DEFAULT_READ_TIMEOUT_S, auth_callback=None):
"""Establish an ADB connection to the device.
1. Use the transport to establish a connection
2. Send a ``b'CNXN'`` message
3. Unpack the ``cmd``, ``arg0``, ``arg1``, and ``banner`` fields from the response
4. If ``cmd`` is not ``b'AUTH'``, then authentication is not necesary and so we are done
5. If no ``rsa_keys`` are provided, raise an exception
6. Loop through our keys, signing the last ``banner`` that we received
1. If the last ``arg0`` was not :const:`adb_shell.constants.AUTH_TOKEN`, raise an exception
2. Sign the last ``banner`` and send it in an ``b'AUTH'`` message
3. Unpack the ``cmd``, ``arg0``, and ``banner`` fields from the response via :func:`adb_shell.adb_message.unpack`
4. If ``cmd`` is ``b'CNXN'``, set transfer maxdata and return ``True``
7. None of the keys worked, so send ``rsa_keys[0]``'s public key; if the response does not time out, we must have connected successfully
See :meth:`_AdbIOManager.connect`.
Parameters
----------
rsa_keys : list, None
A list of signers of type :class:`~adb_shell.auth.sign_cryptography.CryptographySigner`,
:class:`~adb_shell.auth.sign_pycryptodome.PycryptodomeAuthSigner`, or :class:`~adb_shell.auth.sign_pythonrsa.PythonRSASigner`
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
auth_timeout_s : float, None
The time in seconds to wait for a ``b'CNXN'`` authentication response
read_timeout_s : float
The total time in seconds to wait for expected commands in :meth:`AdbDevice._read`
The total time in seconds to wait for expected commands in :meth:`_AdbIOManager._read_expected_packet_from_device`
auth_callback : function, None
Function callback invoked when the connection needs to be accepted on the device
Expand All @@ -648,13 +631,6 @@ def connect(self, rsa_keys=None, transport_timeout_s=None, auth_timeout_s=consta
bool
Whether the connection was established (:attr:`AdbDevice.available`)
Raises
------
adb_shell.exceptions.DeviceAuthError
Device authentication required, no keys available
adb_shell.exceptions.InvalidResponseError
Invalid auth response from the device
"""
# Get `self._banner` if it was not provided in the constructor
if not self._banner:
Expand Down Expand Up @@ -686,10 +662,10 @@ def _service(self, service, command, transport_timeout_s=None, read_timeout_s=co
command : bytes
The command that will be sent
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
decode : bool
Expand All @@ -715,10 +691,10 @@ def _streaming_service(self, service, command, transport_timeout_s=None, read_ti
command : bytes
The command that will be sent
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
decode : bool
Whether to decode the output to utf8 before returning
Expand Down Expand Up @@ -746,10 +722,10 @@ def exec_out(self, command, transport_timeout_s=None, read_timeout_s=constants.D
command : str
The exec-out command that will be sent
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
decode : bool
Expand All @@ -774,10 +750,10 @@ def root(self, transport_timeout_s=None, read_timeout_s=constants.DEFAULT_READ_T
Parameters
----------
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
Expand All @@ -795,10 +771,10 @@ def shell(self, command, transport_timeout_s=None, read_timeout_s=constants.DEFA
command : str
The shell command that will be sent
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
decode : bool
Expand All @@ -823,10 +799,10 @@ def streaming_shell(self, command, transport_timeout_s=None, read_timeout_s=cons
command : str
The shell command that will be sent
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
decode : bool
Whether to decode the output to utf8 before returning
Expand Down Expand Up @@ -857,7 +833,7 @@ def list(self, device_path, transport_timeout_s=None, read_timeout_s=constants.D
transport_timeout_s : float, None
Expected timeout for any part of the pull.
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
Returns
-------
Expand Down Expand Up @@ -901,7 +877,7 @@ def pull(self, device_path, local_path, progress_callback=None, transport_timeou
transport_timeout_s : float, None
Expected timeout for any part of the pull.
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
"""
if not device_path:
Expand Down Expand Up @@ -968,7 +944,7 @@ def push(self, local_path, device_path, st_mode=constants.DEFAULT_PUSH_MODE, mti
transport_timeout_s : float, None
Expected timeout for any part of the push.
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
"""
if not device_path:
Expand Down Expand Up @@ -1055,7 +1031,7 @@ def stat(self, device_path, transport_timeout_s=None, read_timeout_s=constants.D
transport_timeout_s : float, None
Expected timeout for any part of the pull.
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
Returns
-------
Expand Down Expand Up @@ -1124,24 +1100,19 @@ def _okay(self, adb_info):
def _open(self, destination, transport_timeout_s, read_timeout_s, timeout_s):
"""Opens a new connection to the device via an ``b'OPEN'`` message.
1. :meth:`~AdbDevice._send` an ``b'OPEN'`` command to the device that specifies the ``local_id``
2. :meth:`~AdbDevice._read` a response from the device that includes a command, another local ID (``their_local_id``), and ``remote_id``
* If ``local_id`` and ``their_local_id`` do not match, raise an exception.
* If the received command is ``b'CLSE'``, :meth:`~AdbDevice._read` another response from the device
* If the received command is not ``b'OKAY'``, raise an exception
* Set the ``adb_info.local_id`` and ``adb_info.remote_id`` attributes
1. :meth:`~_AdbIOManager.send` an ``b'OPEN'`` command to the device that specifies the ``local_id``
2. :meth:`~_AdbIOManager.read` the response from the device and fill in the ``adb_info.remote_id`` attribute
Parameters
----------
destination : bytes
``b'SERVICE:COMMAND'``
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
Expand All @@ -1167,33 +1138,24 @@ def _open(self, destination, transport_timeout_s, read_timeout_s, timeout_s):
def _read_until(self, expected_cmds, adb_info):
"""Read a packet, acknowledging any write packets.
1. Read data via :meth:`AdbDevice._read`
1. Read data via :meth:`_AdbIOManager.read`
2. If a ``b'WRTE'`` packet is received, send an ``b'OKAY'`` packet via :meth:`AdbDevice._okay`
3. Return the ``cmd`` and ``data`` that were read by :meth:`AdbDevice._read`
3. Return the ``cmd`` and ``data`` that were read by :meth:`_AdbIOManager.read`
Parameters
----------
expected_cmds : list[bytes]
:meth:`AdbDevice._read` with look for a packet whose command is in ``expected_cmds``
:meth:`_AdbIOManager.read` will look for a packet whose command is in ``expected_cmds``
adb_info : _AdbTransactionInfo
Info and settings for this ADB transaction
Returns
-------
cmd : bytes
The command that was received by :meth:`AdbDevice._read`, which is in :const:`adb_shell.constants.WIRE_TO_ID` and must be in ``expected_cmds``
The command that was received by :meth:`_AdbIOManager.read`, which is in :const:`adb_shell.constants.WIRE_TO_ID` and must be in ``expected_cmds``
data : bytes
The data that was received by :meth:`AdbDevice._read`
Raises
------
adb_shell.exceptions.InterleavedDataError
We don't support multiple streams...
adb_shell.exceptions.InvalidResponseError
Incorrect remote id.
adb_shell.exceptions.InvalidCommandError
Never got one of the expected responses.
The data that was received by :meth:`_AdbIOManager.read`
"""
cmd, _, _, data = self._io_manager.read(expected_cmds, adb_info, allow_zeros=True)
Expand Down Expand Up @@ -1258,10 +1220,10 @@ def _streaming_command(self, service, command, transport_timeout_s, read_timeout
command : bytes
The service command
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>`
Timeout in seconds for sending and receiving data, or ``None``; see :meth:`BaseTransport.bulk_read() <adb_shell.transport.base_transport.BaseTransport.bulk_read>`
and :meth:`BaseTransport.bulk_write() <adb_shell.transport.base_transport.BaseTransport.bulk_write>`
read_timeout_s : float
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`AdbDevice._read`
The total time in seconds to wait for a ``b'CLSE'`` or ``b'OKAY'`` command in :meth:`_AdbIOManager.read`
timeout_s : float, None
The total time in seconds to wait for the ADB command to finish
Expand Down
Loading

0 comments on commit 9824574

Please sign in to comment.