Mercurial URL Parser - libvcs.url.hg¶

Detect and parse Mercurial URLs through HgURL, aka hg(1).

Detect, parse, and validate hg (Mercurial) URLs.

Note

Mercurial URL support is experimental. If you rely on these URL shapes in production, please verify them against your hosts and report gaps in the project tracker.

libvcs.url.hg.DEFAULT_RULES: list[Rule] = <...truncated, 634 chars>
¶
data
data
libvcs.url.hg.DEFAULT_RULES: list[Rule] = <...truncated, 634 chars>
¶

Core regular expressions. These are patterns understood by hg(1)

libvcs.url.hg.PIP_DEFAULT_RULES: list[Rule] = <...truncated, 513 chars>
¶
data
data
libvcs.url.hg.PIP_DEFAULT_RULES: list[Rule] = <...truncated, 513 chars>
¶

pip-style hg URLs.

Examples of PIP-style hg URLs (via pip.pypa.io):

MyProject @ hg+http://hg.myproject.org/MyProject
MyProject @ hg+https://hg.myproject.org/MyProject
MyProject @ hg+ssh://hg.myproject.org/MyProject
MyProject @ hg+file:///home/user/projects/MyProject

Refs (via pip.pypa.io):

MyProject @ hg+http://hg.example.com/MyProject@da39a3ee5e6b
MyProject @ hg+http://hg.example.com/MyProject@2019
MyProject @ hg+http://hg.example.com/MyProject@v1.0
MyProject @ hg+http://hg.example.com/MyProject@special_feature

Notes

class libvcs.url.hg.HgBaseURL
¶
class[source]
class[source]
class libvcs.url.hg.HgBaseURL
¶

Bases: URLProtocol, SkipDefaultFieldsReprMixin

Mercurial repository location. Parses URLs on initialization.

Examples

>>> HgBaseURL(url='https://hg.mozilla.org/mozilla-central/')
HgBaseURL(url=https://hg.mozilla.org/mozilla-central/,
        scheme=https,
        hostname=hg.mozilla.org,
        path=mozilla-central/,
        rule=core-hg)

>>> myrepo = HgURL(url='https://hg.mozilla.org/mozilla-central/')

>>> myrepo.hostname
'hg.mozilla.org'

>>> myrepo.path
'mozilla-central/'

>>> HgBaseURL.is_valid(url='ssh://username@machinename/path/to/repo')
True

>>> HgBaseURL(url='ssh://username@machinename/path/to/repo')
HgBaseURL(url=ssh://username@machinename/path/to/repo,
        scheme=ssh,
        user=username,
        hostname=machinename,
        path=path/to/repo,
        rule=core-hg)
url: str
¶
attribute
attribute
url: str
¶
scheme: str | None = None
¶
attribute
attribute
scheme: str | None = None
¶
user: str | None = None
¶
attribute
attribute
user: str | None = None
¶
hostname: str = ''
¶
attribute
attribute
hostname: str = ''
¶
port: int | None = None
¶
attribute
attribute
port: int | None = None
¶
separator: str = '/'
¶
attribute
attribute
separator: str = '/'
¶
path: str = ''
¶
attribute
attribute
path: str = ''
¶
suffix: str | None = None
¶
attribute
attribute
suffix: str | None = None
¶
ref: str | None = None
¶
attribute
attribute
ref: str | None = None
¶
rule: str | None = None
¶
attribute
attribute
rule: str | None = None
¶
rule_map = <...truncated, 679 chars>
¶
attribute
attribute
rule_map = <...truncated, 679 chars>
¶
Parameters:

_rule_map (dict[str, Rule])

classmethod is_valid(url, is_explicit=None)
¶
classmethod method[source]
classmethod method[source]
classmethod is_valid(url, is_explicit=None)
¶

Whether URL is compatible with VCS or not.

Examples

>>> HgBaseURL.is_valid(
...     url='https://hg.mozilla.org/mozilla-central'
... )
True

>>> HgBaseURL.is_valid(url='ssh://[email protected]/cpython')
True

>>> HgBaseURL.is_valid(url='notaurl')
False
Parameters:
Return type:

bool

to_url()
¶
method[source]
method[source]
to_url()
¶

Return a hg(1)-compatible URL. Can be used with hg clone.

Examples

>>> hg_url = HgBaseURL(url='https://hg.mozilla.org/mozilla-central')

>>> hg_url
HgBaseURL(url=https://hg.mozilla.org/mozilla-central,
        scheme=https,
        hostname=hg.mozilla.org,
        path=mozilla-central,
        rule=core-hg)

