From e316e18d9887a0774b6532d79a935600a437c7c1 Mon Sep 17 00:00:00 2001 From: shuiyu1123 Date: Wed, 24 Jun 2026 23:01:32 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20MIT=20=E8=AE=B8?= =?UTF-8?q?=E5=8F=AF=E8=AF=81=20+=20README=20+=20setup.py=EF=BC=8C?= =?UTF-8?q?=E4=BB=93=E5=BA=93=E5=B7=B2=E5=BC=80=E6=94=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - LICENSE: MIT License - README.md: 完整项目文档 (特性/安装/快速开始/项目结构/设计理念) - setup.py: 支持 pip install 安装 - 仓库已通过 Gitee API 设为公开 --- LICENSE | 21 +++++++ README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 46 ++++++++++++++ 3 files changed, 249 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100644 setup.py diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..683b79e --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..60a9bfa --- /dev/null +++ b/README.md @@ -0,0 +1,182 @@ +# 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) diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..b6361b7 --- /dev/null +++ b/setup.py @@ -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", + ], +)