Metadata-Version: 2.3
Name: pymordial
Version: 0.1.0
Summary: A Python library designed to control BlueStacks through ADB commands, enabling seamless automation and management of Android applications on a PC.
Author: IAmNo1Special
Author-email: IAmNo1Special <ivmno1special@gmail.com>
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Emulators
Classifier: Topic :: Utilities
Requires-Dist: adb-shell>=0.4.4
Requires-Dist: av>=16.0.1
Requires-Dist: easyocr>=1.7.2
Requires-Dist: numpy>=2.2.5
Requires-Dist: opencv-python>=4.12.0.88
Requires-Dist: pillow>=11.1.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pytesseract>=0.3.13
Requires-Dist: pywin32>=310
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tqdm>=4.67.1
Requires-Dist: easyocr>=1.7.2 ; extra == 'easyocr'
Requires-Dist: pytesseract>=0.3.10 ; extra == 'tesseract'
Requires-Python: >=3.13
Project-URL: documentation, https://pymordial.readthedocs.io
Project-URL: homepage, https://github.com/IAmNo1Special/Pymordial
Project-URL: issues, https://github.com/IAmNo1Special/Pymordial/issues
Provides-Extra: easyocr
Provides-Extra: tesseract
Description-Content-Type: text/markdown

# Pymordial 💊

**Automate BlueStacks like a pro. Or a robot.**