Switch repo libvcs -> vcspull:

>>> hg_url.path = 'mobile-browser'

>>> hg_url.to_url()
'https://hg.mozilla.org/mobile-browser'

Switch them to localhost:

>>> hg_url.hostname = 'localhost'
>>> hg_url.scheme = 'http'

>>> hg_url.to_url()
'http://localhost/mobile-browser'

Another example, hugin:

>>> hugin = HgBaseURL(
...     url="http://hugin.hg.sourceforge.net:8000/hgroot/hugin/hugin")

>>> hugin
HgBaseURL(url=http://hugin.hg.sourceforge.net:8000/hgroot/hugin/hugin,
        scheme=http,
        hostname=hugin.hg.sourceforge.net,
        port=8000,
        path=hgroot/hugin/hugin,
        rule=core-hg)

>>> hugin.to_url()
'http://hugin.hg.sourceforge.net:8000/hgroot/hugin/hugin'

SSH URL with a username, graphicsmagic:

>>> graphicsmagick = HgBaseURL(
...     url="ssh://[email protected]//hg/GraphicsMagick"
... )

>>> graphicsmagick
HgBaseURL(url=ssh://[email protected]//hg/GraphicsMagick,
        scheme=ssh,
        user=yourid,
        hostname=hg.GraphicsMagick.org,
        path=/hg/GraphicsMagick,
        rule=core-hg)

>>> graphicsmagick.to_url()
'ssh://[email protected]//hg/GraphicsMagick'

Switch the username:

>>> graphicsmagick.user = 'lucas'

>>> graphicsmagick.to_url()
'ssh://[email protected]//hg/GraphicsMagick'
Return type:

str

__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None)
¶
method[source]
method[source]
__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None)
¶
Parameters:
Return type:

None

_abc_impl = <_abc._abc_data object>
¶
attribute
attribute
_abc_impl = <_abc._abc_data object>
¶
_is_protocol = False
¶
attribute
attribute
_is_protocol = False
¶
class libvcs.url.hg.HgPipURL
¶
class[source]
class[source]
class libvcs.url.hg.HgPipURL
¶

Bases: HgBaseURL, URLProtocol, SkipDefaultFieldsReprMixin

Supports pip hg URLs.

rev: str | None = None
¶
attribute
attribute
rev: str | None = None
¶
rule_map = <...truncated, 559 chars>
¶
attribute
attribute
rule_map = <...truncated, 559 chars>
¶
Parameters:

_rule_map (dict[str, Rule])

classmethod is_valid(url, is_explicit=None)
¶
classmethod method[source]
classmethod method[source]
classmethod is_valid(url, is_explicit=None)
¶

Whether URL is compatible with VCS or not.

Examples

>>> HgPipURL.is_valid(
...     url='hg+https://hg.mozilla.org/mozilla-central'
... )
True

>>> HgPipURL.is_valid(url='hg+ssh://[email protected]:cpython')
True

>>> HgPipURL.is_valid(url='notaurl')
False
Parameters:
Return type:

bool

to_url()
¶
method[source]
method[source]
to_url()
¶

Return a hg(1)-compatible URL. Can be used with hg clone.

Examples

>>> hg_url = HgPipURL(url='hg+https://hg.mozilla.org/mozilla-central')

>>> hg_url
HgPipURL(url=hg+https://hg.mozilla.org/mozilla-central,
        scheme=hg+https,
        hostname=hg.mozilla.org,
        path=mozilla-central,
        rule=pip-url)

Switch repo mozilla-central -> mobile-browser:

>>> hg_url.path = 'mobile-browser'

>>> hg_url.to_url()
'hg+https://hg.mozilla.org/mobile-browser'

Switch them to localhost:

>>> hg_url.hostname = 'localhost'
>>> hg_url.scheme = 'http'

>>> hg_url.to_url()
'http://localhost/mobile-browser'
Return type:

str

__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None, rev=None)
¶
method[source]
method[source]
__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None, rev=None)
¶
Parameters:
Return type:

None

_abc_impl = <_abc._abc_data object>
¶
attribute
attribute
_abc_impl = <_abc._abc_data object>
¶
_is_protocol = False
¶
attribute
attribute
_is_protocol = False
¶
class libvcs.url.hg.HgURL
¶
class[source]
class[source]
class libvcs.url.hg.HgURL
¶

Bases: HgPipURL, HgBaseURL, URLProtocol, SkipDefaultFieldsReprMixin

Batteries included URL Parser. Supports hg(1) and pip URLs.

Ancestors (MRO) This URL parser inherits methods and attributes from the following parsers:

