Metadata-Version: 2.4
Name: py2droid-api
Version: 0.1.0
Summary: Python bindings and helpers for Android system scripts and Magisk modules
Keywords: android,apatch,ctypes,kernelsu,magisk,system-properties
Author: Mrakorez
Author-email: Mrakorez <66641112+Mrakorez@users.noreply.github.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Android
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/Mrakorez/py2droid-api
Project-URL: Repository, https://github.com/Mrakorez/py2droid-api
Project-URL: Issues, https://github.com/Mrakorez/py2droid-api/issues
Description-Content-Type: text/markdown

# py2droid-api

`py2droid-api` provides Python bindings and helpers for Android system scripts and Magisk modules,
making them more comfortable to write than doing it by hand.

It’s part of a small ecosystem I’m building around [py2droid](https://github.com/Mrakorez/py2droid),
my Python build for Android, packaged as a Magisk module.

## Project status

This project is in early development (pre-1.0). Breaking changes may land in minor releases.
It’s maintained in my spare time, whenever I have the time and motivation, so releases and fixes may
be slow.

## Installation

```bash
pip install py2droid-api
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add py2droid-api
```

Requires Python 3.13+. This floor is set with headroom for Android support, which landed in CPython
3.13. I also reserve the right to raise the minimum version if
[py2droid](https://github.com/Mrakorez/py2droid) supports it and doing so helps implement new
features or make existing ones more ergonomic.

## Modules

- **`py2droid.sysprops`** — bindings for the Android bionic system property API
  (`__system_property_*`), for reading, listing, and setting system properties.
  Requires a real Android device; importing it elsewhere raises `NonAndroidDeviceError`.
- **`py2droid.fs`** — filesystem helpers mirroring the Magisk module installation API (`set_perm`,
  `set_perm_recursive`, `replace`, `remove`).
- **`py2droid.fileprops`** — utilities for reading, writing, and editing `.prop` files.
- **`py2droid.typing`** — shared type aliases and protocols used throughout the package.

Only `py2droid.sysprops` requires an Android device.
`py2droid.fs` relies on Unix-specific calls (`os.chown`, `os.setxattr`, `os.mknod`) and won’t work
on Windows; `py2droid.fileprops` and `py2droid.typing` have no such requirement and work on any
platform.

## Usage

See [`examples/`](examples/) for runnable examples covering the main functions of each module.

## A note on AI assistance

I use AI tools to help polish the documentation (English isn’t my native language), draft CI/CD and
tooling configuration, and bounce ideas around during code review.

## License

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