| Name | ghrepo JSON |
| Version |
0.7.1
JSON |
| download |
| home_page | None |
| Summary | Parse & construct GitHub repository URLs & specifiers |
| upload_time | 2024-12-01 12:41:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
github
url parsing
repository
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
|repostatus| |ci-status| |coverage| |pyversions| |license|
.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
:target: https://www.repostatus.org/#active
:alt: Project Status: Active — The project has reached a stable, usable
state and is being actively developed.
.. |ci-status| image:: https://github.com/jwodder/ghrepo/actions/workflows/test.yml/badge.svg
:target: https://github.com/jwodder/ghrepo/actions/workflows/test.yml
:alt: CI Status
.. |coverage| image:: https://codecov.io/gh/jwodder/ghrepo/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jwodder/ghrepo
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/ghrepo.svg
:target: https://pypi.org/project/ghrepo/
.. |license| image:: https://img.shields.io/github/license/jwodder/ghrepo.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/jwodder/ghrepo>`_
| `PyPI <https://pypi.org/project/ghrepo/>`_
| `Issues <https://github.com/jwodder/ghrepo/issues>`_
| `Changelog <https://github.com/jwodder/ghrepo/blob/master/CHANGELOG.md>`_
``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
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install it::
python3 -m pip install ghrepo
API
===
``GHRepo``
----------
.. code:: python
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}``.
.. code:: python
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}``.
.. code:: python
property clone_url: str
The URL for cloning the repository over HTTPS
.. code:: python
property git_url: str
The URL for cloning the repository via the native Git protocol
.. code:: python
property html_url: str
The URL for the repository's web interface
.. code:: python
property ssh_url: str
The URL for cloning the repository over SSH
.. code:: python
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``.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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
.. code:: python
GH_USER_RGX: str
A regular expression string (unanchored) for a valid GitHub username or
organization name.
.. code:: python
GH_REPO_RGX: str
A regular expression string (unanchored) for a valid GitHub repository name
(without ".git" extension).
Exceptions
----------
.. code:: python
class DetachedHeadError(Exception)
*(New in version 0.6.0)* Raised by ``get_current_branch()`` if the Git
repository is in a detached ``HEAD`` state
.. code:: python
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.
.. code:: python
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:
.. code:: json
{
"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": "git@github.com:jwodder/ghrepo.git"
}
Options
-------
-J, --json Output JSON
-r REMOTE, --remote REMOTE Parse the GitHub URL from the given remote
[default: origin]
Raw data
{
"_id": null,
"home_page": null,
"name": "ghrepo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "GitHub, URL parsing, repository",
"author": null,
"author_email": "John Thorvald Wodder II <ghrepo@varonathe.org>",
"download_url": "https://files.pythonhosted.org/packages/81/c6/9901ac741f4635c4ac99fb27950de8105b5f0788321e61b2c556a51e14c6/ghrepo-0.7.1.tar.gz",
"platform": null,
"description": "|repostatus| |ci-status| |coverage| |pyversions| |license|\n\n.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg\n :target: https://www.repostatus.org/#active\n :alt: Project Status: Active \u2014 The project has reached a stable, usable\n state and is being actively developed.\n\n.. |ci-status| image:: https://github.com/jwodder/ghrepo/actions/workflows/test.yml/badge.svg\n :target: https://github.com/jwodder/ghrepo/actions/workflows/test.yml\n :alt: CI Status\n\n.. |coverage| image:: https://codecov.io/gh/jwodder/ghrepo/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/ghrepo\n\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/ghrepo.svg\n :target: https://pypi.org/project/ghrepo/\n\n.. |license| image:: https://img.shields.io/github/license/jwodder/ghrepo.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/jwodder/ghrepo>`_\n| `PyPI <https://pypi.org/project/ghrepo/>`_\n| `Issues <https://github.com/jwodder/ghrepo/issues>`_\n| `Changelog <https://github.com/jwodder/ghrepo/blob/master/CHANGELOG.md>`_\n\n``ghrepo`` extracts a GitHub repository's owner & name from various GitHub URL\nformats (or just from a string of the form ``OWNER/REPONAME`` or ``REPONAME``),\nand the resulting object provides properties for going in reverse to determine\nthe possible URLs. Also included is a function for determining the GitHub\nowner & name for a local Git repository, plus a couple of other useful Git\nrepository inspection functions.\n\nInstallation\n============\n``ghrepo`` requires Python 3.8 or higher. Just use `pip\n<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install it::\n\n python3 -m pip install ghrepo\n\n\nAPI\n===\n\n``GHRepo``\n----------\n\n.. code:: python\n\n class GHRepo(typing.NamedTuple):\n owner: str\n name: str\n\nA pair of a GitHub repository's owner and base name. Stringifying a ``GHRepo``\ninstance produces a repository \"fullname\" of the form ``{owner}/{name}``.\n\n.. code:: python\n\n property api_url: str\n\nThe base URL for accessing the repository via the GitHub REST API; this is a\nstring of the form ``https://api.github.com/repos/{owner}/{name}``.\n\n.. code:: python\n\n property clone_url: str\n\nThe URL for cloning the repository over HTTPS\n\n.. code:: python\n\n property git_url: str\n\nThe URL for cloning the repository via the native Git protocol\n\n.. code:: python\n\n property html_url: str\n\nThe URL for the repository's web interface\n\n.. code:: python\n\n property ssh_url: str\n\nThe URL for cloning the repository over SSH\n\n.. code:: python\n\n classmethod parse_url(url: str) -> GHRepo\n\nParse a GitHub repository URL. The following URL formats are recognized:\n\n- ``[https://[<username>[:<password>]@]][www.]github.com/<owner>/<name>[.git][/]``\n- ``[https://]api.github.com/repos/<owner>/<name>``\n- ``git://github.com/<owner>/<name>[.git]``\n- ``[ssh://]git@github.com:<owner>/<name>[.git]``\n\nAll other formats produce a ``ValueError``.\n\n.. code:: python\n\n classmethod parse(\n spec: str,\n default_owner: Optional[Union[str, Callable[[], str]]] = None,\n ) -> GHRepo\n\nParse a GitHub repository specifier. This can be either a URL (as accepted by\n``parse_url()``) or a string in the form ``{owner}/{name}``. If\n``default_owner`` is specified (as either a string or a zero-argument callable\nthat returns a string), strings that are just a repository name are also\naccepted, and the resulting ``GHRepo`` instances will have their ``owner`` set\nto the given value.\n\n\nFunctions & Constants\n---------------------\n\n**Note**: All of the functions require Git to be installed in order to work. I\nam not certain of the minimal viable Git version, but the functions should work\nwith any Git as least as far back as version 1.7.\n\n.. code:: python\n\n get_local_repo(dirpath: Optional[AnyPath] = None, remote: str = \"origin\") -> GHRepo\n\nDetermine the GitHub repository for the Git repository located at or containing\nthe directory ``dirpath`` (default: the current directory) by parsing the URL\nfor the specified remote. Raises ``NoSuchRemoteError`` if the given remote\ndoes not exist. Raises ``subprocess.CalledProcessError`` if a different Git\nerror occurs, such as the given path not being in a Git repository.\n\n.. code:: python\n\n get_branch_upstream(branch: str, dirpath: Optional[AnyPath] = None) -> GHRepo\n\n*(New in version 0.5.0)* Determine the GitHub repository for the upstream\nremote of the given branch in the Git repository located at or containing the\ndirectory ``dirpath`` (default: the current directory).\n\nRaises ``NoUpstreamError`` if the given branch does not have an upstream remote\nconfigured (This includes the situation in which the branch does not exist).\nRaises ``subprocess.CalledProcessError`` if a different Git error occurs, such\nas the given path not being in a Git repository.\n\n.. code:: python\n\n get_current_branch(dirpath: Optional[AnyPath] = None) -> str\n\nGet the current branch for the Git repository located at or containing the\ndirectory ``dirpath`` (default: the current directory). Raises\n``DetachedHeadError`` if the repository is in a detached ``HEAD`` state.\nRaises ``subprocess.CalledProcessError`` if a different Git error occurs, such\nas the given path not being in a Git repository.\n\n.. code:: python\n\n is_git_repo(dirpath: Optional[AnyPath] = None) -> bool\n\nTests whether the given directory (default: the current directory) is either a\nGit repository or contained in one\n\n.. code:: python\n\n GH_USER_RGX: str\n\nA regular expression string (unanchored) for a valid GitHub username or\norganization name.\n\n.. code:: python\n\n GH_REPO_RGX: str\n\nA regular expression string (unanchored) for a valid GitHub repository name\n(without \".git\" extension).\n\n\nExceptions\n----------\n\n.. code:: python\n\n class DetachedHeadError(Exception)\n\n*(New in version 0.6.0)* Raised by ``get_current_branch()`` if the Git\nrepository is in a detached ``HEAD`` state\n\n.. code:: python\n\n class NoSuchRemoteError(Exception)\n\n*(New in version 0.6.0)* Raised by ``get_local_repo()`` when the given remote\ndoes not exist in the GitHub repository. The queried remote is available as\nthe ``remote`` attribute.\n\n.. code:: python\n\n class NoUpstreamError(Exception)\n\n*(New in version 0.6.0)* Raised by ``get_branch_upstream()`` if the given\nbranch does not have a remote configured. The queried branch is available as\nthe ``branch`` attribute.\n\n\nCommand\n=======\n\n``ghrepo`` also provides a command of the same name for getting the GitHub\nrepository associated with a local Git repository::\n\n ghrepo [<options>] [<dirpath>]\n\nBy default, the ``ghrepo`` command just outputs the repository \"fullname\" (a\nstring of the form ``{owner}/{name}``). If the ``-J`` or ``--json`` option is\nsupplied, a JSON object is instead output, containing fields for the repository\nowner, name, fullname, and individual URLs, like so:\n\n.. code:: json\n\n {\n \"owner\": \"jwodder\",\n \"name\": \"ghrepo\",\n \"fullname\": \"jwodder/ghrepo\",\n \"api_url\": \"https://api.github.com/repos/jwodder/ghrepo\",\n \"clone_url\": \"https://github.com/jwodder/ghrepo.git\",\n \"git_url\": \"git://github.com/jwodder/ghrepo.git\",\n \"html_url\": \"https://github.com/jwodder/ghrepo\",\n \"ssh_url\": \"git@github.com:jwodder/ghrepo.git\"\n }\n\nOptions\n-------\n\n-J, --json Output JSON\n\n-r REMOTE, --remote REMOTE Parse the GitHub URL from the given remote\n [default: origin]\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parse & construct GitHub repository URLs & specifiers",
"version": "0.7.1",
"project_urls": {
"Bug Tracker": "https://github.com/jwodder/ghrepo/issues",
"Source Code": "https://github.com/jwodder/ghrepo"
},
"split_keywords": [
"github",
" url parsing",
" repository"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af759b716104d39b97840609aff7d3fabf5d565b078e38d9eb6bfe065292870e",
"md5": "3050e32ce5561900f31071b68e7cf4bf",
"sha256": "cb7d6ec9a313aa2e407b3ce67b58a4bceec1dfb26b2b39ac320905a96e0ae14b"
},
"downloads": -1,
"filename": "ghrepo-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3050e32ce5561900f31071b68e7cf4bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9116,
"upload_time": "2024-12-01T12:41:35",
"upload_time_iso_8601": "2024-12-01T12:41:35.733389Z",
"url": "https://files.pythonhosted.org/packages/af/75/9b716104d39b97840609aff7d3fabf5d565b078e38d9eb6bfe065292870e/ghrepo-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81c69901ac741f4635c4ac99fb27950de8105b5f0788321e61b2c556a51e14c6",
"md5": "925d58433cd54f66d4a1bcd1646f1698",
"sha256": "6ace38c5f6543916028fe94baa63145bd3cc6085ab71a2e7fd7840abedfd2b66"
},
"downloads": -1,
"filename": "ghrepo-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "925d58433cd54f66d4a1bcd1646f1698",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12738,
"upload_time": "2024-12-01T12:41:37",
"upload_time_iso_8601": "2024-12-01T12:41:37.278449Z",
"url": "https://files.pythonhosted.org/packages/81/c6/9901ac741f4635c4ac99fb27950de8105b5f0788321e61b2c556a51e14c6/ghrepo-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-01 12:41:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwodder",
"github_project": "ghrepo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ghrepo"
}
