Skip to content

Some improvements for Python 3.14 / PEP 649 support - #440

Closed
JelleZijlstra wants to merge 1 commit into
beartype:mainfrom
JelleZijlstra:pep649-redux
Closed

JelleZijlstra wants to merge 1 commit into
beartype:mainfrom
JelleZijlstra:pep649-redux

Conversation

@JelleZijlstra

Copy link
Copy Markdown

It's still very early for Python 3.14, but I decided to try running
beartype's test suite to see how well it works with all the annotations
changes that have landed in CPython.

There were a few test failures for boring reasons (mostly, the fact
that typing.ForwardRef is now in the annotationlib module). I fixed
some but not all of those.

I also tried to make beartype work well with code that relies on
new PEP 649 functionality, such as:

from beartype import beartype

@beartype
def f(x: notyetdefined) -> notyetdefined:
return x

class notyetdefined:
pass

f(notyetdefined())
f(1) # error

To support such code, I made beartype use annotationlib.get_annotations()
with the FORWARDREF format, which appears to work fine.

I will leave this as a draft for now since it's still early in the PEP 649
stage, but I feel this is a promising indicator that it shouldn't be too
hard to adapt beartype to the PEP 649 world.

It's still very early for Python 3.14, but I decided to try running
beartype's test suite to see how well it works with all the annotations
changes that have landed in CPython.

There were a few test failures for boring reasons (mostly, the fact
that typing.ForwardRef is now in the annotationlib module). I fixed
some but not all of those.

I also tried to make beartype work well with code that relies on
new PEP 649 functionality, such as:

from beartype import beartype

@beartype
def f(x: notyetdefined) -> notyetdefined:
    return x

class notyetdefined:
    pass

f(notyetdefined())
f(1)  # error

To support such code, I made beartype use annotationlib.get_annotations()
with the FORWARDREF format, which appears to work fine.

I will leave this as a draft for now since it's still early in the PEP 649
stage, but I feel this is a promising indicator that it shouldn't be too
hard to adapt beartype to the PEP 649 world.
@leycec

leycec commented Sep 24, 2024

Copy link
Copy Markdown
Member

Wondrousness! Thanks so much for this incredible show of strength, Typing Master @JelleZijlstra. I didn't even know annotationslib was on the cusp of becoming a standard thing. I bow before your overpowering skills. 🙇

It's wonderful to see that PEP 649 is now mostly trivially supportable, too. That's a tremendous relief for all of us on the runtime side of the aisle. You even generalized @beartype's low-level get_func_annotations_or_none() getter to ensure general-purpose PEP 649 support throughout the entire @beartype codebase. I am in awe. Most devs just run when they see the real @beartype.

All of your changes are literally perfect. I have nothing meaningful to add. When you're ready, I'll happily merge this. Let me know when you'd like me to push that giant glowing red "MERGE DIS!" button.

I do have a foolish question:

Is modification of the __annotations__ dictionary still a concern?

I recall that being a bit... complex in the initial PEP 649 writeup. To avoid destroying Python, @beartype tries (as hard as possible, anyway) to avoid modifying dunder attributes like __annotations__. Still, @beartype does currently modify __annotations__ in one or two choice locations. We all commit sins in our lives.

Should @beartype reconsider that? I should probably just re-read the new PEP 649 spec, huh? Oh, precious free time! Where art thou, free time? 🥹

@JelleZijlstra

Copy link
Copy Markdown
Author

