ghrepo 0.7.1

Parse & construct GitHub repository URLs & specifiers

GitHub | PyPI | Issues | Changelog

ghrepo extracts a GitHub repository’s owner & name from various GitHub URL formats (or just from a string of the form OWNER/REPONAME or REPONAME), and the resulting object provides properties for going in reverse to determine the possible URLs. Also included is a function for determining the GitHub owner & name for a local Git repository, plus a couple of other useful Git repository inspection functions.

Installation

ghrepo requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install it:

python3 -m pip install ghrepo

API

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://][e-mail]:<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.

Command

ghrepo also provides a command of the same name for getting the GitHub repository associated with a local Git repository:

ghrepo [<options>] [<dirpath>]

By default, the ghrepo command just outputs the repository “fullname” (a string of the form {owner}/{name}). If the -J or --json option is supplied, a JSON object is instead output, containing fields for the repository owner, name, fullname, and individual URLs, like so:

{
    "owner": "jwodder",
    "name": "ghrepo",
    "fullname": "jwodder/ghrepo",
    "api_url": "https://api.github.com/repos/jwodder/ghrepo",
    "clone_url": "https://github.com/jwodder/ghrepo.git",
    "git_url": "git://github.com/jwodder/ghrepo.git",
    "html_url": "https://github.com/jwodder/ghrepo",
    "ssh_url": "[e-mail]:jwodder/ghrepo.git"
}

Options

-J, --json

Output JSON

-r REMOTE, --remote REMOTE

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