Refactor Repo and introduce branch detection (#167)

tomschr · sushant-suse · web-flow · commit 55d9c9d2aed1 · 2026-02-13T13:56:54.000+01:00
* Refactor Repo and introduce branch detection

* Rework former regular expressions for HTTPS, SSH, abbreviated and plain
  notations into a single regex
* Introduce three new attributes to `Repo`:
  * `branch`: The branch of the repository. For example in `gh://org/repo@branch`
    Similar to other notations.
  * `origin`: The original unchainged URL of the repository.
  * `treeurl`: The full URL including the branch of the repository.
    This was necessary as the URLs differ from each Git service.
* Introduce `_TREE_PATTERN` as a template for constructing tree-based URLs
  based on service.
* Extended `__init__` to allow `default_branch` argument (default is `None`)
  For URLs like `https://HOST/ORG/REPO.git` there is no branch to operate
  on.
* Refactor the distinction logic between URLs from HTTPS, SSH, abbreviated,
  or plain. Use a `match`...`case` block.
* Fix wrong notation of repo URL in `tests/utils/test_git.py`


---------

Co-authored-by: Sushant Gaurav &lt;sushant.gaurav@suse.com&gt;
diff --git a/changelog.d/167.refactor.rst b/changelog.d/167.refactor.rst
@@ -0,0 +1,8 @@
+Refactor how Git repository URLs are parsed and handled.
+Previously, multiple regular expressions were used to identify different
+URL formats (like HTTPS, SSH, plain, and abbreviated notations).
+These have now been consolidated into a single, more robust regular expression.
+
+Additionally, the :class:`~docbuild.model.repo.Repo` class was
+enhanced with new attributes (:attr:`Repo.branch`, :attr:`Repo.origin`,
+:attr:`Repo.treeurl`) to better manage repository details.
diff --git a/src/docbuild/models/repo.py b/src/docbuild/models/repo.py
@@ -3,7 +3,6 @@
 from dataclasses import dataclass, field
 import re
 from typing import ClassVar
-from urllib.parse import urlparse
 
 
 @dataclass(frozen=True, init=False)
@@ -21,104 +20,196 @@ class Repo:
     """The default host to use when constructing a URL from a short name."""
 
     _MAP_SERVICE2URL: ClassVar[dict[str, str]] = {
-        "gl": "https://gitlab.com",
-        "gls": "https://gitlab.suse.de",
-        "gh": "https://github.com",
         "bb": "https://bitbucket.org",
-        "gt": "https://gitea.com",
         "cb": "https://codeberg.org",
+        "gh": "https://github.com",
         "ghe": "https://github.enterprise.com",
+        "git@": "https://github.com",
+        "gl": "https://gitlab.com",
+        "gls": "https://gitlab.suse.de",
+        "gt": "https://gitea.com",
     }
+
     _MAP_URL2SERVICE: ClassVar[dict[str, str]] = {
-        v: k for k, v in _MAP_SERVICE2URL.items()
+        v: k for k, v in _MAP_SERVICE2URL.items() if k != "git@"
     }
 
-    _SSH_PATTERN: ClassVar[re.Pattern] = re.compile(
-        r"^(?P<user>[^@]+)@(?P<host>[^:]+):(?P<repo>.+?)(?:\.git)?$"
+    _SERVICES: ClassVar[str] = "|".join(
+        [k for k in _MAP_SERVICE2URL.keys() if k != "git@"]
     )
 
-    _SERVICE_PATTERN: ClassVar[re.Pattern] = re.compile(
-        r"^(?P<abbr>[a-z]{2,4}):/{1,2}(?P<repo>.+?)(?:\.git)?$", re.IGNORECASE
+    _REPOS_PATTERN: ClassVar[re.Pattern] = re.compile(
+        rf"""^                                 # Start of string
+        (?:                               # Start of URL formats group
+            # Option 1: HTTPS (Supports .git OR /tree/branch)
+            (?:
+                # Capture the repo name *without* the optional trailing
+                # ".git" so that the canonical URL does not end up with
+                # a duplicated suffix like "repo.git.git".
+                (?P<https_schema>https?)://(?P<https_host>[^/]+)/(?P<https_org>[^/]+)/(?P<https_repo>[^/@\s?#]+?)
+                (?:\.git
+                   |
+                   /tree/(?P<tree_branch>[^/\s?#]+)
+                )?/?
+            )
+            |
+            # Option 2: SSH
+            (?:
+                (?P<ssh_schema>git@)
+                (?P<ssh_host>[^:]+):(?P<ssh_org>[^/]+)/(?P<ssh_repo>[^/@\s?]+?)(?:\.git)?/?
+            )
+            |
+            # Option 3: Abbreviated protocol-style URL (e.g., gh://, gl://) + optional @branch
+            (?:
+                (?:(?P<gh_schema>{_SERVICES})://)?
+                (?P<gh_org>[^/]+)/(?P<gh_repo>[^/@\s?]+?)(?:/|\.git)?
+            )
+        )                                 # End of URL formats group
+        (?:@(?P<branch>[^@\s]+))?         # Consolidated optional @branch suffix
+        $                                 # End of string
+        """,
+        re.VERBOSE | re.IGNORECASE,
     )
+    """The regex to match for the different URL notations."""
+
+    _TREE_PATTERN: ClassVar[dict[str, str]] = {
+        "bb": "https://bitbucket.com/{owner}/{repo}/",
+        "cb": "https://codeberg.org/{owner}/{repo}/src/branch/{branch}",
+        "gh": "https://github.com/{owner}/{repo}/tree/{branch}",
+        "ghe": "https://github.enterprise.com/{owner}/{repo}/tree/{branch}",
+        "git@": "https://github.com/{owner}/{repo}/tree/{branch}",
+        "gl": "https://gitlab.com/{owner}/{repo}/-/tree/{branch}",
+        "gls": "https://gitlab.suse.de/{owner}/{repo}/-/tree/{branch}",
+        "gt": "https://gitea.com/{owner}/{repo}/src/branch/{branch}",
+    }
+    """URL template for constructing tree URLs based on the service."""
 
-    _SCHEMA_PATTERN: ClassVar[re.Pattern] = re.compile(r"(?P<schema>https?)://")
+    _default_branches = ("main", "master")
 
     url: str = field(repr=False)
     """The full URL of the repository."""
 
+    treeurl: str = field(init=False, repr=False)
+    """The full URL including the branch of the repository."""
+
     surl: str
     """The shortened URL version of the repository, for example gh://org/repo for
         a GitHub repo."""
 
     name: str = field(init=False, repr=False)
     """The abbreviated name of the repository (e.g., 'org/repo')."""
 
-    def __init__(self, value: str) -> None:
+    branch: str | None = field(init=False, repr=False)
+    """The branch of the repository"""
+
+    origin: str = field(init=False, repr=False)
+    """The original unchanged URL of the repository."""
+
+    def __init__(self, value: str, default_branch: str | None = None) -> None:
         """Initialize a repository model from a URL or a short name.
 
+        :param default_branch: The default branch to use if no branch is specified in the URL.
+
         This initializer understands:
 
-        * A full URL like ``https://host/org/repo.git``.
-        * A SSH URL like ``git@host:org/repo.git``.
-        * An abbreviated URL like ``gh://org/repo`` for a GitHub URL.
+        * A full URL like ``https://HOST/ORG/REPO.git`` or a URL pointing
+            to a branch like ``https://HOST/ORG/REPO/tree/BRANCH``
+
+        * A SSH URL like ``git@HOST:ORG/REPO.git``.
+
+        * An abbreviated URL like ``SERVICE://ORG/REPO`` or ``SERVICE://ORG/REPO.git``
           The service part (before '://') is a two to four letter code:
-          - ``gh`` for GitHub
-          - ``gl`` for GitLab
-          - ``bb`` for BitBucket
-          - ``gt`` for Gitea
-          - ``cb`` for Codeberg
-          - ``ghe`` for GitHub Enterprise
-        * An abbreviated name like ``org/repo`` which defaults to GitHub.
+            - ``gh`` for GitHub (default)
+            - ``gl`` for GitLab
+            - ``bb`` for BitBucket
+            - ``gt`` for Gitea
+            - ``cb`` for Codeberg
+            - ``ghe`` for GitHub Enterprise
+          This makes the reference to a Git repo more readable.
+
+        * A plain notation like ``ORG/REPO`` which defaults to GitHub.
+
+        Branches other than default branches (main or master) are added
+        by ``@BRANCH_NAME`` to the URL.
         """
         if not value:
             raise ValueError("Repository value cannot be empty.")
 
-        url: str
-        name: str
-
-        service_match = self._SERVICE_PATTERN.match(value)
-        ssh_match = self._SSH_PATTERN.match(value)
-
-        if "https://" in value or "http://" in value:
-            parsed_original = urlparse(value.lower())
-            name = parsed_original.path.strip("/").rsplit(".git", 1)[0]
-            url = f"{parsed_original.scheme}://{parsed_original.netloc}/{name}.git"
-            host = f"{parsed_original.scheme}://{parsed_original.netloc}"
-            surl = f"{self._MAP_URL2SERVICE.get(host, 'gh')}://{name}"
-
-        elif service_match:
-            service = service_match.group("abbr").lower()
-            name = service_match.group("repo").lower().rstrip("/")
-            host = self._MAP_SERVICE2URL.get(service)
-            if not host:
-                raise ValueError(f"Unknown repo abbreviation: '{service}'")
-            url = f"{host}/{name}.git"
-            surl = f"{service}://{name}"
-
-        elif ssh_match:
-            host = ssh_match["host"].lower()
-            name = ssh_match["repo"].lower()
-            name = name.rstrip("/")
-            url = f"https://{host}/{name}.git"
-            surl = f"{self._MAP_URL2SERVICE.get(host, 'gh')}://{name}"
-
-        elif "/" in value:
-            value = value.lower()
-            name = value.rsplit(".git", 1)[0].rstrip("/")
-            url = f"{self.DEFAULT_HOST}/{name}.git"
-            surl = f"gh://{name}"
-
-        else:
+        # Store the original string
+        object.__setattr__(self, "origin", value)
+
+        data = self._consolidate_match(value.lower())
+
+        # Consolidate data from regex match
+        name = f"{data['org']}/{data['repo']}"
+        branch = data.get("branch")
+        host = data.get("host")
+        schema = data.get("schema")
+
+        match schema:
+            case "http" | "https":
+                # For https, a host from regex does not include the schema
+                service = self._MAP_URL2SERVICE.get(f"{schema}://{host}", "gh")
+                url = f"{schema}://{host}/{name}.git"
+            case "git@":
+                # For ssh, map to service and get canonical URL
+                service = self._MAP_URL2SERVICE.get(f"https://{host}", "gh")
+                host = self._MAP_SERVICE2URL.get(service, self.DEFAULT_HOST)
+                url = f"{host}/{name}.git"
+            case _:
+                # For abbreviations (gh://) or bare (org/repo)
+                service = schema or "gh"
+                host = self._MAP_SERVICE2URL.get(service, self.DEFAULT_HOST)
+                url = f"{host}/{name}.git"
+
+        # Build URLs
+        surl = f"{service}://{name}"
+        if branch:
+            surl += f"@{branch}"
+
+        # Create the effecive branch for tree URL: prioritize found branch (either
+        # from /tree/ or @branch), then the given default branch, then defined defaults.
+        effective_branch = branch or default_branch or self._default_branches[0]
+        treeurl_template = self._TREE_PATTERN.get(service, self._TREE_PATTERN["gh"])
+        treeurl = treeurl_template.format(
+            owner=data["org"], repo=data["repo"], branch=effective_branch
+        )
+
+        # Use object.__setattr__ because the dataclass is frozen
+        object.__setattr__(self, "url", url)
+        object.__setattr__(self, "treeurl", treeurl)
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "surl", surl)
+        object.__setattr__(self, "branch", branch)
+
+    def _consolidate_match(self, value: str) -> dict:
+        """Consolidate keys for a cleaner API."""
+        match = self._REPOS_PATTERN.match(value)
+        if not match:
             raise ValueError(
                 f"Invalid repository value: '{value}'. "
                 "Expected a full HTTPS URL, SSH URL, abbr notation, "
                 "or an abbreviated name."
             )
+        raw_data = match.groupdict()
+        result = {
+            "schema": raw_data.get("https_schema")
+            or raw_data.get("ssh_schema")
+            or raw_data.get("gh_schema"),
+            "host": raw_data.get("https_host") or raw_data.get("ssh_host"),
+            "org": raw_data.get("https_org")
+            or raw_data.get("ssh_org")
+            or raw_data.get("gh_org"),
+            "repo": raw_data.get("https_repo")
+            or raw_data.get("ssh_repo")
+            or raw_data.get("gh_repo"),
+        }
 
-        # Use object.__setattr__ because the dataclass is frozen
-        object.__setattr__(self, "url", url)
-        object.__setattr__(self, "name", name)
-        object.__setattr__(self, "surl", surl)
+        # Branch Logic: Prioritize the /tree/ branch, fallback to @branch
+        branch = raw_data.get("tree_branch") or raw_data.get("branch")
+        result["branch"] = branch
+
+        return result
 
     def __eq__(self, other: object) -> bool:
         """Compare Repo with another Repo (by name) or a string (by name)."""
@@ -148,3 +239,24 @@ def slug(self) -> str:
         return self.url.translate(
             str.maketrans({":": "_", "/": "_", "-": "_", ".": "_"}),
         )
+
+
+if __name__ == "__main__":
+    test_urls = [
+        "https://github.com/lycheeverse/lychee/tree/relative-link-fixes",  # New #variant
+        "https://GitHub.com/opensuse/docbuild.git",  # HTTPS no branch
+        "git@github.com:openSUSE/docbuild.git",  # SSH no branch
+        "gh://openSUSE/docbuild",  # Abbr no branch
+        "gh://openSUSE/docbuild@v1",
+    ]
+
+    for url in test_urls:
+        repo = Repo(url)
+        print(f"┌ {url}")
+        print(f"├─ {repo.treeurl=}")
+        print(f"├─ {repo.surl=}")
+        print(f"├─ {repo.name=}")
+        print(f"├─ {repo.branch=}")
+        print(f"└─ {repo.url=}")
+        # print("└")
+        print()
diff --git a/tests/models/test_repo.py b/tests/models/test_repo.py
@@ -38,6 +38,8 @@ def repo_url(request) -> str:
             "org/repo_git",
             "https://github.com/org/repo_git.git",
         ),
+        # 7
+        ("http://a.b/org/c.git", "org/c", "http://a.b/org/c.git"),
     ],
 )
 def test_repo_https(input_value, name, url):
