adb.adb_commands module

A libusb1-based ADB reimplementation.

ADB was giving us trouble with its client/server architecture, which is great for users and developers, but not so great for reliable scripting. This will allow us to more easily catch errors as Python exceptions instead of checking random exit codes, and all the other great benefits from not going through subprocess and a network socket.

All timeouts are in milliseconds.

Contents

• AdbCommands

  • AdbCommands.__reset()

  • AdbCommands._Connect()

  • AdbCommands._get_service_connection()

  • AdbCommands.Close()

  • AdbCommands.ConnectDevice()

  • AdbCommands.Devices()

  • AdbCommands.DisableVerity()

  • AdbCommands.EnableVerity()

  • AdbCommands.GetState()

  • AdbCommands.Install()

  • AdbCommands.InteractiveShell()

  • AdbCommands.List()

  • AdbCommands.Logcat()

  • AdbCommands.Pull()

  • AdbCommands.Push()

  • AdbCommands.Reboot()

  • AdbCommands.RebootBootloader()

  • AdbCommands.Remount()

  • AdbCommands.Root()

  • AdbCommands.Shell()

  • AdbCommands.Stat()

  • AdbCommands.StreamingShell()

  • AdbCommands.Uninstall()

class adb.adb_commands.AdbCommands

Bases: object

Exposes adb-like methods for use.

Some methods are more-pythonic and/or have more options.

build_props

TODO

Type

TODO, None

filesync_handler

TODO

Type

filesync_protocol.FilesyncProtocol

protocol_handler

TODO

Type

adb_protocol.AdbMessage

_device_state

TODO

Type

TODO, None

_handle

TODO

Type

adb.common.TcpHandle, adb.common.UsbHandle, None

_service_connections

[TODO] Connection table tracks each open AdbConnection objects per service type for program functions that choose to persist an AdbConnection object for their functionality, using AdbCommands._get_service_connection()

Type

dict

Close()

TODO

ConnectDevice(port_path=None, serial=None, default_timeout_ms=None, **kwargs)

Convenience function to setup a transport handle for the adb device from usb path or serial then connect to it.

Parameters

• port_path (TODO, None) – The filename of usb port to use.

• serial (TODO, None) – The serial number of the device to use. If serial specifies a TCP address:port, then a TCP connection is used instead of a USB connection.

• default_timeout_ms (TODO, None) – The default timeout in milliseconds to use.

• **kwargs – Keyword arguments

• handle (common.TcpHandle, common.UsbHandle) – Device handle to use

• banner (TODO) – Connection banner to pass to the remote device

• rsa_keys (list[adb_protocol.AuthSigner]) – List of AuthSigner subclass instances to be used for authentication. The device can either accept one of these via the Sign method, or we will send the result of GetPublicKey from the first one if the device doesn’t accept any of them.

• auth_timeout_ms (int) – Timeout to wait for when sending a new public key. This is only relevant when we send a new public key. The device shows a dialog and this timeout is how long to wait for that dialog. If used in automation, this should be low to catch such a case as a failure quickly; while in interactive settings it should be high to allow users to accept the dialog. We default to automation here, so it’s low by default.

Returns

self – TODO

Return type

AdbCommands

classmethod Devices()

Get a generator of UsbHandle for devices available.

Returns

TODO

Return type

TODO

DisableVerity()

Disable dm-verity checking on userdebug builds.

Returns

TODO

Return type

TODO

EnableVerity()

Re-enable dm-verity checking on userdebug builds.

Returns

TODO

Return type

TODO

GetState()

TODO

Returns

self._device_state – TODO

Return type

TODO

Install(apk_path, destination_dir='', replace_existing=True, grant_permissions=False, timeout_ms=None, transfer_progress_callback=None)

Install an apk to the device.

Doesn’t support verifier file, instead allows destination directory to be overridden.

Parameters

• apk_path (TODO) – Local path to apk to install.

• destination_dir (str) – Optional destination directory. Use /system/app/ for persistent applications.

• replace_existing (bool) – Whether to replace existing application

• grant_permissions (bool) – If True, grant all permissions to the app specified in its manifest

• timeout_ms (int, None) – Expected timeout for pushing and installing.

• transfer_progress_callback (TODO, None) – callback method that accepts filename, bytes_written, and total_bytes of APK transfer

Returns

ret – The pm install output.

Return type

TODO

InteractiveShell(cmd=None, strip_cmd=True, delim=None, strip_delim=True)

Get stdout from the currently open interactive shell and optionally run a command on the device, returning all output.

Parameters

• cmd (TODO, None) – Command to run on the target.

