sphinx_polyversion.git

Git VCS support.

Functions

`file_predicate`(files)	Return a predicate that checks for files in a git revision.
`refs_by_type`(refs)	Group refs by type.

Classes

`Git`(branch_regex, tag_regex[, remote, ...])	Provide versions from git repository.
`GitRef`(name, obj, ref, type_, date[, remote])	A git ref representing a possible doc version.
`GitRefType`(value)	Types of git refs.

Bases: VersionProvider[GitRef]

Provide versions from git repository.

Parameters:

branch_regex (str | re.Pattern) – Regex branches must match completely
tag_regex (str | re.Pattern) – Regex tags must match completely
remote (str | None, optional) – Limit to this remote or to local refs if not specified, by default None

async static aroot(path: str | Path) → Path

Determine the root of the current git repository (async).

Parameters:: path (Path) – A path inside the repo. (Usually the current working directory)
Returns:: The root path of the repo.
Return type:: Path

async checkout(root: Path, dest: Path, revision: GitRef) → None

Extract a specific revision to the given path.

Parameters:

root (Path) – The root path of the git repository.
dest (Path) – The destination to copy the revision to.
revision (Any) – The revision to extract.

name(revision: GitRef) → str

Get the (unique) name of a revision.

This name will usually be used for creating the subdirectories of the revision.

Parameters:

root (Path) – The root path of the project.
revision (Any) – The revision whose name is requested.

Returns:

The name of the revision.

Return type:

str

async predicate(root: Path, ref: GitRef) → bool

Check whether a revision should be build.

This predicate is used by retrieve() to filter the git references retrieved.

Parameters:

root (Path) – The root path of the git repo.
ref (GitRef) – The git reference to check.

Returns:

Whether to build the revision referenced.

Return type:

bool

async retrieve(root: Path) → Iterable[GitRef]

List all build targets.

This retrieves all references from git and filters them using the options this instance was initialized with.

Parameters:: root (Path) – The root path of the project.
Returns:: The revisions/git references to build.
Return type:: tuple[GitRef]

classmethod root(path: str | Path) → Path

Determine the root of the current git repository.

Parameters:: path (Path) – A path inside the repo. (Usually the current working directory)
Returns:: The root path of the repo.
Return type:: Path

class sphinx_polyversion.git.GitRef(name: str, obj: str, ref: str, type_: GitRefType, date: datetime, remote: str | None = None)[source]

Bases: NamedTuple

A git ref representing a possible doc version.

date: datetime: Alias for field number 4

name: str: Alias for field number 0

obj: str: Alias for field number 1

ref: str: Alias for field number 2

remote: str | None: Alias for field number 5

type_: GitRefType: Alias for field number 3

class sphinx_polyversion.git.GitRefType(value)[source]

Bases: Enum

Types of git refs.

sphinx_polyversion.git.file_predicate(files: Iterable[str | PurePath]) → Callable[[Path, GitRef], Coroutine[None, None, bool]][source]

Return a predicate that checks for files in a git revision.

The returned predicate calls file_exists() for each file and checks whether all files exists in a given revision.

Parameters:: files (Iterable[str | PurePath]) – The files to check for.
Returns:: The predicate.
Return type:: Callable[[Path, GitRef], Coroutine[None, None, bool]]

sphinx_polyversion.git.refs_by_type(refs: Iterator[GitRef]) → Tuple[list[GitRef], list[GitRef]][source]

Group refs by type.

Parameters:

refs (Iterator[GitRef]) – The refs to group.

Returns:

branches (list[GitRef])
tags (list[GitRef])