Parser - libvcs.parse#

VCS URL parser for python.

Parsing capabilities#

Warning

The APIs and structures themselves are still unstable APIs. If you are missing a field or use case, please file an issue.

  1. Detect VCS URLs

  1. Convert input VCS to usable URLs

    pip knows what a certain URL string means, but git clone won’t.

    e.g. pip install git+https://github.com/django/django.git@3.2 works great with pip.

    $ pip install git+https://github.com/django/[email protected]
...
Successfully installed Django-3.2

    but git clone can’t use that:

    $ git clone git+https://github.com/django/[email protected]  # Fail
...
Cloning into [email protected]''...'
git: 'remote-git+https' is not a git command. See 'git --help'.

    It needs something like this:

    $ git clone https://github.com/django/django.git --branch 3.2

    But before we get there, we don’t know if we want a URL yet. We return a structure, e.g. GitURL.

  • Common result primitives across VCS, e.g. GitURL.

    Compare to a urllib.parse.ParseResult in urlparse

    This is where fun can happen, or you can just parse a URL.

  • Allow mutating / replacing parse of a vcs (e.g. just the hostname)

  • Support common cases with popular VCS systems

  • Support extending parsing for users needing to do so

Scope#

Out of the box#

The ambition for this is to build extendable parsers for package-like URLs, e.g.

  • Vanilla VCS URLs

    • any URL supported by the VCS binary, e.g. git(1), svn(1), hg(1).

  • pip-style urls [1]

    • branches

    • tags

  • NPM-style urls[2]

    • branches

    • tags

Extendability#

Patterns can be registered. Similar behavior exists in urlparse (undocumented).

  • Any formats not covered by the stock

  • Custom urls

    • For orgs on , e.g:

      • python:mypy -> git@github.com:python/mypy.git

      • inkscape:inkscape -> git@gitlab.com:inkscape/inkscape.git

    • For out of domain trackers, e.g.

      Direct to site:

      Direct to site + org / group:

      • gnome:gedit -> git@gitlab.gnome.org:GNOME/gedit.git

      • openstack:openstack -> https://opendev.org/openstack/openstack.git

      • mozilla:central -> https://hg.mozilla.org/mozilla-central/

From there, GitURL can be used downstream directly by other projects.

In our case, libvcss’ own Commands - libvcs.cmd and Projects - libvcs.projects, as well as a $ vcspull · configuration, will be able to detect and accept various URL patterns.

Location objects#

Compare to urllib.parse.ParseResult. These are structures that break the VCS location into parse so they can be filled, replaced [3], and exported into a URL specifier compatible with the VCS.

Explore#

API