@@ -153,6 +155,45 @@ def test_repo_abbreviated(input_value, name, url):
     assert repo.url == url
 
 
+@pytest.mark.parametrize(
+    "input_value, name, branch, expected_surl, expected_tree",
+    [
+        # 1
+        (
+            "org/repo@main",
+            "org/repo",
+            "main",
+            "gh://org/repo@main",
+            "https://github.com/org/repo/tree/main",
+        ),
+        # 2
+        (
+            "ORG/repo@develop",
+            "org/repo",
+            "develop",
+            "gh://org/repo@develop",
+            "https://github.com/org/repo/tree/develop",
+        ),
+        # 3
+        (
+            "org/repo_git.git@v1.2.4",
+            "org/repo_git",
+            "v1.2.4",
+            "gh://org/repo_git@v1.2.4",
+            "https://github.com/org/repo_git/tree/v1.2.4",
+        ),
+        # 4
+    ],
+)
+def test_repo_with_branch(input_value, name, branch, expected_surl, expected_tree):
+    repo = Repo(input_value)
+    assert repo.name == name
+    assert repo.branch == branch
+    assert repo.surl == expected_surl
+    assert repo.treeurl == expected_tree
+    assert repo.origin == input_value
+
+
 def test_repo_with_empty_value():
     with pytest.raises(ValueError):
         Repo("")
diff --git a/tests/utils/test_git.py b/tests/utils/test_git.py
