### Install adb-shell with Async Support

Source: https://github.com/jefflirion/adb_shell/blob/master/README.rst

Install the package with async support for Python 3.7+ environments.

```bash
pip install adb-shell[async]
```

--------------------------------

### Install adb-shell with USB Support

Source: https://github.com/jefflirion/adb_shell/blob/master/README.rst

Install the package with experimental USB support.

```bash
pip install adb-shell[usb]
```

--------------------------------

### Install adb-shell

Source: https://github.com/jefflirion/adb_shell/blob/master/README.rst

Install the package using pip.

```bash
pip install adb-shell
```

--------------------------------

### Install ADB Shell

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Install the ADB Shell library using pip. Use the `[async]` extra for asyncio support and `[usb]` for experimental USB support.

```bash
pip install adb-shell

# With async support (Python 3.7+)
pip install adb-shell[async]

# With USB support (experimental)
pip install adb-shell[usb]
```

--------------------------------

### Connect to ADB Device and Send Shell Command

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/index.md

Example demonstrating how to load RSA keys, connect to an ADB device via TCP or USB, and send a shell command. Ensure the adbkey file exists at the specified path.

```python
from adb_shell.adb_device import AdbDeviceTcp, AdbDeviceUsb
from adb_shell.auth.sign_pythonrsa import PythonRSASigner

# Load the public and private keys
adbkey = 'path/to/adbkey'
with open(adbkey) as f:
    priv = f.read()
with open(adbkey + '.pub') as f:
     pub = f.read()
signer = PythonRSASigner(pub, priv)

# Connect
device1 = AdbDeviceTcp('192.168.0.222', 5555, default_transport_timeout_s=9.)
device1.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Connect via USB (package must be installed via `pip install adb-shell[usb])`
device2 = AdbDeviceUsb()
device2.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Send a shell command
response1 = device1.shell('echo TEST1')
response2 = device2.shell('echo TEST2')
```

--------------------------------

### Establish ADB Connection with Callback

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Connect to an ADB device, providing RSA keys and a callback function to handle user authentication prompts on the device. This example uses `PythonRSASigner` and specifies various timeouts.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_pythonrsa import PythonRSASigner

signer = PythonRSASigner.FromRSAKeyPath('/home/user/.android/adbkey')
device = AdbDeviceTcp('10.0.0.5', 5555, default_transport_timeout_s=9.0)

def on_auth_required(device):
    print('Please accept the RSA key prompt on your Android device.')

connected = device.connect(
    rsa_keys=[signer],
    auth_timeout_s=10.0,      # wait up to 10 s for user to tap "Allow"
    read_timeout_s=10.0,
    auth_callback=on_auth_required,
)
# Returns True if connection succeeded
assert connected is True
```

--------------------------------

### get(arg0, arg1)

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.hidden_helpers.md

Retrieves the next entry from a queue associated with `arg0` and `arg1`. It's assumed that the existence of `(arg0, arg1)` in `self` has already been verified.

```APIDOC
## get(arg0, arg1)

### Description
Get the next entry from the queue for `arg0` and `arg1`.

This function assumes you have already checked that `(arg0, arg1) in self`.

### Parameters
#### Path Parameters
- **arg0** (int | None) - Required - The `arg0` return value from the `_read_packet_from_device()` methods; `None` serves as a wildcard.
- **arg1** (int | None) - Required - The `arg1` return value from the `_read_packet_from_device()` methods; `None` serves as a wildcard.

### Returns
- **cmd** (bytes) - The ADB packet’s command.
- **arg0** (int) - The `arg0` value from the returned packet.
- **arg1** (int) - The `arg1` value from the returned packet.
- **data** (bytes) - The ADB packet’s data.
```

--------------------------------

### Connect to ADB Device and Send Shell Command

Source: https://github.com/jefflirion/adb_shell/blob/master/README.rst

Connect to an ADB device via TCP or USB, load RSA keys for authentication, and send shell commands. Ensure the USB package is installed if connecting via USB.

```python
from adb_shell.adb_device import AdbDeviceTcp, AdbDeviceUsb
from adb_shell.auth.sign_pythonrsa import PythonRSASigner

# Load the public and private keys
ada_key = 'path/to/adbkey'
with open(adbkey) as f:
    priv = f.read()
with open(adbkey + '.pub') as f:
     pub = f.read()
signer = PythonRSASigner(pub, priv)