One thing that might still change is that annotationlib might end up being called something else, so it may be better to wait a bit with merging. (The timeline is that Python 3.14 will enter its feature freeze in May 2025, which means we'll have to decide on things like the name of annotationlib by then, and that it will have its final release in October 2025. Plenty of time!)

Is modification of the __annotations__ dictionary still a concern?

This is something we're still talking about. What I'd currently like is written up at file:///Users/jelle/py/peps/build/pep-0749.html#effect-of-setting-annotations, but PEP 649 proposed something more complex, and we may go back to a version of that.

There's two kinds of modifying that we need to be concerned about:

  • Modifying the dictionary in place (func.__annotations__["key"] = value)
  • Assigning to the attribute (func.__annotations__ = some_dict). I saw some code in beartype that does this, apparently to replace string annotations with resolved annotations.

Modifying annotations will almost certainly continue to work in the sense that you can run func.__annotations__ = something and then if you access func.__annotations__, you get something back. But we're not sure yet on what will happen if you request annotations in the FORWARDREF or SOURCE formats. Your use cases for modifying the __annotations__ could help in making that decision.

@leycec

leycec commented Sep 25, 2024 •

Copy link
Copy Markdown
Member

Guh! I just wrote a doctoral thesis on this. Then GitHub ate my thesis. This truncated snippet of my former glory is all that remains. You should've seen the original post. It was a thing of wonder.

Interestingly, the @beartype codebase performs both kinds of __annotations__ modifications – but mostly not by choice. Let's break this down before I break GitHub down.

PEP 563 Resolution: Who Didn't See That One Coming?

@beartype generally prefers to only modify __annotations__ atomically (i.e., all-at-once); that's both optimal and thread-safe. Sadly, the existence of C-based @class, @static, and @property descriptor objects throws a significant spanner in the works. They proxy __annotations__ as a read-only attribute, requiring that @beartype fall back to modifying __annotations__ key-value pairs "in-situ" with brute-force iteration. The whole thing makes my eyes bleed:

# In the public "beartype._peps.pep563" submodule:
def resolve_pep563(...):
  ...

  # Attempt to...
  try:
      # Atomically (i.e., all-at-once) replace that callable's postponed
      # annotations with these resolved annotations for safety and efficiency.
      #
      # While the @beartype decorator goes to great lengths to preserve the
      # originating "__annotations__" dictionary as is, PEP 563 is
      # sufficiently expensive, non-trivial, and general-purpose to support
      # that generically resolving postponed annotations for all downstream
      # third-party callers is justified. Everyone benefits from replacing
      # useless postponed annotations with useful real annotations; so, do so.
      func.__annotations__ = arg_name_to_hint
  # If doing so fails with an exception resembling the following, then that
  # callable is *NOT* a pure-Python callable but rather a C-based decorator
  # object of some sort (e.g., class, property, or static method descriptor):
  #     AttributeError: 'method' object has no attribute '__annotations__'
  #
  # C-based decorator objects define a read-only "__annotations__" dunder
  # attribute that proxies an original writeable "__annotations__" dunder
  # attribute of the pure-Python callables they originally decorated. Ergo,
  # detecting this edge case is non-trivial and most easily deferred to
  # this late time. While non-ideal, simplicity >>>> idealism in this case.
  except AttributeError:
      # For the name of each annotated parameter and return of that callable
      # and the destringified type hint annotating this parameter or return,
      # overwrite the stringified type hint originally annotating this
      # parameter or return with this destringified type hint.
      #
      # Note that:
      # * The above assignment is an efficient O(1) operation and thus
      #   intentionally performed first.
      # * This iteration-based assignment is an inefficient O(n) operation
      #   (where "n" is the number of annotated parameters and returns of that
      #   callable) and thus intentionally performed last here.
      for arg_name, arg_hint in arg_name_to_hint.items():
          func.__annotations__[arg_name] = arg_hint

resolve_pep563() is a popular public @beartype API frequently called by downstream reverse dependencies like Plum as well as @beartype itself. My spidey sense is now tingling. 🕸️

Type Hint Deduplication: UHH. WUT.

Most PEP 484-compliant type hints deduplicate (i.e., memoize) themselves, reducing space and time consumption. Since @beartype internally memoizes itself on the basis of type hints, deduplicated type hints improve the speed of @beartype: e.g.,

$ python3.8
>>> from typing import List
>>> List[str] is List[str]
True  # <-- good. this is good.

Most PEP 585-compliant type hints do not deduplicate themselves, increasing space and time consumption. For all the reasons that deduplication is good in the modern era, the lack of deduplication is likewise bad: e.g.,

$ python3.9
>>> list[str] is list[str]
False  # <-- ...uhh, wut? i shake my fist at you, python 3.9!

@beartype resolves this discrepancy between PEP 484 and 585 by forcefully deduplicating all PEP 585 type hints. Why? Because everybody wants deduplication. So, @beartype deduplicates on behalf of humanity. For example, if the @beartype decorator sees that two distinct callables are both annotated as returning list[str], then @beartype:

  • Internally caches the first list[str].
  • Externally replaces the second list[str] return type hint in the __annotations__ of the second callable with its internally cached list[str].

As expected, @beartype achieves this saintly goal by simply replacing each specific key-value of the __annotations__ dictionary that benefits from deduplication. If @beartype had to, it could instead do that with an atomic replacement of the entire __annotations__ dictionary all-at-once. In fact, maybe it should be doing that already. Let's not think about the labyrinthian @beartype codebase too much. 😅

But... yeah. It'd be kinda nice to continue to support both use cases in a backward-compatible manner – even if the internal CPython implementation required to do so is a little inefficient or cumbersome or whatevahs.

But... yeah. You know best, Typing Master @JelleZijlstra. I leave this in your capable paws. Which leads us to...

FORWARDREF: Still Not the Default, Huh?

The preference for basically all third-party packages that introspect __annotations__ would be for __annotations__ access to internally default to the forward-thinking FORWARDREF mode of operation. That's always what everyone wants. Any other default invites non-determinism from the perspective of third-party consumers, because __annotations__ then becomes a ticking time bomb that non-deterministically explodes some (but not all) of the times you access it.

Since third-party consumers can't predict which __annotations__ contain forward references requiring FORWARDREF to resolve and which don't, the only safe assumption for us is that all __annotations__ contain forward references requiring FORWARDREF to resolve – which really just means that the default is effectively already FORWARDREF for us.

tl;dr:

Any default other than FORWARDREF breaks forward-compatibility with existing code accessing __annotations__.

This isn't an issue for @beartype so much as this is an issue for everybody else. The @beartype codebase avoids directly accessing __annotations__ by deferring to the higher-level get_func_annotations() getter that you've so wonderfully patched for us. You're wonderful! Let's please reiterate this critical point.

It's everybody else I'm concerned about. Turning existing legacy code that directly accesses __annotations__ into a ticking time bomb is pretty rough. I mean, I get it. If that's what we have to do to get transparent forward reference resolution, then I see the "value add" there. But do we have to do that? Can't we just make FORWARDREF the default?

Then again, I'm a bald middle-aged redneck in the Canadian wilderness. It's best not to listen to people like me. 😆

@JelleZijlstra

Copy link
Copy Markdown
Author

Thank you! I'm going to have to think about whether we could make FORWARDREF the default; I do agree it's what many users should want.

Regarding caching of generic aliases, there have been some attempts to change CPython's behavior there, but getting the caching right has been tricky because some users want union ordering to be preserved: python/cpython#101859 (comment). We may have to think more about how to achieve caching.

@JelleZijlstra

Copy link
Copy Markdown
Author

We talked about this at the CPython core sprint and the consensus is that it's less surprising for users to keep VALUE the default. It keeps behavior that is more like what people are used to on previous Python versions.

@leycec

leycec commented Oct 18, 2024 •

Copy link
Copy Markdown
Member

Guh! Users hate change, huh? It's undeniably true. Change is painful. Butterflies know this in their guts. But users are really gonna hate unexpected and unreadable AttributeError or TypeError or [whatevah] exceptions when code that previously worked when accessing __annotations__ now no longer works.

PEP 649 may have bigger issues, though. These issues are mostly not of PEP 649's making. They live at the intersection between PEP 649 and other PEPs and static type-checkers and linters. This is actually why I haven't immediately replied. I wasn't ghosting you, @JelleZijlstra! I swears it. I was deeply cogitating about all this stuff. Without further ado...

@leycec's Big List of PEP 649 Misery

You've probably already hashed out all of this stuff with the other CPython devs – but a bulleted list never hurt no one:

  • PEP 526-compliant variable assignment annotations subscripted by one or more forward references. Does PEP 649 intersect with annotations that only exist at static analysis time? Hybrid runtime-static type-checkers like @beartype and typeguard do, because we both type-check these assignments at runtime: e.g.,

    muh_global_var: Optional[MuhUndefinedType] = None  # <-- what happens here? is "MuhUndefinedType" proxied by PEP 649 here? @beartype kinda needs that to happen.
    class MuhUndefinedType(object): ...
  • PEP 484- or 585-compliant generics subclassing one or more type hints subscripted by one or more forward references. Does PEP 649 intersect with annotations that only exist in __orig_bases__ rather than __annotations__? Again, @beartype (and probably also typeguard) does, because @beartype type-checks generics all the way up the __orig_bases__ type hint "hierarchy" at runtime: e.g.,

    class MuhGenericSequence(Sequence[MuhUndefinedType]): ...  # <-- what happens here? is "MuhUndefinedType" proxied by PEP 649 here? @beartype kinda needs that to happen.
    def muh_func(muh_generic: MuhGenericSequence): ...  # <-- what about here? is "MuhUndefinedType" still proxied by PEP 649 here? @beartype kinda needs that to happen.
    class MuhUndefinedType(object): ...
  • PEP 695-compliant type statements whose right-hand sides (RHSes) contain one or more forward references. So, funny story. It turns out that PEP 695 is fundamentally broken at runtime. Who knew, huh? As currently implemented, PEP 649 doesn't actually support forward references despite claiming all over the place that it supports forward references: e.g.,

    $ python3.12
    >>> type Animals = Lions | Tigers | Bears | OhMy
    >>> Animals.__value__
    Traceback (most recent call last):
      File "<python-input-1>", line 1, in <module>
        Animals.__value__
      File "<python-input-0>", line 1, in Animals
        type Animals = Lions | Tigers | Bears | OhMy
                       ^^^^^
    NameError: name 'Lions' is not defined

    Pretty sure a NameError is not a forward reference. PEP 695 is horribly broken in other obvious ways, too. For example, PEP 695 explicitly instructs users to embed strings in PEP 604-style new unions:

    # A type alias that includes a forward reference
    type AnimalOrVegetable = Animal | "Vegetable"

    But PEP 604 explicitly prohibits strings in new unions! This is clearly evidenced by stringifying the first forward reference in the prior type statement. If "Vegetable" works, then so should "Animal". Right? Clearly. Instead, CPython erupts with madness:

    $ python3.12
    >>> type AnimalOrVegetable = "Animal" | "Vegetable"
    >>> AnimalOrVegetable.__value__
    Traceback (most recent call last):
      File "<python-input-3>", line 1, in <module>
        AnimalOrVegetable.__value__
      File "<python-input-2>", line 1, in AnimalOrVegetable
        type AnimalOrVegetable = "Animal" | "Vegetable"
                                 ~~~~~~~~~^~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for |: 'str' and 'str'

    That's definitely not a forward reference. So, PEP 695 lies about everything. I'm facepalming over here. 🤦

And now we get to the real biggie. Everything above was just chump change. Because...

Ruff Hates PEP 695. There, I Said It.

If I asked you for the name of Python's most popular static linter or type-checker as of today, you might admit that "Okay. It's Ruff." But you'd probably prefer to suggest that it's mypy or pyright or pylint or flake8 or somebody else. Anybody else! But...

...yeah. It's Ruff. Mostly just because Ruff is (by far and away) the fastest static linter, mostly just because Ruff is implemented in Rust. This means that what Rust thinks about Python is now a Big Deal™. Unfortunately for us all, Rust hates PEP 695, PEP 563, and runtime typing in general. This is what Rust is now publicly advising everybody to do – and actually emitting fatal "errors" over:

# Instead of this:
from __future__ import annotations
from pathlib import Path

def func(path: Path) -> str:
    return str(path)


# Use instead:
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pathlib import Path

def func(path: Path) -> str:
    return str(path)

Rust calls this "error" and corresponding "advice" THC003. Let's unpack exactly what THC003 is now advising literally all Python code everywhere to do:

  • Under Python ≥ 3.14, from __future__ import annotations (probably) silently reduces to a noop.
  • At runtime, TYPE_CHECKING is False. That entire if conditional also silently reduces to a noop.

Rust's THC003 "error" thus reduces code that previously worked at runtime to code that no longer works at runtime. The above advice reduces to this non-working code:

def func(path: Path) -> str:
    return str(path)

That code now violates PEP 649 as well as PEP 563 and all runtime type-checkers and type hint introspectors. Why? Because PEP 649 coerces the Path type hint in the above code into a forward reference proxy. Likewise, PEP 563 coerces the same hint into the stringified forward reference "Path". But Path doesn't exist in the current submodule! Path only exists in the external pathlib module.

Rust's THC003 "error" destroys essential context needed to resolve forward references at runtime.

Uhh... That Sounds Kinda Bad.

It's kinda bed. This is why PEP 563 explicitly advises use of absolute rather than relative forward references to resolve circular imports:

import typing

if typing.TYPE_CHECKING:
    import expensive_mod

def a_func(arg: expensive_mod.SomeClass) -> None:
    a_var: expensive_mod.SomeClass = arg
    ...

For the same reason, mypy unsurprisingly offers identical advice:

# File foo.py:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import bar

def listify(arg: 'bar.BarClass') -> 'list[bar.BarClass]':
    return [arg]

# File bar.py:

from foo import listify

class BarClass:
    def listifyme(self) -> 'list[BarClass]':
        return listify(self)

@beartype loves and adores what PEP 563 and mypy instruct users to do, because those instructions preserve essential context needed to resolve forward references at runtime.

B-b-but Surely Nobody Is Doing What Ruff Is Saying!?

Everybody is doing what Ruff is saying. Everybody includes:

  • Pydantic and thus the popular LangChain LLM AI ML toolkit, which leverages Pydantic. 😬
  • xarray. 🤮

So many downstream third-party packages are now doing what Ruff is saying that our upcoming @beartype 0.19.1 patch release internally blacklists both Pydantic and xarray. Both packages violate PEP 563 and 649. @beartype is PEP-compliant. But users understandably want @beartype to support Pydantic, LangChain, and xarray!

@beartype 0.19.1 resolves this discrepancy by pretending that Pydantic and xarray no longer exist. They are dead to us.

@beartype 0.19.2 will tighten things up even further by:

  • Explicitly emitting warnings on detecting Pydantic or xarray.
  • Explicitly emitting warnings on each usage of a from ... import ...-style statement embedded in an if TYPE_CHECKING: block. Those imports are all indicative of a runtime-hostile forward reference antipattern, as now popularized by Ruff's THC003.
  • Internally repairing these broken forward references with stupid(ly clever) AST transformations. This wouldn't be the first broken thing @beartype has repaired at AST transformation-time. This won't be the last, either. 😢

@beartype Ain't Havin' None of It, Ruff

But PEP 649 shouldn't have any of it either. It would probably be wise to get out ahead of this antipattern before it proliferates like a malignant tumour through the Python ecosystem any further. Somebody who is not me should probably consider adding a new subsection to PEP 649 entitled "Circular Imports" or "Import Cycles" or [whatevah]. Clarity and unambiguity would do wonders to putting this beast to rest.

To preserve both backward compatibility and sanity going forward, PEP 649 should ideally:

  • Continue to promote the same approach taken by both PEP 563 and mypy.
  • Reject the contrary approach taken by Ruff's THC003, Pydantic, and xarray.

I beg many things of you, @JelleZijlstra. But this, I beg of you the most. 🙇‍♂️

@JelleZijlstra

Copy link
Copy Markdown
Author

PEP 526-compliant variable assignment annotations

What happens in your example is that the assignment goes through fine, because the annotations are not evaluated when the assignment happens. When the module execution is done, the annotations are gathered up in an __annotate__ function that can be used to retrieve the annotations.

How does beartype check such assignments at runtime, while the module is executing? That might be a use case that is difficult to preserve, but I also don't see how you can currently do that without fairly invasive hacks.

PEP 484- or 585-compliant generics subclassing one or more type hints subscripted by one or more forward references

Base classes are not annotations. Nothing is changing here.

PEP 695-compliant type statements whose right-hand sides (RHSes) contain one or more forward references

The syntax is not changing here in Python 3.14. Forward references work, but they must be defined when you actually evaluate the type alias. However, in Python 3.14 we're planning to add a way to retrieve the value of a type alias in the annotations FORWARDREF format: annotationlib.call_evaluate_functions(Animals.__evaluate_value__, Format.FORWARDREF).

PEP 695 explicitly instructs users to embed strings in PEP 604-style new unions

Where do you see that? I would recommend against looking too much at the PEPs only; the type system is now specified in https://typing.readthedocs.io/en/latest/spec/aliases.html#type-statement, which doesn't say anything about strings.

Since the value of type aliases is lazily evaluated, you shouldn't need to use strings in them.

Ruff Hates PEP 695

Ruff has a number of rules of questionable value, because it pulled in all the rules it could find from various popular(ish) flake8 plugins. That doesn't mean that everybody who is running Ruff enables all these rules. People who use runtime typing are obviously going to have a hard time if they use this TCH003 rule; that means they shouldn't use that rule if they care about runtime typing.

@leycec

leycec commented Jan 11, 2025 •

Copy link
Copy Markdown
Member

Gah! So sorry for the extreme delay... and for shamefully breaking this PR. I knew I should have merged this immediately sight unseen. Instead, I was dumb. Now one of must suffer by manually resolving the growing laundry list of merge conflicts. Pain intensifies. :hurtrealbad:

How does beartype check such assignments at runtime, while the module is executing?

...heh. @beartype doesn't. That's just it. That's where all the cleverness and madness lies.

Modern runtime type-checkers like @beartype and typeguard aren't actually runtime type-checkers (in the pure sense of the word "runtime") anymore. We're not doing what everyone thinks we're doing. @beartype and typeguard are hybrid third-generation runtime-static type-checkers. That is, @beartype and typeguard perform both runtime type-checking and static type-checking.

In @beartype's case, @beartype performs a preliminary phase of static type-checking on each module importation before CPython executes that module. How? beartype.claw import hooks (e.g., beartype.claw.beartype_this_package()). Like all import hooks, beartype.claw import hooks register import path hooks that then dynamically apply abstract syntax tree (AST) transformations on each module importation. Pretty fun stuff.

Specifically, beartype.claw import hooks transform...

# PEP 526-compliant annotated variable assignments like this...
muh_attr: MuhTypeHint = muh_value

# ...into runtime type-checking validation like this.
from beartype.door import die_if_unbearable
muh_attr = muh_value
die_if_unbearable(muh_attr, MuhTypeHint)

Works flawlessly without issue or edge cases in both @beartype and typeguard. Certainly, invasive hacks are neither required nor desired. I'm personally allergic to fragile kludges that fall apart when you squint at them. I don't tolerate any of that sort of ugly in my codebase.

Most of us in this problem space are similar. The techbros who write fragile code? They're no longer with us. Their type-checkers were unmaintainable. They broke and nobody bothered fixing them. They died and then got replaced with type-checkers that actually worked.

@beartype is hard enough to maintain without hacks. 😆

Base classes are not annotations.

Hard disagree with that. The whole point of PEP 484-, 544-, and 585-compliant generics is to subclass a type hint, which typing systems then use to validate those generics. The hints that generics subclass absolutely satisfy the PEP 747-compliant typing.TypeForm annotation. They're 100% PEP-compliant type hints.

For example:

from collections.abc import Iterable, Container
class IterableContainer[T](Iterable[T], Container[T]): ...

Iterable[T] and Container[T] both satisfy typing.TypeForm. Ergo, they are type hints. They're also "base classes" in the sense that the IterableContainer subclass "subclasses" those "base classes." Of course, we know better. Type erasure erases those "base classes" into the __orig_bases__ dunder attribute.

Still, at least semantically, they're "base classes." When IterableContainer is subscripted by a child type hint (e.g., as IterableContainer[str]), that child type hint then dynamically replaces the type variable T parametrizating those base classes. So:

# This type hint...
IterableContainerStr = IterableContainer[str]

# ...is effectively equivalent to this type.
class IterableContainerStr(Iterable[str], Container[str]): ...

All of the above only works because Iterable[T] and Container[T] are both type hints.

Anyway, arguments about semantics are entirely besides the point. The point is that real-world generics should be able to subclass type hints subscripted by forward references to types that are currently undefined: e.g.,

class IterableContainerStr(Iterable[WhatTheHeck], Container[WhatTheHeck]): ...
class WhatTheHeck(object): ...

The IterableContainerStr type subclasses the Iterable[WhatTheHeck] and Container[WhatTheHeck] type hints referring to the WhatTheHeck type. Since WhatTheHeck is still undefined at the time the IterableContainerStr type is declared, PEP 649 should ideally have something to say about this.

Does PEP 649 have something to say about this? Probably not, huh? D users just have to continue manually stringifying forward references in generics? Is the following really the only way to reference undefined types in generics?

class IterableContainerStr(Iterable['WhatTheHeck'], Container['WhatTheHeck']): ...
class WhatTheHeck(object): ...

Kinda wierd that users can use unquoted forward references in some syntactic contexts but not in others. Ideally, users would be able to globally use unquoted forward references in all possible valid syntactic contexts for a type hint, right? The alternative is mass confusion and frustration.

Oh, well. Guess we're going with mass confusion and frustration. 😮‍💨

Forward references work, but they must be defined when you actually evaluate the type alias.

So... what you're saying is that forward references don't work in type statements. The definition of a forward reference is "something that safely refers to something else that has yet to be defined without blowing up when you access it." But type aliases referencing types that have yet to be defined blow up when you access them. So... they actually prohibit rather than support forward references.

For efficiency, @beartype dynamically generates type-checking code at decoration time. If a user annotates a function parameter with a type alias referencing types that have yet to be defined, @beartype needs that alias to be introspectable without blowing up.

Thankfully...

annotationlib.call_evaluate_functions(Animals.__evaluate_value__, Format.FORWARDREF)

Superb! That's exactly what @beartype needs. I mean, the syntax is pretty awful. It'd be nice if type aliases just behaved like this by default, because this is what everybody wants by default. Nobody wants type aliases that spontaneously explode whenever you directly access their __value__ attribute. They want type aliases that work robustly across all use cases without exploding.

Still, I'll take it. @beartype takes whatever scraps it can get. 🥲

PEP 695 explicitly instructs users to embed strings in PEP 604-style new unions

Where do you see that?

I mean, it's right there in PEP 695:

# A type alias that includes a forward reference
type AnimalOrVegetable = Animal | "Vegetable"

Animal | "Vegetable" isn't syntactically valid Python. Period. You can't take the union of a str. The str builtin doesn't support the __or__() dunder method, nor should the str builtin support the __or__() dunder method.

It's like nobody even peer-reviewed that thing. I sigh. </sigh>

I would recommend against looking too much at the PEPs only...

Respectfully disagree. Standards matter. In fact, standards are pretty much the only thing that matter to @beartype. For type-checkers, everything else is just gossip and hearsay. We're here to enforce uniform standards – whatever those standards might be. All other documentation (although occasionally valuable) is ultimately pretty incidental to the rigorous work performed by type-checkers.

Since the value of type aliases is lazily evaluated, you shouldn't need to use strings in them.

Under Python ≤ 3.13, type aliases absolutely are not lazily evaluated from @beartype's perspective. @beartype needs "lazily evaluated" to mean "unquoted forward references are transparently replaced with objects proxying __instancecheck__() and __subclasscheck__() calls that internally resolve the external types those unquoted forward references refer to at the last possible moment." Because type aliases currently don't behave that way, users absolutely need to use strings in type aliases to safely refer to types that have yet to be defined. For @beartype users, type aliases definitely do not support unquoted forward references.

Thankfully, that seems to be a moot point under Python ≥ 3.14. @beartype gives thanks and praise. 🙇

And... Now We're Both Tired

This is what happens when @leycec writes essays on a Friday night. Everyone ends up passed out in the futon in a puddle of their sputum. 🤤 🛌

@leycec

leycec commented May 17, 2025

Copy link
Copy Markdown
Member

...finally. With the recent release of @beartype 0.21.0, @beartype now fully supports PEP 695 type aliases – recursion, unquoted forward references, warts, and all. This was a face-numbing project three years in the making. It seems like yesterday. I don't know where those three years went. I only know that I can finally move on from the accumulated QA trauma. 😅

Python 3.14 + PEP 649 is now up! Let us do this. Thanks so much yet again for this phenomenal pull request, @JelleZijlstra. I sincerely apologize for not merging this immediately. Since a giant pile of non-trivial merge conflicts has erupted, I'll now be merging this manually. I'm rolling up my sleeves. This is gonna get greasy.

Without further ado, Leonardo DiCaprio will now announce what is about to happen.


PEP 649: pretty sure it's that intense

leycec added a commit that referenced this pull request May 17, 2025
This commit is the first in a commit chain adding official support for
both Python 3.14 *and* PEP 649- and 749-compliant unquoted forward
references, en-route to manually merging long-standing pull request #440
by wondrous CPython core dev @JelleZijlstra (Jelle Zijlstra).
Specifically, this commit begins detecting
`annotationlib.ForwardRef`-style forward references supported under
Python ≥ 3.14. (*Libidinous dinosaurs do not have livid lipids!*)
leycec added a commit that referenced this pull request May 20, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649- and 749-compliant unquoted forward
references, en-route to manually merging long-standing pull request #440
by wondrous CPython core dev @JelleZijlstra (Jelle Zijlstra).
Specifically, this commit negligibly revises docstrings to pretend that
I actually did something meaningful with Monday evening rather than get
repeatedly rickrolled by `conda-forge` (which is what happened instead).
Conda-forge: This is why I don't make meaningful progress on a Monday.
(*Trepidatious traps are mendacious, men!*)
leycec added a commit that referenced this pull request May 21, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649- and 749-compliant unquoted forward
references, en-route to manually merging long-standing pull request #440
by wondrous CPython core dev @JelleZijlstra (Jelle Zijlstra).
Specifically, this commit begins generalizing our existing private
`get_func_annotations()` getter to internally defer to the PEP
649-compliant `annotationslib.get_annotations()` getter. (*Grand AND, Mandy!*)
leycec added a commit that referenced this pull request May 24, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649- and 749-compliant unquoted forward
references, en-route to manually merging long-standing pull request #440
by wondrous CPython core dev @JelleZijlstra (Jelle Zijlstra).
Specifically, this commit begins defining a new private
`get_pep649_hintable_annotations()` getter internally deferring to the
PEP 649-compliant `annotationslib.get_annotations()` getter. (*Rough stuff!*)
leycec added a commit that referenced this pull request May 27, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra).

