eval-type-backport

0.3.1 verified Tue May 12 auth: no python install: verified

Like `typing._eval_type`, this tiny package provides a replacement to support newer typing features (such as `X | Y` for unions from PEP 604 and `list[X]` for generic built-ins from PEP 585) in older Python versions (>=3.7). It allows libraries like Pydantic to maintain modern type hint syntax while supporting a wider range of Python environments. It is currently at version 0.3.1 and sees updates as needed for compatibility.

pip install eval-type-backport

Common errors

error TypeError: You have a type annotation 'bool | None' which makes use of newer typing features than are supported in your version of Python. ↓

cause This error arises when running Python code with modern type hint syntax (like `X | Y` for unions or `list[X]` for generic built-ins) on older Python versions (e.g., Python < 3.10 for union operator, Python < 3.9 for generic built-ins) without `eval-type-backport` installed or properly utilized by a dependent library like Pydantic, causing Python's runtime to fail evaluating the unsupported syntax.

fix

Install the eval-type-backport package: pip install eval-type-backport. Ensure any libraries that rely on it (like Pydantic) are also updated to versions that correctly leverage this backport. Alternatively, manually replace X | Y with typing.Union[X, Y] and list[X] with typing.List[X] in your code.

error TypeError: Unable to evaluate type annotation 'ClassVar'. ↓

cause This specific `TypeError` occurs when a library, such as Pydantic, attempts to evaluate a `ClassVar` type annotation in a Python environment where `eval-type-backport` either doesn't have the necessary logic to backport `ClassVar` evaluation for that Python version, or an older version of `eval-type-backport` is in use.

fix

Upgrade eval-type-backport to its latest version (pip install --upgrade eval-type-backport) to ensure you have the most recent compatibility fixes. If the problem persists, ensure ClassVar is explicitly typed (e.g., MY_CLASS_CONSTANT: ClassVar[int] = 5) as some contexts might require clearer annotations for evaluation.

error ModuleNotFoundError: No module named 'eval_type_backport' ↓

cause The Python interpreter cannot find the `eval_type_backport` package because it has not been installed in the active Python environment, or there is a typo in the import statement.

fix

Install the package using pip: pip install eval-type-backport. Verify that you are running Python from the correct environment (e.g., a virtual environment) where the package was installed.

Warnings

gotcha This library is primarily intended for use by other libraries (e.g., Pydantic) that need to evaluate type annotations at runtime for compatibility with modern Python typing features on older Python versions. Direct usage by end-user applications is generally rare unless you have a specific, advanced use case mirroring `typing._eval_type`. ↓

fix Consider if you truly need to evaluate types at runtime for compatibility; often, simply upgrading your Python version or using `typing.Union`/`typing.List` directly is more appropriate for application code.

breaking If you are using modern type hint syntax (e.g., `X | Y` for unions, `list[X]` for generic built-ins) in a project targeting Python <3.10 or <3.9 respectively, you may encounter `TypeError` or `ImportError` at runtime. `eval-type-backport` provides the mechanism to resolve these types dynamically. ↓

fix Install `eval-type-backport` and ensure libraries evaluating your type hints are configured to use it, or explicitly use older `typing` constructs (e.g., `typing.Union[X, Y]`, `typing.List[X]`), or upgrade to a Python version that natively supports these features.

gotcha While `eval-type-backport` provides a compatibility layer, the recommended long-term solution for leveraging modern Python typing features is to upgrade your Python interpreter. Python 3.9+ natively supports generic built-in types (e.g., `list[int]`), and Python 3.10+ natively supports the `X | Y` union syntax. ↓

fix Upgrade your project's Python version to 3.10 or newer to remove the need for this backport for common modern syntax.

breaking A `SyntaxError` regarding `from __future__ import annotations` indicates that this import statement was not placed at the very beginning of the script. While often used in conjunction with modern type hints that `eval-type-backport` helps to resolve, this error is a basic Python syntax requirement independent of the library's functionality. ↓

fix Ensure `from __future__ import annotations` is the absolute first executable statement in your Python script, immediately after the shebang (if present) and encoding declaration (if present), and before any other code or comments.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.03s 17.8M

3.10 alpine (musl) - - 0.03s 17.8M

3.10 slim (glibc) wheel 1.4s 0.02s 18M

3.10 slim (glibc) - - 0.02s 18M

3.11 alpine (musl) wheel - 0.03s 19.6M

3.11 alpine (musl) - - 0.04s 19.6M

3.11 slim (glibc) wheel 1.5s 0.03s 20M

3.11 slim (glibc) - - 0.03s 20M

3.12 alpine (musl) wheel - 0.02s 11.5M

3.12 alpine (musl) - - 0.02s 11.5M

3.12 slim (glibc) wheel 1.4s 0.02s 12M

3.12 slim (glibc) - - 0.02s 12M

3.13 alpine (musl) wheel - 0.02s 11.3M

3.13 alpine (musl) - - 0.02s 11.2M

3.13 slim (glibc) wheel 1.4s 0.02s 12M

3.13 slim (glibc) - - 0.02s 12M

3.9 alpine (musl) wheel - 0.02s 17.3M

3.9 alpine (musl) - - 0.03s 17.3M

3.9 slim (glibc) wheel 1.7s 0.02s 18M

3.9 slim (glibc) - - 0.02s 18M

Imports

eval_type_backport
wrong
```
import eval_type_backport
```
correct
```
from eval_type_backport import eval_type_backport
```
The package provides a single function, not typically imported as the top-level package.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to use `eval_type_backport` to resolve a modern type hint like `str | None`. This function is typically used internally by other libraries (like Pydantic) to provide compatibility for newer Python typing features on older Python versions. The `globalns` and `localns` arguments provide the context for evaluating the type string, similar to `eval()`.

import sys
from __future__ import annotations

from eval_type_backport import eval_type_backport

class MyModel:
    field: str | None

def demonstrate_eval(cls):
    # Simulate a scenario where `str | None` might not be directly evaluable
    # e.g., on Python < 3.10 without __future__.annotations, or in certain contexts.
    # The backport ensures it resolves to typing.Union[str, None].
    # For this example, we're just showing the direct usage of the function.
    
    # Get the annotation for 'field'
    annotation = cls.__annotations__['field']
    
    # Evaluate it using the backport function
    evaluated_type = eval_type_backport(annotation, globalns=sys.modules[__name__].__dict__, localns={})
    
    print(f"Original annotation: {annotation!r}")
    print(f"Evaluated type: {evaluated_type!r}")

if __name__ == "__main__":
    demonstrate_eval(MyModel)