Use future annotations

CHANGES

@@ -15,6 +15,17 @@ $ pip install --user --upgrade --pre libvcs
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### Development
+
+#### chore: Implement PEP 563 deferred annotation resolution (#483)
+
+- Add `from __future__ import annotations` to defer annotation resolution and reduce unnecessary runtime 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/
+
 ## libvcs 0.34.0 (2024-11-22)
 
 _Maintenance only, no bug fixes, or new features_

conftest.py

@@ -8,11 +8,15 @@
 https://docs.pytest.org/en/stable/deprecations.html
 """
 
-import pathlib
+from __future__ import annotations
+
 import typing as t
 
 import pytest
 
+if t.TYPE_CHECKING:
+    import pathlib
+
 pytest_plugins = ["pytester"]
 
 

docs/conf.py

@@ -1,6 +1,8 @@
 # flake8: NOQA: E501
 """Sphinx configuration for libvcs."""
 
+from __future__ import annotations
+
 import inspect
 import pathlib
 import sys
@@ -71,7 +73,7 @@
 html_favicon = "_static/favicon.ico"
 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/libvcs.svg",
     "dark_logo": "img/libvcs-dark.svg",
     "footer_icons": [
@@ -150,7 +152,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.
 
@@ -220,14 +222,14 @@ 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:
         tabs_js = pathlib.Path(app.builder.outdir) / "_static" / "tabs.js"
         tabs_js.unlink(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

@@ -154,6 +154,7 @@ exclude_lines = [
   "if TYPE_CHECKING:",
   "if t.TYPE_CHECKING:",
   "@overload( |$)",
+  "from __future__ import annotations",
 ]
 
 [tool.ruff]
@@ -177,16 +178,25 @@ 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.isort]
 known-first-party = [
   "libvcs",
 ]
 combine-as-imports = true
+required-imports = [
+  "from __future__ import annotations",
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"

src/libvcs/__about__.py

@@ -1,5 +1,7 @@
 """Metadata package for libvcs."""
 
+from __future__ import annotations
+
 __title__ = "libvcs"
 __package_name__ = "libvcs"
 __description__ = "Lite, typed, python utilities for Git, SVN, Mercurial, etc."

src/libvcs/__init__.py

@@ -1,5 +1,7 @@
 """Project package for libvcs."""
 
+from __future__ import annotations
+
 import logging
 
 from ._internal.run import CmdLoggingAdapter

src/libvcs/_internal/dataclasses.py

@@ -5,6 +5,8 @@
 This is an internal API not covered by versioning policy.
 """
 
+from __future__ import annotations
+
 import dataclasses
 import typing as t
 from operator import attrgetter
@@ -78,7 +80,7 @@ class SkipDefaultFieldsReprMixin:
     ItemWithMixin(name=Test, unit_price=2.05)
     """
 
-    def __repr__(self: "DataclassInstance") -> str:
+    def __repr__(self: DataclassInstance) -> str:
         """Omit default fields in object representation."""
         nodef_f_vals = (
             (f.name, attrgetter(f.name)(self))

src/libvcs/_internal/module_loading.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import sys
 import typing as t
 

src/libvcs/_internal/query_list.py

@@ -5,6 +5,8 @@
 This is an internal API not covered by versioning policy.
 """
 
+from __future__ import annotations
+
 import logging
 import re
 import traceback
@@ -28,7 +30,7 @@ class ObjectDoesNotExist(Exception):
 def keygetter(
     obj: Mapping[str, t.Any],
     path: str,
-) -> t.Union[None, t.Any, str, list[str], Mapping[str, str]]:
+) -> None | t.Any | str | list[str] | Mapping[str, str]:
     """Fetch values in objects and keys, supported nested data.
 
     **With dictionaries**:
@@ -94,7 +96,7 @@ def keygetter(
     return dct
 
 
-def parse_lookup(obj: Mapping[str, t.Any], path: str, lookup: str) -> t.Optional[t.Any]:
+def parse_lookup(obj: Mapping[str, t.Any], path: str, lookup: str) -> t.Any | None:
     """Check if field lookup key, e.g. "my__path__contains" has comparator, return val.
 
     If comparator not used or value not found, return None.
