Quickstart

This page documents the implemented gitcode_api SDK surface rather than the upstream raw REST endpoints.

Create a sync client

from gitcode_api import GitCode

client = GitCode(
    api_key="your-token",
    owner="SushiNinja",
    repo="GitCode-API",
)

repo = client.repos.get()
print(repo.full_name)

Create an async client

import asyncio

from gitcode_api import AsyncGitCode


async def main() -> None:
    client = AsyncGitCode(owner="SushiNinja", repo="GitCode-API")
    pulls = await client.pulls.list(state="open", per_page=20)
    print(len(pulls))


asyncio.run(main())

Encrypted tokens

Pass decrypt= when api_key= or GITCODE_ACCESS_TOKEN contains an encrypted token value.

from gitcode_api import GitCode
from trusted_library import decrypt_token

with GitCode(
    api_key="encrypted-token",
    decrypt=decrypt_token,
    owner="SushiNinja",
    repo="GitCode-API",
) as client:
    repo = client.repos.get()
    print(repo.full_name)

Context managers

GitCode / AsyncGitCode (and SyncAPIClient / AsyncAPIClient) implement synchronous and asynchronous context managers. Exiting the block closes the underlying httpx client automatically, including a supplied http_client instance.

from gitcode_api import GitCode

with GitCode(owner="SushiNinja", repo="GitCode-API") as client:
    repo = client.repos.get()
    print(repo.full_name)

import asyncio

from gitcode_api import AsyncGitCode


async def main() -> None:
    async with AsyncGitCode(owner="SushiNinja", repo="GitCode-API") as client:
        pulls = await client.pulls.list(state="open", per_page=20)
        print(len(pulls))


asyncio.run(main())

TLS and certificate verification

When http_client is omitted, GitCode / AsyncGitCode (and SyncAPIClient / AsyncAPIClient) build an httpx client whose verify argument is resolved from the environment:

  1. If GITCODE_CA_BUNDLE is set to a non-empty string, it is used as the CA bundle path (GitCode-specific).

  2. Else if REQUESTS_CA_BUNDLE is set to a non-empty string, it is used (same general idea as for the requests library).

  3. Otherwise verify is True (system trust store).

Use this when GitCode HTTPS sits behind a corporate proxy or private PKI. For full control, pass http_client= with your own httpx.Client or httpx.AsyncClient (including custom verify values).

Repository-scoped defaults

Most repository resources accept owner= and repo= per call. If you set them on the client, repository methods can omit them:

client = GitCode(owner="SushiNinja", repo="GitCode-API")

branches = client.branches.list(per_page=10)
commits = client.commits.list(sha="main", per_page=10)
pulls = client.pulls.list(state="open")

If owner and repo are missing for a repository-scoped call, the SDK raises GitCodeConfigurationError.

Working with response objects

Responses are wrapped in lightweight APIObject subclasses. Use attribute access for common fields or .get() when a field may be missing.

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

payload = pull.to_dict()

For JSON or other consumers that expect dict objects, use as_dict() on one model or on a list of models. With deep_copy=True each result is a copy.deepcopy() of to_dict() output.

from gitcode_api import GitCode, as_dict

client = GitCode(owner="SushiNinja", repo="GitCode-API")
pulls = client.pulls.list(state="open", per_page=5)
serialized = as_dict(pulls)

Common workflows

Create a pull request:

pull = client.pulls.create(
    title="Add feature",
    head="feature-branch",
    base="main",
    body="Implements the new flow.",
)

Create or update repository content:

result = client.contents.create(
    path="README.md",
    content="IyBIZWxsbyBHaXRDb2RlCg==",
    message="Add README",
    branch="main",
)

Search across GitCode:

repos = client.search.repositories(q="sdk language:python", per_page=10)
users = client.search.users(q="SushiNinja")

OAuth helper methods

The oauth resource includes helper methods for the authorization code flow.

authorize_url = client.oauth.build_authorize_url(
    client_id="client-id",
    redirect_uri="https://example.com/callback",
    scope="user_info",
    state="opaque-state",
)

token = client.oauth.exchange_token(
    code="returned-code",
    client_id="client-id",
    client_secret="client-secret",
)

Examples

The repository includes runnable examples under examples/ for:

  • current user lookup

  • repository overview

  • issue and pull request template listing (see Issue and pull request templates)

  • pull request listing

  • asynchronous branch listing