More support for deprecated fields/models

[Viicos]

Initial Checks

• I have searched Google & GitHub for similar requests and couldn't find anything
• I have read and followed the docs and still think this feature is missing

Description

#8237 implemented support for deprecated fields. While doing so, we encountered/postponed some extra features that could be nice to have:

1. When using the deprecated decorator class, extra information (such as the category and stacklevel) can be passed. It would be great if Pydantic could support such attributes when emitting the runtime warning. For reference, this commit implements the feature: cf06a73 (extra care should be taken with the typing-extensions version -- Only 4.9.0 and greater support the class implementation of the deprecated decorator).

2. When instantiating a model with a deprecated field explicitly specified (Model(deprecated_field=...)), the runtime warning could be emitted.

3. Support for Pydantic/stdlib dataclasses: not sure if there are any technical limitations for this one?

4. Support for deprecated models:

• With the @deprecated decorator:

  @deprecated("deprecated model")
  class Model(BaseModel):
      pass

  The decorator takes care of the runtime warning (tested locally and doesn't seem to cause any issues with the model metaclass). However, the JSON Schema should reflect the deprecation.
• via a config option, in a similar fashion to the argument to Field:

  class Model(BaseModel):
      model_config = {"deprecated": "deprecated model"}

  I wouldn't really recommend the second option, as type checkers won't be aware of the deprecation (same for computed_field)

These were the ideas I had while implementing support for deprecated fields. Some of them requires some discussion, as I'm not sure whether it should be supported or not. Happy to hear your opinions

Affected Components

• Compatibility between releases
• Data validation/parsing
• Data serialization - .model_dump() and .model_dump_json()
• JSON Schema
• Dataclasses
• Model Config
• Field Types - adding or changing a particular data type
• Function validation decorator
• Generic Models
• Other Model behaviour - model_construct(), pickling, private attributes, ORM mode
• Plugins and integration with other tools - mypy, FastAPI, python-devtools, Hypothesis, VS Code, PyCharm, etc.

[sydney-runkle]

Agreed. PRs welcome for parts or all of the above features. Ping me if you want to chat more about implementation details :).

[NeevCohen]

@sydney-runkle @Viicos I had started to look into implementing point 4, and from my testing, the @deprecated decorator on a model does emit a runtime warning when using the model.

My question is, should a warning also be emitted in the following scenario?

@deprecated
class DeprecatedModel(BaseModel):
    pass

class NewModel(BaseModel):
    field: DeprecatedModel

Do you think that in this case Pydantic should emit a warning along the lines of Usage of deprecated model `DeprecatedModel`?

[Viicos]

That's great to hear!

Do you think that in this case Pydantic should emit a warning along the lines of Usage of deprecated model `DeprecatedModel`?

Do you mean the warning should be emitted during class creation? (And thus whenever the model's module is imported).
That might be too invasive, although I can't think of a use case where a user would be constrained to use a deprecated model as a field in the model he is defining. Let's maybe here what the maintainers think of it

[NeevCohen]

Do you mean the warning should be emitted during class creation? (And thus whenever the model's module is imported). That might be too invasive, although I can't think of a use case where a user would be constrained to use a deprecated model as a field in the model he is defining. Let's maybe here what the maintainers think of it

I actually meant to emit a warning when a user defines a model with one of its fields being a deprecated model, not when the deprecated model is created/imported.

In my examples above, when creating NewModel, we could check to see if a field is defined with the type of another subclass of BaseModel and then check if has the __deprecated__ attribute.

[sydney-runkle]

Also, just a side note, I don't think we should support the config based deprecation above, but the deprecated decorator approach is great.