Specifically, this commit is the first in a commit subchain refactoring
the @beartype codebase to guaranteeably modify annotations only
anatomically (i.e., all-at-once). Although @beartype sometimes modifies
annotations anatomically, @beartype also occasionally modifies
annotations iteratively in a piecemeal (i.e., individual type hint by
individual type hint) fashion. PEP 649 supports the former but *not* the
latter workflow. Consequently, this commit subchain refactors all
instances of the latter into the former workflow. Doing so is
non-trivial, requiring @beartype to store additional metadata context at
decoration-time so as to reconstruct the desired new annotations
atomically when finalizing the decoration of a callable or class.
Brutal, in other words. Simply brutal.

(*Brute lute!*)
leycec added a commit that referenced this pull request May 28, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra).

Specifically, this commit is the next in a commit subchain defining a
new private `get_pep649_hintable_annotations()` getter internally
deferring to the PEP 649-compliant `annotationslib.get_annotations()`
getter. (*Crude altitude atop a rude attitude!*)
leycec added a commit that referenced this pull request May 29, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra).

Specifically, this commit is the next in a commit subchain defining a
new private `get_pep649_hintable_annotations()` getter internally
deferring to the PEP 649-compliant `annotationslib.get_annotations()`
getter. (*Demonstrable monstrosity demons!*)
leycec added a commit that referenced this pull request May 30, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra).

