anomalyco/opencode-sdk-python
GitHub: anomalyco/opencode-sdk-python
Opencode AI 平台的官方 Python SDK，提供类型安全的同步/异步客户端，便捷访问 Opencode REST API。
Stars: 202 | Forks: 19
# Opencode Python API 库
[)](https://pypi.org/project/opencode-ai/)
Opencode Python 库提供了从任何 Python 3.8+ 应用程序便捷访问 Opencode REST API 的方式。该库包含对所有请求参数和响应字段的类型定义，并提供由 [httpx](https://github.com/encode/httpx) 驱动的同步和异步客户端。
它由 [Stainless](https://www.stainless.com/) 生成。
## 文档
REST API 文档可在 [opencode.ai](https://opencode.ai/docs) 上找到。该库的完整 API 可在 [api.md](api.md) 中找到。
## 安装
```
# 从 PyPI install
pip install --pre opencode-ai
```
## 使用方法
该库的完整 API 可在 [api.md](api.md) 中找到。
```
from opencode_ai import Opencode
client = Opencode()
sessions = client.session.list()
```
## 异步使用
只需导入 `AsyncOpencode` 而不是 `Opencode`，并在每次 API 调用时使用 `await`：
```
import asyncio
from opencode_ai import AsyncOpencode
client = AsyncOpencode()
async def main() -> None:
sessions = await client.session.list()
asyncio.run(main())
```
同步和异步客户端的功能在其他方面完全相同。
### 使用 aiohttp
默认情况下，异步客户端使用 `httpx` 进行 HTTP 请求。但是，为了提高并发性能，您也可以使用 `aiohttp` 作为 HTTP 后端。
您可以通过安装 `aiohttp` 来启用它：
```
# 从 PyPI install
pip install --pre opencode-ai[aiohttp]
```
然后您可以通过使用 `http_client=DefaultAioHttpClient()` 实例化客户端来启用它：
```
import asyncio
from opencode_ai import DefaultAioHttpClient
from opencode_ai import AsyncOpencode
async def main() -> None:
async with AsyncOpencode(
http_client=DefaultAioHttpClient(),
) as client:
sessions = await client.session.list()
asyncio.run(main())
```
## 流式响应
我们提供使用 Server Side Events (SSE) 的流式响应支持。
```
from opencode_ai import Opencode
client = Opencode()
stream = client.event.list()
for events in stream:
print(events)
```
异步客户端使用完全相同的接口。
```
from opencode_ai import AsyncOpencode
client = AsyncOpencode()
stream = await client.event.list()
async for events in stream:
print(events)
```
## 使用类型
嵌套的请求参数是 [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict)。响应是 [Pydantic models](https://docs.pydantic.dev)，它们还提供用于以下操作的辅助方法：
- 序列化回 JSON，`model.to_json()`
- 转换为字典，`model.to_dict()`
类型化的请求和响应在您的编辑器中提供自动补全和文档。如果您希望在 VS Code 中看到类型错误以帮助更早地捕获 Bug，请将 `python.analysis.typeCheckingMode` 设置为 `basic`。
## 处理错误
当库无法连接到 API 时（例如，由于网络连接问题或超时），会引发 `opencode_ai.APIConnectionError` 的子类。
当 API 返回非成功状态码（即 4xx 或 5xx 响应）时，会引发 `opencode_ai.APIStatusError` 的子类，其中包含 `status_code` 和 `response` 属性。
所有错误均继承自 `opencode_ai.APIError`。
```
import opencode_ai
from opencode_ai import Opencode
client = Opencode()
try:
client.session.list()
except opencode_ai.APIConnectionError as e:
print("The server could not be reached")
print(e.__cause__) # an underlying Exception, likely raised within httpx.
except opencode_ai.RateLimitError as e:
print("A 429 status code was received; we should back off a bit.")
except opencode_ai.APIStatusError as e:
print("Another non-200-range status code was received")
print(e.status_code)
print(e.response)
```
错误码如下：
| 状态码 | 错误类型 |
| ----------- | -------------------------- |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| >=500 | `InternalServerError` |
| N/A | `APIConnectionError` |
### 重试
默认情况下，某些错误会自动重试 2 次，并带有短暂的指数退避。
连接错误（例如，由于网络连接问题）、408 Request Timeout、409 Conflict、429 Rate Limit 以及 >=500 Internal 错误默认都会被重试。
您可以使用 `max_retries` 选项来配置或禁用重试设置：
```
from opencode_ai import Opencode
# Configure 所有 requests 的默认设置：
client = Opencode(
# default is 2
max_retries=0,
)
# 或者，按 request Configure：
client.with_options(max_retries=5).session.list()
```
### 超时
默认情况下，请求会在 1 分钟后超时。您可以使用 `timeout` 选项进行配置，该选项接受一个浮点数或一个 [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) 对象：
```
from opencode_ai import Opencode
# Configure 所有 requests 的默认设置：
client = Opencode(
# 20 seconds (default is 1 minute)
timeout=20.0,
)
# 更精细的控制：
client = Opencode(
timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)
# 按 request Override：
client.with_options(timeout=5.0).session.list()
```
超时时，会抛出 `APITimeoutError`。
请注意，超时的请求默认[会重试两次](#retries)。
## 高级
### 日志
我们使用标准库的 [`logging`](https://docs.python.org/3/library/logging.html) 模块。
您可以通过将环境变量 `OPENCODE_LOG` 设置为 `info` 来启用日志记录。
```
$ export OPENCODE_LOG=info
```
或者设置为 `debug` 以获取更详细的日志。
### 如何判断 `None` 表示 `null` 还是缺失
在 API 响应中，一个字段可能是显式的 `null`，或者完全缺失；在这两种情况下，该库中的值均为 `None`。您可以使用 `.model_fields_set` 来区分这两种情况：
```
if response.my_field is None:
if 'my_field' not in response.model_fields_set:
print('Got json like {}, without a "my_field" key present at all.')
else:
print('Got json like {"my_field": null}.')
```
### 访问原始响应数据（例如 headers）
可以通过在任何 HTTP 方法调用前加上 `.with_raw_response.` 来访问“原始”Response 对象，例如，
```
from opencode_ai import Opencode
client = Opencode()
response = client.session.with_raw_response.list()
print(response.headers.get('X-My-Header'))
session = response.parse() # get the object that `session.list()` would have returned
print(session)
```
这些方法返回一个 [`APIResponse`](https://github.com/sst/opencode-sdk-python/tree/main/src/opencode_ai/_response.py) 对象。
异步客户端返回一个具有相同结构的 [`AsyncAPIResponse`](https://github.com/sst/opencode-sdk-python/tree/main/src/opencode_ai/_response.py)，唯一的区别是读取响应内容的方法是 `await`able 的。
#### `.with_streaming_response`
上述接口在您发出请求时会立即读取完整的响应体，这可能并不总是您想要的。
要流式传输响应体，请改用 `.with_streaming_response`，这需要使用上下文管理器，并且只有在您调用 `.read()`、`.text()`、`.json()`、`.iter_bytes()`、`.iter_text()`、`.iter_lines()` 或 `.parse()` 时才会读取响应体。在异步客户端中，这些是异步方法。
```
with client.session.with_streaming_response.list() as response:
print(response.headers.get("X-My-Header"))
for line in response.iter_lines():
print(line)
```
之所以需要上下文管理器，是为了确保响应能够被可靠地关闭。
### 发出自定义/未记录的请求
该库为便捷访问已记录的 API 进行了类型化处理。
如果您需要访问未记录的 endpoints、params 或 response properties，仍然可以使用该库。
#### 未记录的 endpoints
要向未记录的 endpoints 发出请求，您可以使用 `client.get`、`client.post` 以及其他 HTTP 动词。发出此请求时，客户端上的选项（例如重试）将得到遵守。
```
import httpx
response = client.post(
"/foo",
cast_to=httpx.Response,
body={"my_param": True},
)
print(response.headers.get("x-foo"))
```
#### 未记录的请求参数
如果您想显式发送额外的参数，可以通过 `extra_query`、`extra_body` 和 `extra_headers` 请求选项来实现。
#### 未记录的响应属性
要访问未记录的响应属性，您可以像 `response.unknown_prop` 这样访问额外的字段。您还可以使用 [`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra) 将 Pydantic 模型上的所有额外字段作为 dict 获取。
### 配置 HTTP 客户端
您可以直接重写 [httpx client](https://www.python-httpx.org/api/#client) 以根据您的用例进行自定义，包括：
- 支持 [proxies](https://www.python-httpx.org/advanced/proxies/)
- 自定义 [transports](https://www.python-httpx.org/advanced/transports/)
- 其他 [advanced](https://www.python-httpx.org/advanced/clients/) 功能
```
import httpx
from opencode_ai import Opencode, DefaultHttpxClient
client = Opencode(
# Or use the `OPENCODE_BASE_URL` env var
base_url="http://my.test.server.example.com:8083",
http_client=DefaultHttpxClient(
proxy="http://my.test.proxy.example.com",
transport=httpx.HTTPTransport(local_address="0.0.0.0"),
),
)
```
您还可以使用 `with_options()` 在每个请求的基础上自定义客户端：
```
client.with_options(http_client=DefaultHttpxClient(...))
```
### 管理 HTTP 资源
默认情况下，只要客户端被[垃圾回收](https://docs.python.org/3/reference/datamodel.html#object.__del__)，该库就会关闭底层的 HTTP 连接。如果需要，您可以使用 `.close()` 方法手动关闭客户端，或者在退出时关闭的上下文管理器中关闭它。
```
from opencode_ai import Opencode
with Opencode() as client:
# make requests here
...
# HTTP client 现已 closed
```
## 版本控制
此包通常遵循 [SemVer](https://semver.org/spec/v2.0.0.html) 约定，尽管某些向后不兼容的更改可能会作为次要版本发布：
1. 仅影响静态类型而不破坏运行时行为的更改。
2. 对库内部结构的更改，这些内部结构在技术上是公开的，但并非旨在或记录供外部使用。_(如果您依赖于此类内部结构，请开启一个 GitHub issue 告知我们。)_
3. 我们预计在实践中不会影响绝大多数用户的更改。
我们非常重视向后兼容性，并努力确保您获得顺畅的升级体验。
我们热切期待您的反馈；如有任何问题、Bug 或建议，请开启一个 [issue](https://www.github.com/sst/opencode-sdk-python/issues)。
### 确定已安装的版本
如果您已升级到最新版本，但没有看到您期望的任何新功能，那么您的 python 环境可能仍在使用旧版本。
您可以通过以下方式确定运行时正在使用的版本：
```
import opencode_ai
print(opencode_ai.__version__)
```
## 要求
Python 3.8 或更高版本。
## 贡献
参见[贡献文档](./CONTRIBUTING.md)。
标签：aiohttp, AI开发工具, API客户端, DLL 劫持, httpx, LLM工具, Opencode, PyPI, Python, RESTful API, SaaS API, 人工智能, 大语言模型, 威胁情报, 开发者工具, 开源库, 异步编程, 提示词优化, 搜索引擎爬虫, 无后门, 用户模式Hook绕过, 类型提示, 网络调试, 自动化, 运行时操纵, 逆向工具