docs: 添加 MIT 许可证 + README + setup.py，仓库已开放
- LICENSE: MIT License - README.md: 完整项目文档 (特性/安装/快速开始/项目结构/设计理念) - setup.py: 支持 pip install 安装 - 仓库已通过 Gitee API 设为公开
This commit is contained in:
shuiyu1123 committed
1 parent
690022cea3
commit
e316e18d98
3 files changed
+249
No files matched your search
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 shuiyu1123
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -0,0 +1,182 @@
|
|||||||
|
# Android-pyApi
|
||||||
|
|
||||||
|
> **Android API for Python** — 在桌面/Linux 上原生运行 Android API 的 Python 库
|
||||||
|
|
||||||
|
[](https://opensource.org/licenses/MIT)
|
||||||
|
[](https://www.python.org/downloads/)
|
||||||
|
[](#)
|
||||||
|
|
||||||
|
## 这是什么
|
||||||
|
|
||||||
|
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)
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
from setuptools import setup, find_packages
|
||||||
|
|
||||||
|
setup(
|
||||||
|
name="android-pyapi",
|
||||||
|
version="1.0.0",
|
||||||
|
description="Android API for Python — 在桌面/Linux 上原生运行 Android API",
|
||||||
|
long_description=open("README.md").read(),
|
||||||
|
long_description_content_type="text/markdown",
|
||||||
|
license="MIT",
|
||||||
|
author="shuiyu1123",
|
||||||
|
url="https://gitee.com/shuiyu1123/Android-pyApi",
|
||||||
|
packages=find_packages(),
|
||||||
|
python_requires=">=3.8",
|
||||||
|
install_requires=[
|
||||||
|
# 核心依赖（全部可选，缺失时自动降级）
|
||||||
|
],
|
||||||
|
extras_require={
|
||||||
|
"linux": [
|
||||||
|
"psutil",
|
||||||
|
"requests",
|
||||||
|
"Pillow",
|
||||||
|
"opencv-python",
|
||||||
|
"numpy",
|
||||||
|
],
|
||||||
|
"dev": [
|
||||||
|
"pytest",
|
||||||
|
"pytest-cov",
|
||||||
|
],
|
||||||
|
},
|
||||||
|
classifiers=[
|
||||||
|
"Development Status :: 4 - Beta",
|
||||||
|
"Intended Audience :: Developers",
|
||||||
|
"License :: OSI Approved :: MIT License",
|
||||||
|
"Operating System :: POSIX :: Linux",
|
||||||
|
"Operating System :: MacOS",
|
||||||
|
"Operating System :: Microsoft :: Windows",
|
||||||
|
"Programming Language :: Python :: 3",
|
||||||
|
"Programming Language :: Python :: 3.8",
|
||||||
|
"Programming Language :: Python :: 3.9",
|
||||||
|
"Programming Language :: Python :: 3.10",
|
||||||
|
"Programming Language :: Python :: 3.11",
|
||||||
|
"Programming Language :: Python :: 3.12",
|
||||||
|
"Topic :: Software Development :: Libraries :: Python Modules",
|
||||||
|
"Topic :: System :: Hardware",
|
||||||
|
],
|
||||||
|
)
|
||||||
Reference in new issue
Block a user