Specifically, this commit is the next in a commit subchain defining a
new private `get_pep649_hintable_annotations()` getter internally
deferring to the PEP 649-compliant `annotationslib.get_annotations()`
getter. (*Rain of brainiacs or maniacal maniacs!?*)
leycec added a commit that referenced this pull request May 31, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit defines a new private `clear_pep649_caches()` function clearing
all internal data structures caching `__annotations__` dunder
dictionaries returned by the probably notoriously slow PEP 649-compliant
`annotationslib.get_annotations()` getter. (*Notorious toroids or not n-ary notaries!?*)
leycec added a commit that referenced this pull request Jun 3, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the first in a subcommit chain generalizing the existing
public `set_pep649_hintable_annotations()` function to support Python
3.14 and PEP 649. Needless to say, the road ahead remains long, dirty,
thankless, and filled with potholes. (*Rowdy roadie!*)
leycec added a commit that referenced this pull request Jun 4, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the next in a subcommit chain generalizing the existing
public `set_pep649_hintable_annotations()` function to support Python
3.14 and PEP 649. Needless to say, the road ahead remains long, dirty,
thankless, and filled with QA potholes. (*Wholly holes! Holy holly!*)
leycec added a commit that referenced this pull request Jun 6, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the next in a subcommit chain generalizing the existing
public `set_pep649_hintable_annotations()` function to support Python
3.14 and PEP 649. Needless to say, the road ahead remains long, dirty,
thankless, and filled with QA potholes. (*Crustaceous mustiness ate curvaceousness!*)
leycec added a commit that referenced this pull request Jun 7, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the next in a subcommit chain generalizing the existing
public `set_pep649_hintable_annotations()` function to support Python
3.14 and PEP 649. Needless to say, the road ahead remains long, dirty,
thankless, and filled with QA potholes. (*Act, rectilinear delicatessen in a delicate tesseract!*)
leycec added a commit that referenced this pull request Jun 8, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the last in a subcommit chain generalizing the existing
public `set_pep649_hintable_annotations()` function to support Python
3.14 and PEP 649. Needless to say, the road ahead remains long, dirty,
thankless, and filled with QA potholes. (*Phenomenal phenomenology!*)
leycec added a commit that referenced this pull request Jun 10, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the first in a subcommit chain exhaustively unit-testing both:

