Skip to content

nurl wrapper

nurl is THE prefetcher, that can prefetch all imaginable sources with ease. You should always prefer it over other fetchers (only for prefetching the hash, it can't do the job of the GitHub helper for example).

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 usecase 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.

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

nurl async 

nurl(
    url: str,
    revision: str | None = None,
    *,
    additional_arguments: Iterable[str] | None = None,
    submodules: bool = False,
    fetcher: FETCHERS | None = None,
    fallback: FETCHERS | None = None,
) -> NurlResult

Just a fancy wrapper around nurl to handle edge-cases like caching.

Parameters:

  • fetcher

    (FETCHERS | None, default: None ) –

    A fetcher to use. List of all possible fethers can be obtained using nurl -l.

  • fallback

    (FETCHERS | None, default: None ) –

    The fetcher to fall back to when nurl fails to infer it from the URL.

Raises:

  • NurlError –

    If nupd return non-zero exit code or wrote something to stderr.

nurl_parse async 

nurl_parse(
    url: str,
    revision: str | None = None,
    *,
    additional_arguments: Iterable[str] | None = None,
    submodules: bool = False,
    fetcher: FETCHERS | None = None,
    fallback: FETCHERS | None = None,
) -> NurlResult

Wrapper around nurl function, to also pass --parse argument.

From nurl --help: Parse the url without fetching the hash, output in json format.

Example 
>>> nurl_parse("https://github.com/NixOS/nixpkgs")
NurlResult(args=frozendict.frozendict({'owner': 'NixOS', 'repo': 'nixpkgs'}), fetcher='fetchFromGitHub')

Response classes

FETCHERS is a list of all fetchers that nurl supports (obtained via nurl -l).

NurlResult

Bases: NupdModel

args instance-attribute 

args: FrozenDict[str, Any]

fetcher instance-attribute 

fetcher: FETCHERS

NurlError

Bases: NetworkError