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()。
• 每个资源组均提供 methods（按稳定 SDK 顺序、基于路径段排序的公开可调用名称列表）和 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

响应对象

响应为轻量级对象，而非原始字典（plain dict）。

典型用法示例：

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/workflow-patterns.md

常见问题（FAQ）

Q：在公司网络中访问 GitCode 时出现 SSL 错误，提示 “self-signed certificate”。
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)
    ...