Parser: Support explicit matchers, touchups, critical bug fixes (#386)

- Git scp-style URLs: Fix detection detect of scp style URLs with `.git` prefixes
- Fix critical bug where `matchers` were being applied as variable not annotations
- Fix `pattern_defaults`
- Base tests: Rename `Location` to `URL`
- Tests and modules: Rename `_location` to `_url`

Author: tony

CHANGES

@@ -16,7 +16,8 @@ $ pip install --user --upgrade --pre libvcs
 ### What's new
 
 - New and improved logo
-- **Parser**: Experimental VCS URL parsing added ({issue}`376`, {issue}`381`, {issue}`384`):
+- **Parser**: Experimental VCS URL parsing added ({issue}`376`, {issue}`381`, {issue}`384`,
+  {issue}`386`):
 
   VCS Parsers return {func}`dataclasses.dataclass` instances. The new tools support validation,
   parsing, mutating and exporting into URLs consumable by the VCS.

libvcs/parse/base.py

@@ -1,5 +1,5 @@
 import dataclasses
-from typing import Iterator, Pattern, Protocol
+from typing import Iterator, Optional, Pattern, Protocol
 
 from libvcs._internal.dataclasses import SkipDefaultFieldsReprMixin
 
@@ -13,7 +13,7 @@ def __init__(self, url: str):
     def to_url(self) -> str:
         ...
 
-    def is_valid(self, url: str) -> bool:
+    def is_valid(self, url: str, is_explicit: Optional[bool] = None) -> bool:
         ...
 
 
@@ -28,6 +28,8 @@ class Matcher(SkipDefaultFieldsReprMixin):
     pattern: Pattern
     """Regex pattern"""
     pattern_defaults: dict = dataclasses.field(default_factory=dict)
+    """Is the match unambiguous with other VCS systems? e.g. git+ prefix"""
+    is_explicit: bool = False
 
 
 @dataclasses.dataclass(repr=False)
@@ -37,10 +39,11 @@ class MatcherRegistry(SkipDefaultFieldsReprMixin):
     _matchers: dict[str, Matcher] = dataclasses.field(default_factory=dict)
 
     def register(self, cls: Matcher) -> None:
-        """
+        r"""
 
         .. currentmodule:: libvcs.parse.git
 
+        >>> from dataclasses import dataclass
         >>> from libvcs.parse.git import GitURL, GitBaseURL
 
         :class:`GitBaseURL` - the ``git(1)`` compliant parser - won't accept a pip-style URL:
@@ -56,30 +59,69 @@ def register(self, cls: Matcher) -> None:
         But what if you wanted to do ``github:org/repo``?
 
         >>> GitURL.is_valid(url="github:org/repo")
-        False
+        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,
+           matcher=core-git-scp)
+
+        We need something more specific. What do we do?
 
         **Extending matching capability:**
 
         >>> class GitHubPrefix(Matcher):
         ...     label = 'gh-prefix'
         ...     description ='Matches prefixes like github:org/repo'
-        ...     pattern = r'^github:(?P<path>)'
+        ...     pattern = r'^github:(?P<path>.*)$'
         ...     pattern_defaults = {
         ...         'hostname': 'github.com',
         ...         'scheme': 'https'
         ...     }
+        ...     # We know it's git, not any other VCS
+        ...     is_explicit = True
 
-        >>> class GitHubLocation(GitURL):
-        ...    matchers = MatcherRegistry = MatcherRegistry(
+        >>> @dataclasses.dataclass(repr=False)
+        ... class GitHubURL(GitURL):
+        ...    matchers: MatcherRegistry = MatcherRegistry(
         ...        _matchers={'github_prefix': GitHubPrefix}
         ...    )
 
-        >>> GitHubLocation.is_valid(url='github:vcs-python/libvcs')
+        >>> GitHubURL.is_valid(url='github:vcs-python/libvcs')
+        True
+
+        >>> GitHubURL.is_valid(url='github:vcs-python/libvcs', is_explicit=True)
         True
 
-        >>> GitHubLocation.is_valid(url='gitlab:vcs-python/libvcs')
+        Notice how ``pattern_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,
+            matcher=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 matcher,
+        `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').matcher
+        'core-git-scp'
+
         >>> class GitLabPrefix(Matcher):
         ...     label = 'gl-prefix'
         ...     description ='Matches prefixes like gitlab:org/repo'
@@ -92,25 +134,33 @@ def register(self, cls: Matcher) -> None:
 
         Option 1: Create a brand new matcher
 
-        >>> class GitLabLocation(GitURL):
-        ...    matchers = MatcherRegistry = MatcherRegistry(
-        ...        _matchers={'gitlab_prefix': GitLabPrefix}
-        ...    )
+        >>> @dataclasses.dataclass(repr=False)
+        ... class GitLabURL(GitURL):
+        ...     matchers: MatcherRegistry = MatcherRegistry(
+        ...         _matchers={'gitlab_prefix': GitLabPrefix}
+        ...     )
 
-        >>> GitLabLocation.is_valid(url='gitlab:vcs-python/libvcs')
+        >>> GitLabURL.is_valid(url='gitlab:vcs-python/libvcs')
         True
 
         Option 2 (global, everywhere): Add to the global :class:`GitURL`:
 
         >>> GitURL.is_valid(url='gitlab:vcs-python/libvcs')
-        False
+        True
+
+        Are we home free, though? Remember our issue with vague matches.
+
+        >>> GitURL(url='gitlab:vcs-python/libvcs').matcher
+        'core-git-scp'
+
+        Register:
 
         >>> GitURL.matchers.register(GitLabPrefix)
 
         >>> GitURL.is_valid(url='gitlab:vcs-python/libvcs')
         True
 
-        git URLs + pip-style git URLs:
+        **Example: git URLs + pip-style git URLs:**
 
         This is already in :class:`GitURL` via :data:`PIP_DEFAULT_MATCHERS`. For the
         sake of showing how extensibility works, here is a recreation based on
@@ -120,8 +170,9 @@ def register(self, cls: Matcher) -> None:
 
         >>> from libvcs.parse.git import DEFAULT_MATCHERS, PIP_DEFAULT_MATCHERS
 
-        >>> class GitURLWithPip(GitBaseURL):
-        ...    matchers = MatcherRegistry = MatcherRegistry(
+        >>> @dataclasses.dataclass(repr=False)
+        ... class GitURLWithPip(GitBaseURL):
+        ...    matchers: MatcherRegistry = MatcherRegistry(
         ...        _matchers={m.label: m for m in [*DEFAULT_MATCHERS, *PIP_DEFAULT_MATCHERS]}
         ...    )