@@ -134,23 +136,23 @@ class LookupProtocol(t.Protocol):
 
     def __call__(
         self,
-        data: t.Union[str, list[str], Mapping[str, str]],
-        rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+        data: str | list[str] | Mapping[str, str],
+        rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
     ) -> bool:
         """Return callback for :class:`QueryList` filtering operators."""
         ...
 
 
 def lookup_exact(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     return rhs == data
 
 
 def lookup_iexact(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, str):
         return False
@@ -159,8 +161,8 @@ def lookup_iexact(
 
 
 def lookup_contains(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, (str, Mapping, list)):
         return False
@@ -169,8 +171,8 @@ def lookup_contains(
 
 
 def lookup_icontains(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, (str, Mapping, list)):
         return False
@@ -184,8 +186,8 @@ def lookup_icontains(
 
 
 def lookup_startswith(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, str):
         return False
@@ -194,8 +196,8 @@ def lookup_startswith(
 
 
 def lookup_istartswith(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, str):
         return False
@@ -204,8 +206,8 @@ def lookup_istartswith(
 
 
 def lookup_endswith(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, str):
         return False
@@ -214,17 +216,17 @@ def lookup_endswith(
 
 
 def lookup_iendswith(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if not isinstance(rhs, str) or not isinstance(data, str):
         return False
     return data.lower().endswith(rhs.lower())
 
 
 def lookup_in(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if isinstance(rhs, list):
         return data in rhs
@@ -248,8 +250,8 @@ def lookup_in(
 
 
 def lookup_nin(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if isinstance(rhs, list):
         return data not in rhs
@@ -273,17 +275,17 @@ def lookup_nin(
 
 
 def lookup_regex(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if isinstance(data, (str, bytes, re.Pattern)) and isinstance(rhs, (str, bytes)):
         return bool(re.search(rhs, data))
     return False
 
 
 def lookup_iregex(
-    data: t.Union[str, list[str], Mapping[str, str]],
-    rhs: t.Union[str, list[str], Mapping[str, str], re.Pattern[str]],
+    data: str | list[str] | Mapping[str, str],
+    rhs: str | list[str] | Mapping[str, str] | re.Pattern[str],
 ) -> bool:
     if isinstance(data, (str, bytes, re.Pattern)) and isinstance(rhs, (str, bytes)):
         return bool(re.search(rhs, data, re.IGNORECASE))
@@ -467,9 +469,9 @@ class QueryList(list[T], t.Generic[T]):
     """
 
     data: Sequence[T]
-    pk_key: t.Optional[str]
+    pk_key: str | None
 
-    def __init__(self, items: t.Optional["Iterable[T]"] = None) -> None:
+    def __init__(self, items: Iterable[T] | None = None) -> None:
         super().__init__(items if items is not None else [])
 
     def items(self) -> list[tuple[str, T]]:
@@ -502,9 +504,9 @@ def __eq__(
 
     def filter(
         self,
-        matcher: t.Optional[t.Union[Callable[[T], bool], T]] = None,
+        matcher: Callable[[T], bool] | T | None = None,
         **kwargs: t.Any,
-    ) -> "QueryList[T]":
+    ) -> QueryList[T]:
         def filter_lookup(obj: t.Any) -> bool:
             for path, v in kwargs.items():
                 try:
@@ -529,7 +531,7 @@ def filter_lookup(obj: t.Any) -> bool:
             filter_ = matcher
         elif matcher is not None:
 
-            def val_match(obj: t.Union[str, list[t.Any], T]) -> bool:
+            def val_match(obj: str | list[t.Any] | T) -> bool:
                 if isinstance(matcher, list):
                     return obj in matcher
                 return bool(obj == matcher)
@@ -542,10 +544,10 @@ def val_match(obj: t.Union[str, list[t.Any], T]) -> bool:
 
     def get(
         self,
-        matcher: t.Optional[t.Union[Callable[[T], bool], T]] = None,
-        default: t.Optional[t.Any] = no_arg,
+        matcher: Callable[[T], bool] | T | None = None,
+        default: t.Any | None = no_arg,
         **kwargs: t.Any,
-    ) -> t.Optional[T]:
+    ) -> T | None:
         objs = self.filter(matcher=matcher, **kwargs)
         if len(objs) > 1:
             raise MultipleObjectsReturned