GitHub repository fetcher

This helper implements extensive fetching for GitHub repositories.

Info

All requests to the functions are automatically cached.

Fetching general information about GitHub repository

If you have a GitHub API token, you should use github_fetch_graphql, if you don't - github_fetch_rest.

The difference, is that GraphQL requires API key, but has much higher rate limits, while REST API is the opposite. Which makes REST API great for one-time uses and GraphQL for massive updates.

After you fetched general information about the repository, you would probably want to fetch such things as latest commit/release/Git tag. For this you should use result.prefetch_commit() and/or result.prefetch_latest_version(). As every function is limited to only one request (this is to make predicting rate limiting intuitive), github_fetch_rest will not fetch that data but github_fetch_graphql will (GraphQL allows us to include multiple requests into one).

Note

Those functions don't do any additional requests if data is already present in the result object. Which means, you can safely do code like this:

if token:
    result = await github_fetch_graphql(...)
else:
    result = await github_fetch_rest(...)

# if we used GraphQL API, we already have that data,
# so these functions return immediately
result = await result.prefetch_commit()
result = await result.prefetch_latest_version()

Don't forget to consult result.prefetch_commit() and result.prefetch_latest_version().

Functions

github_fetch_graphql async

github_fetch_graphql(
    owner: str, repo: str, github_token: str
) -> GHRepository

Fetch a GitHub repository using GraphQL API.

GraphQL API allows us to include multiple different requests in one, which makes it superior for ratelimit-sensitive operations, but it requires a token.

github_fetch_rest async

github_fetch_rest(
    owner: str, repo: str, *, github_token: str | None
) -> GHRepository

Fetch a GitHub repository using REST API.

REST API makes GitHub token optional, but it is a lot easier to get rate limited. If GitHub token is provided, use GraphQL API instead.

Do not forget to handle redirects!

Warning

Other undocumented functions in this module are considered private and you should not use them.

Response classes

GHRepository

Bases: NupdModel

branch instance-attribute

branch: str

commit instance-attribute

commit: Commit | None

has_submodules instance-attribute

has_submodules: bool | None

latest_version instance-attribute

latest_version: str | None

meta instance-attribute

meta: MetaInformation

owner instance-attribute

owner: str

repo instance-attribute

repo: str

url property

url: str

prefetch_commit async

prefetch_commit(*, github_token: str | None = None) -> Self

Prefetch latest commit, if it is not yet prefetched.

Example

Note that the result object is immutable, which means this function has to do a copy and return it. You have to call this function like this:

result = await result.prefetch_latest_version()

prefetch_latest_version async

prefetch_latest_version(
    github_token: str | None = None,
) -> Self

Prefetch latest version, if it is not yet prefetched.

First it tries to fetch the latest GitHub release, if it fails - it fallbacks to Git tags. If there are no tags, the returned object's latest_version stays None.

Example

Note that the result object is immutable, which means this function has to do a copy and return it. You have to call this function like this:

result = await result.prefetch_latest_version()

MetaInformation

Bases: NupdModel

archived instance-attribute

archived: bool

archived_at instance-attribute

archived_at: datetime | None

description instance-attribute

description: str | None

homepage instance-attribute

homepage: str | None

license instance-attribute

license: str | None

stars instance-attribute

stars: int

Commit

Bases: NupdModel

date instance-attribute

date: datetime

id instance-attribute

id: str

SHA1 hash of the commit.