Don't render Annotated by default; add include_extras (#8)

* Add include_extras and don't render Annotated by default

* Add PR and issue to changelog

* Add new environment to GitHub Actions matrix

* Just use two steps

* Do the matrix correctly

* Try this

* Just run the two commands

* Remove extra curly brace

---------

Co-authored-by: Jay Qi <jayqi@users.noreply.github.com>

Author: jayqi

.github/workflows/tests.yml

@@ -36,7 +36,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
@@ -52,6 +52,13 @@ jobs:
           pipx install hatch
 
       - name: Run tests
+        if: matrix.python-version == '3.8'
+        run: |
+          hatch run tests.py${{ matrix.python-version }}-typing_extensions:run
+          hatch run tests.py${{ matrix.python-version }}-no-typing_extensions:run
+
+      - name: Run tests
+        if: matrix.python-version != '3.8'
         run: |
           hatch run tests.py${{ matrix.python-version }}:run
 

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.3.0 (2024-07-16)
+
+- Changed how `typenames` handles type annotations that include `typing.Annotated` or `typing_extensions.Annotated`. ([PR #8](https://github.com/jayqi/typenames/pull/8), [Issue #7](https://github.com/jayqi/typenames/issues/7))
+    - Added `include_extras` configuration option to `typenames` to control whether `Annotated` and metadata should be shown.
+    - By default, `include_extras` is `False`, and `Annotated` and extra metadata will _not_ be rendered.
+
 ## v1.2.0 (2024-03-19)
 
 - Fixed the type signatures of `typenames` and `parse_type_tree` to reflect the typing of input type annotations, according to static type checkers. ([PR #6](https://github.com/jayqi/typenames/pull/6))

README.md

@@ -169,6 +169,22 @@ typenames(
 
 To remove all module names, you can use `REMOVE_ALL_MODULES`, which contains the pattern `re.compile(r"^(<?\w+>?\.)+")`.
 
+### Annotated (`include_extras`)
+
+This option controls whether to render `typing.Annotated` (or `typing_extensions.Annotated` if using Python 3.8) and the extra metadata. `Annotated` is a [typing special form](https://docs.python.org/3/library/typing.html#typing.Annotated) introduced in Python 3.9 and originally specified by [PEP 593](https://peps.python.org/pep-0593/). Many libraries like [Pydantic](https://docs.pydantic.dev/latest/concepts/fields/#using-annotated), [FastAPI](https://fastapi.tiangolo.com/python-types/#type-hints-with-metadata-annotations), and [Typer](https://typer.tiangolo.com/tutorial/arguments/optional/#an-alternative-cli-argument-declaration) use it to attach metadata to type annotations that are used at runtime.
+
+By default, typenames will _not_ render `Annotated` and extra metadata. Set `include_extras=True` to render them.
+
+```python
+from typing import Annotated
+from typenames import typenames
+
+typenames(Annotated[int, "some metadata"])
+#> 'int'
+typenames(Annotated[int, "some metadata"], include_extras=True)
+#> "Annotated[int, 'some metadata']"
+```
+
 ---
 
 <sup>Reproducible examples created by <a href="https://github.com/jayqi/reprexlite">reprexlite</a>.</sup>

pyproject.toml

@@ -22,7 +22,6 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
 ]
 requires-python = ">=3.8"
-dependencies = ["typing_extensions>4 ; python_version < '3.8'"]
 
 [project.optional-dependencies]
 tests = ["pytest>=6"]
@@ -51,6 +50,11 @@ lint = [
   "ruff check",
 ]
 typecheck = ["mypy --install-types --non-interactive"]
+clean-coverage = [
+  "rm .coverage || true",
+  "rm coverage.xml || true",
+  "rm -r htmlcov || true",
+]
 
 ## TESTS ENVIRONMENT ##
 
@@ -60,10 +64,22 @@ dependencies = ["coverage", "pytest-cov"]
 template = "tests"
 
 [[tool.hatch.envs.tests.matrix]]
-python = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+python = ["3.8"]
+typing_extensions = ["typing_extensions", "no-typing_extensions"]
+
+[[tool.hatch.envs.tests.matrix]]
+python = ["3.9", "3.10", "3.11", "3.12"]
+
+[tool.hatch.envs.tests.overrides]
+matrix.typing_extensions.dependencies = [
+  { value = "typing_extensions>4", if = ["typing_extensions"], python = "3.8" },
+]
+matrix.typing_extensions.env-vars = [
+  { key = "NO_TYPING_EXTENSIONS", value = "1", if = ["no-typing_extensions"] },
+]
 
 [tool.hatch.envs.tests.scripts]
-run = "pytest tests --cov=typenames --cov-report=term --cov-report=html --cov-report=xml"
+run = "pytest tests -vv --cov=typenames --cov-report=term --cov-report=html --cov-report=xml --cov-append"
 run-debug = "run --pdb"
 
 ## DOCS ENVIRONMENT ##

tests/test_typenames.py

@@ -1,5 +1,6 @@
 import collections
 import enum
+import os
 import sys
 import typing
 
@@ -9,6 +10,7 @@
     DEFAULT_REMOVE_MODULES,
     REMOVE_ALL_MODULES,
     TypenamesConfig,
+    is_annotated_special_form,
     is_standard_collection_type_alias,
     is_typing_module_collection_alias,
     is_union_or_operator,
@@ -17,6 +19,19 @@
     typenames,
 )
 
+if sys.version_info >= (3, 9):
+    from typing import Annotated
+
+    ANNOTATED_AVAILABLE = True
+else:
+    try:
+        from typing_extensions import Annotated
+
+        ANNOTATED_AVAILABLE = True
+    except ModuleNotFoundError:
+        ANNOTATED_AVAILABLE = False
+
+
 T = typing.TypeVar("T")
 
 
@@ -91,6 +106,17 @@ class MyTypedDict(typing.TypedDict):
         ]
     )
 
+if ANNOTATED_AVAILABLE:
+    # typing.Annotated is available in Python 3.9, or backported with typing_extensions
+    cases.extend(
+        [
+            (Annotated[str, "some metadata"], "str"),
+            (Annotated[str, object()], "str"),
+            (typing.Optional[Annotated[str, "some metadata"]], "Optional[str]"),
+            (typing.Optional[Annotated[str, object()]], "Optional[str]"),
+        ]
+    )
+
 if sys.version_info >= (3, 10):
     # Python 3.10 adds union syntax with the | operator (bitwise or),
     # typing.Concatenate, typing.ParamSpec, typing.TypeAlias
@@ -252,6 +278,19 @@ def test_standard_collection_syntax_typing_module():
         assert typenames(list[int], standard_collection_syntax="typing_module") == "List[int]"
 
 
+if ANNOTATED_AVAILABLE:
+
+    def test_annotated_include_extras():
+        """Test that Annotated is included in the output when include_extras=True."""
+        assert (
+            typenames(Annotated[str, "some metadata"], include_extras=True)
+            == "Annotated[str, 'some metadata']"
+        )
+
+        obj = object()
+        assert typenames(Annotated[str, obj], include_extras=True) == f"Annotated[str, {obj}]"
+
+
 def test_node_repr():
     assert repr(parse_type_tree(int)) == "<TypeNode <class 'int'>>"
     assert repr(parse_type_tree(typing.Any)) == "<TypeNode typing.Any>"
@@ -402,3 +441,20 @@ def test_nested_collection_types_nested_both():
         tp2 = dict[typing.Tuple[int, int], str]
         assert is_typing_module_collection_alias(tp2) is False
         assert is_standard_collection_type_alias(tp2) is True
+
+
+if ANNOTATED_AVAILABLE:
+
+    def test_annotated():
+        assert is_annotated_special_form(Annotated[str, "some metadata"]) is True
+        assert is_annotated_special_form(Annotated[str, object()]) is True
+
+
+@pytest.mark.skipif(
+    os.getenv("NO_TYPING_EXTENSIONS") != "1",
+    reason="Test for the no-typing_extensions environment only.",
+)
+def test_no_typing_extensions():
+    """typing_extensions should not be installed in test environment that shouldn't have it."""
+    with pytest.raises(ModuleNotFoundError):
+        import typing_extensions  # noqa: F401

typenames/__init__.py

@@ -7,18 +7,30 @@
 import sys
 import types
 import typing
-from typing import Any, List, Optional, Union, get_args, get_origin
+from typing import Any, List, Optional, Union
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 OR_OPERATOR_SUPPORTED = sys.version_info >= (3, 10)
 """Flag for whether PEP 604's | operator (bitwise or) between types is supported."""
 
 LITERAL_TYPE_SUPPORTED = sys.version_info >= (3, 8)
-"""(DEPRECATED) Flag for whether PEP 586's typing.Literal is supported. typenames no longer 
+"""(DEPRECATED) Flag for whether PEP 586's typing.Literal is supported. typenames no longer
 supports Python versions where this is false.
 """
 
+# Annotated was introduced in Python 3.9 but backported in typing_extensions
+# Need to use get_args and get_origin from typing_extensions to work correctly with
+# typing_extensions.Annotated
+if sys.version_info >= (3, 9):
+    from typing import Annotated, get_args, get_origin
+else:
+    try:
+        from typing_extensions import Annotated, get_args, get_origin
+    except ModuleNotFoundError:
+        Annotated = object()
+        from typing import get_args, get_origin
+
 # TypeVar for type annotations
 # Most typing special forms have type 'object'
 # There is a stalled proposal for TypeForm: https://github.com/python/mypy/issues/9773
@@ -80,6 +92,7 @@ class TypenamesConfig:
     remove_modules: List[Union[str, re.Pattern]] = dataclasses.field(
         default_factory=lambda: list(DEFAULT_REMOVE_MODULES)
     )
+    include_extras: bool = False
 
     def __post_init__(self):
         self.union_syntax = UnionSyntax(self.union_syntax)
@@ -257,6 +270,13 @@ def __str__(self) -> str:
             else:
                 origin_module_prefix = "typing."
                 origin_name = self.tp._name
+        # Case: typing.Annotated
+        elif is_annotated_special_form(self.tp):
+            if self.config.include_extras:
+                origin_module_prefix = "typing."
+                origin_name = "Annotated"
+            else:
+                return str(arg_nodes[0])
         # Case: Some other generic type
         else:
             if hasattr(self.origin, "__module__"):
@@ -449,3 +469,8 @@ def is_typing_module_collection_alias(tp: type) -> bool:
     return (
         get_origin(tp) in STANDARD_COLLECTION_CLASSES and type(tp) is typing._GenericAlias  # type: ignore[attr-defined]
     )
+
+
+def is_annotated_special_form(tp: type) -> bool:
+    """Check if type annotation is the typing.Annotated special form."""
+    return get_origin(tp) is Annotated