Only mark model as complete once all fields are complete by DouweM · Pull Request #11759 · pydantic/pydantic

DouweM · 2025-04-15T21:43:28Z

Change Summary

BaseModel.model_rebuild already ensured that __pydantic_fields_complete__ was True before marking the model as complete, including rebuilding model fields to 1) see if any unknown annotations could not be resolved, and 2) if not, to make sure that the mock error message includes the name of the unknown annotation.

We now do the same on ModelMetaclass.__new__, to make sure that subclasses of incomplete superclasses don't incorrectly get marked as complete.

Here is such an example:

class MyModel(BaseModel):
    sub_models: list['SubModel']

class SubModel(MyModel):
    pass

Related issue number

Preparation for #11453

Edit: fixes #12061.

Checklist

The pull request title is a good summary of the changes - it will be used in the changelog
Unit tests for the changes exist
Tests pass on CI
Documentation reflects the changes where applicable
My PR is ready to review, please add a comment including the phrase "please review" to assign reviewers

Selected Reviewer: @sydney-runkle

DouweM · 2025-04-15T21:47:26Z

Hmm, we're good on Python 3.11+, but failing on earlier versions...

The issue appears to be that inside FieldInfo.from_annotation, typing._eval_type("list['SubModel']", {}, {}) raises a NameError on 3.11+ because SubModel couldn't be found, but happily returns list['SubModel'] on earlier versions.

This causes Pydantic to leave the FieldInfo as _complete=True, while the failing test expects it to be False:

pydantic/pydantic/_internal/_fields.py

Lines 211 to 213 in 625dd42

    
           field_info = FieldInfo_.from_annotation(ann_type, _source=AnnotationSource.CLASS) 
        
           if not evaluated: 
        
               field_info._complete = False

Pydantic behaves correctly because GenerateSchema still raises PydanticUndefinedAnnotation (it also uses _eval_type, but only after explicitly parsing the type hints in _get_args_resolving_forward_refs), which causes it to call set_model_mocks and leave __pydantic_complete__ False. But it looks like __pydantic_fields_complete__ cannot be fully relied on <3.11.

Interestingly, sub_model: 'SubModel' does cause NameError to be raised by FieldInfo.from_annotation and _complete to be False, because 'SubModel' is turned into ForwardRef('SubModel') by this method:

pydantic/pydantic/_internal/_typing_extra.py

Lines 274 to 289 in 625dd42

    
           def _type_convert(arg: Any) -> Any: 
        
               """Convert `None` to `NoneType` and strings to `ForwardRef` instances. 
        
               This is a backport of the private `typing._type_convert` function. When 
        
               evaluating a type, `ForwardRef._evaluate` ends up being called, and is 
        
               responsible for making this conversion. However, we still have to apply 
        
               it for the first argument passed to our type evaluation functions, similarly 
        
               to the `typing.get_type_hints` function. 
        
               """ 
        
               if arg is None: 
        
                   return NoneType 
        
               if isinstance(arg, str): 
        
                   # Like `typing.get_type_hints`, assume the arg can be in any context, 
        
                   # hence the proper `is_argument` and `is_class` args: 
        
                   return _make_forward_ref(arg, is_argument=False, is_class=True) 
        
               return arg

For this PR, I'll change it from list['SubModel'] to 'SubModel', but if we want to be able to trust FieldInfo._complete and __pydantic_fields_complete__ on <3.11, we may want to apply logic similar to _get_args_resolving_forward_refs before we call typing._eval_type to turn strs inside generics (like list) into ForwardRefs as well.

@Viicos What do you think?

codspeed · 2025-04-15T21:51:08Z

CodSpeed Performance Report

Merging #11759 will not alter performance

_{Comparing DouweM:model-fields-complete-mismatch (ed18a83) with main (eb295f2)}

Summary

✅ 46 untouched benchmarks

github-actions · 2025-04-15T23:54:33Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
pydantic/_internal
_model_construction.py
Project Total

_{This report was generated by python-coverage-comment-action}

DouweM · 2025-04-16T00:54:49Z

@Viicos Please review!

Viicos · 2025-04-16T08:47:40Z

The issue appears to be that inside FieldInfo.from_annotation, typing._eval_type("list['SubModel']", {}, {}) raises a NameError on 3.11+ because SubModel couldn't be found, but happily returns list['SubModel'] on earlier versions.

This is a bug that was fixed in python/cpython#30900. iirc, this unfortunately can't be backported to typing_extensions because it would require copying a lot of code from typing. Ideally, we should have our own typing._eval_type() implementation, but the logic is already messy with the eval_type_backport integration. Anyway, I think I'll give it another shot once a fix (python/cpython#131583) gets accepted upstream.

but if we want to be able to trust FieldInfo._complete and __pydantic_fields_complete__ on <3.11, we may want to apply logic similar to _get_args_resolving_forward_refs before we call typing._eval_type to turn strs inside generics (like list) into ForwardRefs as well.

I think we can live with the inconsistency here. The primary goal of FieldInfo._complete is to indicate whether we should recreate the instance (by calling FieldInfo.from_annotation()/from_annotated_attribute() using the temp. FieldInfo._original_annotation/_original_assignment attrs.). While a FieldInfo with an annotation like list['Forward'] is currently treated as _complete on < 3.11, there will be no need to rebuild the instance as the forward annotation is "inside" list, and won't affect FieldInfo attributes. On the other hand, a FieldInfo instance with an annotation like "Annotated[Forward, Field(alias='a')]" will have attributes (in this case, alias) altered when being rebuilt with the evaluated annotation.

DouweM · 2025-04-16T19:35:15Z

@Viicos I've limited this PR to the fields/model complete mismatch issue, and split out the new hook into #11762 (to be updated and merged after this).

Viicos

Otherwise looks good

DouweM · 2025-04-17T14:04:05Z

@Viicos Back to you!

DouweM · 2025-04-17T15:19:38Z

The failing Pandera test is already being fixed in #11767.

…hon <3.11

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Viicos

Thanks @DouweM

github-actions Bot added the relnotes-fix Used for bugfixes. label Apr 15, 2025

DouweM changed the title ~~Only mark model as complete once all fields are complete~~ Add __pydantic_on_complete__ hook that is called once model is fully ready to be used Apr 16, 2025

DouweM mentioned this pull request Apr 16, 2025

Raise a warning when accessing incomplete model fields #11453

Open

pydantic-hooky Bot added the ready for review label Apr 16, 2025

Viicos reviewed Apr 16, 2025

View reviewed changes

Comment thread pydantic/_internal/_model_construction.py

Viicos added relnotes-feature and removed relnotes-fix Used for bugfixes. labels Apr 16, 2025

DouweM force-pushed the model-fields-complete-mismatch branch from 0c9ec0f to dd5f919 Compare April 16, 2025 19:25

DouweM changed the title ~~Add __pydantic_on_complete__ hook that is called once model is fully ready to be used~~ Only mark model as complete once all fields are complete Apr 16, 2025

DouweM mentioned this pull request Apr 16, 2025

Add __pydantic_on_complete__() hook that is called once model is fully ready to be used #11762

Merged

4 of 5 tasks

Viicos reviewed Apr 17, 2025

View reviewed changes

Comment thread pydantic/_internal/_model_construction.py

Comment thread pydantic/_internal/_model_construction.py Outdated

Viicos added change Suggested alteration to Pydantic, not a new feature nor a bug relnotes-fix Used for bugfixes. third-party-tests Add this label on a PR to trigger 3rd party tests and removed relnotes-feature change Suggested alteration to Pydantic, not a new feature nor a bug labels Apr 17, 2025

Viicos closed this Apr 17, 2025

Viicos reopened this Apr 17, 2025

DouweM and others added 4 commits April 17, 2025 17:41

Only mark model as complete once all fields are complete

2f66b18

Simplify type annotation in test_incomplete_superclass to work on Pyt…

83d7c0d

…hon <3.11

Try to rebuild fields before generating schema so we can bail out early

2e9be5f

Clarify why model fields may be rebuilt in complete_model_class

51c0933

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Fix order of ns_resolver argument on complete_model_class

ed18a83

DouweM force-pushed the model-fields-complete-mismatch branch from 03eebf1 to ed18a83 Compare April 17, 2025 17:41

Viicos approved these changes Apr 17, 2025

View reviewed changes

Viicos merged commit b77ad73 into pydantic:main Apr 17, 2025

Viicos mentioned this pull request Jul 15, 2025

model_rebuild incorrectly determines rebuild not required #12061

Closed

1 task done

Viicos removed the ready for review label Jul 20, 2025

Viicos mentioned this pull request Jul 20, 2025

model_rebuild() skips for subclasses unless force=True #12075

Closed

1 task done

Viicos mentioned this pull request Dec 4, 2025

No ForwardRef in model_fields annotations with list['Model'] field type with legacy-style annotations (w/o from __future__ import annotations) #12610

Open

1 task done

willingc mentioned this pull request Apr 5, 2026

Specify pydantic >= 2.12 because of an incompatibility with pydantic 2.11? napari/npe2#448

Closed

Navigation Menu

Repository navigation

Only mark model as complete once all fields are complete - #11759

Only mark model as complete once all fields are complete#11759
Viicos merged 5 commits into
pydantic:mainfrom
DouweM:model-fields-complete-mismatch

DouweM commented Apr 15, 2025 •

edited by Viicos

Loading

Uh oh!

DouweM commented Apr 15, 2025 •

edited

Loading

Uh oh!

codspeed Bot commented Apr 15, 2025 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 15, 2025 •

edited

Loading

Uh oh!

DouweM commented Apr 16, 2025

Uh oh!

Viicos commented Apr 16, 2025

Uh oh!

Uh oh!

DouweM commented Apr 16, 2025

Uh oh!

Viicos left a comment

Uh oh!

Uh oh!

Uh oh!

DouweM commented Apr 17, 2025

Uh oh!

DouweM commented Apr 17, 2025

Uh oh!

Viicos left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

DouweM commented Apr 15, 2025 • edited by Viicos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Summary

Related issue number

Checklist

Uh oh!

DouweM commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed Bot commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #11759 will not alter performance

Summary

Uh oh!

github-actions Bot commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Uh oh!

DouweM commented Apr 16, 2025

Uh oh!

Viicos commented Apr 16, 2025

Uh oh!

Uh oh!

DouweM commented Apr 16, 2025

Uh oh!

Viicos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DouweM commented Apr 17, 2025

Uh oh!

DouweM commented Apr 17, 2025

Uh oh!

Viicos left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DouweM commented Apr 15, 2025 •

edited by Viicos

Loading

DouweM commented Apr 15, 2025 •

edited

Loading

codspeed Bot commented Apr 15, 2025 •

edited

Loading

github-actions Bot commented Apr 15, 2025 •

edited

Loading