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.
Detect VCS URLs
Parse results of URL to a structure
Compare to
urllib.parse.ParseResult
Convert input VCS to usable URLs
pip
knows what a certain URL string means, butgit clone
won’t.e.g.
pip install git+https://github.com/django/django.git@3.2
works great withpip
.$ 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
inurlparse
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.
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:
cb:python-vcs/libtmux
->https://codeberg.org/vcs-python/libvcs
kde:plasma/plasma-sdk
->git@invent.kde.org:plasma/plasma-sdk.git
Aside: Note KDE’s git docs use of
url.<base>.insteadOf
andurl.<base>.pushInsteadOf
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, libvcs
s’ 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
- Git URL Parser -
libvcs.parse.git
- SVN URL Parser -
libvcs.parse.svn
- Mercurial URL Parser -
libvcs.parse.hg
- Framework: Add and extend URL parsers -
libvcs.parse.base