# adb-pywrapper
A python wrapper for the Android Debug Bridge enabling interaction with Android devices and emulators.
<img src="adb-pywrapper_logo.jpg" alt="adb-pywrapper logo" width="500"/>
## AdbDevice: Interacting with Android Devices using ADB in Python
The `AdbDevice` class in the `adb-pywrapper` Python package facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) directly within Python scripts.
Installation
------------
To install the `adb-pywrapper` package from the internal Nexus PyPI server, you can use `pip`:
```bash
pip install adb-pywrapper
```
Before using `adb-pywrapper`, ensure that ADB is installed on your machine and added to PATH. You can download and install the Android SDK, which includes ADB, from the official Android developer website.
If running the below in a terminal gives you an output, you are ready to go!
```bash
adb --version
```
## Getting Started
Import the necessary modules:
```python
from adb-pywrapper import AdbDevice, AdbResult, PullResult
```
## Listing Connected Devices
You can list all connected devices using the `list_devices` method (this can be done before creating an instance):
Looks for connected adb devices and returns the device names in a list.
`:return:` list of adb device names. Example: `['device-5554','AU9AD74','netagfer987']`
```python
devices = AdbDevice.list_devices()
```
### get_device_status
After which you can also get the status of said device without having initialized AdbDevice since this way you can see if the device might be `offline` or `unauthorized`
Get the status corresponding to the device_name. This uses the 'adb devices' command.
`:param device_name:` the device adb name/identifier.
`:return:` a string with the status of the given device. Example: 'offline', 'device' or 'unauthorized'
```python
status = AdbDevice.get_device_status('your_device_identifier')
```
# Creating an ADB Device Instance
To interact with a specific Android device, create an instance of the `AdbDevice` class. You can specify the device identifier as an argument (obtained from either Adb using `adb devices`).
```python
adb_device = AdbDevice(device='your_device_identifier')
```
## ADB Commands
All the commands below can be called once a device instance has been initiated. This is exemplified by the `adb_device` variable.
## getting root privileges
You can gain root privilages using the `root` method:
Restarts adb with root privileges.
`:return:` AdbResult containing the completed process of `adb root`
```python
adb_device.root()
```
- Expected result: AdbResult instance with either `success=True and stdout='{device_status}'` or `success=False and stderr='ADB error'`
## Executing Shell Commands
You can excecute shell commands on the device using the `shell` method:
Executes a command on the shell of the device like: `adb shell {command}`
`:param command:` the command to run on the shell of the connected device.
`:return:` AdbResult containing the completed process of `adb shell {command}`
```python
shell_result = adb_device.shell(command="dumpsys activity")
```
## Pulling Files from the Device
You can pull files from the device using the `pull` method:
Copies a file off the device to a given local directory
`:param file_to_pull:` complete path to the file to copy from the device
`:param destination:` the directory in which the package file(s) are to be located. Will be created if needed.
`:return:` A PullResult object with the completed_adb_process of the `adb pull` action, the destination path and a success flag
```python
pull_result = adb_device.pull(file_to_pull='/path/on/device/file', destination='/local/path')
#example usage
if pull_result.success:
print(f"File pulled to: {pull_result.path}")
else:
print(f"File pull failed. See {pull_result.completed_adb_process}.")
```
## Installing APKs
You can install APK files on the device using the `install` method:
Installs a given apk on the connected device.
`:param apk_path:` the location of the apk file on the local machine
`:param r: -r option:` replace already installed application. This is needed on physical devices or if you get an error that the application already exists and should be uninstalled first.
`:return:` the completed process of 'adb install [-r] {apk_path}'
```python
install_result = adb_device.install(apk_path='/local/path/to/apk')
if install_result.success:
print("APK installed successfully.")
else:
print("APK installation failed.")
```
## Opening Intents
You can open intents on the device using the `open_intent` method. This is useful for opening URLs:
Opens a given url on the device by starting an intent. If a default app is associated with this URL, this will
result in the app being opened.
`:param url:` The URL to open
`:return:` the completed process of adb shell and start -a android.intent.action.VIEW -d '{url}'
```python
intent_result = adb_device.open_intent(url='http://example.com')
if intent_result.success:
print("Intent opened successfully.")
else:
print("Failed to open intent.")
```
## Getting properties
You can get properties from the device using the `get_prop` method:
Retrieves the value of a given property through the `adb getprop method`
`:param property:` the property from which the value is needed
`:return:` the value of the property, or None if the property doesn't exist
```python
intent_result = adb_device.open_intent(url='http://example.com')
if intent_result.success:
print("Intent opened successfully.")
else:
print("Failed to open intent.")
```
## Overview
We cannot cover everything in detail here, but here is a more general overview of all the functionality
#### Initialization and Connection:
* AdbDevice(device=None, check_device_exists=True)
* get_device_status(device_name)
#### General Information:
* get_device_status(device_name)
* get_state()
#### Executing Shell Commands:
* shell(command, timeout=None)
* root()
* wait_for_device()
* emu_avd(command)
#### Management of Installed Packages:
* installed_packages()
* path_package(package_name)
* package_versions(package_name)
#### File Management:
ls(path)
* pull(file_to_pull, destination)
* pull_multi(files_to_pull, destination)
#### APK Management:
* pull_package(package_name, destination)
* install(apk_path, r=False)
* install_multiple(apk_paths, r=False)
#### Intent and URL Handling:
* open_intent(url)
#### Emulator Snapshot Management:
* snapshots_list()
* snapshot_exists(snapshot_name)
* snapshot_load(snapshot_name)
* snapshot_save(snapshot_name)
* snapshot_delete(delete=None)
## Error Handling
Be sure to handle errors gracefully in your code, as various operations may fail, adb-pywrapper tries to provide information where possible on success or failure in the `AdbResult` and `PullResult` objects.
## Contributing
Contributions to the adb-pywrapper package are welcome. If you encounter any issues, have suggestions, or want to contribute, feel free to open an issue or PR. Find our contribution guidelines [here](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/NetherlandsForensicInstitute/adb-pywrapper",
"name": "adb-pywrapper",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Netherlands Forensic Institute",
"author_email": "netherlandsforensicinstitute@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/b7/c2/9b383391ec6313fb2e9a69367c2ad619f4c3e910ce973f904d2546588143/adb_pywrapper-1.0.0.tar.gz",
"platform": null,
"description": "# adb-pywrapper\nA python wrapper for the Android Debug Bridge enabling interaction with Android devices and emulators.\n\n<img src=\"adb-pywrapper_logo.jpg\" alt=\"adb-pywrapper logo\" width=\"500\"/>\n\n\n## AdbDevice: Interacting with Android Devices using ADB in Python\n\nThe `AdbDevice` class in the `adb-pywrapper` Python package facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) directly within Python scripts.\n\nInstallation\n------------\n\nTo install the `adb-pywrapper` package from the internal Nexus PyPI server, you can use `pip`:\n\n```bash\npip install adb-pywrapper\n```\n\nBefore using `adb-pywrapper`, ensure that ADB is installed on your machine and added to PATH. You can download and install the Android SDK, which includes ADB, from the official Android developer website.\n\nIf running the below in a terminal gives you an output, you are ready to go!\n\n```bash\nadb --version\n```\n\n## Getting Started\n\nImport the necessary modules:\n\n```python\nfrom adb-pywrapper import AdbDevice, AdbResult, PullResult\n```\n\n## Listing Connected Devices\n\nYou can list all connected devices using the `list_devices` method (this can be done before creating an instance):\n\nLooks for connected adb devices and returns the device names in a list. \n`:return:` list of adb device names. Example: `['device-5554','AU9AD74','netagfer987']`\n```python\ndevices = AdbDevice.list_devices()\n```\n\n### get_device_status\nAfter which you can also get the status of said device without having initialized AdbDevice since this way you can see if the device might be `offline` or `unauthorized`\n\nGet the status corresponding to the device_name. This uses the 'adb devices' command. \n`:param device_name:` the device adb name/identifier. \n`:return:` a string with the status of the given device. Example: 'offline', 'device' or 'unauthorized'\n```python\nstatus = AdbDevice.get_device_status('your_device_identifier')\n```\n\n# Creating an ADB Device Instance\n\nTo interact with a specific Android device, create an instance of the `AdbDevice` class. You can specify the device identifier as an argument (obtained from either Adb using `adb devices`).\n\n```python\nadb_device = AdbDevice(device='your_device_identifier')\n```\n\n## ADB Commands\nAll the commands below can be called once a device instance has been initiated. This is exemplified by the `adb_device` variable.\n\n## getting root privileges\nYou can gain root privilages using the `root` method:\n\nRestarts adb with root privileges. \n`:return:` AdbResult containing the completed process of `adb root`\n```python\nadb_device.root()\n```\n- Expected result: AdbResult instance with either `success=True and stdout='{device_status}'` or `success=False and stderr='ADB error'`\n\n## Executing Shell Commands\nYou can excecute shell commands on the device using the `shell` method:\n\nExecutes a command on the shell of the device like: `adb shell {command}` \n`:param command:` the command to run on the shell of the connected device. \n`:return:` AdbResult containing the completed process of `adb shell {command}`\n```python\nshell_result = adb_device.shell(command=\"dumpsys activity\")\n```\n\n## Pulling Files from the Device\nYou can pull files from the device using the `pull` method:\n\nCopies a file off the device to a given local directory \n`:param file_to_pull:` complete path to the file to copy from the device \n`:param destination:` the directory in which the package file(s) are to be located. Will be created if needed. \n`:return:` A PullResult object with the completed_adb_process of the `adb pull` action, the destination path and a success flag\n\n```python\npull_result = adb_device.pull(file_to_pull='/path/on/device/file', destination='/local/path')\n\n#example usage\nif pull_result.success:\n print(f\"File pulled to: {pull_result.path}\")\nelse:\n print(f\"File pull failed. See {pull_result.completed_adb_process}.\")\n```\n\n## Installing APKs\n\nYou can install APK files on the device using the `install` method:\n\nInstalls a given apk on the connected device. \n`:param apk_path:` the location of the apk file on the local machine \n`:param r: -r option:` replace already installed application. This is needed on physical devices or if you get an error that the application already exists and should be uninstalled first. \n`:return:` the completed process of 'adb install [-r] {apk_path}' \n\n```python\ninstall_result = adb_device.install(apk_path='/local/path/to/apk')\nif install_result.success:\n print(\"APK installed successfully.\")\nelse:\n print(\"APK installation failed.\")\n```\n\n## Opening Intents\nYou can open intents on the device using the `open_intent` method. This is useful for opening URLs:\n\nOpens a given url on the device by starting an intent. If a default app is associated with this URL, this will \nresult in the app being opened. \n`:param url:` The URL to open \n`:return:` the completed process of adb shell and start -a android.intent.action.VIEW -d '{url}' \n```python\nintent_result = adb_device.open_intent(url='http://example.com')\nif intent_result.success:\n print(\"Intent opened successfully.\")\nelse:\n print(\"Failed to open intent.\")\n```\n\n## Getting properties\n\nYou can get properties from the device using the `get_prop` method:\n\nRetrieves the value of a given property through the `adb getprop method` \n`:param property:` the property from which the value is needed \n`:return:` the value of the property, or None if the property doesn't exist \n```python\nintent_result = adb_device.open_intent(url='http://example.com')\nif intent_result.success:\n print(\"Intent opened successfully.\")\nelse:\n print(\"Failed to open intent.\")\n```\n\n## Overview\n\nWe cannot cover everything in detail here, but here is a more general overview of all the functionality\n\n#### Initialization and Connection: \n* AdbDevice(device=None, check_device_exists=True) \n* get_device_status(device_name) \n\n#### General Information: \n* get_device_status(device_name) \n* get_state() \n\n#### Executing Shell Commands: \n* shell(command, timeout=None) \n* root() \n* wait_for_device() \n* emu_avd(command) \n\n#### Management of Installed Packages: \n* installed_packages() \n* path_package(package_name) \n* package_versions(package_name) \n\n#### File Management: \nls(path) \n* pull(file_to_pull, destination) \n* pull_multi(files_to_pull, destination) \n\n#### APK Management: \n* pull_package(package_name, destination) \n* install(apk_path, r=False) \n* install_multiple(apk_paths, r=False)\n\n#### Intent and URL Handling: \n* open_intent(url)\n\n#### Emulator Snapshot Management: \n* snapshots_list() \n* snapshot_exists(snapshot_name) \n* snapshot_load(snapshot_name) \n* snapshot_save(snapshot_name) \n* snapshot_delete(delete=None) \n\n## Error Handling\nBe sure to handle errors gracefully in your code, as various operations may fail, adb-pywrapper tries to provide information where possible on success or failure in the `AdbResult` and `PullResult` objects.\n\n## Contributing\nContributions to the adb-pywrapper package are welcome. If you encounter any issues, have suggestions, or want to contribute, feel free to open an issue or PR. Find our contribution guidelines [here](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "EUPL-1.2",
"summary": "adb-pywrapper facilitates seamless interaction with Android devices using the Android Debug Bridge (ADB) directly within Python scripts.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/NetherlandsForensicInstitute/adb-pywrapper"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dca5657c03c3ffeaf1d5d7ea6fa313f80b81f4c1585f5f6e3d8f8eaeeee5e106",
"md5": "f05b1dc26e0b5c145c7242cca136b03a",
"sha256": "17caded00e7002cd786a0105e3c1e35fdd4d9c629cac345d38db461de44e462e"
},
"downloads": -1,
"filename": "adb_pywrapper-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f05b1dc26e0b5c145c7242cca136b03a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10039,
"upload_time": "2024-04-18T07:26:33",
"upload_time_iso_8601": "2024-04-18T07:26:33.038247Z",
"url": "https://files.pythonhosted.org/packages/dc/a5/657c03c3ffeaf1d5d7ea6fa313f80b81f4c1585f5f6e3d8f8eaeeee5e106/adb_pywrapper-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b7c29b383391ec6313fb2e9a69367c2ad619f4c3e910ce973f904d2546588143",
"md5": "0d62425afe19f624ff189f9d9b175542",
"sha256": "56516cc95037cc4f755aa5eff688e9503e4d46053e575de054e5a9fdcf8c8d47"
},
"downloads": -1,
"filename": "adb_pywrapper-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0d62425afe19f624ff189f9d9b175542",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13854,
"upload_time": "2024-04-18T07:26:34",
"upload_time_iso_8601": "2024-04-18T07:26:34.494771Z",
"url": "https://files.pythonhosted.org/packages/b7/c2/9b383391ec6313fb2e9a69367c2ad619f4c3e910ce973f904d2546588143/adb_pywrapper-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 07:26:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NetherlandsForensicInstitute",
"github_project": "adb-pywrapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "adb-pywrapper"
}
JSON
