Metadata-Version: 2.4
Name: twitter-sdk
Version: 0.2.3
Summary: Async gRPC client SDK for go-twitter-api (X private API executor)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: grpcio<2,>=1.62
Requires-Dist: protobuf<7,>=4.25

# twitter-sdk

`go-twitter-api` 的异步 Python gRPC 客户端。

本包**只是 gRPC 客户端**：不含任务编排、持久化、重试或账号锁——这些由调用方业务层决定。
所有协议实现（登录状态机、签名、设备证明、TLS 指纹）都在 Go server 侧。

## 安装

```bash
uv add twitter-sdk        # 或从 GitHub Release 附件安装 wheel / sdist
```

## 用法

平台是**导入命名空间**维度，不是运行时参数：`x.android` / `x.ios` / `x.web`（当前仅 Android 落地）。

```python
from twitter_sdk import x

async with x.android.AndroidClient("127.0.0.1:50051", api_key=KEY) as client:
    state = await client.login(username=USER, password=PASS, totp=CODE)
    # ★ 必须保存 state（含设备身份）；后续 RPC 复用，禁止重新生成设备
    acct = client.account(state)
    tweet = await acct.posts.create("hello")
    await acct.posts.delete(tweet.tweet_id)
    saved = acct.state          # 每次 RPC 后自动刷新，持久化这个
```

状态序列化：

```python
from twitter_sdk import dump_account_state, load_account_state

blob = dump_account_state(acct.state)   # 含明文 token/secret，调用方必须加密存储
state = load_account_state(blob)
```

## 测试

```bash
uv run --project python python -m pytest -q -m "not live" python/tests   # 离线契约测试
uv run --project python python -m pytest -q -m live python/tests         # 真机 E2E，需自有账号
```

真机 E2E 会发起真实请求并执行写操作，受平台频控影响，不在 CI 中运行。
