Metadata-Version: 2.4
Name: adbflow
Version: 0.1.0
Summary: Feature-rich Android device automation via ADB
Project-URL: Homepage, https://github.com/Shahadh7/adbflow
Project-URL: Documentation, https://shahadh7.github.io/adbflow/
Project-URL: Repository, https://github.com/Shahadh7/adbflow
Project-URL: Issues, https://github.com/Shahadh7/adbflow/issues
Author: Shahadh
License-Expression: MIT
License-File: LICENSE
Keywords: adb,android,async,automation,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: lxml>=5.0
Requires-Dist: pillow>=10.0
Provides-Extra: all
Requires-Dist: easyocr>=1.7; extra == 'all'
Requires-Dist: opencv-python>=4.8; extra == 'all'
Provides-Extra: dev
Requires-Dist: lxml-stubs>=0.5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: ocr
Requires-Dist: easyocr>=1.7; extra == 'ocr'
Provides-Extra: vision
Requires-Dist: opencv-python>=4.8; extra == 'vision'
Description-Content-Type: text/markdown

# adbflow

[![PyPI version](https://img.shields.io/pypi/v/adbflow.svg)](https://pypi.org/project/adbflow/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/adbflow.svg)](https://pypi.org/project/adbflow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://shahadh7.github.io/adbflow/)

**Async-first, type-safe Python package for Android device automation via ADB.**

adbflow gives you a clean, modern Python API for everything you'd do with `adb` — UI automation, gestures, app management, file operations, screen capture, and much more. Built on `asyncio` with full type hints.

**[Documentation](https://shahadh7.github.io/adbflow/)** · **[PyPI](https://pypi.org/project/adbflow/)** · **[GitHub](https://github.com/Shahadh7/adbflow)**

---

## Features

- **Async-first** — every operation is `async/await` with sync wrappers available
- **Type-safe** — full type hints, passes `mypy --strict`
- **UI automation** — find elements by text/ID/class, tap, type, wait for conditions
- **Gestures** — tap, swipe, drag, pinch, multi-touch
- **App management** — install, launch, stop, permissions, intents
- **File operations** — push, pull, ls, sync directories with checksum diffing
- **Screen capture** — screenshots (bytes, PIL, file), screen recording
- **Wait engine** — composable conditions with `AllOf`, `AnyOf`, `Not`
- **Vision** — template matching and color detection (optional: opencv)
- **OCR** — on-screen text recognition (optional: easyocr)
- **Watchers** — auto-dismiss dialogs, background UI monitors
- **Recorder** — record and replay action sequences
- **Flow engine** — multi-step workflows with conditions and retry logic
- **Multi-device** — parallel execution across device pools
- **Logcat** — stream, filter, and capture logs
- **Network** — WiFi, mobile data, airplane mode, port forwarding, proxy
- **Notifications** — list, find, wait for notifications
- **CLI** — `adbflow` command for common operations

## Installation

```bash
pip install adbflow
```

### Optional extras

```bash
pip install adbflow[vision]   # Template matching, color detection (opencv)
pip install adbflow[ocr]      # Text recognition (EasyOCR)
pip install adbflow[all]      # Everything
```

### Requirements

- Python 3.10+
- ADB installed and on `PATH` ([Android Platform-Tools](https://developer.android.com/tools/releases/platform-tools))
- An Android device with USB Debugging enabled

## Quick Start

```python
import asyncio
from adbflow import ADB

async def main():
    adb = ADB()
    device = await adb.device_async()

    # Device info
    model = await device.info.model_async()
    print(f"Connected to {model}")

    # Shell commands
    output = await device.shell_async("getprop ro.product.model")

    # UI automation
    from adbflow.ui import Selector

    element = await device.ui.find_async(
        Selector().text("Settings").clickable()
    )
    if element:
        await element.tap_async()

    # Wait for UI state
    await device.wait_for_text_async("Display", timeout=5.0)

    # Gestures
    from adbflow.utils.types import SwipeDirection
    await device.gestures.swipe_direction_async(SwipeDirection.UP)

    # Screenshots
    png_bytes = await device.screenshot_async()

    # App management
    await device.apps.start_async("com.example.app")
    await device.apps.stop_async("com.example.app")

asyncio.run(main())
```

### Sync API

Every `_async` method has a sync wrapper for scripts that don't need asyncio:

```python
from adbflow import ADB

adb = ADB()
device = adb.device()
output = device.shell("getprop ro.product.model")
print(output)
```

## Modules

| Module | Access | Description |
|--------|--------|-------------|
| **UI** | `device.ui` | Find elements, tap, type, wait |
| **Gestures** | `device.gestures` | Tap, swipe, drag, pinch, keys |
| **Apps** | `device.apps` | Install, launch, stop, permissions, intents |
| **Files** | `device.files` | Push, pull, ls, sync, backup |
| **Media** | `device.media` | Screenshots, screen recording, audio |
| **Network** | `device.network` | WiFi, mobile data, airplane, port forwarding |
| **Logcat** | `device.logcat` | Stream, filter, capture, crash detection |
| **Notifications** | `device.notifications` | List, find, wait for notifications |
| **Wait** | `device.wait_for_text_async()` | Composable wait conditions |
| **Vision** | `device.vision` | Template matching, color detection |
| **OCR** | `device.ocr` | Text recognition via EasyOCR |
| **Watchers** | `device.watchers` | Auto-dismiss dialogs |
| **Recorder** | `device.recorder` | Record and replay actions |
| **Parallel** | `DevicePool` | Multi-device execution |
| **Flow** | `Flow` | Multi-step workflow engine |

## Examples

### UI Automation

```python
from adbflow.ui import Selector

# Find and tap
button = await device.ui.find_async(
    Selector().resource_id("com.example:id/submit").clickable()
)
await button.tap_async()

# Wait for element
element = await device.ui.wait_for_async(
    Selector().text("Welcome"), timeout=10.0
)

# Type text
field = await device.ui.find_async(
    Selector().resource_id("com.example:id/search")
)
await field.tap_async()
await field.text_input_async("hello world")
```

### Wait Conditions

```python
from adbflow.wait import wait_for, TextVisible, any_of, not_

# Wait for success or error
await wait_for(
    any_of(TextVisible(device, "Success"), TextVisible(device, "Error")),
    timeout=10.0
)

# Wait for loading to disappear
await wait_for(not_(TextVisible(device, "Loading...")), timeout=15.0)
```

### Multi-Device

```python
from adbflow.parallel import DevicePool

pool = DevicePool(devices)

async def screenshot_all(device):
    model = await device.info.model_async()
    await device.media.screenshot.capture_to_file_async(f"{model}.png")

results = await pool.run_async(screenshot_all)
```

### Flow Engine

```python
from adbflow.flow import Flow
from adbflow.utils.types import ErrorStrategy

flow = Flow(device)
flow.add_step("open", open_app)
flow.add_step("login", login, retries=2)
flow.add_step("verify", verify, on_error=ErrorStrategy.SKIP)
result = await flow.run_async()
```

## CLI

```bash
adbflow devices              # List connected devices
adbflow shell "ls /sdcard"   # Run shell command
adbflow screenshot out.png   # Take screenshot
adbflow install app.apk      # Install APK
adbflow info                 # Device info
adbflow logcat               # Stream logs
adbflow record -o rec.json   # Record actions
adbflow play rec.json        # Replay actions
```

## Documentation

Full documentation is available at **[shahadh7.github.io/adbflow](https://shahadh7.github.io/adbflow/)**.

- [Installation](https://shahadh7.github.io/adbflow/getting-started/installation/)
- [Quickstart](https://shahadh7.github.io/adbflow/getting-started/quickstart/)
- [UI Automation Guide](https://shahadh7.github.io/adbflow/guides/ui-automation/)
- [API Reference](https://shahadh7.github.io/adbflow/api/device/)

## Contributing

```bash
git clone https://github.com/Shahadh7/adbflow.git
cd adbflow
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"

pytest                    # Run tests
ruff check src/           # Lint
mypy src/adbflow/         # Type check
```

See the [Contributing guide](https://shahadh7.github.io/adbflow/contributing/) for details.

## License

MIT — see [LICENSE](LICENSE) for details.
