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

[Viicos]

Best reviewed commit per commit.

In a nutshell, this now raises a warning:

from typing import Annotated

from pydantic import BaseModel, Field

type MyInt = Annotated[int, Field(alias='my_alias')]

class Model(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:
class Model(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 for default and default_factory. Currently, the following works:

type MyInt = Annotated[int, Field(default=1)]

class Model(BaseModel):
    a: MyInt

Model()
#> 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:

type MyInt = Annotated[int, Field(default=1)]

class Model(BaseModel):
    a: MyInt

Model.model_fields['a'].is_required()  # True

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

Imo, I think we should keep the warning for default and default_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]

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

[Viicos]

This is referring to the following use case:

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

[Viicos]

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

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

[github-actions]

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 by python-coverage-comment-action

[codspeed-hq]

CodSpeed Performance Report

Merging #12028 will not alter performance

_{Comparing field-info-attr-warning (705951a) with main (dac3c43)}

Summary

✅ 46 untouched benchmarks

[cloudflare-workers-and-pages]

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

[Viicos]

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

[DouweM]

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

[Viicos]

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.

[DouweM]

@Viicos Ah I like that!

[Viicos]

@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.