* The PEP 649-compliant implementation of our private
  `beartype._util.hint.pep.proposal.pep649.set_pep649_hintable_annotations()`
  getter under Python >= 3.14.
* The PEP 649-noncompliant implementation of that same getter under
  Python <= 3.13.

Needless to say, the road ahead remains long, dirty, thankless, and
filled with QA potholes. (*The first thirst!*)
leycec added a commit that referenced this pull request Jun 24, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit documents significant improvements to the existing API and
implementation of our private `beartype._util.hint.pep.proposal.pep649`
submodule required to fully address the tangentially related feature
request #534 (i.e., `beartype.door.is_subhint()` support for PEP
589-compliant `TypedDict` subclasses). Although seemingly unrelated,
comparing `TypedDict` subclasses according to the subhint relation
interestingly requires efficient memoized access to the PEP
649-compliant `Format.STRING` rendition of the annotations dictionaries
for `TypedDict` subclasses containing one or more unquoted forward
references under Python >= 3.14.

Needless to say, the road ahead remains long, dirty, thankless, and
filled with QA potholes. (*Diffuse suffusion diffidently suffices indifference!*)
leycec added a commit that referenced this pull request Jun 27, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the first in a commit subchain resolving internal issues in
the existing API and implementation of our private
`beartype._util.hint.pep.proposal.pep649` submodule documented by the
16th commit in this commit chain. Needless to say, the road ahead
remains long, dirty, thankless, and filled with QA potholes.
(*No somber Novembers or novel members!*)
leycec added a commit that referenced this pull request Jun 28, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the next in a commit subchain resolving internal issues in
the existing API and implementation of our private
`beartype._util.hint.pep.proposal.pep649` submodule documented by the
16th commit in this commit chain. Needless to say, the road ahead
remains long, dirty, thankless, and filled with QA potholes. (*Too rigid didgeridoo!*)
leycec added a commit that referenced this pull request Jun 29, 2025
This commit is the next in a commit chain adding official support for
both Python 3.14 *and* PEP 649-compliant unquoted forward references,
en-route to manually merging long-standing pull request #440 by wondrous
CPython core dev @JelleZijlstra (Jelle Zijlstra). Specifically, this
commit is the last in a commit subchain resolving internal issues in
the existing API and implementation of our private
`beartype._util.hint.pep.proposal.pep649` submodule documented by the
16th commit in this commit chain. Needless to say, the road ahead
remains long, dirty, thankless, and filled with QA potholes.
(*Soothingly onward, wayward soothsayer!*)
@leycec

