chore: Implement PEP 563 deferred annotation resolution (#34)

- Add `from __future__ import annotations` to defer annotation resolution and reduce unnecessary symbol computations during type checking
- Enable Ruff checks for PEP-compliant annotations:
  - [non-pep585-annotation (UP006)](https://docs.astral.sh/ruff/rules/non-pep585-annotation/)
  - [non-pep604-annotation (UP007)](https://docs.astral.sh/ruff/rules/non-pep604-annotation/)

For more details on PEP 563, see: https://peps.python.org/pep-0563/

Author: tony

CHANGES

@@ -21,6 +21,17 @@ $ pipx install --suffix=@next g --pip-args '\--pre' --force
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### Development
+
+#### chore: Implement PEP 563 deferred annotation resolution (#34)
+
+- Add `from __future__ import annotations` to defer annotation resolution and reduce unnecessary symbol computations during type checking
+- Enable Ruff checks for PEP-compliant annotations:
+  - [non-pep585-annotation (UP006)](https://docs.astral.sh/ruff/rules/non-pep585-annotation/)
+  - [non-pep604-annotation (UP007)](https://docs.astral.sh/ruff/rules/non-pep604-annotation/)
+
+For more details on PEP 563, see: https://peps.python.org/pep-0563/
+
 ## g 0.0.7 (2024-12-20)
 
 _Maintenance only, no bug fixes, or new features_

conftest.py

@@ -1,5 +1,7 @@
 """Setup pytest for g."""
 
+from __future__ import annotations
+
 import pytest
 
 

docs/conf.py

@@ -1,6 +1,8 @@
 # flake8: noqa: E501
 """Sphinx configuration for g."""
 
+from __future__ import annotations
+
 import contextlib
 import inspect
 import pathlib
@@ -71,7 +73,7 @@
 html_extra_path = ["manifest.json"]
 html_theme = "furo"
 html_theme_path: list[str] = []
-html_theme_options: dict[str, t.Union[str, list[dict[str, str]]]] = {
+html_theme_options: dict[str, str | list[dict[str, str]]] = {
     "light_logo": "img/g.svg",
     "dark_logo": "img/g-dark.svg",
     "footer_icons": [
@@ -129,7 +131,7 @@
 }
 
 
-def linkcode_resolve(domain: str, info: dict[str, str]) -> t.Union[None, str]:
+def linkcode_resolve(domain: str, info: dict[str, str]) -> None | str:
     """
     Determine the URL corresponding to Python object.
 
@@ -199,7 +201,7 @@ def linkcode_resolve(domain: str, info: dict[str, str]) -> t.Union[None, str]:
     )
 
 
-def remove_tabs_js(app: "Sphinx", exc: Exception) -> None:
+def remove_tabs_js(app: Sphinx, exc: Exception) -> None:
     """Remove tabs.js from _static after build."""
     # Fix for sphinx-inline-tabs#18
     if app.builder.format == "html" and not exc:
@@ -208,6 +210,6 @@ def remove_tabs_js(app: "Sphinx", exc: Exception) -> None:
             tabs_js.unlink()  # When python 3.7 deprecated, use missing_ok=True
 
 
-def setup(app: "Sphinx") -> None:
+def setup(app: Sphinx) -> None:
     """Configure Sphinx app hooks."""
     app.connect("build-finished", remove_tabs_js)

pyproject.toml

@@ -152,10 +152,16 @@ select = [
   "PERF", # Perflint
   "RUF", # Ruff-specific rules
   "D", # pydocstyle
+  "FA100",  # future annotations
 ]
 ignore = [
   "COM812", # missing trailing comma, ruff format conflict
 ]
+extend-safe-fixes = [
+  "UP006",
+  "UP007",
+]
+pyupgrade.keep-runtime-typing = false
 
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
@@ -165,6 +171,9 @@ known-first-party = [
   "g",
 ]
 combine-as-imports = true
+required-imports = [
+  "from __future__ import annotations",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "*/__init__.py" = ["F401"]
@@ -184,3 +193,15 @@ filterwarnings = [
 [tool.pytest-watcher]
 now = true
 ignore_patterns = ["*.py.*.py"]
+
+[tool.coverage.report]
+exclude_also = [
+  "def __repr__",
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+  "class .*\\bProtocol\\):",
+  "@(abc\\.)?abstractmethod",
+  "from __future__ import annotations",
+]

src/g/__about__.py

@@ -1,5 +1,7 @@
 """Metadata package for g."""
 
+from __future__ import annotations
+
 __title__ = "g"
 __package_name__ = "g"
 __description__ = "CLI alias for your current directory's VCS command: git, svn, hg"

src/g/__init__.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 """Package for g."""
 
+from __future__ import annotations
+
 import io
 import logging
 import os
@@ -17,7 +19,7 @@
 log = logging.getLogger(__name__)
 
 
-def find_repo_type(path: t.Union[pathlib.Path, str]) -> t.Optional[str]:
+def find_repo_type(path: pathlib.Path | str) -> str | None:
     """Detect repo type looking upwards."""
     for _path in [*list(pathlib.Path(path).parents), pathlib.Path(path)]:
         for p in _path.iterdir():
@@ -30,12 +32,12 @@ def find_repo_type(path: t.Union[pathlib.Path, str]) -> t.Optional[str]:
 
 
 def run(
-    cmd: t.Union[str, bytes, "PathLike[str]", "PathLike[bytes]", object] = DEFAULT,
+    cmd: str | bytes | PathLike[str] | PathLike[bytes] | object = DEFAULT,
     cmd_args: object = DEFAULT,
     wait: bool = False,
     *args: object,
     **kwargs: t.Any,
-) -> t.Optional["subprocess.Popen[str]"]:
+) -> subprocess.Popen[str] | None:
     """CLI Entrypoint for g, overlay for current directory's VCS utility.
 
     Environment variables

tests/test_cli.py

@@ -1,7 +1,8 @@
 """Tests for g's CLI package."""
 
+from __future__ import annotations
+
 import enum
-import pathlib
 import subprocess
 import typing as t
 from unittest.mock import patch
@@ -10,11 +11,14 @@
 
 from g import run
 
+if t.TYPE_CHECKING:
+    import pathlib
+
 
 def get_output(
     *args: t.Any,
     **kwargs: t.Any,
-) -> t.Union[subprocess.CalledProcessError, t.Any]:
+) -> subprocess.CalledProcessError | t.Any:
     """Retrieve output from CLI subprocess, whether success or error."""
     try:
         return subprocess.check_output(*args, **kwargs)
@@ -49,7 +53,7 @@ class CommandLineTestFixture(t.NamedTuple):
     argv_args: list[str]
 
     # results
-    expect_cmd: t.Optional[str]
+    expect_cmd: str | None
 
 
 TEST_FIXTURES: list[CommandLineTestFixture] = [
@@ -90,7 +94,7 @@ def test_command_line(
     test_id: str,
     env: EnvFlag,
     argv_args: list[str],
-    expect_cmd: t.Optional[str],
+    expect_cmd: str | None,
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: pathlib.Path,
 ) -> None: