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