leycec commented Jul 1, 2025

Copy link
Copy Markdown
Member

Merged by 2b44dbf! Thanks to your astounding volunteerism (and gentle prodding in the back), @beartype now purportedly supports PEP 649. PEP 749 support has yet to happen – but hopefully will over the course of the summer. Which will be just in time for...

Full-blown Python 3.14 support! That still has yet to happen, too. According to impressive Fedora dev @gotmax23 over at issue #537, the @beartype test suite currently has 80 failing tests under Python 3.14. Win some, lose some. Some GitHub commits are like that. 😂

Further Commentary: "Will @leycec not stop talking?"

Because I am annoyingly loquacious, I have a bucket-load to say about all of this on the CPython issue tracker at some future date. Surprisingly, most of it is good. I have much praise. PEP 649 is a substantial real-world improvement over PEP 563, which was literally unusable at runtime. PEP 649 purports to work and then does actually work. I applaud both you and @larryhastings. 👏 👏

Not all that glitters is gold, though. I hit a few genuine bugs, performance regressions, and usability concerns with respect to PEP 649. I should document them before I forget them. Sadly, I am tired and so are you. Let us just close this and pretend I documented everything.

Thanks yet again for being so forthright, @JelleZijlstra. This PR closure is for you. 👍

@leycec leycec closed this Jul 1, 2025
@JelleZijlstra