rule_map = <...truncated, 1219 chars>
¶
attribute
attribute
rule_map = <...truncated, 1219 chars>
¶
Parameters:

_rule_map (dict[str, Rule])

__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None, rev=None)
¶
method[source]
method[source]
__init__(url, scheme=None, user=None, hostname='', port=None, separator='/', path='', suffix=None, ref=None, rule=None, rev=None)
¶
Parameters:
Return type:

None

_abc_impl = <_abc._abc_data object>
¶
attribute
attribute
_abc_impl = <_abc._abc_data object>
¶
_is_protocol = False
¶
attribute
attribute
_is_protocol = False
¶
classmethod is_valid(url, is_explicit=None)
¶
classmethod method[source]
classmethod method[source]
classmethod is_valid(url, is_explicit=None)
¶

Whether URL is compatible included Hg URL rule_map or not.

Examples

Will match normal hg(1) URLs, use HgURL.is_valid() for that.

>>> HgURL.is_valid(url='https://hg.mozilla.org/mozilla-central/mozilla-central')
True

>>> HgURL.is_valid(url='[email protected]:MyProject/project')
True

Pip-style URLs:

>>> HgURL.is_valid(url='hg+https://hg.mozilla.org/mozilla-central/project')
True

>>> HgURL.is_valid(url='hg+ssh://[email protected]:MyProject/project')
True

>>> HgURL.is_valid(url='notaurl')
False

Explicit VCS detection

Pip-style URLs are prefixed with the VCS name in front, so its rule_map can unambiguously narrow the type of VCS:

>>> HgURL.is_valid(
...     url='hg+ssh://[email protected]:mozilla-central/image', is_explicit=True
... )
True

Below, while it’s hg.mozilla.org, that doesn’t necessarily mean that the URL itself is conclusively a hg URL (e.g. the pattern is too broad):

>>> HgURL.is_valid(
...     url='[email protected]:mozilla-central/image', is_explicit=True
... )
False

You could create a Mozilla rule that consider hg.mozilla.org hostnames to be exclusively hg:

>>> MozillaRule = Rule(
...     # Since hg.mozilla.org exclusively serves hg repos, make explicit
...     label='mozilla-rule',
...     description='Matches hg.mozilla.org https URLs, exact VCS match',
...     pattern=re.compile(
...         rf'''
...         ^(?P<scheme>ssh)?
...         ((?P<user>\w+)@)?
...         (?P<hostname>(hg.mozilla.org)+):
...         (?P<path>(\w[^:]+))
...         {RE_SUFFIX}?
...         ''',
...         re.VERBOSE,
...     ),
...     is_explicit=True,
...     defaults={
...         'hostname': 'hg.mozilla.org'
...     }
... )

>>> HgURL.rule_map.register(MozillaRule)

>>> HgURL.is_valid(
...     url='[email protected]:mozilla-central/image', is_explicit=True
... )
True

>>> HgURL(url='[email protected]:mozilla-central/image').rule
'mozilla-rule'

This is just us cleaning up:

>>> HgURL.rule_map.unregister('mozilla-rule')

>>> HgURL(url='[email protected]:mozilla-central/mozilla-rule').rule
'core-hg-scp'
Parameters:
Return type:

bool

to_url()
¶
method[source]
method[source]
to_url()
¶

Return a hg(1)-compatible URL. Can be used with hg clone.

Examples

SSH style URL:

>>> hg_url = HgURL(url='[email protected]:mozilla-central/browser')

>>> hg_url.path = 'mozilla-central/gfx'

>>> hg_url.to_url()
'ssh://[email protected]:mozilla-central/gfx'

HTTPs URL:

>>> hg_url = HgURL(url='https://hg.mozilla.org/mozilla-central/memory')

>>> hg_url.path = 'mozilla-central/image'

>>> hg_url.to_url()
'https://hg.mozilla.org/mozilla-central/image'

Switch them to hglab:

>>> hg_url.hostname = 'localhost'
>>> hg_url.scheme = 'http'

>>> hg_url.to_url()
'http://localhost/mozilla-central/image'

Pip style URL, thanks to this class implementing HgPipURL:

>>> hg_url = HgURL(url='hg+ssh://[email protected]/mozilla-central/image')

>>> hg_url.hostname = 'localhost'

>>> hg_url.to_url()
'hg+ssh://hg@localhost/mozilla-central/image'

>>> hg_url.user = None

>>> hg_url.to_url()
'hg+ssh://localhost/mozilla-central/image'

See also

HgBaseURL.to_url(), HgPipURL.to_url()

Return type:

str