Metadata-Version: 2.4
Name: wecom-smartsheet
Version: 0.2.0
Summary: WeCom SmartSheet Python SDK with full CRUD operations support
Author: WeCom SmartSheet SDK Contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/wecom-smartsheet
Project-URL: Documentation, https://github.com/yourusername/wecom-smartsheet#readme
Project-URL: Repository, https://github.com/yourusername/wecom-smartsheet
Project-URL: Bug Tracker, https://github.com/yourusername/wecom-smartsheet/issues
Keywords: wecom,wechat,smartsheet,enterprise,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# WeCom SmartSheet Python SDK

企业微信智能表格 Python SDK，提供完整的 CRUD 操作支持。

## 功能特性

- ✅ **完整的 CRUD 操作**
  - 读取记录（支持分页、过滤、转换）
  - 新增记录（单条/批量）
  - 更新记录（单条/批量）
  - 删除记录（单条/批量）

- ✅ **自动 Token 管理**
  - 自动获取和缓存 access_token
  - Token 过期自动刷新

- ✅ **灵活的数据导出**
  - 导出为 JSON 格式
  - 导出为 CSV 格式（支持 Excel）

- ✅ **命令行工具**
  - 提供 `wecom-smartsheet-fetch` CLI 工具

## 安装

```bash
pip install wecom-smartsheet
```

## 快速开始

### 初始化客户端

```python
from wecom_smartsheet import WeComSmartSheetClient

client = WeComSmartSheetClient(
    corpid="your_corpid",
    corpsecret="your_corpsecret"
)
```

### 读取记录

```python
# 读取所有记录
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id"
)

# 读取并转换为扁平格式
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    transform="flat"
)
```

### 新增记录

```python
# 新增单条记录
result = client.add_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records={
        "values": {
            "字段1": [{"text": "值1", "type": "text"}],
            "字段2": [{"text": "值2", "type": "text"}]
        }
    }
)

# 批量新增记录
result = client.add_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records=[
        {"values": {"字段1": [{"text": "值1", "type": "text"}]}},
        {"values": {"字段1": [{"text": "值2", "type": "text"}]}}
    ]
)
```

### 更新记录

```python
# 更新单条记录
result = client.update_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records={
        "record_id": "rec123",
        "values": {
            "字段1": [{"text": "新值", "type": "text"}]
        }
    }
)

# 批量更新记录
result = client.update_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    records=[
        {"record_id": "rec1", "values": {"字段1": [{"text": "新值1", "type": "text"}]}},
        {"record_id": "rec2", "values": {"字段1": [{"text": "新值2", "type": "text"}]}}
    ]
)
```

### 删除记录

```python
# 删除单条记录
result = client.delete_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    record_ids="rec123"
)

# 批量删除记录
result = client.delete_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    record_ids=["rec1", "rec2", "rec3"]
)
```

### 导出数据

```python
# 导出为 JSON
client.fetch_records_to_json(
    docid="your_docid",
    sheet_id="your_sheet_id",
    output_path="output.json"
)

# 导出为 CSV
client.fetch_records_to_csv(
    docid="your_docid",
    sheet_id="your_sheet_id",
    output_path="output.csv"
)
```

## 错误处理

```python
from wecom_smartsheet import WeComSmartSheetClient, WeComAPIError

client = WeComSmartSheetClient(corpid="...", corpsecret="...")

try:
    result = client.add_records(
        docid="your_docid",
        sheet_id="your_sheet_id",
        records={"values": {"字段1": [{"text": "值", "type": "text"}]}}
    )
except ValueError as e:
    print(f"参数错误: {e}")
except WeComAPIError as e:
    print(f"API 错误: {e}")
```

## 命令行工具

安装后可以使用 `wecom-smartsheet-fetch` 命令：

```bash
wecom-smartsheet-fetch --help
```

## 配置参数

### 获取配置参数

- **corpid**: 企业微信管理后台 -> 我的企业 -> 企业 ID
- **corpsecret**: 企业微信管理后台 -> 应用管理 -> 自建应用 -> Secret
- **docid**: 智能表格文档 URL 中的文档 ID
- **sheet_id**: 智能表格中的工作表 ID

## 高级用法

### 分页控制

```python
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    page_size=100,        # 每页记录数
    max_pages=10,         # 最大页数
    pause_seconds=0.1     # 页面间暂停时间
)
```

### 视图过滤

```python
records = client.fetch_records(
    docid="your_docid",
    sheet_id="your_sheet_id",
    view_id="your_view_id"  # 使用特定视图
)
```

## 系统要求

- Python >= 3.10
- 无外部依赖（仅使用 Python 标准库）

## 许可证

MIT License

## 更新日志

### v0.2.0 (2026-03-03)
- ✨ 新增 `add_records` 方法（新增记录）
- ✨ 新增 `update_records` 方法（更新记录）
- ✨ 新增 `delete_records` 方法（删除记录）
- 📝 添加完整的使用示例和文档

### v0.1.0 (2026-02-13)
- 🎉 初始版本
- ✨ 实现 `fetch_records` 方法（读取记录）
- ✨ 支持 JSON 和 CSV 导出
- ✨ 提供命令行工具

## 贡献

欢迎提交 Issue 和 Pull Request！

## 支持

如有问题，请在 GitHub 上提交 Issue。