Copy link
Copy Markdown
Author

Thanks for your work! Please let us know on the CPython issue tracker if you'd like to see anything changed while 3.14 is still in beta.

@leycec

leycec commented Jul 1, 2025

Copy link
Copy Markdown
Member

Ho, ho... That's a dangerous yet welcome request.

I have much that is boring to say, yet sadly no time with which to bore you with it. Supporting Python 3.14 has proven... non-trivial. I tried to make @beartype robust against porting issues. Clearly, I failed. Once I've finally nailed Python 3.14 down to the ground, I'll happily chat with everybody on the CPython issue tracker.

I suspect that some sort of PEP 849 follow-up to PEP 749 will probably be eventually required. There's a prominent edge case that PEP 563 supports that neither PEP 649 nor 749 appear to support. Authoring and implementing a new PEP probably can't happen by this October. So, my prevaricating and doing absolutely nothing is probably fine... probably. There sure is a lot of probably happening here, isn't there?

Thanks again for your immense life-long work with Python. Have a great summer in Orinda, too. That place looks amazing. What a super-fun ecotourism place to live. 😄

adamtheturtle added a commit to VWS-Python/vws-python-mock that referenced this pull request Jan 28, 2026
Python 3.14's deferred annotation evaluation (PEP 649) causes
`_Stringifier.__format__` to raise a TypeError when beartype
inspects function signatures at test collection time.

