Metadata-Version: 2.4
Name: py-adbkit
Version: 0.1.0
Summary: Python ADB automation toolkit for Android device management, scripting, and pentesting
Author-email: ghost-ble <bill.jtrammell@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bill-jtrammell/py-adbkit
Project-URL: Repository, https://github.com/bill-jtrammell/py-adbkit
Keywords: adb,android,automation,pentesting,root,fastboot,magisk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# py-adbkit

Python ADB automation toolkit for Android. Control devices, run shell commands, manage apps, capture screenshots, stream logcat, and automate pentesting workflows.

## Install

```bash
pip install py-adbkit
```

## Quick Start

```python
from pyadbkit import ADB

adb = ADB()

# List devices
devices = adb.devices()
for dev in devices:
    print(f"{dev.serial} - {dev.model} (Android {dev.android_version})")

# Connect via WiFi
adb.connect("192.168.1.100")

# Shell commands
code, stdout, stderr = adb.shell("DEVICE_SERIAL", "ls -la /sdcard/")

# Take screenshot
screenshot = adb.screenshot("DEVICE_SERIAL")
with open("screenshot.png", "wb") as f:
    f.write(screenshot)

# Battery info
battery = adb.battery("DEVICE_SERIAL")
print(f"Battery: {battery.get('level', '?')}%")
```

## Shell Automation

```python
from pyadbkit import ADB

adb = ADB()
serial = adb.devices()[0].serial

# High-level shell interface
from pyadbkit.commands import Shell
sh = Shell(adb, serial)

# Get/set properties
android_ver = sh.getprop("ro.build.version.release")

# Settings
sh.settings_put("system", "screen_off_timeout", "600000")

# Launch activities
sh.am_start("com.android.settings/.Settings")

# Input automation
sh.input_tap(500, 500)
sh.input_swipe(100, 500, 900, 500, 300)
sh.input_text("hello world")
sh.input_keyevent(3)  # HOME

# Root shell (if rooted)
sh.su("cat /data/data/com.package/databases/app.db")
```

## App Management

```python
# List installed packages
packages = adb.packages(serial, third_party=True)

# Install APK
adb.install(serial, "app.apk", flags=["-r", "-g"])

# Uninstall
adb.uninstall(serial, "com.package.name")

# Backup
adb.backup(serial, "backup.ab", packages=["com.package.name"])
```

## Logcat

```python
from pyadbkit.commands import Logcat

logcat = Logcat(adb, serial)

# Dump all logs
lines = logcat.dump(max_lines=500)

# Filter by tag
errors = logcat.by_tag("ActivityManager", level="E")

# Crash logs only
crashes = logcat.crash()

# Kernel logs
kernel = logcat.kernel()
```

## File Operations

```python
from pyadbkit.commands import Push, Pull

# Push file
pusher = Push(adb, serial)
pusher.file("local.apk", "/sdcard/Download/")

# Push entire directory
count = pusher.dir("./my_folder", "/sdcard/my_folder")

# Pull file
puller = Pull(adb, serial)
puller.file("/sdcard/Download/data.json", "./data.json")

# Pull directory
count = puller.dir("/sdcard/Documents", "./backup_docs")
```

## Network

```python
# WiFi ADB
adb.tcpip(serial, port=5555)
adb.connect("192.168.1.100", port=5555)

# Port forwarding
adb.forward(serial, local_port=8080, remote_port=8080)

# Reverse forwarding
adb.reverse(serial, remote_port=9090, local_port=9090)
```

## Device Info

```python
# Full device properties
dev = adb.get_device_props(serial)
print(f"Model: {dev.model}")
print(f"Android: {dev.android_version}")
print(f"Build: {dev.build_id}")

# Battery
battery = adb.battery(serial)
print(battery)

# Disk usage
mounts = adb.df(serial)
for m in mounts:
    print(f"{m['mount']}: {m['used']}/{m['size']} ({m['use_pct']})")

# Running processes
processes = adb.process_list(serial)
```

## Requirements

- Python >= 3.10
- `adb` and `fastboot` installed and in PATH
- USB debugging enabled on target device

## Use Cases

- **Root automation**: Script the full root workflow alongside [moto-root-2026](https://github.com/bill-jtrammell/moto-root-2026)
- **Pentesting**: Automate Android device reconnaissance and data extraction
- **Testing**: UI automation, app testing, screenshot capture
- **Forensics**: Pull app data, databases, and device logs

## Donate

If this saved you time:
- **PayPal**: bill.jtrammell@gmail.com
- **Cash App**: $slauter99

## License

MIT
