Add initial support for Python 3.14

[Viicos]

Change Summary

Fixes (partially) #11613.

The remaining failing tests require:

• Raise consistent NameError in ForwardRef.evaluate() python/cpython#135646
• gh-136316: Make typing.evaluate_forward_ref better at evaluating nested forwardrefs python/cpython#136319

both to be available in 3.14a4.

This PR adds basic support for Python 3.14. More 3.14 specific features (e.g. python/cpython#114051) will be added in follow up PRs.

Remaining issues

Using Field() in dataclasses

To support the following:

from pydantic import Field

from pydantic.dataclasses import dataclass  # Also with stdlib dataclasses

@dataclass
class A:
    a: int = Field(default=1)

We currently have a somewhat hacky solution, which involves wrapping Field(default=1) into dataclasses.field(default=Field(default=1)), and more importantly directly writing into the __annotations__ dict (L184):

pydantic/pydantic/dataclasses.py

Lines 153 to 184 in dac3c43

	def make_pydantic_fields_compatible(cls: type[Any]) -> None:
	"""Make sure that stdlib `dataclasses` understands `Field` kwargs like `kw_only`
	To do that, we simply change
	`x: int = pydantic.Field(..., kw_only=True)`
	into
	`x: int = dataclasses.field(default=pydantic.Field(..., kw_only=True), kw_only=True)`
	"""
	for annotation_cls in cls.__mro__:
	annotations: dict[str, Any] = getattr(annotation_cls, '__annotations__', {})
	for field_name in annotations:
	field_value = getattr(cls, field_name, None)
	# Process only if this is an instance of `FieldInfo`.
	if not isinstance(field_value, FieldInfo):
	continue
	# Initialize arguments for the standard `dataclasses.field`.
	field_args: dict = {'default': field_value}
	# Handle `kw_only` for Python 3.10+
	if sys.version_info >= (3, 10) and field_value.kw_only:
	field_args['kw_only'] = True
	# Set `repr` attribute if it's explicitly specified to be not `True`.
	if field_value.repr is not True:
	field_args['repr'] = field_value.repr
	setattr(cls, field_name, dataclasses.field(**field_args))
	# In Python 3.9, when subclassing, information is pulled from cls.__dict__['__annotations__']
	# for annotations, so we must make sure it's initialized before we add to it.
	if cls.__dict__.get('__annotations__') is None:
	cls.__annotations__ = {}
	cls.__annotations__[field_name] = annotations[field_name]

In 3.14, writing/accessing __annotations__ is no longer safe, as a NameError can be raised if a an unresolvable annotation is used. In other words, this now raises:

from pydantic import Field

from pydantic.dataclasses import dataclass

@dataclass
class A:  # raises at declaration
    a: Forward = Field(default=1)

Forward = int

Unfortunately, I've tried hard to see if this could be supported somehow, and came to the conclusion that there is no way to do so without an unreasonable amount of workarounds. Such usage of forward references (without using stringified annotations) is only going to get more popular as 3.14 adoption grows, but it is hard to know how common this issue will be encountered. A couple notes:

• This can be mitigated if we only want to support using Field() on the class being decorated (in which case we don't need to write to __annotations__) but not on any super-classes.

• To support the case where Field() is defined on a super-class, this super-class needs to be a Pydantic dataclass (in which case the previous point would have handled it). If the super-class is a stdlib dataclass, it will not be possible to reasonably support this without too much hassle:

  @stdlib_dataclass
  class A:
       a: int = pydantic.Field(kw_only=True)
  
  @pydantic.dataclasses.dataclass
  class B(A):
      b: int

Here are the options we have:

• Deprecate support for repr and kw_only support together with Field() for dataclasses. I'm not a fan of this approach, as the issue only arises when using forward references as a deferred annotation, and works fine in other cases.
• Catch any NameError exceptions when trying to write to __annotations__, and raise a user warning saying the usage of Field() won't be supported if we catch one. Not a fan of this either, as the end user will only get a warning without any real explanation as to why it happened (they don't have to be aware of the Pydantic internals implemented to support Field()).

I don't have any satisfactory answers for now. I have added an xfailing test for this, and we can revisit later.

Edit: tracked in #12045, a different implementation will be used.

Real deferred annotations

PEP 649/749 should now allow use cases like this:

def outer():
    def inner():
        class Model(BaseModel):
            ann: Annotated[List[Dict[str, str]], MaxLen(1)]

        Dict = dict

        return Model

    List = list

    Model = inner()

    return Model

Model = outer()

Model.__annotations__['ann']
#> Annotated[list[dict[str, str]], MaxLen(1)]

However, trying to rebuild Model after getting it from outer() will raise an exception. This is because when we rebuild model fields, we do so individually by using typing._eval_type(). In reality, we should try accessing __annotations__ again to let CPython internals resolve the references for us. This is far from trivial to implement, so deferred for a follow-up PR.

[cloudflare-workers-and-pages]

Deploying pydantic-docs with    Cloudflare Pages

Latest commit:	26c0811
Status:	✅  Deploy successful!
Preview URL:	https://938ce782.pydantic-docs.pages.dev
Branch Preview URL:	https://3-14-initial-support.pydantic-docs.pages.dev

View logs

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
pydantic
dataclasses.py
pydantic/_internal
_config.py
_fields.py
_generics.py
_model_construction.py
_typing_extra.py
Project Total

This report was generated by python-coverage-comment-action

[codspeed-hq]

CodSpeed Performance Report

Merging #11991 will not alter performance

_{Comparing 3.14-initial-support (26c0811) with main (dac3c43)}

Summary

✅ 46 untouched benchmarks

[davidhewitt]

LGTM with some final nits!

[davidhewitt]

This is to build memray from source?

If so, it might be that for free-threading we can also build memray: bloomberg/memray#772

[Viicos]

Seems like it doesn't build: https://github.com/pydantic/pydantic/actions/runs/16191109859/job/45706902917?pr=11991