{"id":7812,"library":"typeapi","title":"Python Type API for Type Hint Introspection","description":"The `typeapi` package provides a unified and consistent API for the reflection and introspection of Python type hints. It enables evaluating future annotations such as PEP 585 (e.g., `list[str]`) and PEP 604 (e.g., `int | str`) in Python versions that do not natively support them. The current version is 2.3.0, and it maintains an active release cadence with regular updates.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/NiklasRosenstein/python-typeapi","tags":["typing","type hints","introspection","reflection","PEP 585","PEP 604"],"install":[{"cmd":"pip install typeapi","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary class for introspecting type hints from various sources (functions, classes, standalone types).","symbol":"TypeHint","correct":"from typeapi import TypeHint"}],"quickstart":{"code":"from __future__ import annotations\nfrom typeapi import TypeHint\nfrom typing import Any\n\ndef process_items(items: list[str], limit: int | None = None) -> dict[str, Any]:\n    \"\"\"Example function with type hints to introspect.\"\"\"\n    processed_data = {}\n    actual_limit = limit if limit is not None else len(items)\n    for i, item in enumerate(items[:actual_limit]):\n        processed_data[f\"item_{i}\"] = item.upper()\n    return processed_data\n\n# Introspect the type hints of the function\nfunction_type_hints = TypeHint.from_callable(process_items)\n\nprint(f\"Function: {process_items.__name__}\")\nprint(f\"  Parameters:\")\nfor name, param_hint in function_type_hints.parameters.items():\n    print(f\"    - {name}: {param_hint.annotation} (is_optional={param_hint.is_optional})\")\n\nprint(f\"  Return type: {function_type_hints.return_type.annotation} (is_generic={function_type_hints.return_type.is_generic})\")\n\n# Example of introspecting a standalone type (e.g., from a variable annotation)\nmy_type_var: dict[str, int | None]\nstandalone_type_hint = TypeHint.from_annotation(my_type_var.__annotations__['my_type_var'])\nprint(f\"\\nStandalone type: {standalone_type_hint.annotation}\")\nprint(f\"  Is generic: {standalone_type_hint.is_generic}\")\nprint(f\"  Origin: {standalone_type_hint.origin}\")\n# For generic types, you can access the arguments\nif standalone_type_hint.is_generic:\n    print(f\"  Generic arguments: {standalone_type_hint.args}\")","lang":"python","description":"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."},"warnings":[{"fix":"Use `from __future__ import annotations` at the top of your module or ensure your project runs on Python 3.9+ for native support. `typeapi` then provides a consistent introspection API across these versions.","message":"When using Python versions older than 3.9, native generic type syntax like `list[str]` or `dict[str, int]` will raise `TypeError: 'type' object is not subscriptable` or `NameError: name 'list' is not defined` errors. `typeapi` is designed to parse these modern annotations, but for the Python interpreter to accept them, you either need Python 3.9+ or `from __future__ import annotations` (for runtime evaluation) in older versions.","severity":"gotcha","affected_versions":"<3.9"},{"fix":"If runtime type checking is required, consider integrating a dedicated runtime type checker library (e.g., `pydantic`, `typer` validation features, or `typeguard`) in addition to `typeapi` for introspection.","message":"Python's type hints are primarily for static analysis and are not enforced at runtime by default. `typeapi` provides tools for *inspecting* these hints but does not perform runtime type checking or validation. Developers often mistakenly assume type hints add runtime validation.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `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.","cause":"Attempting to use new-style generic type hints like `list[str]` directly in Python < 3.9 without `from __future__ import annotations` enabled.","error":"NameError: name 'list' is not defined"},{"fix":"Ensure `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]`.","cause":"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`.","error":"TypeError: 'type' object is not subscriptable"},{"fix":"Consult 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.","cause":"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.","error":"AttributeError: 'TypeHint' object has no attribute 'non_existent_attribute'"}]}