refactor: convert wildcard re-exports to explicit imports for griffe compatibility

Convert all wildcard imports in public API re-export modules to explicit
'from X import Y as Y' style imports. This allows static analysis tools
like griffe to properly detect re-exported symbols and verify API stability.

Changes:
- Convert wildcard imports to explicit re-exports in:
  * src/setuptools_scm/version.py (26 symbols)
  * src/setuptools_scm/git.py (14 symbols)
  * src/setuptools_scm/hg.py (6 symbols)
  * src/setuptools_scm/discover.py (4 symbols)
  * src/setuptools_scm/fallbacks.py (3 symbols)
  * src/setuptools_scm/integration.py (2 symbols)

- Add missing re-export modules:
  * src/setuptools_scm/scm_workdir.py (Workdir, get_latest_file_mtime, log)
  * src/setuptools_scm/hg_git.py (GitWorkdirHgClient, log)

- Add griffe-public-wildcard-imports extension to:
  * pyproject.toml (test and docs dependency groups)
  * mkdocs.yml (mkdocstrings configuration)

- Create check_api.py script:
  * Local script to run griffe API checks with proper configuration
  * Includes vcs-versioning source path for resolving re-exports
  * Enables griffe-public-wildcard-imports extension

- Update .github/workflows/api-check.yml to use check_api.py

- Fix test import: use vcs_versioning._version_schemes.mismatches directly

All re-exports maintain 100% backward compatibility. The griffe API check
now passes cleanly (exit code 0).

Author: RonnyPfannschmidt

.github/workflows/api-check.yml

@@ -45,4 +45,5 @@ jobs:
       - name: Check API stability against latest release
         run: |
           echo "Comparing current code against tag: ${{ steps.latest-tag.outputs.tag }}"
-          uv run griffe check setuptools_scm -ssrc --verbose --against ${{ steps.latest-tag.outputs.tag }}
+          # Use local check_api.py script which includes griffe-public-wildcard-imports extension
+          uv run python check_api.py --against ${{ steps.latest-tag.outputs.tag }}

check_api.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+Local script to check API stability using griffe.
+
+Usage:
+    uv run check_api.py [--against TAG]
+
+This script runs griffe with the public-wildcard-imports extension enabled
+to properly detect re-exported symbols from vcs-versioning.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from pathlib import Path
+
+
+def main() -> int:
+    """Run griffe API check with proper configuration."""
+    # Parse arguments
+    against = "v9.2.1"  # Default baseline
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--against" and len(sys.argv) > 2:
+            against = sys.argv[2]
+        else:
+            against = sys.argv[1]
+
+    # Ensure we're in the right directory
+    repo_root = Path(__file__).parent
+
+    # Build griffe command
+    cmd = [
+        "griffe",
+        "check",
+        "setuptools_scm",
+        "-ssrc",
+        "-snextgen/vcs-versioning/src",
+        "--verbose",
+        "--extensions",
+        "griffe_public_wildcard_imports",
+        "--against",
+        against,
+    ]
+
+    result = subprocess.run(cmd, cwd=repo_root)
+
+    return result.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mkdocs.yml

@@ -31,10 +31,13 @@ plugins:
     default_handler: python
     handlers:
       python:
-        paths: [ src ]
-
+        paths: [ src, nextgen/vcs-versioning/src ]
+        import:
+          - https://docs.python.org/3/objects.inv
         options:
           separate_signature: true
           show_signature_annotations: true
           allow_inspection: true
           show_root_heading: true
+          extensions:
+            - griffe_public_wildcard_imports

pyproject.toml