• strip_cmd (bool) – Strip command name from stdout.

• delim (TODO, None) – Delimiter to look for in the output to know when to stop expecting more output (usually the shell prompt)

• strip_delim (bool) – Strip the provided delimiter from the output

Returns

The stdout from the shell command.

Return type

TODO

List(device_path)

Return a directory listing of the given path.

Parameters

device_path (TODO) – Directory to list.

Returns

listing – TODO

Return type

TODO

Logcat(options, timeout_ms=None)

Run shell logcat and stream the output to stdout.

Parameters

• options (str) – Arguments to pass to logcat

• timeout_ms (int, None) – Maximum time to allow the command to run.

Returns

The responses from the logcat command

Return type

generator

Pull(device_filename, dest_file=None, timeout_ms=None, progress_callback=None)

Pull a file from the device.

Parameters

• device_filename (TODO) – Filename on the device to pull.

• dest_file (str, file, io.IOBase, None) – If set, a filename or writable file-like object.

• timeout_ms (int, None) – Expected timeout for any part of the pull.

• progress_callback (TODO, None) – Callback method that accepts filename, bytes_written and total_bytes, total_bytes will be -1 for file-like objects

Returns

The file data if dest_file is not set. Otherwise, True if the destination file exists

Return type

TODO

Raises

ValueError – If dest_file is of unknown type.

Push(source_file, device_filename, mtime='0', timeout_ms=None, progress_callback=None, st_mode=None)

Push a file or directory to the device.

Parameters

• source_file (TODO) – Either a filename, a directory or file-like object to push to the device.

• device_filename (TODO) – Destination on the device to write to.

• mtime (str) – Modification time to set on the file.

• timeout_ms (int, None) – Expected timeout for any part of the push.

• progress_callback (TODO, None) – Callback method that accepts filename, bytes_written and total_bytes, total_bytes will be -1 for file-like objects

• st_mode (TODO, None) – Stat mode for filename

Reboot(destination=b'')

Reboot the device.

Parameters

destination (bytes) – Specify 'bootloader' for fastboot.

RebootBootloader()

Reboot device into fastboot.

Remount()

Remount / as read-write.

Returns

TODO

Return type

TODO

Root()

Restart adbd as root on the device.

Returns

TODO

Return type

TODO

Shell(command, timeout_ms=None)

Run command on the device, returning the output.

Parameters

• command (TODO) – Shell command to run

• timeout_ms (int, None) – Maximum time to allow the command to run.

Returns

TODO

Return type

TODO

Stat(device_filename)

Get a file’s stat() information.

Parameters

device_filename (TODO) – TODO

Returns

• mode (TODO) – TODO

• size (TODO) – TODO

• mtime (TODO) – TODO

StreamingShell(command, timeout_ms=None)

Run command on the device, yielding each line of output.

Parameters

• command (bytes) – Command to run on the target.

• timeout_ms (int, None) – Maximum time to allow the command to run.

Returns

The responses from the shell command.

Return type

generator

Uninstall(package_name, keep_data=False, timeout_ms=None)

Removes a package from the device.

Parameters

• package_name (TODO) – Package name of target package.

• keep_data (bool) – Whether to keep the data and cache directories

• timeout_ms (int, None) – Expected timeout for pushing and installing.

Returns

The pm uninstall output.

Return type

TODO

_AdbCommands__reset()

TODO

_Connect(banner=None, **kwargs)

Connect to the device.

Parameters

• banner (bytes, None) – A string to send as a host identifier. (See adb.adb_protocol.AdbMessage.Connect().)

• **kwargs (TODO) – See adb.adb_protocol.AdbMessage.Connect() and AdbCommands.ConnectDevice() for kwargs. Includes handle, rsa_keys, and auth_timeout_ms.

Returns

True

Return type

bool

_get_service_connection(service, service_command=None, create=True, timeout_ms=None)

Based on the service, get the AdbConnection for that service or create one if it doesnt exist

Parameters

• service (TODO) – TODO

• service_command (TODO, None) – Additional service parameters to append

• create (bool) – If False, don’t create a connection if it does not exist

• timeout_ms (int, None) – TODO

Returns

connection – TODO

Return type

TODO

filesync_handler

alias of adb.filesync_protocol.FilesyncProtocol

protocol_handler

alias of adb.adb_protocol.AdbMessage

adb.adb_commands.CLASS = 255

From adb.h

adb.adb_commands.DeviceIsAvailable(device)

From adb.h

adb.adb_commands.PROTOCOL = 1

From adb.h

adb.adb_commands.SUBCLASS = 66

From adb.h