Skip to content

Commit 7c2f473

Browse files
vyrnsynxMarkGus0
andauthored
Fix unquoted Struct forward references on Python 3.14 (msgspec#1168)
Fixes msgspec#1165. On Python 3.14, Struct field collection invoked the class __annotate__ function with annotationlib.Format.VALUE. That evaluates annotations immediately, so an unquoted forward reference raises NameError while the class is still being created. Ordinary 3.14 classes do not do this. This change evaluates annotations through annotationlib.call_annotate_function(..., Format.FORWARDREF), matching the annotationlib metaclass guidance. Compiler-generated annotate functions often raise NotImplementedError if FORWARDREF is passed directly; call_annotate_function implements that format. Field names (and ClassVar detection) still run at class creation time; types continue to resolve later through the existing delayed annotation path. Quoted annotations and from __future__ import annotations are unchanged. Older Python versions are unaffected because they never take the __annotate__ path. Tests cover quoted forward refs, future-annotations forward refs, unquoted forward refs and self-recursive structs on 3.14+, JSON encode/decode after both types are defined, and existing ClassVar cases on 3.14. --------- Co-authored-by: MarkGus0 <[email protected]> Co-authored-by: MarkGus0 <[email protected]> Co-authored-by: VyrnSynx <[email protected]>
1 parent 7b18791 commit 7c2f473

4 files changed

Lines changed: 122 additions & 10 deletions

File tree

‎docs/changelog.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@
3737
- Fix the `msgspec.json.decode` docstring to say `dec_hook` should raise
3838
`NotImplementedError` for unsupported types, not `TypeError` ({issue}`774`).
3939
- Fix backing type declaration of `Ext.code` ({pr}`1135`).
40+
- Fix `NameError` when creating a `Struct` with an unquoted forward
41+
reference on Python 3.14 ({issue}`1165`).
4042
- msgspec moved to the [msgspec GitHub organization](https://github.com/msgspec/msgspec);
4143
documentation now lives at [msgspec.dev](https://msgspec.dev) (repository
4244
references updated in {pr}`1045`).

‎src/msgspec/_core.c‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -530,6 +530,7 @@ typedef struct {
530530
PyObject *concrete_types;
531531
PyObject *get_type_hints;
532532
PyObject *get_class_annotations;
533+
PyObject *call_annotate_forwardref;
533534
PyObject *get_typeddict_info;
534535
PyObject *get_dataclass_info;
535536
PyObject *convert_generic_alias;
@@ -6120,16 +6121,12 @@ structmeta_collect_fields(StructMetaInfo *info, MsgspecState *mod, bool kwonly)
61206121
Py_DECREF(annotate);
61216122
return 0;
61226123
}
6123-
PyObject *format = PyLong_FromLong(1); /* annotationlib.Format.VALUE */
6124-
if (format == NULL) {
6125-
Py_DECREF(annotate);
6126-
return -1;
6127-
}
6128-
annotations = PyObject_CallOneArg(
6129-
annotate, format
6130-
);
6124+
/* Use Format.FORWARDREF so unresolved names do not raise NameError
6125+
* while the class body is still executing. See PEP 649 / annotationlib:
6126+
* https://docs.python.org/3/library/annotationlib.html#using-annotations-in-a-metaclass
6127+
*/
6128+
annotations = PyObject_CallOneArg(mod->call_annotate_forwardref, annotate);
61316129
Py_DECREF(annotate);
6132-
Py_DECREF(format);
61336130
if (annotations == NULL) {
61346131
return -1;
61356132
}
@@ -22695,6 +22692,7 @@ msgspec_clear(PyObject *m)
2269522692
Py_CLEAR(st->concrete_types);
2269622693
Py_CLEAR(st->get_type_hints);
2269722694
Py_CLEAR(st->get_class_annotations);
22695+
Py_CLEAR(st->call_annotate_forwardref);
2269822696
Py_CLEAR(st->get_typeddict_info);
2269922697
Py_CLEAR(st->get_dataclass_info);
2270022698
Py_CLEAR(st->rebuild);
@@ -22769,6 +22767,7 @@ msgspec_traverse(PyObject *m, visitproc visit, void *arg)
2276922767
Py_VISIT(st->concrete_types);
2277022768
Py_VISIT(st->get_type_hints);
2277122769
Py_VISIT(st->get_class_annotations);
22770+
Py_VISIT(st->call_annotate_forwardref);
2277222771
Py_VISIT(st->get_typeddict_info);
2277322772
Py_VISIT(st->get_dataclass_info);
2277422773
Py_VISIT(st->rebuild);
@@ -22971,6 +22970,7 @@ PyInit__core(void)
2297122970
SET_REF(concrete_types, "_CONCRETE_TYPES");
2297222971
SET_REF(get_type_hints, "get_type_hints");
2297322972
SET_REF(get_class_annotations, "get_class_annotations");
22973+
SET_REF(call_annotate_forwardref, "call_annotate_forwardref");
2297422974
SET_REF(get_typeddict_info, "get_typeddict_info");
2297522975
SET_REF(get_dataclass_info, "get_dataclass_info");
2297622976
SET_REF(typing_annotated_alias, "_AnnotatedAlias");

‎src/msgspec/_utils.py‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,29 @@ def _eval_type(t, globalns, localns):
5353

5454

5555
if sys.version_info >= (3, 14):
56-
from annotationlib import get_annotations as _get_class_annotations
56+
from annotationlib import (
57+
Format as _AnnotationFormat,
58+
call_annotate_function as _call_annotate_function,
59+
get_annotations as _get_class_annotations,
60+
)
61+
62+
def call_annotate_forwardref(annotate):
63+
"""Evaluate a class annotate function without requiring names to exist.
64+
65+
Metaclasses should use ``Format.FORWARDREF`` (via
66+
``call_annotate_function``, which implements the format when the
67+
annotate function only supports ``VALUE``).
68+
"""
69+
return _call_annotate_function(annotate, _AnnotationFormat.FORWARDREF)
70+
5771
else:
5872

5973
def _get_class_annotations(cls):
6074
return cls.__dict__.get("__annotations__", {})
6175

76+
def call_annotate_forwardref(annotate):
77+
return annotate(1) # annotationlib.Format.VALUE
78+
6279

6380
def _apply_params(obj, mapping):
6481
if isinstance(obj, typing.TypeVar):

‎tests/unit/test_struct.py‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2700,3 +2700,96 @@ def __post_init__(self):
27002700
x2 = x1.__copy__()
27012701
assert x1 == x2
27022702
assert count == 1
2703+
2704+
2705+
class TestForwardReferences:
2706+
"""Quoted forward refs work on all supported Pythons. Unquoted forward
2707+
refs are only valid under PEP 649 deferred annotations (3.14+).
2708+
"""
2709+
2710+
def test_quoted_forward_reference_struct_fields(self):
2711+
source = """
2712+
import msgspec
2713+
2714+
class Outer(msgspec.Struct):
2715+
inner: "Inner"
2716+
2717+
class Inner(msgspec.Struct):
2718+
value: int
2719+
"""
2720+
with temp_module(source) as mod:
2721+
assert mod.Outer.__struct_fields__ == ("inner",)
2722+
msg = mod.Outer(mod.Inner(1))
2723+
assert msgspec.json.decode(msgspec.json.encode(msg), type=mod.Outer) == msg
2724+
2725+
def test_future_annotations_forward_reference_struct_fields(self):
2726+
source = """
2727+
from __future__ import annotations
2728+
import msgspec
2729+
2730+
class Outer(msgspec.Struct):
2731+
inner: Inner
2732+
2733+
class Inner(msgspec.Struct):
2734+
value: int
2735+
"""
2736+
with temp_module(source) as mod:
2737+
assert mod.Outer.__struct_fields__ == ("inner",)
2738+
msg = mod.Outer(mod.Inner(1))
2739+
assert msgspec.json.decode(msgspec.json.encode(msg), type=mod.Outer) == msg
2740+
2741+
@pytest.mark.skipif(
2742+
sys.version_info < (3, 14),
2743+
reason="unquoted forward references require PEP 649 (Python 3.14+)",
2744+
)
2745+
def test_unquoted_forward_reference_struct_fields(self):
2746+
source = """
2747+
import msgspec
2748+
2749+
class Outer(msgspec.Struct):
2750+
inner: Inner
2751+
2752+
class Inner(msgspec.Struct):
2753+
value: int
2754+
"""
2755+
with temp_module(source) as mod:
2756+
assert mod.Outer.__struct_fields__ == ("inner",)
2757+
assert mod.Outer.__annotations__["inner"] is mod.Inner
2758+
msg = mod.Outer(mod.Inner(1))
2759+
assert msgspec.json.decode(msgspec.json.encode(msg), type=mod.Outer) == msg
2760+
2761+
@pytest.mark.skipif(
2762+
sys.version_info < (3, 14),
2763+
reason="unquoted forward references require PEP 649 (Python 3.14+)",
2764+
)
2765+
def test_unquoted_forward_reference_generic_container(self):
2766+
source = """
2767+
import msgspec
2768+
2769+
class Outer(msgspec.Struct):
2770+
items: list[Inner]
2771+
2772+
class Inner(msgspec.Struct):
2773+
value: int
2774+
"""
2775+
with temp_module(source) as mod:
2776+
assert mod.Outer.__struct_fields__ == ("items",)
2777+
msg = mod.Outer([mod.Inner(1), mod.Inner(2)])
2778+
assert msgspec.json.decode(msgspec.json.encode(msg), type=mod.Outer) == msg
2779+
2780+
@pytest.mark.skipif(
2781+
sys.version_info < (3, 14),
2782+
reason="unquoted forward references require PEP 649 (Python 3.14+)",
2783+
)
2784+
def test_unquoted_mutual_forward_references(self):
2785+
source = """
2786+
import msgspec
2787+
2788+
class Node(msgspec.Struct):
2789+
value: int
2790+
child: Node | None = None
2791+
"""
2792+
with temp_module(source) as mod:
2793+
assert mod.Node.__struct_fields__ == ("value", "child")
2794+
msg = mod.Node(1, mod.Node(2))
2795+
assert msgspec.json.decode(msgspec.json.encode(msg), type=mod.Node) == msg

0 commit comments

Comments
 (0)