13549.bugfix.rst

Overview

This file documents a critical bugfix related to Python function signature inspection in version 3.14. Specifically, it addresses the problem of evaluating type annotations during the inspection of function signatures, which previously caused crashes during module collection.

In Python, type annotations may reference types imported only within a `if TYPE_CHECKING:` block to avoid runtime overhead or circular imports. However, when these annotations are evaluated eagerly (instead of being treated as strings or postponed), it can lead to import errors or crashes if the types are not actually available at runtime.

This bugfix ensures that type annotations are no longer evaluated during signature inspection in Python 3.14, preventing such crashes and improving the robustness of module collection and introspection processes.

Functionality

Prevents evaluation of type annotations when inspecting function signatures under Python 3.14.
Ensures compatibility with usage of from future import annotations and if TYPE_CHECKING: blocks.
Avoids import errors and crashes during module collection and inspection phases in the system.

Detailed Explanation

While this file content is brief and does not contain explicit code, the underlying implementation likely involves changes to the introspection logic, such as:

Using inspect.signature() or similar APIs carefully to avoid triggering annotation evaluation.
Leveraging Python's support for postponed evaluation of annotations (PEP 563) or adapting to Python 3.14's behavior.
Adjusting the type inspection strategy to treat annotations as strings or deferred objects when possible.

By not evaluating annotations, the system prevents execution of imports or code that might only be available in a type-checking context, thus preventing crashes.

Usage Example

Consider a module with the following pattern:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from some_module import SomeType

def func(arg: 'SomeType') -> None:
    pass

Prior to this fix, inspecting `func`'s signature might attempt to evaluate `'SomeType'` annotation, causing import errors if `some_module` is unavailable at runtime.

With this fix, annotation evaluation is skipped or deferred, allowing signature inspection without import errors.

Interaction with the System

This fix is important in systems that perform dynamic module loading, test discovery, or API introspection where function signatures are inspected programmatically.

It improves stability during module collection phases.
Prevents crashes in tooling such as test runners, documentation generators, or IDEs that analyze function signatures.
Enhances compatibility with modern Python typing practices, especially in codebases that use if TYPE_CHECKING: and postponed annotation evaluation.

Mermaid Diagram

Since the file concerns behavior around function signature inspection and annotation evaluation, the diagram below illustrates the conceptual workflow of the enhanced introspection process with the bugfix applied:

flowchart TD
    A[Start: Inspect Function Signature] --> B{Python Version >= 3.14?}
    B -- Yes --> C[Do NOT Evaluate Annotations]
    B -- No --> D[Evaluate Annotations Normally]
    C --> E[Return Signature with Deferred Annotations]
    D --> E
    E --> F[Use Signature for Module Collection / Introspection]
    F --> G[End]

    style C fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#bbf,stroke:#333,stroke-width:2px

The decision node checks the Python version.
For Python 3.14 and later, annotation evaluation is skipped.
The signature is returned with deferred or string annotations, preventing import-related crashes.
The signature is then safely used in module collection or other introspection activities.

Summary

This bugfix enhances the robustness of function signature inspection by preventing evaluation of type annotations in Python 3.14, particularly in scenarios involving conditional imports within `if TYPE_CHECKING:` blocks. It addresses a critical stability issue during module collection and introspection, aligning with modern Python type hinting best practices and future language versions.