ghrepo 0.7.1

GHRepo

class GHRepo(typing.NamedTuple):
    owner: str
    name: str

A pair of a GitHub repository’s owner and base name. Stringifying a GHRepo instance produces a repository “fullname” of the form {owner}/{name}.

property api_url: str

The base URL for accessing the repository via the GitHub REST API; this is a string of the form https://api.github.com/repos/{owner}/{name}.

property clone_url: str

The URL for cloning the repository over HTTPS

property git_url: str

The URL for cloning the repository via the native Git protocol

property html_url: str

The URL for the repository’s web interface

property ssh_url: str

The URL for cloning the repository over SSH

classmethod parse_url(url: str) -> GHRepo

Parse a GitHub repository URL. The following URL formats are recognized:

• [https://[<username>[:<password>]@]][www.]github.com/<owner>/<name>[.git][/]

• [https://]api.github.com/repos/<owner>/<name>

• git://github.com/<owner>/<name>[.git]

• [ssh://]git@github.com:<owner>/<name>[.git]

All other formats produce a ValueError.

classmethod parse(
    spec: str,
    default_owner: Optional[Union[str, Callable[[], str]]] = None,
) -> GHRepo

Parse a GitHub repository specifier. This can be either a URL (as accepted by parse_url()) or a string in the form {owner}/{name}. If default_owner is specified (as either a string or a zero-argument callable that returns a string), strings that are just a repository name are also accepted, and the resulting GHRepo instances will have their owner set to the given value.

Functions & Constants

Note: All of the functions require Git to be installed in order to work. I am not certain of the minimal viable Git version, but the functions should work with any Git as least as far back as version 1.7.

get_local_repo(dirpath: Optional[AnyPath] = None, remote: str = "origin") -> GHRepo

Determine the GitHub repository for the Git repository located at or containing the directory dirpath (default: the current directory) by parsing the URL for the specified remote. Raises NoSuchRemoteError if the given remote does not exist. Raises subprocess.CalledProcessError if a different Git error occurs, such as the given path not being in a Git repository.

get_branch_upstream(branch: str, dirpath: Optional[AnyPath] = None) -> GHRepo

(New in version 0.5.0) Determine the GitHub repository for the upstream remote of the given branch in the Git repository located at or containing the directory dirpath (default: the current directory).

Raises NoUpstreamError if the given branch does not have an upstream remote configured (This includes the situation in which the branch does not exist). Raises subprocess.CalledProcessError if a different Git error occurs, such as the given path not being in a Git repository.

get_current_branch(dirpath: Optional[AnyPath] = None) -> str

Get the current branch for the Git repository located at or containing the directory dirpath (default: the current directory). Raises DetachedHeadError if the repository is in a detached HEAD state. Raises subprocess.CalledProcessError if a different Git error occurs, such as the given path not being in a Git repository.

is_git_repo(dirpath: Optional[AnyPath] = None) -> bool

Tests whether the given directory (default: the current directory) is either a Git repository or contained in one

GH_USER_RGX: str

A regular expression string (unanchored) for a valid GitHub username or organization name.

GH_REPO_RGX: str

A regular expression string (unanchored) for a valid GitHub repository name (without “.git” extension).

Exceptions

class DetachedHeadError(Exception)

(New in version 0.6.0) Raised by get_current_branch() if the Git repository is in a detached HEAD state

class NoSuchRemoteError(Exception)

(New in version 0.6.0) Raised by get_local_repo() when the given remote does not exist in the GitHub repository. The queried remote is available as the remote attribute.

class NoUpstreamError(Exception)

(New in version 0.6.0) Raised by get_branch_upstream() if the given branch does not have a remote configured. The queried branch is available as the branch attribute.

Options

-J, --json

Output JSON

-r REMOTE, --remote REMOTE

Parse the GitHub URL from the given remote [default: origin]