semvec/pypi-packages huggingface dataset:
tq-share-sms 1.0.0
TQ短信验证码API Python客户端
Requires Python: >=3.7
Keywords: sms, api, 短信, 验证码

# TQ短信验证码API Python客户端

一个简单易用的TQ短信验证码API Python客户端库。

## 安装

```bash
pip install tq-sms
```

## 快速开始

### 基本使用

```python
from tq_sms import TQSmsClient

# 使用用户名和密码初始化（会自动登录）
client = TQSmsClient(username="您的用户名", password="您的密码")

# 或者使用已有的token
# client = TQSmsClient(token="您的token")

# 获取余额
balance = client.get_wallet()
print(f"余额: {balance['data']['balances']}")

# 获取手机号
phone_result = client.get_phone(channel_id="您的渠道ID")
phone_number = phone_result['data']['mobile']
print(f"获取到手机号: {phone_number}")

# 获取验证码
code_result = client.get_code(channel_id="您的渠道ID", phone_num=phone_number)
if code_result['data']['code']:
    print(f"验证码: {code_result['data']['code']}")

# 如果没获取到验证码，拉黑手机号
else:
    client.blacklist_phone(channel_id="您的渠道ID", phone_no=phone_number)
    print("已拉黑手机号")
```

### 高级使用

```python
# 获取验证码（带重试机制）
code = client.get_code_with_retry(
    channel_id="您的渠道ID", 
    phone_num=phone_number, 
    max_retries=50
)

if code:
    print(f"验证码: {code}")
else:
    print("获取验证码失败")
    # 拉黑手机号
    client.blacklist_phone(channel_id="您的渠道ID", phone_no=phone_number)
```

## API 方法

### `login()`
登录获取token（如果初始化时提供了用户名密码会自动调用）

### `get_wallet()`
获取用户余额

### `get_phone(channel_id, phone_num=None, operator=None, scope=None)`
获取手机号
- `channel_id`: 渠道ID（必需）
- `phone_num`: 指定手机号码（可选）
- `operator`: 运营商类型，0=全部，5=虚拟，4=非虚拟（可选）
- `scope`: 指定号段，多个号段用逗号隔开（可选）

### `get_code(channel_id, phone_num)`
获取验证码
- `channel_id`: 渠道ID（必需）
- `phone_num`: 手机号码（必需）

### `blacklist_phone(channel_id, phone_no)`
拉黑手机号码
- `channel_id`: 渠道ID（必需）
- `phone_no`: 手机号码（必需）

### `get_code_with_retry(channel_id, phone_num, max_retries=100)`
获取验证码（带重试机制）
- `channel_id`: 渠道ID（必需）
- `phone_num`: 手机号码（必需）
- `max_retries`: 最大重试次数，默认100次（可选）

## 注意事项

1. 所有API调用均会自动添加1秒休眠，避免请求过于频繁
2. 网络请求具有自动重试机制，遇到网络错误会无限重试
3. 建议获取验证码最多重试100次
4. 如果没有获取到手机号，务必调用拉黑手机号接口
5. Token具有永久有效性，请妥善保管

## 错误处理

所有方法在失败时会抛出异常：
- `ValueError`: 参数错误
- `Exception`: API调用失败

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request。
ticktick-py-v2 0.24.1
API wrapper for the unofficial TickTick v2 API to access Tasks, Habits and Focus Times data
Requires Python: <4.0,>=3.11

# 📦 TickTick-Unofficial-Api

TickTick-Unofficial-Api is a Python wrapper for the unofficial TickTick API (v2). 
It provides access to task, focus, and habit data, and currently supports reading and writing habit entries. 
Authentication is handled via cookies retrieved either through Selenium or manually extracted browser sessions.

## ✨ Features

- Retrieve and add TickTick habit entries
- Retrieve TickTick focus time data
- Retrieve TickTick tasks (also supported by the official v1 API)

#### Planned features:
- Add support for writing focus sessions
- Add support for creating and updating tasks

## 🗂️ Project Structure

```
src/  
└── ticktick_v2/  
    ├── utils/                 utility functions  
    ├── web/                   web-related functionality (e.g., Selenium login)  
    ├── cookies_login.py       handles cookie retrieval via Selenium  
    ├── focus.py               focus session access  
    ├── habits.py              habit access and writing  
    └── tasks.py               task access
```

## 📥 Installation

To use the package, add [authentication](#-authentication) and install via:  
`pip install ticktick-py-v2`


## 🚀 Usage

You can use the module by importing `ticktick_v2`:
```
from ticktick_v2.habits import TicktickHabitHandler, TickTickHabitEntry 
from ticktick_v2.focus import TicktickFocusHandler, TickTickFocusTime
from ticktick_v2.tasks import TicktickTaskHandler, TickTickTask
```

All return values use pydantic BaseModel for data validation. 
To use data as dict, simply convert via `.dict()`

### 🔐 Authentication

To access your TickTick data, you must authenticate using one of two methods:

#### Method 1: Environment Variables + Selenium

Set the following environment variables:  
`TICKTICK_USERNAME="your_email@example.com"`  
`TICKTICK_PASSWORD="your_password"`

The package will use a headless Selenium session to retrieve the necessary cookies for API access.

#### Method 2: Pre-saved Cookies

Create a file named `.ticktick-cookies` in your working directory. 
This file should contain cookies exported from a logged-in TickTick browser session (e.g., using browser developer tools).


## 🤝 Contributing

Contributions are welcome. Please open issues or pull requests for new features, improvements, or bug fixes.

## 🪪 License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.