![Python Version](https://img.shields.io/badge/python-3.13-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-beta-orange)
![Tests](https://img.shields.io/badge/tests-155%20passing-brightgreen)

**Pymordial** is a Python library designed to control BlueStacks through ADB commands and image recognition, enabling seamless automation of Android applications on PC.

## 📑 Table of Contents

- [Why Pymordial?](#-why-pymordial)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Common Recipes](#-common-recipes)
- [Key Concepts](#-key-concepts)
- [Documentation](#-documentation)
- [Examples](#-examples)
- [Requirements](#-requirements)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Why Pymordial?

-   **Smart Automation**: Uses OCR and Image Recognition to find buttons, not just blind coordinates.
-   **State Aware**: Knows if your app is Loading, Open, or Closed. No more clicking on black screens.
-   **Clean API**: Intuitive methods like `controller.go_home()` and `controller.capture_screen()`.
-   **Extensible**: Easy to add new apps, screens, and elements.
-   **Pythonic**: Clean, typed, and modern Python 3.13+ codebase.
-   **Well Tested**: 155 passing tests including integration tests with real BlueStacks.

## 🛠️ Installation

Pymordial uses `uv` for dependency management.

```bash
# Clone the repository
git clone https://github.com/IAmNo1Special/Pymordial.git
cd Pymordial

# Install with uv
uv pip install .

# Or install in development mode
uv pip install -e .
```

## ⚡ Quick Start

```python
from pymordial import WorldLink
from pymordial.core.world import World
from pymordial.core.elements.button_element import ButtonElement
from pathlib import Path

# 1. Initialize Controller (connection is automatic!)
controller = WorldLink()

# 2. Define your App
my_game = World(
    app_name="MyGame",
    package_name="com.example.mygame"
)

# 3. Register App
controller.add_app(my_game)

# 4. Open App
my_game.open()  # Opens the app and waits for it to load

# 5. Navigate using clean API
controller.go_home()  # ← Much cleaner than controller.adb.go_home()

# 6. Define and click a button
start_button = ButtonElement(
    name="start",
    asset_path=Path("assets/start_btn.png"),
    element_text="Start",
    is_static=True
)

# Click with automatic retry
if controller.bluestacks.click_element(start_button, timeout=10):
    print("Button clicked successfully!")

# 7. Read text from screen with OCR
screenshot = controller.capture_screen()  # ← Clean API!
text_lines = controller.image.read_text(screenshot)
print(f"Found text: {text_lines}")
```

## 🧩 Common Recipes

###  Check if an element is visible

```python
from pymordial.core.elements.image_element import ImageElement

logo = ImageElement(
    name="game_logo",
    asset_path=Path("assets/logo.png"),
    is_static=True
)

if my_game.is_element_visible(logo):
    print("On the main menu!")
```

### Navigate and interact

```python
# Go to home screen
controller.go_home()

# Press back button
controller.go_back()

# Tap at specific coordinates
controller.tap(x=500, y=300)

# Swipe gesture
controller.swipe(start_x=500, start_y=800, end_x=500, end_y=200, duration=300)
```

### Search for specific text

```python
screenshot = controller.capture_screen()

if controller.image.check_text(screenshot, "Victory!", case_sensitive=False):
    print("Battle won!")
```

### Handle app lifecycle

```python
# Check if app is running
if controller.adb.is_app_running(my_game, timeout=5, wait_time=1):
    print("App is active")

# Close app
my_game.close()
```

## 🔑 Key Concepts

-   **Controller**: The brain. Manages ADB, BlueStacks, and Image recognition.
    - **Convenience Methods**: `go_home()`, `go_back()`, `tap()`, `swipe()`, `capture_screen()`
    - Delegates to sub-controllers internally for clean API
-   **App**: Represents an Android package. Has a lifecycle (OPEN, CLOSED, LOADING).
-   **Screen**: A collection of elements representing a UI screen (e.g., "Main Menu").
-   **Element**: A UI component - button, image, text, or pixel that can be detected and interacted with.
-   **State Machine**: Manages app and BlueStacks states with automatic transition handlers.

## 📚 Documentation

We have documentation for everyone:

-   **[Explain Like I'm a Potato](.protel/explain_pymordial_like_im_a_potato.md)**: For non-technical folks.
-   **[Junior Dev Survival Guide](.protel/pymordial_survival_guide_for_eager_juniors.md)**: For developers getting started.
-   **[God Mode Architecture Review](.protel/pymordial_god_mode_architecture_review.md)**: For architects and experts.

### Detailed Guides

-   **[Quickstart Guide](docs/QUICKSTART.md)**: Step-by-step tutorial for beginners
-   **[API Reference](docs/API_REFERENCE.md)**: Complete API documentation
-   **[State Management](docs/STATE_MANAGEMENT.md)**: Understanding the state machine
-   **[Testing Guide](docs/TESTING.md)**: Running and writing tests
-   **[Config Guide](docs/CONFIG.md)**: Configuration options
-   **[OCR Engines](docs/OCR_ENGINES.md)**: Choosing and configuring OCR
-   **[Pluggability Guide](docs/PLUGGABILITY_GUIDE.md)**: Extending Pymordial

## 💡 Examples

Check out the [examples/](examples/) directory for practical, runnable examples:

- `01_basic_connection.py` - Connect to BlueStacks (automatic connection!)
- `02_app_control.py` - Open and close apps (uses config values)
- `03_element_clicking.py` - Find and click UI elements
- `04_ocr_reading.py` - Extract text with OCR
- `05_custom_app_screens.py` - Structure complex apps

Run any example:
```bash
uv run python examples/01_basic_connection.py
```

## ⚠️ Requirements

-   **Windows 10/11** (Required for window management)
-   **BlueStacks 5+** (Tested on 5, might work on others)
-   **Python 3.13+**
-   **ADB** (Included with BlueStacks or install Android SDK)

### Optional Dependencies

- **Tesseract OCR**: For text extraction (install separately)
- **EasyOCR**: Alternative OCR engine (slower but no external dependencies)

## 🔧 Troubleshooting

### "No ADB device connected"
**Cause**: BlueStacks not running or ADB not enabled

**Solution**:
1. Start BlueStacks
2. Enable ADB in BlueStacks Settings → Advanced → Android Debug Bridge
3. Restart Pymordial controller

### "Element not found" errors
**Cause**: Element image doesn't match or wrong screen

**Solution**:
1. Verify element is visible on current screen
2. Recapture element image at your resolution
3. Increase timeout: `click_element(element, timeout=20)`
4. Check image confidence threshold

### "BlueStacks is closed" warnings
**Cause**: BlueStacks state not initialized

**Solution**:
```python
controller = WorldLink()
# State is automatically set to READY when controller is created
```

### OCR not detecting text
**Cause**: Poor image quality or wrong OCR engine

**Solution**:
1. Use high-contrast text
2. Crop screenshot to text area
3. Try different extraction strategies
4. Switch between Tesseract and EasyOCR

### Import errors
**Cause**: Missing dependencies

**Solution**:
```bash
# Reinstall with all dependencies
uv pip install -e ".[dev]"
```

## 🤝 Contributing

Contributions welcome! Please:

1. Read the [Junior Dev Guide](.protel/pymordial_survival_guide_for_eager_juniors.md)
2. Check existing issues
3. Follow the Google Python Style Guide
4. Write tests for new features
5. Run the test suite: `uv run pytest tests/ -v`

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.

---

**Made with 💊 by IAmNo1Special**

*Automate responsibly. Don't break any ToS.*
