type-analyzer 0.1.2__tar.gz → 0.2.0__tar.gz

type_analyzer-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: type-analyzer
+Version: 0.2.0
+Summary: Functions for introspecting Python type hints.
+Project-URL: Repository, https://github.com/100nm/type-analyzer
+Author: remimd
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.16,>=3.12
+Description-Content-Type: text/markdown
+
+# type-analyzer
+
+[![PyPI - Version](https://shieldcn.dev/pypi/v/type-analyzer.svg?color=3775A9&size=xs&variant=secondary)](https://pypi.org/project/type-analyzer)
+[![PyPI - Downloads](https://shieldcn.dev/pypi/dm/type-analyzer.svg?color=3775A9&size=xs&variant=secondary)](https://pypistats.org/packages/type-analyzer)
+[![GitHub Stars](https://shieldcn.dev/github/stars/100nm/type-analyzer.svg?size=xs&variant=secondary)](https://github.com/100nm/type-analyzer/stargazers)
+[![CI](https://shieldcn.dev/github/ci/100nm/type-analyzer.svg?size=xs&variant=secondary&workflow=ci.yml)](https://github.com/100nm/type-analyzer/actions/workflows/ci.yml)
+[![Ruff](https://shieldcn.dev/badge/code_style-Ruff-261230.svg?logo=ruff&size=xs&variant=secondary)](https://github.com/astral-sh/ruff)
+
+Functions for introspecting Python type hints.
+
+## Installation
+
+⚠️ _Requires Python 3.12 or higher_
+
+```bash
+pip install type-analyzer
+```
+
+## Usage
+
+### `matching_types`
+
+`matching_types` returns every type a type hint matches, without duplicates. Unions
+are unpacked into their members, and `Annotated` metadata is removed:
+
+```python
+from typing import Annotated
+
+from type_analyzer import matching_types
+
+matching_types(str | int)
+# => (str, int)
+
+matching_types(Annotated[str, "metadata"] | None)
+# => (str, NoneType)
+
+matching_types(list[Annotated[int, "metadata"]])
+# => (list[int],)
+```
+
+### Options
+
+`MatchingTypesConfig` adds more types to the result. Every option is disabled by
+default:
+
+| Option                  | Effect                                                   |
+|-------------------------|----------------------------------------------------------|
+| `ignore_none`           | Leaves out `None`.                                       |
+| `with_bases`            | Adds the base classes, with their type arguments.        |
+| `with_origin`           | Adds the origin of generic types (`list[str]` → `list`). |
+| `with_type_alias_value` | Adds the value of type aliases.                          |
+
+```python
+from type_analyzer import MatchingTypesConfig, matching_types
+
+# ----- ignore_none -----
+
+config = MatchingTypesConfig(ignore_none=True)
+matching_types(str | None, config)
+# => (str,)
+
+# ----- with_bases -----
+
+
+class A[T]: ...
+
+
+class B[T]: ...
+
+
+class C[T1, T2](A[T1], B[T2]): ...
+
+
+config = MatchingTypesConfig(with_bases=True)
+matching_types(C[str, int], config)
+# => (C[str, int], A[str], B[int])
+
+# ----- with_origin -----
+
+config = MatchingTypesConfig(with_origin=True)
+matching_types(list[str], config)
+# => (list[str], list)
+
+# ----- with_type_alias_value -----
+
+type StringOr[T] = str | T
+
+config = MatchingTypesConfig(with_type_alias_value=True)
+matching_types(StringOr[int], config)
+# => (StringOr[int], str, int)
+```
+
+Options can be combined: `MatchingTypesConfig(with_bases=True, with_origin=True)`.
+
+### `iter_matching_types`
+
+`iter_matching_types` is the lazy counterpart of `matching_types`: it yields the
+types one by one, and keeps the duplicates.
+
+```python
+from type_analyzer import MatchingTypesConfig, iter_matching_types
+
+
+class Left: ...
+
+
+class Right: ...
+
+
+class Both(Left, Right): ...
+
+
+config = MatchingTypesConfig(with_bases=True)
+list(iter_matching_types(Both, config))
+# => [Both, Left, object, Right, object]
+```

type_analyzer-0.2.0/README.md

@@ -0,0 +1,116 @@
+# type-analyzer
+
+[![PyPI - Version](https://shieldcn.dev/pypi/v/type-analyzer.svg?color=3775A9&size=xs&variant=secondary)](https://pypi.org/project/type-analyzer)
+[![PyPI - Downloads](https://shieldcn.dev/pypi/dm/type-analyzer.svg?color=3775A9&size=xs&variant=secondary)](https://pypistats.org/packages/type-analyzer)
+[![GitHub Stars](https://shieldcn.dev/github/stars/100nm/type-analyzer.svg?size=xs&variant=secondary)](https://github.com/100nm/type-analyzer/stargazers)
+[![CI](https://shieldcn.dev/github/ci/100nm/type-analyzer.svg?size=xs&variant=secondary&workflow=ci.yml)](https://github.com/100nm/type-analyzer/actions/workflows/ci.yml)
+[![Ruff](https://shieldcn.dev/badge/code_style-Ruff-261230.svg?logo=ruff&size=xs&variant=secondary)](https://github.com/astral-sh/ruff)
+
+Functions for introspecting Python type hints.
+
+## Installation
+
+⚠️ _Requires Python 3.12 or higher_
+
+```bash
+pip install type-analyzer
+```
+
+## Usage
+
+### `matching_types`
+
+`matching_types` returns every type a type hint matches, without duplicates. Unions
+are unpacked into their members, and `Annotated` metadata is removed:
+
+```python
+from typing import Annotated
+
+from type_analyzer import matching_types
+
+matching_types(str | int)
+# => (str, int)
+
+matching_types(Annotated[str, "metadata"] | None)
+# => (str, NoneType)
+
+matching_types(list[Annotated[int, "metadata"]])
+# => (list[int],)
+```
+
+### Options
+
+`MatchingTypesConfig` adds more types to the result. Every option is disabled by
+default:
+
+| Option                  | Effect                                                   |
+|-------------------------|----------------------------------------------------------|
+| `ignore_none`           | Leaves out `None`.                                       |
+| `with_bases`            | Adds the base classes, with their type arguments.        |
+| `with_origin`           | Adds the origin of generic types (`list[str]` → `list`). |
+| `with_type_alias_value` | Adds the value of type aliases.                          |
+
+```python
+from type_analyzer import MatchingTypesConfig, matching_types
+
+# ----- ignore_none -----
+
+config = MatchingTypesConfig(ignore_none=True)
+matching_types(str | None, config)
+# => (str,)
+
+# ----- with_bases -----
+
+
+class A[T]: ...
+
+
+class B[T]: ...
+
+
+class C[T1, T2](A[T1], B[T2]): ...
+
+
+config = MatchingTypesConfig(with_bases=True)
+matching_types(C[str, int], config)
+# => (C[str, int], A[str], B[int])
+
+# ----- with_origin -----
+
+config = MatchingTypesConfig(with_origin=True)
+matching_types(list[str], config)
+# => (list[str], list)
+
+# ----- with_type_alias_value -----
+
+type StringOr[T] = str | T
+
+config = MatchingTypesConfig(with_type_alias_value=True)
+matching_types(StringOr[int], config)
+# => (StringOr[int], str, int)
+```
+
+Options can be combined: `MatchingTypesConfig(with_bases=True, with_origin=True)`.
+
+### `iter_matching_types`
+
+`iter_matching_types` is the lazy counterpart of `matching_types`: it yields the
+types one by one, and keeps the duplicates.
+
+```python
+from type_analyzer import MatchingTypesConfig, iter_matching_types
+
+
+class Left: ...
+
+
+class Right: ...
+
+
+class Both(Left, Right): ...
+
+
+config = MatchingTypesConfig(with_bases=True)
+list(iter_matching_types(Both, config))
+# => [Both, Left, object, Right, object]
+```

{type_analyzer-0.1.2 → type_analyzer-0.2.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "type-analyzer"
-version = "0.1.2"
+version = "0.2.0"
 description = "Functions for introspecting Python type hints."
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
-requires-python = ">=3.12, <3.15"
+requires-python = ">=3.12, <3.16"
 authors = [{ name = "remimd" }]
 keywords = []
 classifiers = [
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Operating System :: OS Independent",
     "Intended Audience :: Developers",
     "Natural Language :: English",
@@ -81,7 +82,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.ruff.lint]
-extend-select = ["I", "N"]
+extend-select = ["F", "I", "N"]
 fixable = ["ALL"]
 
 [tool.uv]

type_analyzer-0.2.0/type_analyzer/_core/matching_types.py

@@ -0,0 +1,154 @@
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from types import NoneType, UnionType, get_original_bases
+from typing import (
+    Annotated,
+    Any,
+    Generic,
+    Self,
+    TypeAliasType,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
+
+
+@dataclass(repr=False, eq=False, frozen=True, kw_only=True, slots=True)
+class MatchingTypesConfig:
+    ignore_none: bool = field(default=False)
+    with_bases: bool = field(default=False)
+    with_origin: bool = field(default=False)
+    with_type_alias_value: bool = field(default=False)
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class _TypeHint:
+    value: Any
+    origin: Any
+
+    @property
+    def args(self) -> tuple[Any, ...]:
+        return get_args(self.value)
+
+    @property
+    def generics(self) -> Mapping[TypeVar, Any]:
+        parameters = getattr(self.origin, "__parameters__", ())
+        return dict(zip(parameters, self.args))
+
+    @property
+    def is_none(self) -> bool:
+        return self.value in (None, NoneType)
+
+    @property
+    def is_union(self) -> bool:
+        return self.origin is Union or isinstance(self.value, UnionType)
+
+    @property
+    def target(self) -> Any:
+        return self.value if self.origin is None else self.origin
+
+    def apply_generics(self, generics: Mapping[TypeVar, Any]) -> Self:
+        if isinstance(self.value, TypeVar):
+            return self.from_value(generics.get(self.value, self.value))
+
+        if self.origin is None:
+            return self
+
+        if self.origin is Annotated:
+            return self.from_value(self.args[0]).apply_generics(generics)
+
+        args = tuple(
+            self.from_value(arg).apply_generics(generics).value for arg in self.args
+        )
+
+        if self.is_union:
+            return self.from_value(Union[*args])
+
+        return self.from_value(self.origin[*args])
+
+    @classmethod
+    def from_value(cls, value: Any) -> Self:
+        return cls(value, get_origin(value))
+
+
+_empty_config = MatchingTypesConfig()
+
+
+def iter_matching_types(
+    type_hint: Any,
+    /,
+    config: MatchingTypesConfig | None = None,
+) -> Iterator[Any]:
+    config = config or _empty_config
+    return _iter_matching_types((type_hint,), config, {})
+
+
+def matching_types(
+    type_hint: Any,
+    /,
+    config: MatchingTypesConfig | None = None,
+) -> tuple[Any, ...]:
+    return tuple(dict.fromkeys(iter_matching_types(type_hint, config)))
+
+
+def _iter_bases(type_hint: _TypeHint, config: MatchingTypesConfig) -> Iterator[Any]:
+    try:
+        bases = get_original_bases(type_hint.target)
+    except TypeError:
+        return
+
+    yield from _iter_matching_types(bases, config, type_hint.generics)
+
+
+def _iter_matching_types(
+    type_hints: Sequence[Any],
+    config: MatchingTypesConfig,
+    generics: Mapping[TypeVar, Any],
+) -> Iterator[Any]:
+    for value in type_hints:
+        type_hint = _TypeHint.from_value(value)
+
+        if type_hint.origin is Generic:
+            continue
+
+        yield from _iter_type_hint_matching_types(
+            type_hint.apply_generics(generics),
+            config,
+        )
+
+
+def _iter_type_alias_value(
+    type_hint: _TypeHint,
+    config: MatchingTypesConfig,
+) -> Iterator[Any]:
+    type_alias = type_hint.target
+
+    if not isinstance(type_alias, TypeAliasType):
+        return
+
+    values = (type_alias.__value__,)
+    yield from _iter_matching_types(values, config, type_hint.generics)
+
+
+def _iter_type_hint_matching_types(
+    type_hint: _TypeHint,
+    config: MatchingTypesConfig,
+) -> Iterator[Any]:
+    if config.ignore_none and type_hint.is_none:
+        return
+
+    if type_hint.is_union:
+        yield from _iter_matching_types(type_hint.args, config, {})
+        return
+
+    yield type_hint.value
+
+    if config.with_origin and type_hint.origin is not None:
+        yield type_hint.origin
+
+    if config.with_bases:
+        yield from _iter_bases(type_hint, config)
+
+    if config.with_type_alias_value:
+        yield from _iter_type_alias_value(type_hint, config)

type_analyzer-0.1.2/PKG-INFO

@@ -1,75 +0,0 @@
-Metadata-Version: 2.4
-Name: type-analyzer
-Version: 0.1.2
-Summary: Functions for introspecting Python type hints.
-Project-URL: Repository, https://github.com/100nm/type-analyzer
-Author: remimd
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: <3.15,>=3.12
-Description-Content-Type: text/markdown
-
-# type-analyzer
-
-[![CI](https://github.com/100nm/type-analyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/type-analyzer)
-[![PyPI - Version](https://img.shields.io/pypi/v/type-analyzer.svg?color=blue)](https://pypi.org/project/type-analyzer)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/type-analyzer.svg?color=blue)](https://pypistats.org/packages/type-analyzer)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-
-## Installation
-
-⚠️ _Requires Python 3.12 or higher_
-
-```bash
-pip install type-analyzer
-```
-
-## Quick start
-
-### matching_types
-
-```python
-from type_analyzer import MatchingTypesConfig, matching_types
-
-# ----- Union type -----
-
-matching_types(str | int)
-# => (str, int)
-
-# ----- Generic type alias -----
-
-type StringOr[T] = str | T
-
-config = MatchingTypesConfig(with_type_alias_value=True)
-matching_types(StringOr[int], config)
-# => (StringOr[int], str, int)
-
-# ----- Generic classes -----
-
-class A[T]:
-    ...
-
-class B[T]:
-    ...
-
-class C[T1, T2](A[T1], B[T2]):
-    ...
-
-config = MatchingTypesConfig(with_bases=True)
-matching_types(C[str, int], config)
-# => (C[str, int], A[str], B[int])
-```

type_analyzer-0.1.2/README.md

@@ -1,50 +0,0 @@
-# type-analyzer
-
-[![CI](https://github.com/100nm/type-analyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/type-analyzer)
-[![PyPI - Version](https://img.shields.io/pypi/v/type-analyzer.svg?color=blue)](https://pypi.org/project/type-analyzer)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/type-analyzer.svg?color=blue)](https://pypistats.org/packages/type-analyzer)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-
-## Installation
-
-⚠️ _Requires Python 3.12 or higher_
-
-```bash
-pip install type-analyzer
-```
-
-## Quick start
-
-### matching_types
-
-```python
-from type_analyzer import MatchingTypesConfig, matching_types
-
-# ----- Union type -----
-
-matching_types(str | int)
-# => (str, int)
-
-# ----- Generic type alias -----
-
-type StringOr[T] = str | T
-
-config = MatchingTypesConfig(with_type_alias_value=True)
-matching_types(StringOr[int], config)
-# => (StringOr[int], str, int)
-
-# ----- Generic classes -----
-
-class A[T]:
-    ...
-
-class B[T]:
-    ...
-
-class C[T1, T2](A[T1], B[T2]):
-    ...
-
-config = MatchingTypesConfig(with_bases=True)
-matching_types(C[str, int], config)
-# => (C[str, int], A[str], B[int])
-```

type_analyzer-0.1.2/type_analyzer/_core/matching_types.py

@@ -1,129 +0,0 @@
-from collections.abc import Iterator, Mapping, Sequence
-from dataclasses import dataclass, field
-from types import NoneType, UnionType, get_original_bases
-from typing import (
-    Annotated,
-    Any,
-    Generic,
-    TypeAliasType,
-    TypeVar,
-    Union,
-    get_args,
-    get_origin,
-)
-
-
-@dataclass(repr=False, eq=False, frozen=True, kw_only=True, slots=True)
-class MatchingTypesConfig:
-    ignore_none: bool = field(default=False)
-    with_bases: bool = field(default=False)
-    with_origin: bool = field(default=False)
-    with_type_alias_value: bool = field(default=False)
-
-
-_empty_config = MatchingTypesConfig()
-
-
-def iter_matching_types(
-    type_hint: Any,
-    /,
-    config: MatchingTypesConfig | None = None,
-) -> Iterator[Any]:
-    config = config or _empty_config
-    type_hints = (type_hint,)
-    return _iter_matching_types(type_hints, config)
-
-
-def matching_types(
-    type_hint: Any,
-    /,
-    config: MatchingTypesConfig | None = None,
-) -> tuple[Any, ...]:
-    return tuple(dict.fromkeys(iter_matching_types(type_hint, config)))
-
-
-def _get_bases(type_hint: Any, origin: Any) -> tuple[Any, ...]:
-    target = type_hint if origin is None else origin
-
-    try:
-        return get_original_bases(target)
-    except TypeError:
-        return ()
-
-
-def _get_generics(type_hint: Any, origin: Any) -> Mapping[TypeVar, Any]:
-    args = get_args(type_hint)
-    parameters = getattr(origin, "__parameters__", ())
-    return dict(zip(parameters, args))
-
-
-def _is_type_var(type_hint: Any) -> bool:
-    return isinstance(type_hint, TypeVar)
-
-
-def _is_none_type(type_hint: Any) -> bool:
-    return type_hint in (None, NoneType)
-
-
-def _iter_matching_types(
-    type_hints: Sequence[Any],
-    /,
-    config: MatchingTypesConfig,
-    params: Mapping[TypeVar, Any] | None = None,
-) -> Iterator[Any]:
-    if params is None:
-        params = {}
-
-    for type_hint in type_hints:
-        if config.ignore_none and _is_none_type(type_hint):
-            continue
-
-        if _is_type_var(type_hint):
-            yield params.get(type_hint, type_hint)
-            continue
-
-        origin = get_origin(type_hint)
-
-        if origin is Generic:
-            continue
-
-        if unpacked_types := _unpack_types(type_hint, origin):
-            yield from _iter_matching_types(unpacked_types, config, params)
-            continue
-
-        if origin is None:
-            yield type_hint
-
-        else:
-            args = tuple(
-                next(_iter_matching_types((arg,), _empty_config, params))
-                for arg in get_args(type_hint)
-            )
-            yield origin[*args]
-
-            if config.with_origin:
-                yield origin
-
-        if config.with_bases and (bases := _get_bases(type_hint, origin)):
-            generics = _get_generics(type_hint, origin)
-            yield from _iter_matching_types(bases, config, generics)
-
-        if config.with_type_alias_value:
-            if isinstance(origin, TypeAliasType):
-                values = (origin.__value__,)
-                generics = _get_generics(type_hint, origin)
-                yield from _iter_matching_types(values, config, generics)
-
-            elif isinstance(type_hint, TypeAliasType):
-                values = (type_hint.__value__,)
-                yield from _iter_matching_types(values, config)
-
-
-def _unpack_types(type_hint: Any, origin: Any) -> Sequence[Any]:
-    if origin is Union or isinstance(type_hint, UnionType):
-        return get_args(type_hint)
-
-    elif origin is Annotated:
-        return get_args(type_hint)[:1]
-
-    return ()