refactor(parser,git): Split BaseGitURL from compatibility focused one

Author: tony

libvcs/parse/base.py

@@ -38,11 +38,28 @@ class MatcherRegistry(SkipDefaultFieldsReprMixin):
 
     def register(self, cls: Matcher) -> None:
         """
-        >>> from libvcs.parse.git import GitURL
+
+        .. currentmodule:: libvcs.parse.git
+
+        >>> from libvcs.parse.git import GitURL, GitBaseURL
+
+        :class:`GitBaseURL` - the ``git(1)`` compliant parser - won't accept a pip-style URL:
+
+        >>> GitBaseURL.is_valid(url="git+ssh://git@github.com/tony/AlgoXY.git")
+        False
+
+        :class:`GitURL` - the "batteries-included" parser - can do it:
 
         >>> GitURL.is_valid(url="git+ssh://git@github.com/tony/AlgoXY.git")
+        True
+
+        But what if you wanted to do ``github:org/repo``?
+
+        >>> GitURL.is_valid(url="github:org/repo")
         False
 
+        **Extending matching capability:**
+
         >>> class GitHubPrefix(Matcher):
         ...     label = 'gh-prefix'
         ...     description ='Matches prefixes like github:org/repo'
@@ -95,9 +112,15 @@ def register(self, cls: Matcher) -> None:
 
         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
+        :class:`GitBaseURL`:
+
+        >>> from libvcs.parse.git import GitBaseURL
+
         >>> from libvcs.parse.git import DEFAULT_MATCHERS, PIP_DEFAULT_MATCHERS
 
-        >>> class GitURLWithPip(GitURL):
+        >>> class GitURLWithPip(GitBaseURL):
         ...    matchers = MatcherRegistry = MatcherRegistry(
         ...        _matchers={m.label: m for m in [*DEFAULT_MATCHERS, *PIP_DEFAULT_MATCHERS]}
         ...    )

libvcs/parse/git.py

@@ -1,11 +1,17 @@
 """This module is an all-in-one parser and validator for Git URLs.
 
 - Detection: :meth:`GitURL.is_valid()`
-- Parse: :class:`GitURL`
+- Parse:
 
   compare to :class:`urllib.parse.ParseResult`
 
-  - Output ``git(1)`` URL: :meth:`GitURL.to_url()`
+  - Compatibility focused: :class:`GitURL`: Will work with ``git(1)`` as well as
+    ``pip(1)`` style URLs
+
+    - Output ``git(1)`` URL: :meth:`GitURL.to_url()`
+  - Strict ``git(1)`` compatibility: :class:`GitBaseURL`.
+
+    - Output ``git(1)`` URL: :meth:`GitBaseURL.to_url()`
 - Extendable via :class:`~libvcs.parse.base.MatcherRegistry`,
   :class:`~libvcs.parse.base.Matcher`
 """
@@ -200,7 +206,7 @@
 
 
 @dataclasses.dataclass(repr=False)
-class GitURL(URLProtocol, SkipDefaultFieldsReprMixin):
+class GitBaseURL(URLProtocol, SkipDefaultFieldsReprMixin):
     """Git gepository location. Parses URLs on initialization.
 
     Examples
@@ -333,3 +339,12 @@ def to_url(self) -> str:
             parts.append(self.suffix)
 
         return "".join(part for part in parts if isinstance(part, str))
+
+
+@dataclasses.dataclass(repr=False)
+class GitURL(GitBaseURL, URLProtocol, SkipDefaultFieldsReprMixin):
+    """Batteries included URL Parser. Supports git(1) and pip URLs."""
+
+    matchers = MatcherRegistry = MatcherRegistry(
+        _matchers={m.label: m for m in [*DEFAULT_MATCHERS, *PIP_DEFAULT_MATCHERS]}
+    )

tests/parse/test_git.py

@@ -3,7 +3,7 @@
 import pytest
 
 from libvcs.parse.base import MatcherRegistry
-from libvcs.parse.git import DEFAULT_MATCHERS, PIP_DEFAULT_MATCHERS, GitURL
+from libvcs.parse.git import DEFAULT_MATCHERS, PIP_DEFAULT_MATCHERS, GitBaseURL, GitURL
 from libvcs.projects.git import GitProject
 
 
@@ -141,7 +141,7 @@ def test_git_url_extension_pip(
     git_url_kwargs: GitURLKwargs,
     git_repo: GitProject,
 ):
-    class GitURLWithPip(GitURL):
+    class GitURLWithPip(GitBaseURL):
         matchers = MatcherRegistry = MatcherRegistry(
             _matchers={m.label: m for m in [*DEFAULT_MATCHERS, *PIP_DEFAULT_MATCHERS]}
         )
@@ -152,7 +152,7 @@ class GitURLWithPip(GitURL):
     git_url.url = git_url.url.format(local_repo=git_repo.dir)
 
     assert (
-        GitURL.is_valid(url) != is_valid
+        GitBaseURL.is_valid(url) != is_valid
     ), f"{url} compatibility should work with core, expects {not is_valid}"
     assert (
         GitURLWithPip.is_valid(url) == is_valid