httk.core.git_sources¶

Fetch, cache and install members of git repositories named by git URIs.

A git URI has the form git+SCHEME://AUTHORITY/PATH[@REF][#SUBDIR] with SCHEME one of https, http or file. The repository is cloned at REF (a branch, tag, abbreviated or full commit hash, or the remote default branch when omitted), and the member is the directory SUBDIR (or the repository root), which must hold the consumer’s marker file. The canonical URI always carries the full commit hash, a lowercased scheme and host, and no trailing slashes; the repository path is kept verbatim, so …/repo and …/repo.git are distinct URIs.

Checkout trees are cached per repository and commit under data_home() / "git"; they carry no .git directory and are safe to delete. Referencing a URI with install_git_member() records one installed entry under data_home() / KIND / "installed", where KIND names the consumer (for example "templates"). Git runs with the global and system configuration, hooks, credential helpers and terminal prompts disabled, so only repositories reachable without credentials are supported. The cache-only lookups (cached_git_checkout(), installed_git_members(), installed_git_member(), resolve_installed_name() and uninstall_git_members()) never run git and never fetch.

Classes¶

`GitUri`	One parsed git URI.
`InstalledGitMember`	One installed git member entry.

Functions¶

`parse_git_uri`(text)	Parse and canonicalize a `git+scheme://authority/path[@ref][#subdir]` URI.
`fetch_git_checkout`(uri)	Return the canonical pinned URI and cached checkout tree, cloning only on a cache miss.
`cached_git_checkout`(uri)	Return the cached checkout tree of a pinned URI without running git.
`git_member`(tree, uri, marker)	Return the member directory uri names inside a checkout tree.
`install_git_member`(kind, uri, marker, names)	Fetch the member a git URI names and record it as installed.
`installed_git_members`(kind)	Return the installed entries of kind, sorted by URI, without running git.
`installed_git_member`(kind, uri)	Return the installed entry for exactly this pinned URI, without running git.
`resolve_installed_name`(kind, name)	Return the installed entry a short name means: the latest referenced one.
`uninstall_git_members`(kind, selector)	Remove installed entries without running git; cached checkout trees stay.

Module Contents¶

class httk.core.git_sources.GitUri¶

One parsed git URI.

Parameters:

repository – Give the canonical git+scheme://authority/path repository.
ref – Give the branch, tag or commit, or None for the default branch.
subdir – Give the member directory, or None for the repository root.

repository: str¶

ref: str | None¶

subdir: str | None¶

property pinned: bool¶

Whether the ref is a full commit hash.

class httk.core.git_sources.InstalledGitMember¶

One installed git member entry.

Parameters:

kind – Give the consumer kind, such as "templates".
uri – Give the canonical pinned URI.
repository – Give the canonical repository part of the URI.
commit – Give the full commit hash.
subdir – Give the member directory, or None for the repository root.
names – Give the short names the member claims.
referenced_at – Give the ISO timestamp of the latest explicit reference.
path – Give the member directory inside the cached checkout tree.

kind: str¶

uri: str¶

repository: str¶

commit: str¶

subdir: str | None¶

names: tuple[str, ...]¶

referenced_at: str¶

path: pathlib.Path¶

httk.core.git_sources.parse_git_uri(text)¶

Parse and canonicalize a git+scheme://authority/path[@ref][#subdir] URI.

The ref is split off at the last @ of the path, so repository paths that themselves contain @ are not supported.

Parameters:: text (str) – Supply the URI text.
Returns:: The parsed URI with a lowercased scheme, host and hash and no trailing slashes.
Raises:: ValueError – If the text is not a supported git URI.
Return type:: GitUri

httk.core.git_sources.fetch_git_checkout(uri)¶

Return the canonical pinned URI and cached checkout tree, cloning only on a cache miss.

A pinned URI whose commit is already cached runs no git at all.

Parameters:: uri (str | GitUri) – Supply a git+… URI or a parsed one.
Returns:: The URI pinned to the full commit hash, and the checkout tree root.
Raises:: ValueError – If the URI is invalid or git fails.
Return type:: tuple[GitUri, pathlib.Path]

httk.core.git_sources.cached_git_checkout(uri)¶

Return the cached checkout tree of a pinned URI without running git.

Parameters:: uri (str | GitUri) – Supply a git+… URI or a parsed one.
Returns:: The tree root, or None if the URI is not pinned or not cached.
Raises:: ValueError – If the URI text is invalid.
Return type:: pathlib.Path | None

httk.core.git_sources.git_member(tree, uri, marker)¶

Return the member directory uri names inside a checkout tree.

Parameters:

tree (pathlib.Path) – Give the checkout tree root.
uri (GitUri) – Give the URI whose subdirectory names the member.
marker (str) – Give the file name the member directory must hold.

Returns:

The member directory.

Raises:

ValueError – If the subdirectory is missing, leaves the tree, or lacks the marker.

Return type:

pathlib.Path

httk.core.git_sources.install_git_member(kind, uri, marker, names)¶

Fetch the member a git URI names and record it as installed.

The entry is written only after names accepts the member. Every call refreshes referenced_at, which decides which commit a short name means.

Parameters:

kind (str) – Name the consumer kind, such as "templates".
uri (str) – Supply a git+… URI.
marker (str) – Give the file name the member directory must hold.
names (collections.abc.Callable[[pathlib.Path], collections.abc.Sequence[str]]) – Validate the member directory and return the short names it claims.

Returns:

The installed entry.

Raises:

ValueError – If the URI or kind is invalid, git fails, or the member is missing or invalid.

Return type:

InstalledGitMember

httk.core.git_sources.installed_git_members(kind)¶

Return the installed entries of kind, sorted by URI, without running git.

Malformed or inconsistent entries and entries whose checkout is missing are skipped with a warning.

Parameters:: kind (str) – Name the consumer kind, such as "templates".
Returns:: The installed entries.
Raises:: ValueError – If the kind is invalid.
Return type:: tuple[InstalledGitMember, …]

httk.core.git_sources.installed_git_member(kind, uri)¶

Return the installed entry for exactly this pinned URI, without running git.

Parameters:

kind (str) – Name the consumer kind, such as "templates".
uri (str) – Supply a git+… URI; it is canonicalized first.

Returns:

The entry, or None if the URI is not pinned or not installed.

Raises:

ValueError – If the kind or URI is invalid.

Return type:

InstalledGitMember | None

httk.core.git_sources.resolve_installed_name(kind, name)¶

Return the installed entry a short name means: the latest referenced one.

Parameters:

kind (str) – Name the consumer kind, such as "templates".
name (str) – Give the short name.

Returns:

The latest-referenced entry claiming name, or None if none does.

Raises:

ValueError – If entries from several lineages (repository and subdirectory) claim name.

Return type:

InstalledGitMember | None

httk.core.git_sources.uninstall_git_members(kind, selector)¶

Remove installed entries without running git; cached checkout trees stay.

A pinned URI removes that entry; an unpinned URI (no ref, a branch, tag or abbreviated hash) removes every entry of its repository and subdirectory; a short name removes every entry of the lineage resolve_installed_name() selects.

Parameters:

kind (str) – Name the consumer kind, such as "templates".
selector (str) – Give a git+… URI or a short name.

Returns:

The removed entries.

Raises:

ValueError – If the selector is invalid, ambiguous, or matches nothing.

Return type:

tuple[InstalledGitMember, …]