Android-pyApi/README.md

Android-pyApi

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

这是什么

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	真实点击、输入、按键

Windows 真实实现

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

API	实现方式	真实行为
ConnectivityManager	ipconfig + netsh + socket	真实 IP、接口、DNS、网关、WiFi 信息
LocationManager	IP 地理定位	真实经纬度、城市、ISP
SensorManager	wmi + psutil	真实温度、CPU 频率、风扇转速
AudioManager	pycaw / PowerShell	真实音量控制、静音
BluetoothAdapter	PowerShell Bluetooth cmdlets	真实设备列表、配对状态
ClipboardManager	pyperclip	真实剪贴板读写
PowerManager / BatteryManager	psutil	真实 CPU、内存、电池状态
NotificationManager	win10toast / PowerShell	真实桌面通知 (Toast)
Activity / Display	pyautogui + screeninfo + win32api	真实屏幕尺寸、截屏
ActivityManager	psutil + tasklist	真实进程列表
Shell	subprocess + PowerShell	真实命令执行
Camera	OpenCV	真实拍照
UI 自动化	pyautogui + win32gui	真实点击、输入、按键、窗口操作

跨平台

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

安装

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

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

可选依赖

# Python 库 (所有平台通用)
pip install psutil requests Pillow opencv-python numpy

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

# Windows 专用库 (推荐安装以启用完整功能)
pip install pyautogui pyperclip screeninfo pywin32 wmi pycaw comtypes win10toast

快速开始

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个实现类)
├── _windows_impl.py      # Windows 真实实现层 (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)
• 更多 API 的真实行为实现
• 测试用例

License

MIT