Registry / serialization / eval-type-backport

eval-type-backport

library0.3.1pypypi✓ verified 49d ago

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.

serialization type-stubs

pip install eval-type-backport

github ↗package ↗

Install & Compatibility

Where this runs

tested against v0.4.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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.026s · 17.8MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.5s · import 0.022s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

eval_type_backport

✓ from eval_type_backport import eval_type_backport

✗ import eval_type_backport

The package provides a single function, not typically imported as the top-level package.

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)

Debug

Known issues

gotchaThis 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.

affects: All versions

breakingIf 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.

affects: <3.10 for `X | Y` syntax; <3.9 for `list[X]` (PEP 585) syntax

gotchaWhile `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.

affects: Python 3.7-3.9 (for generic built-ins), Python 3.7-3.9 (for `X | Y`)

breakingA `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.

affects: All Python versions

Errors

Common errors & fixes

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

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.

TypeError: Unable to evaluate type annotation 'ClassVar'.

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.

ModuleNotFoundError: No module named 'eval_type_backport'

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.

Upgrade

Version history

0.4.0latest on PyPI

Audit

Dependencies

pythonrequiredRequires Python 3.7 or newer to run.

pytestoptionalUsed for running tests, not a runtime dependency.

Agent activity

66 hits · last 30 days

node

seranking-bot

ahrefsbot

mj12bot

amazonbot

googlebot

Resources

githubhttps://github.com/alexmojaki/eval_type_backport ↗

packagehttps://pypi.org/project/eval-type-backport/ ↗