# Android-pyApi

> **Android API for Python** — 在桌面/Linux 上原生运行 Android API 的 Python 库

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-green.svg)](#)

## 这是什么

Android-pyApi 将完整的 Android SDK API 翻译为纯 Python 实现，让你在桌面环境直接调用 Android API——不需要模拟器、不需要真机、不需要 Android Studio。

**213 个模块，178,000+ 行代码，覆盖 android/java/javax/org/dalvik 全包。**

在 Linux 上，系统级 API（网络、传感器、蓝牙、音频、位置等）使用真实系统调用，返回真实数据。

## 核心特性

### API 覆盖

| 包 | 模块数 | 内容 |
|---|---|---|
| `android.*` | 167 | app, content, os, view, widget, graphics, media, hardware, net, telephony, provider 等 |
| `java.*` | 35 | lang, io, util, net, nio, security, crypto, sql, math, time 等 |
| `javax.*` | 4 | net, crypto, security, sql |
| `org.*` | 5 | json, w3c_dom, xml_sax, xml_pull, apache_http |
| `dalvik.*` | 1 | system |

### Linux 真实实现

在 Linux 环境下，以下 API 使用真实系统调用而非存根：

| API | 实现方式 | 真实行为 |
|-----|---------|---------|
| ConnectivityManager | `ip` 命令 + `/proc/net` | 真实 IP、接口、DNS、网关 |
| LocationManager | IP 地理定位 | 真实经纬度、城市、ISP |
| SensorManager | `/sys/class/hwmon` | 真实温度、CPU 频率、风扇 |
| AudioManager | `amixer` (ALSA) | 真实音量控制 |
| BluetoothAdapter | `bluetoothctl` (BlueZ) | 真实扫描、配对、连接 |
| ClipboardManager | `xclip` | 真实剪贴板读写 |
| PowerManager / BatteryManager | `psutil` + `/sys/class/power_supply` | 真实 CPU、内存、电池 |
| TelephonyManager | MAC 地址 + 内核版本 | 真实设备 ID |
| NotificationManager | `notify-send` | 真实桌面通知 |
| Activity / Display | `xdotool` + X11 | 真实屏幕尺寸、截屏 |
| ActivityManager | `psutil` + `/proc` | 真实进程列表 |
| Shell | `subprocess` | 真实命令执行 |
| Camera | OpenCV / V4L2 | 真实拍照 |
| UI 自动化 | `xdotool` | 真实点击、输入、按键 |

### 跨平台

- **Linux** — 系统级 API 使用真实实现
- **macOS / Windows** — 系统级 API 使用存根（后续支持）
- **API 形状** — 所有平台一致，方法签名完全对齐 Android SDK

## 安装

```bash
# 从源码安装
git clone https://gitee.com/shuiyu1123/Android-pyApi.git
cd Android-pyApi
pip install -e .

# 或直接使用
export PYTHONPATH=/path/to/Android-pyApi:$PYTHONPATH
```

### 可选依赖

```bash
# Linux 系统工具
sudo apt install xclip xdotool libnotify-bin alsa-utils bluez lm-sensors

# Python 库
pip install psutil requests Pillow opencv-python numpy
```

## 快速开始

```python
from android_pyapi import Intent, Uri, Bundle, File, JSONObject, ArrayList, HashMap

# Intent — Android 最核心的 API
intent = Intent("android.intent.action.VIEW")
intent.setData(Uri.parse("https://example.com"))
intent.putExtra("key", "value")
print(intent.getAction())        # android.intent.action.VIEW
print(intent.getData())          # https://example.com
print(intent.getStringExtra("key"))  # value

# java.util 集合
lst = ArrayList()
lst.add("hello")
lst.add("world")
print(lst.size())                # 2
print(lst.get(0))                # hello

# JSONObject
json = JSONObject()
json.put("name", "test")
json.put("version", 42)
print(json.toString())           # {"name":"test","version":42}

# Linux 真实实现
from android_pyapi import Build, LocationManager, ConnectivityManager
print(Build.MODEL)               # 真实主机名
print(Build.MANUFACTURER)        # Linux

loc = LocationManager().getLastKnownLocation("network")
print(loc)                       # 真实经纬度
```

## 项目结构

```
android_pyapi/
├── _core.py              # Stub 基类、全局上下文
├── _linux_impl.py        # Linux 真实实现层 (14个实现类)
├── __init__.py           # 统一导出
├── android/              # 167 个 Android 模块
│   ├── app.py            # Activity, Service, Fragment, Notification
│   ├── content.py        # Context, Intent, ContentResolver, ClipboardManager
│   ├── os.py             # Handler, Looper, Bundle, Build, PowerManager
│   ├── view.py           # View, ViewGroup, MotionEvent, KeyEvent
│   ├── widget.py         # TextView, Button, ListView, RecyclerView, Toast
│   ├── graphics.py       # Bitmap, Canvas, Paint, Color, Path, Matrix
│   ├── hardware.py       # SensorManager, Camera, BiometricPrompt
│   ├── net.py            # ConnectivityManager, NetworkInfo
│   ├── telephony.py      # TelephonyManager, SmsManager
│   ├── location.py       # LocationManager, Location, Geocoder
│   ├── media.py          # AudioManager, MediaPlayer, MediaRecorder
│   └── ...
├── java/                 # 35 个 Java 标准库模块
│   ├── lang.py           # String, Math, System, Thread, Exception 体系
│   ├── io.py             # File, InputStream, OutputStream, Reader, Writer
│   ├── util.py           # ArrayList, HashMap, Calendar, Collections, UUID
│   ├── net.py            # URL, HttpURLConnection, Socket
│   └── ...
├── javax/                # 4 个 javax 模块
├── org/                  # 5 个 org 模块
└── dalvik/               # 1 个 dalvik 模块
```

## 设计理念

### 不是模拟器

Android-pyApi 不是 Android 模拟器。它不包含 ART 虚拟机、SurfaceFlinger、binder 等底层基础设施。

它是 **API 兼容层**：
- **API 形状** — 类名、方法签名、常量值完全对齐 Android SDK
- **系统级行为** — 在 Linux 上用真实系统调用实现
- **框架级行为** — Activity 生命周期、View 渲染等保持存根（桌面无对应框架）

### 渐进式真实化

```
存根 (所有平台) → Linux 真实实现 → macOS 真实实现 → Windows 真实实现
```

每个 API 从"返回硬编码值"逐步演进为"调用真实系统功能"。

## 使用场景

- **Android 脚本开发** — 在桌面编写和调试依赖 Android API 的 Python 脚本
- **跨平台工具** — 用 Android API 风格编写跨平台系统工具
- **学习 Android API** — 不需要 Android Studio 就能探索 API
- **自动化测试** — 在 CI/CD 中测试 Android API 调用逻辑
- **IoT / 嵌入式** — 在 Linux 设备上用 Android API 风格操作硬件

## 贡献

欢迎贡献！特别需要：

- macOS 真实实现层 (`_macos_impl.py`)
- Windows 真实实现层 (`_windows_impl.py`)
- 更多 API 的真实行为实现
- 测试用例

## License

[MIT](LICENSE)