Metadata-Version: 2.4
Name: igapi-rs
Version: 0.1.5
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: open-luban
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)
- **LLM 速查**: [索引](https://igapi-rs.es007.com/llms.txt) / [Python API](https://igapi-rs.es007.com/latest/llms-python.txt)
- **源码**: [github.com/open-luban/igapi-rs](https://github.com/open-luban/igapi-rs)

## 安装

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

### 环境要求

- Python 3.10+

## 快速开始

```python
import asyncio
import igapi
from igapi.android import Client

async def main():
    # 创建客户端
    client = Client()

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

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

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

    # 获取用户动态
    feed_api = igapi.FeedApi(client)
    items, next_cursor = await feed_api.user(12345678)
    for media in items:
        print(f"媒体: {media.id}, 点赞: {media.like_count}")

asyncio.run(main())
```

## API 参考

### Android Client

```python
from igapi.android import AccountInfo, Client

Client(
    proxy: str | None = None,
    danger_accept_invalid_certs: bool = False,
    http1_only: bool = False,
    account: AccountInfo | None = None,
)
```

创建 Android 平台客户端。

**参数:**
- `proxy` (可选): 代理 URL（例如 "http://localhost:8080"）
- `danger_accept_invalid_certs` (可选): 是否接受无效 TLS 证书
- `http1_only` (可选): 是否强制 HTTP/1.1
- `account` (可选): `igapi.android.AccountInfo`

**方法:**

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

登录 Instagram。

**异常:**
- `ValueError`: 密码错误、用户无效
- `PermissionError`: 需要重新登录 / 账号锁定 / 需要同意条款
- `igapi.TwoFactorRequired` / `igapi.ChallengeRequired`: 需要 2FA / 安全验证
- `RuntimeError`: 网络或 API 错误

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

检查当前是否已登录。

#### 会话与登出（全平台）

- `await logout() -> None`：调用登出端点并清除内存登录态（登出后仍可重新 `login()`）
- `await save_session(path: str) -> None`：用 `FileSessionStorage` 将当前会话写入本地 JSON 文件
- `await restore_session(path: str) -> None`：从 `save_session()` 写入的 JSON 文件恢复会话
- `export_account() -> AccountInfo`：导出完整账号状态（Android/Web，**同步**，不需 await；iOS 暂不支持）
- `export_account_string() -> str`：导出平台账号字符串（Android/Web，**同步**；iOS 暂不支持）

> `save_session`/`restore_session` 的 JSON 格式与 `export_account_string()` 的账号字符串格式**不同**，两者不可混用读写。

### 资源 API 一览

所有资源 API 均以 `igapi.XxxApi(client)` 构造，方法为 `async`。完整签名见
[Python LLM 速查](https://igapi-rs.es007.com/latest/llms-python.txt) 或
[LLM 索引](https://igapi-rs.es007.com/llms.txt)：

| 资源 API | 主要方法 | 可用平台 |
| --- | --- | --- |
| `igapi.UserApi` | `info` / `search` / `id_from_username` / `info_by_username` / `web_id_from_username` | 全平台；`web_id_from_username` 仅 Web |
| `igapi.MediaApi` | `info` / `info_by_shortcode` | 全平台 |
| `igapi.FeedApi` | `user` / `user_all` | 全平台 |
| `igapi.UploadApi` | `photo` / `configure` / `photo_web` / `configure_web`(web) | 全平台 |
| `igapi.PostApi` | `user_posts` / `create_photo` | 仅 `igapi.web.Client` |
| `igapi.DirectApi` | `create_group_thread`(web) / `create_group_thread_graphql`(web) / `send_text`(web) / `send_text_to_thread`(web) / `send_text_broadcast`(android+web) | Android / Web |

### 平台命名空间

平台必须通过显式命名空间选择，不再从 `igapi` 顶层导入全局客户端或全局 `AccountInfo`：

```python
from igapi.android import AccountInfo as AndroidAccountInfo
from igapi.android import Client as AndroidClient
from igapi.ios import Client as IosClient
from igapi.web import AccountInfo as WebAccountInfo
from igapi.web import Client as WebClient

android = AndroidClient()
ios = IosClient()
web = WebClient()
```

Android 从结构化账号信息恢复 session：

```python
from igapi.android import AccountIdentity, AccountInfo, Client, DeviceInfo, SessionInfo

account = AccountInfo(
    identity=AccountIdentity("username", "password"),
    device=DeviceInfo("android_id", "phone_id", "uuid", "device_id"),
    session=SessionInfo(sessionid="...", ds_user_id=123456789),
)
client = Client(account=account)
```

Android 和 Web 均支持账号字符串入口恢复 session：

```python
from igapi.android import AccountInfo as AndroidAccountInfo
from igapi.web import AccountInfo, Client

android_account = AndroidAccountInfo.parse(
    "username:password||android_id;phone_id;uuid;device_id|sessionid=...; ds_user_id=...||"
)
account = AccountInfo.parse("username:password||csrf_token|sessionid=...; ds_user_id=...||")
client = Client(account=account)

account_str = client.export_account_string()
```

### 类型定义

#### 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 API 不返回独立的 `Feed` 类型，而是直接返回二元组：

```python
items, next_cursor = await igapi.FeedApi(client).user(12345678)
```

## 错误处理

```python
import asyncio
import igapi
from igapi.android import Client

async def main():
    client = Client()

    try:
        await client.login("user", "pass")
    except igapi.TwoFactorRequired as e:
        print(f"需要双因素认证: {e}")
    except igapi.ChallengeRequired as e:
        print(f"需要安全验证: {e}")
    except PermissionError as e:
        print(f"登录错误: {e}")
    except ValueError as e:
        print(f"无效输入: {e}")
    except RuntimeError as e:
        print(f"错误: {e}")

asyncio.run(main())
```

## 使用代理

```python
# HTTP 代理
from igapi.android import Client

client = Client(proxy="http://localhost:8080")

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

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

## 示例

更多完整示例请参见仓库根目录的 `docs/getting-started/快速上手.md` 和 `docs/api/`。

## 开发

### 构建

```bash
# 调试构建
maturin develop --manifest-path src/py/Cargo.toml

# 发布构建
maturin develop --release --manifest-path src/py/Cargo.toml

# 构建 wheel 包
maturin build --release --manifest-path src/py/Cargo.toml
```

### 测试

```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/)

