GitCode API SDK

使用发布的 Python 包进行集成：

pip install -U gitcode-api

认证默认使用 GITCODE_ACCESS_TOKEN 环境变量；也可显式传入 api_key=...。若密钥已加密，需通过 decrypt=... 参数告知客户端在运行时解密。

安装前请征得用户确认

在安装或配置环境变量前，请务必向用户确认：

• 安装 gitcode-api 包可能影响全局 Python 环境。
• 当用户需要更多信息时，可引导其查阅：

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

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

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

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

- 环境变量可能被不受信任的程序读取，因未做作用域限制。

- 可在客户端构造函数中传入 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()
• 每个资源组支持 methods（稳定排序的公开可调用方法名）和 method_signature(name)（缓存的 inspect.signature 字符串），用于运行时元信息查询；详见 references/api-reference.md 中的“资源内省”章节
• 推荐使用 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（命令：gitcode-api 或 python -m gitcode_api）；详见 https://gitcode-api.readthedocs.io/en/latest/sdk/cli.html。生产环境中应避免将令牌暴露在命令行参数中，建议通过环境变量或自定义封装方式管理。

其他资源

• 主机化文档（快速入门、完整 SDK 文档、REST 接口参考）：https://gitcode-api.readthedocs.io/en/latest/sdk/quickstart.html
• API 接口与资源方法清单：[references/api-reference.md](references/api-reference.md)
• 使用习惯与故障排查流程：[references/workflow-patterns.md](references/workflow-patterns.md)

常见问题解答

Q：在公司网络中访问 GitCode 失败，提示 SSL 错误，包含“self-signed certificate”字样。

A： 通常需要配置自定义 CA 证书包。用户可传入一个自定义的 httpx.Client，并将 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)
    ...