GitCode API SDK

使用已发布的 Python 包：

pip install -U gitcode-api

认证默认使用 GITCODE_ACCESS_TOKEN 环境变量，或显式传入 api_key=...。如果值为加密状态，请通过 decrypt=... 传递，以便客户端在认证前解密。

安装或设置环境变量前请征得用户确认

在安装前请向用户确认：

• 与所有 Python 包一样，安装 gitcode-api 可能会修改全局环境。
• 当用户需要更多信息时，可引导其查阅：

- 项目 PyPI 页面：https://pypi.org/project/gitcode-api/

- 文档：https://gitcode-api.readthedocs.io/

- 源代码仓库：https://github.com/Trenza1ore/GitCode-API

• 请用户提供 GITCODE_ACCESS_TOKEN 环境变量，建议以加密形式提供：

- 环境变量可能被不受信任的软件读取，因为其作用范围不受限。

- 可在 GitCode 客户端构造函数中传入 decrypt 参数，用于在运行时解密加密的 api_key 值或加密的 GITCODE_ACCESS_TOKEN。

客户端结构

该 SDK 的结构与 OpenAI 的 Python 客户端类似：

• 从顶层客户端对象开始：GitCode(...) 或 AsyncGitCode(...)
• 从客户端调用分组资源，如 client.repos、client.pulls、client.users 和 client.search
• 在这些资源组上调用方法，如 client.repos.get() 或 await client.pulls.list()
• 推荐使用 with GitCode(...) as client: 或 async with AsyncGitCode(...) as client:，以便 SDK 自动关闭底层的 httpx 客户端，包括自定义的 http_client

与 OpenAI 的类型化请求/响应结构不同，本 SDK 聚焦于 GitCode REST 资源，返回轻量级响应对象并支持属性访问。

快速入门

同步方式：

from gitcode_api import GitCode

with GitCode(
    api_key="your-token",
    owner="SushiNinja",
    repo="GitCode-API",
) as client:
    repo = client.repos.get()
    pulls = client.pulls.list(state="open", per_page=5)
    print(repo.full_name)
    for pull in pulls:
        print(pull.number, pull.title)

异步方式：

import asyncio
from gitcode_api import AsyncGitCode

async def main() -> None:
    async with AsyncGitCode(
        api_key="your-token",
        owner="SushiNinja",
        repo="GitCode-API",
    ) as client:
        branches = await client.branches.list(per_page=5)
        for branch in branches:
            print(branch.name)

asyncio.run(main())

加密令牌：

from gitcode_api import GitCode
from trusted_library import decryption_method

with GitCode(
    api_key="encrypted-token",
    owner="SushiNinja",
    repo="GitCode-API",
    decrypt=decryption_method,
) as client:
    repo = client.repos.get()
    pulls = client.pulls.list(state="open", per_page=5)
    print(repo.full_name)
    for pull in pulls:
        print(pull.number, pull.title)

仓库范围的默认值

若在客户端中设置了 owner= 和 repo=，则在调用仓库相关资源时可省略这些参数。若未设置，则需在仓库相关方法中显式传入 owner= 和 repo=。

常见资源组

• client.repos 和 client.contents
• client.branches 和 client.commits
• client.issues 和 client.pulls
• client.labels、client.milestones 和 client.members
• client.releases、client.tags 和 client.webhooks
• client.users、client.orgs、client.search 和 client.oauth

常见任务

• 仓库信息和文件内容：

client.repos.get()、client.contents.get()、client.contents.create()、client.contents.update()

• 分支、提交和差异：

client.branches.list()、client.commits.list()、client.commits.compare()

• 问题和拉取请求：

client.issues.list()、client.issues.create()、client.pulls.list()、client.pulls.create()、client.pulls.merge()

• 账户与发现：

client.users.me()、client.orgs.list_authenticated()、client.search.repositories()

• OAuth：

client.oauth.build_authorize_url()、client.oauth.exchange_token()

更多方法列表请参考：references/api-reference.md

响应对象

响应为轻量级对象，而非普通字典。

典型用法：

pull = client.pulls.get(number=42)
print(pull.title)
print(pull.get("source_branch"))
payload = pull.to_dict()

实用脚本

内置辅助工具：

• scripts/check_env.py：验证 Python 版本、包导入及令牌配置
• scripts/gitcode_api_cli.py：提供一个小型 CLI 示例，演示常见 SDK 调用。建议自行编写版本，并使用加密访问令牌以提升安全性

其他资源

• API 接口与资源方法清单：[references/api-reference.md](references/api-reference.md)
• 使用习惯与故障排查流程：[references/workflow-patterns.md](references/workflow-patterns.md)

常见问题解答

Q：在公司网络中，访问 GitCode 时出现 SSL 错误，提示“自签名证书”。

A：通常需要设置自定义 CA 证书包。用户可传入自定义的 httpx 客户端，并将 verify 设置为证书路径，这与 requests 库中的 REQUESTS_CA_BUNDLE 环境变量类似。

from gitcode_api import GitCode
from httpx import Client

with GitCode(
    owner="SushiNinja",
    repo="GitCode-API",
    http_client=Client(verify="path/to/my/certificate.crt"),
) as client:
    repo = client.repos.get()
    pulls = client.pulls.list(state="open", per_page=5)
    ...