Framework: Add and extend URL parsers - libvcs.url.base#

class libvcs.url.base.URLProtocol(*args, **kwargs)[source]#

Bases: Protocol

Common interface for VCS URL Parsers.

to_url()[source]#
Return type:

str

classmethod is_valid(url, is_explicit=None)[source]#
Return type:

bool

Parameters:
_abc_impl = <_abc._abc_data object>#
_is_protocol = True#
class libvcs.url.base.Rule(label, description, pattern, defaults=<factory>, is_explicit=False)[source]#

Bases: SkipDefaultFieldsReprMixin

A Rule represents an eligible pattern mapping to URL.

Parameters:
  • label (str) –

  • description (str) –

  • pattern (Pattern[str]) –

  • defaults (dict[str, str]) –

  • is_explicit (bool) –

label: str#

Computer readable name / ID

description: str#

Human readable description

pattern: Pattern[str]#

Regex pattern

defaults: dict[str, str]#

Is the match unambiguous with other VCS systems? e.g. git+ prefix

is_explicit: bool = False#
class libvcs.url.base.RuleMap(_rule_map=<factory>)[source]#

Bases: SkipDefaultFieldsReprMixin

Pattern matching and parsing capabilities for URL parsers, e.g. GitURL

Parameters:

_rule_map (dict[str, libvcs.url.base.Rule]) –

_rule_map: dict[str, libvcs.url.base.Rule]#
register(cls)[source]#
>>> from dataclasses import dataclass
>>> from libvcs.url.git import GitURL, GitBaseURL

GitBaseURL - the git(1) compliant parser - won’t accept a pip-style URL:

>>> GitBaseURL.is_valid(url="git+ssh://[email protected]/tony/AlgoXY.git")
False

GitURL - the “batteries-included” parser - can do it:

>>> GitURL.is_valid(url="git+ssh://[email protected]/tony/AlgoXY.git")
True

But what if you wanted to do github:org/repo?

>>> GitURL.is_valid(url="github:org/repo")
True

That actually works, but look, it’s caught in git’s standard SCP regex:

>>> GitURL(url="github:org/repo")
GitURL(url=github:org/repo,
   hostname=github,
   path=org/repo,
   rule=core-git-scp)
>>> GitURL(url="github:org/repo").to_url()
'[email protected]:org/repo'

Eek. That won’t work, can’t do much with that one.

We need something more specific so usable URLs can be generated. What do we do?

Extending matching capability:

>>> class GitHubPrefix(Rule):
...     label = 'gh-prefix'
...     description ='Matches prefixes like github:org/repo'
...     pattern = r'^github:(?P<path>.*)$'
...     defaults = {
...         'hostname': 'github.com',
...         'scheme': 'https'
...     }
...     # We know it's git, not any other VCS
...     is_explicit = True
>>> @dataclasses.dataclass(repr=False)
... class GitHubURL(GitURL):
...    rule_map: RuleMap = RuleMap(
...        _rule_map={'github_prefix': GitHubPrefix}
...    )
>>> GitHubURL.is_valid(url='github:vcs-python/libvcs')
True
>>> GitHubURL.is_valid(url='github:vcs-python/libvcs', is_explicit=True)
True

Notice how defaults neatly fills the values for us.

>>> GitHubURL(url='github:vcs-python/libvcs')
GitHubURL(url=github:vcs-python/libvcs,
    scheme=https,
    hostname=github.com,
    path=vcs-python/libvcs,
    rule=gh-prefix)
>>> GitHubURL(url='github:vcs-python/libvcs').to_url()
'https://github.com/vcs-python/libvcs'
>>> GitHubURL.is_valid(url='gitlab:vcs-python/libvcs')
False

GitHubURL sees this as invalid since it only has one rule, GitHubPrefix.

>>> GitURL.is_valid(url='gitlab:vcs-python/libvcs')
True

Same story, getting caught in git(1)’s own liberal scp-style URL:

>>> GitURL(url='gitlab:vcs-python/libvcs').rule
'core-git-scp'
>>> class GitLabPrefix(Rule):
...     label = 'gl-prefix'
...     description ='Matches prefixes like gitlab:org/repo'
...     pattern = r'^gitlab:(?P<path>)'
...     defaults = {
...         'hostname': 'gitlab.com',
...         'scheme': 'https',
...         'suffix': '.git'
...     }

Option 1: Create a brand new rule

>>> @dataclasses.dataclass(repr=False)
... class GitLabURL(GitURL):
...     rule_map: RuleMap = RuleMap(
...         _rule_map={'gitlab_prefix': GitLabPrefix}
...     )
>>> GitLabURL.is_valid(url='gitlab:vcs-python/libvcs')
True

Option 2 (global, everywhere): Add to the global GitURL:

>>> GitURL.is_valid(url='gitlab:vcs-python/libvcs')
True

Are we home free, though? Remember our issue with vague matches.

>>> GitURL(url='gitlab:vcs-python/libvcs').rule
'core-git-scp'

Register:

>>> GitURL.rule_map.register(GitLabPrefix)
>>> GitURL.is_valid(url='gitlab:vcs-python/libvcs')
True

Example: git URLs + pip-style git URLs:

This is already in GitURL via PIP_DEFAULT_RULES. For the sake of showing how extensibility works, here is a recreation based on GitBaseURL:

>>> from libvcs.url.git import GitBaseURL
>>> from libvcs.url.git import DEFAULT_RULES, PIP_DEFAULT_RULES
>>> @dataclasses.dataclass(repr=False)
... class GitURLWithPip(GitBaseURL):
...    rule_map: RuleMap = RuleMap(
...        _rule_map={m.label: m for m in [*DEFAULT_RULES, *PIP_DEFAULT_RULES]}
...    )
>>> GitURLWithPip.is_valid(url="git+ssh://[email protected]/tony/AlgoXY.git")
True
>>> GitURLWithPip(url="git+ssh://[email protected]/tony/AlgoXY.git")
GitURLWithPip(url=git+ssh://[email protected]/tony/AlgoXY.git,
    scheme=git+ssh,
    user=git,
    hostname=github.com,
    path=tony/AlgoXY,
    suffix=.git,
    rule=pip-url)
Return type:

None

Parameters:

cls (Rule) –

unregister(label)[source]#
Return type:

None

Parameters:

label (str) –

values()[source]#
Return type:

dict_values[str, Rule]