Metadata-Version: 2.4
Name: igapi-rs
Version: 0.0.6.dev0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: black>=23.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1 ; extra == 'dev'
Provides-Extra: dev
Summary: Python bindings for Instagram Private API
Keywords: instagram,api,social-media
Author-email: Your Name <your.email@example.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://igapi-rs.es007.com
Project-URL: Homepage, https://github.com/open-luban/igapi-rs
Project-URL: Repository, https://github.com/open-luban/igapi-rs

# igapi-rs

[![PyPI](https://img.shields.io/pypi/v/igapi-rs)](https://pypi.org/project/igapi-rs/)
[![Python](https://img.shields.io/pypi/pyversions/igapi-rs)](https://pypi.org/project/igapi-rs/)
[![License](https://img.shields.io/pypi/l/igapi-rs)](https://github.com/open-luban/igapi-rs)

Instagram 私有 API 的 Python 绑定，基于 Rust + PyO3 构建，高性能、异步优先。

支持 Android / iOS / Web 三平台模拟。

- **文档**: [igapi-rs.es007.com](https://igapi-rs.es007.com)
- **源码**: [github.com/open-luban/igapi-rs](https://github.com/open-luban/igapi-rs)

## 安装

```bash
pip install igapi-rs
```

### 环境要求

- Python 3.10+

## 快速开始

```python
import igapi

# 创建客户端
client = igapi.Client()

# 登录
client.login("username", "password")

# 获取用户信息
user = client.user_info(12345678)
print(f"用户: @{user.username}")
print(f"粉丝数: {user.follower_count}")

# 搜索用户
results = client.search_users("instagram")
for user in results:
    print(f"@{user.username}")

# 获取用户动态
feed = client.user_feed(12345678)
for media in feed.items:
    print(f"媒体: {media.id}, 点赞: {media.like_count}")
```

## API 参考

### Client

```python
Client(proxy: str | None = None, platform: str = "android")
```

创建新的 Instagram API 客户端。

**参数:**
- `proxy` (可选): 代理 URL（例如 "http://localhost:8080"）
- `platform` (可选): 使用的平台（"android" 或 "web"）

**方法:**

#### `login(username: str, password: str) -> None`

登录 Instagram。

**异常:**
- `PermissionError`: 登录失败（密码错误、需要验证等）
- `ValueError`: 无效的凭据
- `RuntimeError`: 网络或 API 错误

#### `is_logged_in() -> bool`

检查当前是否已登录。

#### `user_info(user_id: int) -> User`

通过 ID 获取用户信息。

**异常:**
- `KeyError`: 用户未找到
- `PermissionError`: 需要登录

#### `search_users(query: str) -> list[User]`

通过用户名或名称搜索用户。

#### `user_feed(user_id: int, max_id: str | None = None) -> Feed`

获取用户的媒体动态。

**参数:**
- `user_id`: 要获取动态的用户 ID
- `max_id` (可选): 分页游标

### 类型定义

#### User

```python
class User:
    pk: int                 # 用户 ID
    username: str           # 用户名
    full_name: str          # 全名
    is_private: bool        # 是否私密账户
    profile_pic_url: str    # 头像 URL
    follower_count: int     # 粉丝数
    following_count: int    # 关注数
```

#### Media

```python
class Media:
    id: str                 # 媒体 ID
    media_type: int         # 类型（1=图片, 2=视频, 8=轮播）
    caption_text: str       # 描述文字
    like_count: int         # 点赞数
    comment_count: int      # 评论数
```

#### Feed

```python
class Feed:
    items: list[Media]      # 媒体项目列表
    has_more: bool          # 是否有更多项目
    next_cursor: str | None # 下一页游标
```

## 错误处理

```python
try:
    client.login("user", "pass")
except PermissionError as e:
    # 登录失败、需要验证、双因素认证等
    print(f"登录错误: {e}")
except ValueError as e:
    # 无效的凭据
    print(f"无效输入: {e}")
except RuntimeError as e:
    # API 或网络错误
    print(f"错误: {e}")
```

## 使用代理

```python
# HTTP 代理
client = igapi.Client(proxy="http://localhost:8080")

# HTTPS 代理
client = igapi.Client(proxy="https://proxy.example.com:8080")

# SOCKS 代理
client = igapi.Client(proxy="socks5://localhost:1080")
```

## 示例

完整使用示例请参见 `examples/python_example.py`。

## 开发

### 构建

```bash
# 调试构建
maturin develop

# 发布构建
maturin develop --release

# 构建 wheel 包
maturin build --release
```

### 测试

```bash
# 运行测试
python -m pytest tests/

# 类型检查
mypy --strict examples/
```

## 性能

Python 绑定使用 PyO3，保持接近原生 Rust 的性能：
- API 调用通过 Tokio 异步处理
- 最小化序列化开销
- 尽可能使用零拷贝数据访问

## 许可证

MIT OR Apache-2.0

## 链接

- [在线文档](https://igapi-rs.es007.com)
- [GitHub 仓库](https://github.com/open-luban/igapi-rs)
- [PyPI](https://pypi.org/project/igapi-rs/)

