Install & Compatibility
Where this runs
tested against v2.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.045s · 18.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.041s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TypeHint
✓ from typeapi import TypeHint
The primary class for introspecting type hints from various sources (functions, classes, standalone types).
This quickstart demonstrates how to use `typeapi.TypeHint.from_callable` to extract and analyze type hints from a function. It then shows how to inspect a standalone type annotation using `TypeHint.from_annotation`. The example highlights accessing parameter details, return type, and generic type properties like origin and arguments.
from __future__ import annotations
from typeapi import TypeHint
from typing import Any
def process_items(items: list[str], limit: int | None = None) -> dict[str, Any]:
"""Example function with type hints to introspect."""
processed_data = {}
actual_limit = limit if limit is not None else len(items)
for i, item in enumerate(items[:actual_limit]):
processed_data[f"item_{i}"] = item.upper()
return processed_data
# Introspect the type hints of the function
function_type_hints = TypeHint.from_callable(process_items)
print(f"Function: {process_items.__name__}")
print(f" Parameters:")
for name, param_hint in function_type_hints.parameters.items():
print(f" - {name}: {param_hint.annotation} (is_optional={param_hint.is_optional})")
print(f" Return type: {function_type_hints.return_type.annotation} (is_generic={function_type_hints.return_type.is_generic})")
# Example of introspecting a standalone type (e.g., from a variable annotation)
my_type_var: dict[str, int | None]
standalone_type_hint = TypeHint.from_annotation(my_type_var.__annotations__['my_type_var'])
print(f"\nStandalone type: {standalone_type_hint.annotation}")
print(f" Is generic: {standalone_type_hint.is_generic}")
print(f" Origin: {standalone_type_hint.origin}")
# For generic types, you can access the arguments
if standalone_type_hint.is_generic:
print(f" Generic arguments: {standalone_type_hint.args}")
Errors
Common errors & fixes
NameError: name 'list' is not defined
Attempting to use new-style generic type hints like `list[str]` directly in Python < 3.9 without `from __future__ import annotations` enabled.
fixAdd `from __future__ import annotations` at the very top of your Python file. Alternatively, upgrade to Python 3.9 or newer, or use `typing.List[str]` for older Python versions if you do not want to use future imports.
TypeError: 'type' object is not subscriptable
Trying to use generic types like `int | str` (PEP 604 union types) in Python < 3.10, or `list[str]` (PEP 585 generics) in Python < 3.9 without enabling `from __future__ import annotations`.
fixEnsure `from __future__ import annotations` is at the top of your module. If targeting Python < 3.10 and not using future imports, use `typing.Union[int, str]`. For Python < 3.9, use `typing.List[str]`.
AttributeError: 'TypeHint' object has no attribute 'non_existent_attribute'
Attempting to access properties or methods on a `TypeHint` object that do not exist or are not applicable to the specific type being introspected. For example, `is_optional` might be accessed incorrectly.
fixConsult the `typeapi` documentation for the available attributes and methods of the `TypeHint` object and its sub-components (e.g., `ParameterTypeHint`). Ensure the attribute is valid for the context. Debug by printing `dir(type_hint_object)` to see available attributes.
Upgrade
Version history
2.3.0latest on PyPI · released Oct 23, 2025
Audit
Dependencies
No dependency data recorded yet.