Metadata-Version: 2.4
Name: termuxlib
Version: 0.1.0
Summary: A lightweight, type-annotated Python wrapper around Termux API utilities
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/nullzinx/termuxlib
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: Android
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# termuxlib 📱🐍

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-Android%20(Termux)-green.svg)](https://termux.dev/)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A lightweight, type-annotated Python wrapper around Termux API command‑line utilities on Android.

`termuxlib` exposes native `termux-api` utilities as structured static Python classes, allowing you to control hardware, sensors, notifications, SMS, text-to-speech, camera, GPS, and Wi-Fi in few lines of code.

---

## Prerequisites

Your Android environment must have Termux and its API package configured:

1. Install the main **[Termux](https://github.com/termux/termux-app)** application.
2. Install the **[Termux:API](https://github.com/termux/termux-api)** addon.
3. Inside Termux, run:
   ```bash
   pkg update && pkg install termux-api python -y
   ```
4. Ensure the *Termux:API* app has the required Android permissions (Location, SMS, Contacts, Camera, etc.).

---

## Installation

To use `termuxlib` locally, clone this repository or copy the `termuxlib` directory into your project root. 

You can also install the package in editable mode:
```bash
pip install -e .
```

---

## Core Concept

All wrappers are defined as `@staticmethod` functions inside organized modules. 

Complex data outputs (such as battery status, location, sensor and network lists) are returned as raw JSON strings directly from the underlying Termux CLI. This keeps the library lightweight and lets you parse outputs as needed:

```python
import json
from termuxlib import device

battery = json.loads(device.battery_status())
print(f"Battery level: {battery['percentage']}% ({battery['status']})")
```

---

## Quick Start

```python
from termuxlib import send_notification, device, tts, clipboard

send_notification("System Alert", "Process started.")
print(device.battery_status())
tts.speak("Termux lib loaded.")
clipboard.copy("Hello from Python!")
```

---

## API Reference

### 1. Notifications

#### `send_notification(title: str, content: str) -> None`
Triggers a native Android notification.
```python
from termuxlib import send_notification
send_notification("Title", "Body message")
```

---

### 2. Device & Sensors (`device`)

Provides access to hardware information and physical sensors.

| Method | Return | Description |
| :--- | :--- | :--- |
| `battery_status()` | `str` (JSON) | Retrieves battery state (level, health, temperature). |
| `location_gps()` | `str` (JSON) | Gets GPS location (latitude, longitude, altitude). |
| `sensor_list()` | `str` (JSON) | Lists all available hardware sensors. |
| `sensor_read(target: str)` | `str` | Reads a single value from the specified sensor (e.g., `light`). |
| `get_fingerprint()` | `str` (JSON) | Prompts biometric fingerprint authentication. |

```python
from termuxlib import device

light_level = device.sensor_read("light")
print(device.get_fingerprint())
```

---

### 3. Text-to-Speech (`tts`)

Synthesizes spoken text using the Android TTS engine.

| Method | Return | Description |
| :--- | :--- | :--- |
| `engine_list()` | `str` | Lists available TTS engines on the device. |
| `speak(text: str)` | `None` | Speaks the given text aloud. |

```python
from termuxlib import tts

print(tts.engine_list())
tts.speak("Action completed successfully.")
```

---

### 4. SMS (`sms`)

Manages text messages and contact databases.

| Method | Return | Description |
| :--- | :--- | :--- |
| `contact_list()` | `str` (JSON) | Lists system contacts. |
| `send(phone_number: str, msg: str)` | `None` | Sends an SMS message to a phone number. |
| `sms_list()` | `str` (JSON) | Retrieves received SMS messages. |

```python
from termuxlib import sms

sms.send("+1234567890", "Automated system update.")
```

---

### 5. Telephony (`telephony`)

Accesses cellular connection details and handles outbound calls.

| Method | Return | Description |
| :--- | :--- | :--- |
| `info()` | `str` (JSON) | Retrieves network and carrier information. |
| `makecall(phone_number: str)` | `None` | Places an outbound call to the target number. |

```python
from termuxlib import telephony

print(telephony.info())
telephony.makecall("+1234567890")
```

---

### 6. Wi-Fi (`wifi`)

Monitors current network states and scans nearby networks.

| Method | Return | Description |
| :--- | :--- | :--- |
| `info()` | `str` (JSON) | Retrieves details of the active Wi-Fi connection. |
| `scan_networks()` | `str` (JSON) | Performs a scan and returns visible Wi-Fi networks. |

```python
from termuxlib import wifi

print(wifi.info())
```

---

### 7. Clipboard (`clipboard`)

Manipulates the Android system clipboard.

| Method | Return | Description |
| :--- | :--- | :--- |
| `copy(text: str)` | `None` | Copies text into the clipboard. |
| `read_clipboard()` | `str` | Reads current clipboard content. |

```python
from termuxlib import clipboard

clipboard.copy("Target payload")
print(clipboard.read_clipboard())
```

---

### 8. Camera & Flashlight (`camera`)

Manages photo capture and toggles the hardware torch.

| Method | Return | Description |
| :--- | :--- | :--- |
| `info()` | `str` (JSON) | Retrieves device camera specifications. |
| `take_photo(output_file: str, camera: str)` | `None` | Captures a photo with the `"front"` or `"back"` camera. |
| `torch(state: bool)` | `None` | Sets the flashlight state (`True` for on, `False` for off). |

```python
from termuxlib import camera

camera.torch(True)
camera.take_photo("/sdcard/Pictures/capture.jpg", camera="back")
camera.torch(False)
```

---

## Error Handling

All standard execution errors from Termux calls propagate as standard `subprocess.CalledProcessError`.

```python
import subprocess
from termuxlib import camera

try:
    camera.take_photo("/sdcard/image.jpg", camera="back")
except subprocess.CalledProcessError as e:
    print(f"Termux command failed: {e}")
```

---

## Examples

To view end-to-end operational automation scripts (such as a battery alert, SMS responder, or a GPS locator):

👉 **[Go to Examples Documentation (docs/EXAMPLES.md)](docs/EXAMPLES.md)**

---

## License

This project is licensed under the terms of the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.