@@ -65,6 +65,7 @@ docs = [
   "mkdocs-material",
   "mkdocstrings[python]",
   "pygments",
+  "griffe-public-wildcard-imports",
 ]
 test = [
   "pip",
@@ -78,6 +79,7 @@ test = [
   'typing-extensions; python_version < "3.11"',
   "wheel",
   "griffe",
+  "griffe-public-wildcard-imports",
   "flake8",
 ]
 

src/setuptools_scm/discover.py

@@ -1,12 +1,18 @@
-# ruff: noqa: F405
 """Re-export discover from vcs_versioning for backward compatibility"""
 
 from __future__ import annotations
 
-from vcs_versioning._discover import *  # noqa: F403
+from vcs_versioning._discover import (
+    iter_matching_entrypoints as iter_matching_entrypoints,
+)
+from vcs_versioning._discover import log as log
+from vcs_versioning._discover import match_entrypoint as match_entrypoint
+from vcs_versioning._discover import walk_potential_roots as walk_potential_roots
 
 __all__ = [
+    # Functions
     "iter_matching_entrypoints",
+    "log",
     "match_entrypoint",
     "walk_potential_roots",
 ]

src/setuptools_scm/fallbacks.py

@@ -1,11 +1,14 @@
-# ruff: noqa: F405
 """Re-export fallbacks from vcs_versioning for backward compatibility"""
 
 from __future__ import annotations
 
-from vcs_versioning._fallbacks import *  # noqa: F403
+from vcs_versioning._fallbacks import fallback_version as fallback_version
+from vcs_versioning._fallbacks import log as log
+from vcs_versioning._fallbacks import parse_pkginfo as parse_pkginfo
 
 __all__ = [
+    # Functions
     "fallback_version",
+    "log",
     "parse_pkginfo",
 ]

src/setuptools_scm/git.py

@@ -1,4 +1,3 @@
-# ruff: noqa: F405
 """Re-export git backend from vcs_versioning for backward compatibility
 
 NOTE: The git backend is private in vcs_versioning and accessed via entry points.
@@ -7,11 +6,43 @@
 
 from __future__ import annotations
 
-from vcs_versioning._backends._git import *  # noqa: F403
+from vcs_versioning._backends._git import DEFAULT_DESCRIBE as DEFAULT_DESCRIBE
+from vcs_versioning._backends._git import DESCRIBE_UNSUPPORTED as DESCRIBE_UNSUPPORTED
+from vcs_versioning._backends._git import REF_TAG_RE as REF_TAG_RE
+from vcs_versioning._backends._git import GitPreParse as GitPreParse
+from vcs_versioning._backends._git import GitWorkdir as GitWorkdir
+from vcs_versioning._backends._git import archival_to_version as archival_to_version
+from vcs_versioning._backends._git import (
+    fail_on_missing_submodules as fail_on_missing_submodules,
+)
+from vcs_versioning._backends._git import fail_on_shallow as fail_on_shallow
+from vcs_versioning._backends._git import fetch_on_shallow as fetch_on_shallow
+from vcs_versioning._backends._git import get_working_directory as get_working_directory
+from vcs_versioning._backends._git import log as log
+from vcs_versioning._backends._git import parse as parse
+from vcs_versioning._backends._git import parse_archival as parse_archival
+from vcs_versioning._backends._git import run_git as run_git
+from vcs_versioning._backends._git import version_from_describe as version_from_describe
+from vcs_versioning._backends._git import warn_on_shallow as warn_on_shallow
 
 __all__ = [
+    # Constants
+    "DEFAULT_DESCRIBE",
+    "DESCRIBE_UNSUPPORTED",
+    "REF_TAG_RE",
+    # Classes
     "GitPreParse",
     "GitWorkdir",
+    # Functions
+    "archival_to_version",
+    "fail_on_missing_submodules",
+    "fail_on_shallow",
+    "fetch_on_shallow",
+    "get_working_directory",
+    "log",
     "parse",
     "parse_archival",
+    "run_git",
+    "version_from_describe",
+    "warn_on_shallow",
 ]

src/setuptools_scm/hg.py

@@ -1,4 +1,3 @@
-# ruff: noqa: F405
 """Re-export hg backend from vcs_versioning for backward compatibility
 
 NOTE: The hg backend is private in vcs_versioning and accessed via entry points.
@@ -7,10 +6,20 @@
 
 from __future__ import annotations
 
-from vcs_versioning._backends._hg import *  # noqa: F403
+from vcs_versioning._backends._hg import HgWorkdir as HgWorkdir
+from vcs_versioning._backends._hg import archival_to_version as archival_to_version
+from vcs_versioning._backends._hg import log as log
+from vcs_versioning._backends._hg import parse as parse
+from vcs_versioning._backends._hg import parse_archival as parse_archival
+from vcs_versioning._backends._hg import run_hg as run_hg
 
 __all__ = [
+    # Classes
     "HgWorkdir",
+    # Functions
+    "archival_to_version",
+    "log",
     "parse",
     "parse_archival",
+    "run_hg",
 ]

src/setuptools_scm/hg_git.py

@@ -0,0 +1,16 @@
+"""Re-export hg_git from vcs_versioning for backward compatibility
+
+NOTE: The hg_git module is private in vcs_versioning.
+This module provides backward compatibility for code that imported from setuptools_scm.hg_git
+"""
+
+from __future__ import annotations
+
+from vcs_versioning._backends._hg_git import GitWorkdirHgClient as GitWorkdirHgClient
+from vcs_versioning._backends._hg_git import log as log
+
+__all__ = [
+    # Classes
+    "GitWorkdirHgClient",
+    "log",
+]

src/setuptools_scm/integration.py

@@ -1,10 +1,12 @@
-# ruff: noqa: F405
 """Re-export integration from vcs_versioning for backward compatibility"""
 
 from __future__ import annotations
 
-from vcs_versioning._integration import *  # noqa: F403
+from vcs_versioning._integration import data_from_mime as data_from_mime
+from vcs_versioning._integration import log as log
 
 __all__ = [
+    # Functions
     "data_from_mime",
+    "log",
 ]