This is a workaround until beartype 0.23 is released with full
Python 3.14 support.

See:
- beartype/beartype#594
- beartype/beartype#440

Co-Authored-By: Claude Opus 4.5 <[email protected]>
adamtheturtle added a commit to VWS-Python/vws-python-mock that referenced this pull request Apr 26, 2026
* Bump sphinx from 8.2.3 to 9.1.0

Bumps [sphinx](https://github.com/sphinx-doc/sphinx) from 8.2.3 to 9.1.0.
- [Release notes](https://github.com/sphinx-doc/sphinx/releases)
- [Changelog](https://github.com/sphinx-doc/sphinx/blob/master/CHANGES.rst)
- [Commits](sphinx-doc/sphinx@v8.2.3...v9.1.0)

---
updated-dependencies:
- dependency-name: sphinx
  dependency-version: 9.1.0
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>

* Bump doc8

* Support Python 3.14

* Don't bump Sphinx

* Fix secrets file lookup for multi-Python matrix

Use modulo arithmetic to map job index to secrets file index,
ensuring that adding Python versions to the matrix doesn't break
the secrets file lookup. Each test pattern maps to the same
secrets file regardless of Python version.

The number of secrets files is determined dynamically from
the extracted tarball.

* Support only 3.14

* Fix ruff

* Revert "Fix ruff"

This reverts commit 9a342f4.

* Ignore ruff TC rules until beartype supports TYPE_CHECKING

Beartype requires imports to be available at runtime, not just under
`if TYPE_CHECKING`. See beartype/beartype#594
for when beartype 0.23 will add support for TYPE_CHECKING imports.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Remove runtime beartype application to test functions

Python 3.14's deferred annotation evaluation (PEP 649) causes
`_Stringifier.__format__` to raise a TypeError when beartype
inspects function signatures at test collection time.

This is a workaround until beartype 0.23 is released with full
Python 3.14 support.

See:
- beartype/beartype#594
- beartype/beartype#440

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* Drop pytest-beartype-tests due to Python 3.14 annotation issue

* [pre-commit.ci lite] apply automatic fixes

* Apply ruff format (PEP 758 except syntax)

* Restore pytest-beartype-tests; disable plugin in repeated pytest.main calls

* Ignore .claude/scheduled_tasks.lock

* Add 'stringify' to spelling dict

* Use real subprocess for pytest collection to avoid plugin state accumulation

* Add new tests to CI matrix; exclude meta-tests from collected-once check

* Restore Python 3.14 in test workflow matrix after merge

* Use real subprocess in test_custom_linters to avoid beartype state accumulation

* Add 'subprocess' to spelling dict

* Re-apply subprocess collection: in-process approach fails on Python 3.14 full-suite runs

* Bump pytest-beartype-tests to 2026.4.26; revert subprocess workaround in ci/test_custom_linters.py

* Run coverage tool on Python 3.14 to parse PEP 758 except syntax

* Set Python 3.14 via setup-uv python-version on coverage job

* Drop comment on coverage job python-version

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <[email protected]>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants