NotificationsYou must be signed in to change notification settings
Fork2.2k
Star24.6k

Emit warning when field-specific metadata is used in invalid contexts#12028

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Jump to bottom

Merged

Viicos merged 9 commits intomainfromfield-info-attr-warning

Jul 18, 2025

Merged

Emit warning when field-specific metadata is used in invalid contexts#12028

Viicos merged 9 commits intomainfromfield-info-attr-warning

Jul 18, 2025

Conversation

Copy link

Member

Viicos commentedJun 30, 2025•
edited
Loading

Best reviewed commit per commit.

In a nutshell, this now raises a warning:

fromtypingimportAnnotatedfrompydanticimportBaseModel,FieldtypeMyInt=Annotated[int,Field(alias='my_alias')]classModel(BaseModel):# see the warning in https://docs.pydantic.dev/latest/concepts/types/#named-type-aliases for more info:a:MyInt""">>> UnsupportedFieldAttributeWarning: The 'alias' attribute with value 'my_alias' was provided to the `Field()` function, which>>> is unsupported in the context it was used. 'alias' is field-specific metadata, and can only be attached to a model field>>> using `Annotated` metadata or by assignment (note that using `Annotated` type aliases using the `type` statement>>> isn't supported)."""# Other use case:classModel(BaseModel):a:list[Annotated[int,Field(default=1)]]""">>> UnsupportedFieldAttributeWarning: The 'default' attribute with value 1 was provided to the `Field()` function, which>>> is unsupported in the context it was used. 'alias' is field-specific metadata, and can only be attached to a model field>>> using `Annotated` metadata or by assignment (note that using `Annotated` type aliases using the `type` statement>>> isn't supported)."""

We still need to figure out if we want the warning to be raised fordefault anddefault_factory. Currently, the following works:

typeMyInt=Annotated[int,Field(default=1)]classModel(BaseModel):a:MyIntModel()#> Model(a=1)

This is explained by the fact that we need to support defaults in type adapters:

TypeAdapter(Annotated[int,Field(default=1)]).get_default_vaue()#> Some(1)

And as a consequence it accidentally worked for models as well. However, things are inconsistent:

typeMyInt=Annotated[int,Field(default=1)]classModel(BaseModel):a:MyIntModel.model_fields['a'].is_required()# True

and JSON Schema generation is also acting weirdly:#12024.

Imo, I think we should keep the warning fordefault anddefault_factory. Sure, validation behavior still works, but it is a footgun for the reasons mentioned above. Users can still ignore the warning if they feel like it.

I've reached out to the FastAPI team regarding the failing tests. They will need to address them in some way.

Viicos added5 commits

June 30, 2025 19:15

Reorganize core schema generation warnings

68663aa

AddUnsupportedFieldAttributeWarning

59a9516

Emit warning when field attributes are used in invalid contexts

59872ae

Remove old and fragile logic that implemented the warning

fe48724

Update and add tests

c3e105f

github-actionsbot added the relnotes-fixUsed for bugfixes. label

Jun 30, 2025

Viicos commented

Jun 30, 2025

View reviewed changes

pydantic/_internal/_fields.py

Comment on lines -416 to -429

		def _warn_on_nested_alias_in_annotation(ann_type: type[Any], ann_name: str) -> None:
		FieldInfo = import_cached_field_info()

		args = getattr(ann_type, '__args__', None)
		if args:
		for anno_arg in args:
		if typing_objects.is_annotated(get_origin(anno_arg)):
		for anno_type_arg in _typing_extra.get_args(anno_arg):
		if isinstance(anno_type_arg, FieldInfo) and anno_type_arg.alias is not None:
		warnings.warn(
		f'`alias` specification on field "{ann_name}" must be set on outermost annotation to take effect.',
		UserWarning,
		)
		return

Copy link

MemberAuthor

ViicosJun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This was fragile logic implemented a long time ago, that is now fully covered by the new warning.

Viicos commented

Jun 30, 2025

View reviewed changes

pydantic/_internal/_generate_schema.py Outdated