# Connect
device1 = AdbDeviceTcp('192.168.0.222', 5555, default_transport_timeout_s=9.)
device1.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Connect via USB (package must be installed via `pip install adb-shell[usb])`
device2 = AdbDeviceUsb()
device2.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Send a shell command
response1 = device1.shell('echo TEST1')
response2 = device2.shell('echo TEST2')
```

--------------------------------

### Get User Information

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.auth.keygen.md

Retrieves user information in the format '<username>@<hostname>'. This is typically used for identifying the user or system generating keys.

```python
get_user_info()
```

--------------------------------

### Get File Metadata with AdbDevice.stat

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Retrieves file metadata (mode, size, mtime) from the device using the FileSync STAT command. Requires device connection setup.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_cryptography import CryptographySigner

signer = CryptographySigner('/home/user/.android/adbkey')
device = AdbDeviceTcp('192.168.1.50', 5555, default_transport_timeout_s=9.0)
device.connect(rsa_keys=[signer], auth_timeout_s=0.1)

mode, size, mtime = device.stat('/sdcard/Download/photo.jpg')
print(f'mode={oct(mode)}, size={size} bytes, mtime={mtime}')
# mode=0o100644, size=2048576 bytes, mtime=1700000000

device.close()
```

--------------------------------

### Connect to USB Device with AdbDeviceUsb

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Connect to an Android device via USB using `AdbDeviceUsb`. This requires the `[usb]` extra to be installed. Optionally, a specific device can be targeted by its serial number. Handles `InvalidTransportError` if USB support is not installed.

```python
from adb_shell.adb_device import AdbDeviceUsb
from adb_shell.auth.sign_cryptography import CryptographySigner
from adb_shell import exceptions

signer = CryptographySigner('/home/user/.android/adbkey')

try:
    # Connect to the first available USB device
    device = AdbDeviceUsb()
    device.connect(rsa_keys=[signer], auth_timeout_s=0.1)

    output = device.shell('getprop ro.serialno').strip()
    print('Serial:', output)

    device.close()
except exceptions.InvalidTransportError:
    print('Install adb-shell[usb] to use USB support')
```

--------------------------------

### max_chunk_size

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Gets the maximum chunk size for filesync operations.

```APIDOC
## property max_chunk_size

### Description
Maximum chunk size for filesync operations

### Returns
Minimum value based on [`adb_shell.constants.MAX_CHUNK_SIZE`](adb_shell.constants.md#adb_shell.constants.MAX_CHUNK_SIZE) and `_max_data / 2`, fallback to legacy [`adb_shell.constants.MAX_PUSH_DATA`](adb_shell.constants.md#adb_shell.constants.MAX_PUSH_DATA)

### Return type
int
```

--------------------------------

### Handle ADB Shell Exceptions

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Demonstrates how to connect to an ADB device, execute a shell command, and handle potential exceptions like AdbConnectionError, AdbTimeoutError, and DeviceAuthError. Ensure you have your RSA keys configured if authentication is required.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_cryptography import CryptographySigner
from adb_shell import exceptions

signer = CryptographySigner('/home/user/.android/adbkey')
device = AdbDeviceTcp('192.168.1.50', 5555, default_transport_timeout_s=2.0)

try:
    device.connect(rsa_keys=[signer], auth_timeout_s=0.1)
    result = device.shell('ls /nonexistent_path', timeout_s=5.0)
except exceptions.AdbConnectionError as e:
    print('Not connected:', e)
except exceptions.AdbTimeoutError as e:
    print('Timed out:', e)
except exceptions.DeviceAuthError as e:
    print('Auth error:', e)
finally:
    device.close()
```

--------------------------------

### UsbTransport.usb_info

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.md

Gets information about the USB device. This property is part of the UsbTransport class.

```APIDOC
## UsbTransport.usb_info

### Description
Gets information about the USB device.

### Method
`usb_info` (property)

### Parameters
None

### Request Example
None

### Response
#### Success Response (dict)
Returns a dictionary containing information about the USB device.

#### Response Example
None
```

--------------------------------

### connect

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Establishes an ADB connection to the device, handling authentication if necessary.

```APIDOC
## async connect(banner, rsa_keys, auth_timeout_s, auth_callback, adb_info)

### Description
Establish an ADB connection to the device.

### Parameters
* **banner** (*bytearray* *,* *bytes*) – The hostname of the machine where the Python interpreter is currently running.
* **rsa_keys** (*list* *,* *None*) – A list of signers of type [`CryptographySigner`](adb_shell.auth.sign_cryptography.md#adb_shell.auth.sign_cryptography.CryptographySigner), [`PycryptodomeAuthSigner`](adb_shell.auth.sign_pycryptodome.md#adb_shell.auth.sign_pycryptodome.PycryptodomeAuthSigner), or [`PythonRSASigner`](adb_shell.auth.sign_pythonrsa.md#adb_shell.auth.sign_pythonrsa.PythonRSASigner).
* **auth_timeout_s** (*float* *,* *None*) – The time in seconds to wait for a `b'CNXN'` authentication response.
* **auth_callback** (*function* *,* *None*) – Function callback invoked when the connection needs to be accepted on the device.
* **adb_info** ( [*\_AdbTransactionInfo*](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)) – Info and settings for this connection attempt.

### Returns
* **bool** – Whether the connection was established
* **maxdata** (*int*) – Maximum amount of data in an ADB packet

### Raises
* [**adb_shell.exceptions.DeviceAuthError**](adb_shell.exceptions.md#adb_shell.exceptions.DeviceAuthError) – Device authentication required, no keys available
* [**adb_shell.exceptions.InvalidResponseError**](adb_shell.exceptions.md#adb_shell.exceptions.InvalidResponseError) – Invalid auth response from the device
```

--------------------------------

### UsbTransport.serial_number

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.md

Gets the serial number of the USB device. This property is part of the UsbTransport class.

```APIDOC
## UsbTransport.serial_number

### Description
Gets the serial number of the USB device.

### Method
`serial_number` (property)

### Parameters
None

### Request Example
None

### Response
#### Success Response (str)
Returns the serial number of the USB device.

#### Response Example
None
```

--------------------------------

### connect

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Establishes an ADB connection to the device, handling authentication and initial handshake.

```APIDOC
## connect(banner, rsa_keys, auth_timeout_s, auth_callback, adb_info)

### Description
Establish an ADB connection to the device.

### Parameters
* **banner** (*bytearray* *,* *bytes*) – The hostname of the machine where the Python interpreter is currently running.
* **rsa_keys** (*list* *,* *None*) – A list of signers of type [`CryptographySigner`](adb_shell.auth.sign_cryptography.md#adb_shell.auth.sign_cryptography.CryptographySigner), [`PycryptodomeAuthSigner`](adb_shell.auth.sign_pycryptodome.md#adb_shell.auth.sign_pycryptodome.PycryptodomeAuthSigner), or [`PythonRSASigner`](adb_shell.auth.sign_pythonrsa.md#adb_shell.auth.sign_pythonrsa.PythonRSASigner).
* **auth_timeout_s** (*float* *,* *None*) – The time in seconds to wait for a `b'CNXN'` authentication response.
* **auth_callback** (*function* *,* *None*) – Function callback invoked when the connection needs to be accepted on the device.
* **adb_info** ( [*_AdbTransactionInfo*](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)) – Info and settings for this connection attempt.

### Returns
* **bool** – Whether the connection was established
* **maxdata** (*int*) – Maximum amount of data in an ADB packet

### Raises
* [**adb_shell.exceptions.DeviceAuthError**](adb_shell.exceptions.md#adb_shell.exceptions.DeviceAuthError) – Device authentication required, no keys available
* [**adb_shell.exceptions.InvalidResponseError**](adb_shell.exceptions.md#adb_shell.exceptions.InvalidResponseError) – Invalid auth response from the device
```

--------------------------------

### _open

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Opens a new connection to the ADB device using an 'OPEN' message.

```APIDOC
## _open(destination, transport_timeout_s, read_timeout_s, timeout_s)

### Description
Opens a new connection to the device via an `b'OPEN'` message.
1. [`send()`](#adb_shell.adb_device_async._AdbIOManagerAsync.send) an `b'OPEN'` command to the device that specifies the `local_id`
2. [`read()`](#adb_shell.adb_device_async._AdbIOManagerAsync.read) the response from the device and fill in the `adb_info.remote_id` attribute

### Parameters
#### Path Parameters
- **destination** (bytes) - Required - `b'SERVICE:COMMAND'`
- **transport_timeout_s** (float | None) - Required - Timeout in seconds for sending and receiving data, or `None`; see [`BaseTransportAsync.bulk_read()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_read) and [`BaseTransportAsync.bulk_write()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_write)
- **read_timeout_s** (float) - Required - The total time in seconds to wait for a `b'CLSE'` or `b'OKAY'` command in [`_AdbIOManagerAsync.read()`](#adb_shell.adb_device_async._AdbIOManagerAsync.read)
- **timeout_s** (float | None) - Required - The total time in seconds to wait for the ADB command to finish

### Returns
- **adb_info** ([\_AdbTransactionInfo](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)) - Info and settings for this ADB transaction
```

--------------------------------

### UsbTransport.port_path

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.md

Gets the port path of the USB transport. This property is part of the UsbTransport class.

```APIDOC
## UsbTransport.port_path

### Description
Gets the port path of the USB transport.

### Method
`port_path` (property)

### Parameters
None

### Request Example
None

### Response
#### Success Response (str)
Returns the port path of the USB transport.

#### Response Example
None
```

--------------------------------

### `AdbDevice.stat` — Get File Metadata

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Returns `(mode, size, mtime)` for a path on the device using the FileSync STAT command.

```APIDOC
## `AdbDevice.stat` — Get File Metadata

Returns `(mode, size, mtime)` for a path on the device using the FileSync STAT command.

### Parameters
- `path` (str): The path to the file on the device.

### Request Example
```python
mode, size, mtime = device.stat('/sdcard/Download/photo.jpg')
print(f'mode={oct(mode)}, size={size} bytes, mtime={mtime}')
# mode=0o100644, size=2048576 bytes, mtime=1700000000
```

### Response
- `tuple`: A tuple containing:
    - `mode` (int): File mode.
    - `size` (int): File size in bytes.
    - `mtime` (int): Last modification time (Unix timestamp).
```

--------------------------------

### Establish Connection

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Establishes an ADB connection to the device, handling authentication and configuration.

```APIDOC
## connect(rsa_keys=None, transport_timeout_s=None, auth_timeout_s=10.0, read_timeout_s=10.0, auth_callback=None)

### Description
Establishes an ADB connection to the device. This method handles the connection handshake and authentication process.

### Parameters
* **rsa_keys** (list | None) – A list of signers.
* **transport_timeout_s** (float | None) – Timeout in seconds for sending and receiving data.
* **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.
* **auth_callback** (function | None) – Function callback invoked when the connection needs to be accepted on the device.

### Returns
Whether the connection was established.

### Return type
bool
```

--------------------------------

### connect

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.usb_transport.md

Creates a USB connection to the device.

```APIDOC
## connect(transport_timeout_s=None)

### Description
Create a USB connection to the device.

### Parameters
#### Path Parameters
- **transport_timeout_s** (float, None) - Set the timeout on the USB instance
```

--------------------------------

### connect

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Establishes an ADB connection to the device. It allows for various timeouts and authentication callbacks.

```APIDOC
## connect(rsa_keys=None, transport_timeout_s=None, auth_timeout_s=10.0, read_timeout_s=10.0, auth_callback=None)

### Description
Establish an ADB connection to the device.

See [`_AdbIOManager.connect()`](#adb_shell.adb_device._AdbIOManager.connect).

### Parameters
#### Parameters
- **rsa_keys** (list or None) - A list of signers of type [`CryptographySigner`](adb_shell.auth.sign_cryptography.md#adb_shell.auth.sign_cryptography.CryptographySigner), [`PycryptodomeAuthSigner`](adb_shell.auth.sign_pycryptodome.md#adb_shell.auth.sign_pycryptodome.PycryptodomeAuthSigner), or [`PythonRSASigner`](adb_shell.auth.sign_pythonrsa.md#adb_shell.auth.sign_pythonrsa.PythonRSASigner)
- **transport_timeout_s** (float or None) - Timeout in seconds for sending and receiving data, or `None`; see [`BaseTransport.bulk_read()`](adb_shell.transport.base_transport.md#adb_shell.transport.base_transport.BaseTransport.bulk_read) and [`BaseTransport.bulk_write()`](adb_shell.transport.base_transport.md#adb_shell.transport.base_transport.BaseTransport.bulk_write)
- **auth_timeout_s** (float or 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 [`_AdbIOManager._read_expected_packet_from_device()`](#adb_shell.adb_device._AdbIOManager._read_expected_packet_from_device)
- **auth_callback** (function or None) - Function callback invoked when the connection needs to be accepted on the device

### Returns
Whether the connection was established ([`AdbDevice.available`](#adb_shell.adb_device.AdbDevice.available))

### Return type
bool
```

--------------------------------

### _service

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Sends an ADB command to the device and returns the output.

```APIDOC
## _service(service, command, transport_timeout_s=None, read_timeout_s=10.0, timeout_s=None, decode=True)

### Description
Send an ADB command to the device.

### Parameters
#### Path Parameters
* **service** (*bytes*) – The ADB service to talk to (e.g., `b'shell'`)
* **command** (*bytes*) – The command that will be sent
* **transport_timeout_s** (*float* *,* *None*) – Timeout in seconds for sending and receiving data, or `None`; see [`BaseTransportAsync.bulk_read()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_read)
  and [`BaseTransportAsync.bulk_write()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_write)
* **read_timeout_s** (*float*) – The total time in seconds to wait for a `b'CLSE'` or `b'OKAY'` command in [`_AdbIOManagerAsync.read()`](#adb_shell.adb_device_async._AdbIOManagerAsync.read)
* **timeout_s** (*float* *,* *None*) – The total time in seconds to wait for the ADB command to finish
* **decode** (*bool*) – Whether to decode the output to utf8 before returning

### Returns
The output of the ADB command as a string if `decode` is True, otherwise as bytes.

### Return type
bytes, str
```

--------------------------------

### AdbDeviceUsb

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Connects to an Android device via USB using libusb1. This class requires the `[usb]` extra to be installed. It can optionally target a specific device by its serial number.

```APIDOC
## AdbDeviceUsb

### Description
Synchronous USB Device connection class. Connects to a device via USB using `libusb1`. Requires the `[usb]` extra. Optionally target a specific device by serial number.

### Initialization
`AdbDeviceUsb()`

### Method
`connect(rsa_keys: list, auth_timeout_s: float = 0.1)`

### Parameters
#### Path Parameters
- **rsa_keys** (list) - Required - A list of signers for authentication.
- **auth_timeout_s** (float) - Optional - Timeout in seconds for authentication. Defaults to 0.1.

### Request Example
```python
from adb_shell.adb_device import AdbDeviceUsb
from adb_shell.auth.sign_cryptography import CryptographySigner

signer = CryptographySigner('/home/user/.android/adbkey')

# Connect to the first available USB device
device = AdbDeviceUsb()
device.connect(rsa_keys=[signer], auth_timeout_s=0.1)

output = device.shell('getprop ro.serialno').strip()
print('Serial:', output)

device.close()
```
```

--------------------------------

### PycryptodomeAuthSigner

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.auth.sign_pycryptodome.md

Initializes the AuthSigner using the pycryptodome package. It takes the path to the private key as an argument.

```APIDOC
## Class: PycryptodomeAuthSigner

### Description
AuthSigner using the pycryptodome package.

### Parameters
* **rsa_key_path** (str | None) - The path to the private key
```

--------------------------------

### Stream Shell Output with AdbDevice.streaming_shell

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Streams shell command output line by line as it arrives. Ideal for long-running commands or large outputs. Requires device connection setup.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_cryptography import CryptographySigner

signer = CryptographySigner('/home/user/.android/adbkey')
device = AdbDeviceTcp('192.168.1.50', 5555, default_transport_timeout_s=9.0)
device.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Stream logcat output
for chunk in device.streaming_shell('logcat -d -t 20'):
    print(chunk, end='')

device.close()
```

--------------------------------

### _push

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Asynchronously pushes a file-like object to the device.

```APIDOC
## _push(stream, device_path, st_mode, mtime, progress_callback, adb_info, filesync_info)

### Description
Push a file-like object to the device.

### Parameters
#### Path Parameters
* **stream** (*AsyncBufferedReader* *,*  [*_AsyncBytesIO*](#adb_shell.adb_device_async._AsyncBytesIO)) – File-like object for reading from
* **device_path** (*str*) – Destination on the device to write to
* **st_mode** (*int*) – Stat mode for the file
* **mtime** (*int*) – Modification time
* **progress_callback** (*function* *,* *None*) – Callback method that accepts `device_path`, `bytes_written`, and `total_bytes`
* **adb_info** ( [*_AdbTransactionInfo*](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)) – Info and settings for this ADB transaction

### Raises
[**PushFailedError**](adb_shell.exceptions.md#adb_shell.exceptions.PushFailedError) – Raised on push failure.
```

--------------------------------

### PythonRSASigner.FromRSAKeyPath

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.auth.sign_pythonrsa.md

Creates a PythonRSASigner instance from a given RSA private key file path. The corresponding public key is expected to be in a file with a .pub extension in the same directory.

```APIDOC
## PythonRSASigner.FromRSAKeyPath(rsa_key_path)

### Description
Creates a `PythonRSASigner` instance using the provided private key path. The public key is automatically derived from the private key path by appending '.pub'.

### Method
`classmethod`

### Parameters
* **rsa_key_path** (*str*) - The path to the RSA private key file.

### Returns
A `PythonRSASigner` instance configured with the specified private and public keys.

### Return type
[PythonRSASigner](#adb_shell.auth.sign_pythonrsa.PythonRSASigner)
```

--------------------------------

### list

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Retrieves a directory listing from the specified path on the device.

```APIDOC
## list(device_path, transport_timeout_s=None, read_timeout_s=10.0)

### Description
Return a directory listing of the given path.

### Parameters
#### Parameters
- **device_path** (str) - Directory to list.
- **transport_timeout_s** (float or 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 [`_AdbIOManager.read()`](#adb_shell.adb_device._AdbIOManager.read)

### Returns
**files** - Filename, mode, size, and mtime info for the files in the directory

### Return type
list[[DeviceFile](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers.DeviceFile)]
```

--------------------------------

### _push

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Pushes a file-like object to the device.

```APIDOC
## _push(stream, device_path, st_mode, mtime, progress_callback, adb_info)

### Description
Push a file-like object to the device.

### Parameters
* **stream** (*_io.BytesIO*) – File-like object for reading from
* **device_path** (*str*) – Destination on the device to write to
* **st_mode** (*int*) – Stat mode for the file
* **mtime** (*int*) – Modification time
* **progress_callback** (*function* *,* *None*) – Callback method that accepts `device_path`, `bytes_written`, and `total_bytes`
* **adb_info** (*_AdbTransactionInfo*) – Info and settings for this ADB transaction

### Raises
[**PushFailedError**](adb_shell.exceptions.md#adb_shell.exceptions.PushFailedError) – Raised on push failure.
```

--------------------------------

### Generate ADB Key Files

Source: https://github.com/jefflirion/adb_shell/blob/master/README.rst

Generate ADB key files using the keygen utility.

```python
from adb_shell.auth.keygen import keygen

keygen('path/to/adbkey')
```

--------------------------------

### PythonRSASigner — RSA Signer (rsa package)

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Loads an existing ADB key pair from disk and provides `Sign()` / `GetPublicKey()` methods used during device authentication. Use `FromRSAKeyPath` as a convenient factory that reads both key files automatically.

```APIDOC
## PythonRSASigner — RSA Signer (rsa package)

Loads an existing ADB key pair from disk and provides `Sign()` / `GetPublicKey()` methods used during device authentication. Use `FromRSAKeyPath` as a convenient factory that reads both key files automatically.

```python
from adb_shell.auth.sign_pythonrsa import PythonRSASigner

# Load from file paths
signer = PythonRSASigner.FromRSAKeyPath('/home/user/.android/adbkey')

# Or load manually from file contents
with open('/home/user/.android/adbkey') as f:
    priv = f.read()
with open('/home/user/.android/adbkey.pub') as f:
    pub = f.read()
signer = PythonRSASigner(pub, priv)

print(type(signer.GetPublicKey()))  # <class 'str'>
```
```

--------------------------------

### AdbDevice.connect — Establish ADB Connection

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Performs the full ADB handshake: sends `CNXN`, handles `AUTH` challenges by trying each RSA key in order, and optionally calls `auth_callback` to prompt the user to approve the connection on the device screen.

```APIDOC
## AdbDevice.connect — Establish ADB Connection

Performs the full ADB handshake: sends `CNXN`, handles `AUTH` challenges by trying each RSA key in order, and optionally calls `auth_callback` to prompt the user to approve the connection on the device screen.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_pythonrsa import PythonRSASigner

signer = PythonRSASigner.FromRSAKeyPath('/home/user/.android/adbkey')
device = AdbDeviceTcp('10.0.0.5', 5555, default_transport_timeout_s=9.0)

def on_auth_required(device):
    print('Please accept the RSA key prompt on your Android device.')

connected = device.connect(
    rsa_keys=[signer],
    auth_timeout_s=10.0,      # wait up to 10 s for user to tap "Allow"
    read_timeout_s=10.0,
    auth_callback=on_auth_required,
)
# Returns True if connection succeeded
assert connected is True
```
```

--------------------------------

### Execute exec-out Command with AdbDevice.exec_out

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Uses the `exec` ADB service for binary-safe output, bypassing PTY artifacts. Useful for commands like `screencap` where exact output is needed. `decode=False` is default.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_cryptography import CryptographySigner

signer = CryptographySigner('/home/user/.android/adbkey')
device = AdbDeviceTcp('192.168.1.50', 5555, default_transport_timeout_s=9.0)
device.connect(rsa_keys=[signer], auth_timeout_s=0.1)

# Binary-safe output without PTY artifacts
data = device.exec_out('screencap -p', decode=False)
with open('/tmp/screenshot.png', 'wb') as f:
    f.write(data)
print('Screenshot saved, size:', len(data), 'bytes')

device.close()
```

--------------------------------

### _open

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Opens a new connection to the device using an 'OPEN' message and retrieves the remote ID.

```APIDOC
## _open(destination, transport_timeout_s, read_timeout_s, timeout_s)

### Description
Opens a new connection to the device via an `b'OPEN'` message.

1. [`send()`](#adb_shell.adb_device._AdbIOManager.send) an `b'OPEN'` command to the device that specifies the `local_id`
2. [`read()`](#adb_shell.adb_device._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 data, or `None`; see [`BaseTransport.bulk_read()`](adb_shell.transport.base_transport.md#adb_shell.transport.base_transport.BaseTransport.bulk_read)
    and [`BaseTransport.bulk_write()`](adb_shell.transport.base_transport.md#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 [`_AdbIOManager.read()`](#adb_shell.adb_device._AdbIOManager.read)
* **timeout_s** (*float* *,* *None*) – The total time in seconds to wait for the ADB command to finish

### Returns
**adb_info** – Info and settings for this ADB transaction

### Return type
[_AdbTransactionInfo](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)
```

--------------------------------

### int_to_cmd() function

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_message.md

Converts a 4-byte integer into an ADB command string.

```APIDOC
### adb_shell.adb_message.int_to_cmd(n)

Convert from an integer (4 bytes) to an ADB command.

* **Parameters:**
  **n** (*int*) – The integer that will be converted to an ADB command
* **Returns:**
  The ADB command (e.g., `'CNXN'`)
* **Return type:**
  str
```

--------------------------------

### available

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Checks if an ADB connection to the device is currently established.

```APIDOC
## available

### Description
Whether or not an ADB connection to the device has been established.

### Returns
`self._available`

### Return type
bool
```

--------------------------------

### put(arg0, arg1, cmd, data)

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.hidden_helpers.md

Adds an entry to the queue for `arg0` and `arg1`. A new dictionary entry will not be created if `cmd` is equal to `constants.CLSE`.

```APIDOC
## put(arg0, arg1, cmd, data)

### Description
Add an entry to the queue for `arg0` and `arg1`.

Note that a new dictionary entry will not be created if `cmd == constants.CLSE`.

### Parameters
#### Path Parameters
- **arg0** (int) - Required - The `arg0` return value from the `_read_packet_from_device()` methods.
- **arg1** (int) - Required - The `arg1` return value from the `_read_packet_from_device()` methods.
- **cmd** (bytes) - Required - The ADB packet’s command.
- **data** (bytes) - Required - The ADB packet’s data.
```

--------------------------------

### push

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Pushes a file or directory from the local path to the device.

```APIDOC
## async push(local_path, device_path, st_mode=33272, mtime=0, progress_callback=None, transport_timeout_s=None, read_timeout_s=10.0)

### Description
Push a file or directory to the device.

### Parameters
#### Path Parameters
- **local_path** (str | BytesIO) - Required - A filename, directory, or BytesIO stream to push to the device
- **device_path** (str) - Required - Destination on the device to write to
#### Query Parameters
- **st_mode** (int) - Optional - Stat mode for `local_path`
- **mtime** (int) - Optional - Modification time to set on the file
- **progress_callback** (function | None) - Optional - Callback method that accepts `device_path`, `bytes_written`, and `total_bytes`
- **transport_timeout_s** (float | None) - Optional - Expected timeout for any part of the push
- **read_timeout_s** (float) - Optional - The total time in seconds to wait for a `b'CLSE'` or `b'OKAY'` command in [`_AdbIOManagerAsync.read()`](#adb_shell.adb_device_async._AdbIOManagerAsync.read)
```

--------------------------------

### _okay

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Sends an 'OKAY' message as part of an ADB transaction.

```APIDOC
## _okay(adb_info)

### Description
Send an `b'OKAY'` mesage.

### Parameters
* **adb_info** (*_AdbTransactionInfo*) – Info and settings for this ADB transaction
```

--------------------------------

### adb_shell.auth.keygen.get_user_info

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.auth.keygen.md

Retrieves user information in the format '<username>@<hostname>'.

```APIDOC
## get_user_info()

### Description
TODO

### Returns
`' <username>@<hostname>`

### Return type
str
```

--------------------------------

### Connect to TCP Device (Synchronous)

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Establish a synchronous connection to an Android device over TCP/IP. Requires an RSA signer and handles connection and authentication timeouts.

```python
from adb_shell.adb_device import AdbDeviceTcp
from adb_shell.auth.sign_cryptography import CryptographySigner
from adb_shell import exceptions

signer = CryptographySigner('/home/user/.android/adbkey')

device = AdbDeviceTcp('192.168.1.50', 5555, default_transport_timeout_s=9.0)

try:
    connected = device.connect(rsa_keys=[signer], auth_timeout_s=0.1)
    print('Connected:', connected)          # Connected: True
    print('Available:', device.available)   # Available: True
except exceptions.DeviceAuthError as e:
    print('Auth failed:', e)
finally:
    device.close()
```

--------------------------------

### _service

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Sends an ADB command to the device and returns the output. Handles both byte and string outputs based on the decode parameter.

```APIDOC
## _service(service, command, transport_timeout_s=None, read_timeout_s=10.0, timeout_s=None, decode=True)

### Description
Send an ADB command to the device.

### Parameters
#### Parameters
- **service** (bytes) - Required - The ADB service to talk to (e.g., `b'shell'`)
- **command** (bytes) - Required - The command that will be sent
- **transport_timeout_s** (float | None) - Optional - Timeout in seconds for sending and receiving data
- **read_timeout_s** (float) - Optional - The total time in seconds to wait for a `b'CLSE'` or `b'OKAY'` command
- **timeout_s** (float | None) - Optional - The total time in seconds to wait for the ADB command to finish
- **decode** (bool) - Optional - Whether to decode the output to utf8 before returning

### Returns
The output of the ADB command as a string if `decode` is True, otherwise as bytes.

### Return type
bytes, str
```

--------------------------------

### Sign Method

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.auth.sign_cryptography.md

Signs the provided data using the instance's private RSA key.

```APIDOC
## Method: Sign

### Description
Signs given data using a private key.

### Parameters
* **data** (TODO) – TODO

### Returns
* The signed `data`
* **Return type:** TODO
```

--------------------------------

### _send

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Asynchronously sends a message to the ADB device, first sending the header and then the data.

```APIDOC
## async _send(msg, adb_info)

Send a message to the device.

1. Send the message header (`adb_shell.adb_message.AdbMessage.pack`)
2. Send the message data

* **Parameters:**
  * **msg** ([*AdbMessage*](adb_shell.adb_message.md#adb_shell.adb_message.AdbMessage)) – The data that will be sent
  * **adb_info** ( [*_AdbTransactionInfo*](adb_shell.hidden_helpers.md#adb_shell.hidden_helpers._AdbTransactionInfo)) – Info and settings for this ADB transaction
```

--------------------------------

### AdbDeviceAsync Constructor

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Initializes an AdbDeviceAsync instance with a transport layer for device communication. It accepts optional parameters for default transport timeout and a banner indicating the local hostname.

```APIDOC
## AdbDeviceAsync(transport, default_transport_timeout_s=None, banner=None)

### Description
Initializes an AdbDeviceAsync instance.

### Parameters
* **transport** ([*BaseTransportAsync*](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync)) – A user-provided transport for communicating with the device; must be an instance of a subclass of [`BaseTransportAsync`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync)
* **default_transport_timeout_s** (*float* *,* *None*) – Default timeout in seconds for transport 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.InvalidTransportError**](adb_shell.exceptions.md#adb_shell.exceptions.InvalidTransportError) – The passed `transport` is not an instance of a subclass of [`BaseTransportAsync`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync)
```

--------------------------------

### shell

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device_async.md

Send an ADB shell command to the device and retrieve its output.

```APIDOC
## shell

Send an ADB shell command to the device.

### Parameters

* **command** (*str*) – The shell command that will be sent
* **transport_timeout_s** (*float* | *None*) – Timeout in seconds for sending and receiving data, or `None`; see [`BaseTransportAsync.bulk_read()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_read) and [`BaseTransportAsync.bulk_write()`](adb_shell.transport.base_transport_async.md#adb_shell.transport.base_transport_async.BaseTransportAsync.bulk_write)
* **read_timeout_s** (*float*) – The total time in seconds to wait for a `b'CLSE'` or `b'OKAY'` command in [`_AdbIOManagerAsync.read()`](#adb_shell.adb_device_async._AdbIOManagerAsync.read)
* **timeout_s** (*float* | *None*) – The total time in seconds to wait for the ADB command to finish
* **decode** (*bool*) – Whether to decode the output to utf8 before returning

### Returns

The output of the ADB shell command as a string if `decode` is True, otherwise as bytes.

### Return type

bytes, str
```

--------------------------------

### exec_out

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.adb_device.md

Sends an ADB `exec-out` command to the device and returns its output.

```APIDOC
## exec_out(command, transport_timeout_s=None, read_timeout_s=10.0, timeout_s=None, decode=True)

### Description
Send an ADB `exec-out` command to the device.

[https://www.linux-magazine.com/Issues/2017/195/Ask-Klaus](https://www.linux-magazine.com/Issues/2017/195/Ask-Klaus)

### Parameters
#### Parameters
- **command** (str) - The exec-out command that will be sent
- **transport_timeout_s** (float or None) - Timeout in seconds for sending and receiving data, or `None`; see [`BaseTransport.bulk_read()`](adb_shell.transport.base_transport.md#adb_shell.transport.base_transport.BaseTransport.bulk_read) and [`BaseTransport.bulk_write()`](adb_shell.transport.base_transport.md#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 [`_AdbIOManager.read()`](#adb_shell.adb_device._AdbIOManager.read)
- **timeout_s** (float or None) - The total time in seconds to wait for the ADB command to finish
- **decode** (bool) - Whether to decode the output to utf8 before returning

### Returns
The output of the ADB exec-out command as a string if `decode` is True, otherwise as bytes.

### Return type
bytes, str
```

--------------------------------

### UsbTransport.connect()

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.usb_transport.md

Establishes a connection to the USB device. This method is essential for initiating communication after the UsbTransport object has been created.

```APIDOC
## UsbTransport.connect()

Connects to the USB device.
```

--------------------------------

### AdbDevice.list

Source: https://context7.com/jefflirion/adb_shell/llms.txt

Lists the contents of a directory on the remote device. It returns a list of DeviceFile named tuples, each containing filename, mode, size, and modification time.

```APIDOC
## AdbDevice.list

### Description
Returns a list of `DeviceFile` named tuples (filename, mode, size, mtime) for all entries in a device directory.

### Method
`list(path: str)`

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to the directory on the device to list.

### Response
- **DeviceFile** (named tuple) - A list of named tuples, where each tuple represents a file or directory entry with attributes: filename, mode, size, mtime.

### Request Example
```python
files = device.list('/sdcard/Download')
for f in files:
    print(f'{f.filename:40s}  {f.size:>10d} bytes  mode={oct(f.mode)}')
```
```

--------------------------------

### TcpTransport.connect()

Source: https://github.com/jefflirion/adb_shell/blob/master/docs/source/adb_shell.transport.tcp_transport.md

Establishes a TCP socket connection to the ADB device.

```APIDOC
## connect(transport_timeout_s)

### Description
Create a socket connection to the device.

### Parameters
* **transport_timeout_s** (float | None) - Optional - Set the timeout on the socket instance
```