Comment on lines 582 to 587

		with warnings.catch_warnings():
		# We kind of abused `Field()` default factories to be able to specify
		# the `defaultdict`'s `default_factory`. As a consequence, we get warnings
		# as normally `FieldInfo.default_factory` is unsupported in the context where
		# `Field()` is used and our only solution is to ignore them (note that this might
		# wrongfully ignore valid warnings, e.g. if the `value_type` to a PEP 695 type alias

Copy link

MemberAuthor

ViicosJun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This is referring to the following use case:

classModel(BaseModel):a:defaultdict[int,Annotated[list[int],Field(default_factory=lambda:MyList())]]

Viicos commented

Jun 30, 2025

View reviewed changes

pydantic/_internal/_generate_schema.py

Comment on lines +1556 to +1559

		# Because we pass `field` as metadata above (required for attributes relevant for
		# JSON Scheme generation), we need to ignore the potential warnings about `FieldInfo`
		# attributes that will not be used:
		check_unsupported_field_info_attributes=False,

Copy link

MemberAuthor

ViicosJun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This is for validated function calls (seetest_unsupported_field_attribute_nested_with_function()). We don't want to raise a warning for:

@validate_calldeffunc(a:Annotated[int,Field(alias='b')]): ...

Viicos commented

Jun 30, 2025

View reviewed changes

pydantic/_internal/_generate_schema.py OutdatedShow resolvedHide resolved

Viicos requested review fromDouweM anddavidhewitt

June 30, 2025 17:40

Viicos added relnotes-change

Used for changes to existing functionality which don't have a better categorization.

needs-blogpost-entryThis PR needs to be documented in the release notes blog post and removed relnotes-fixUsed for bugfixes. labels

Jun 30, 2025

Viicos mentioned this pull request

Jun 30, 2025

JSON Schema inconsistently sets Annotated type aliases as required or not#12024

Closed

1 task

Copy link

Contributor

github-actionsbot commentedJun 30, 2025

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
pydantic
functional_validators.py
warnings.py
pydantic/_internal
_fields.py
_generate_schema.py
Project Total

_{This report was generated bypython-coverage-comment-action}

Copy link

codspeed-hqbot commentedJun 30, 2025•
edited
Loading

CodSpeed Performance Report

Merging#12028 willnot alter performance

_{Comparingfield-info-attr-warning (705951a) withmain (dac3c43)}

Summary

✅ 46 untouched benchmarks

Viicos added the third-party-testsAdd this label on a PR to trigger 3rd party tests label

Jun 30, 2025

Viicos closed this

Jun 30, 2025

Viicos reopened this

Jun 30, 2025

Cope with FastAPI

6b7f8dd

Copy link

cloudflare-workers-and-pagesbot commentedJun 30, 2025•
edited
Loading

Deploying pydantic-docs with Cloudflare Pages

Latest commit:	`705951a`
Status:	✅ Deploy successful!
Preview URL:	https://e6f68bfe.pydantic-docs.pages.dev
Branch Preview URL:	https://field-info-attr-warning.pydantic-docs.pages.dev

View logs

Fix implementation

6c868fa

Viicos force-pushed thefield-info-attr-warning branch from59be012 to6c868faCompare

June 30, 2025 20:04

DouweM requested changes

Jul 1, 2025

View reviewed changes

pydantic/_internal/_generate_schema.py OutdatedShow resolvedHide resolved

Feedback

30acc55

Viicos force-pushed thefield-info-attr-warning branch from91fc505 to30acc55Compare

July 1, 2025 15:04

Copy link

MemberAuthor

Viicos commentedJul 1, 2025

I'm wondering if, similar to usage errors, we should link to a new documentation section about warnings, to show examples of this issue.

Copy link

Contributor

DouweM commentedJul 1, 2025

@Viicos If we haven't documented yet that this is unsupported, I agree we should

Copy link

MemberAuthor

Viicos commentedJul 1, 2025

Well it is documented, but I was thinking about linking to the docs from the warning message, so that users don't get confused when they see it.

Copy link

Contributor

DouweM commentedJul 1, 2025

@Viicos Ah I like that!

Copy link

MemberAuthor

Viicos commentedJul 5, 2025

@Viicos Ah I like that!

Actually this is going to be a bit hard to implement as is, as we'll need to set up the same logic as for errors (that is, construct the URL from the current version, etc). I improved the warning message and we can revisit if users still get confused.