More support for deprecated fields/models

Viicos commented 7 months ago

Initial Checks

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

Description

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

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: https://github.com/pydantic/pydantic/pull/8237/commits/cf06a7322d59aefc2e3ca607f0c5ee66d28f6757 (extra care should be taken with the typing-extensions version -- Only 4.9.0 and greater support the class implementation of the deprecated decorator).
When instantiating a model with a deprecated field explicitly specified (Model(deprecated_field=...)), the runtime warning could be emitted.
Support for Pydantic/stdlib dataclasses: not sure if there are any technical limitations for this one?

[x] 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) https://github.com/pydantic/pydantic/pull/9298

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
[X] Data validation/parsing
[ ] Data serialization - .model_dump() and .model_dump_json()
[X] 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 commented 7 months ago

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

NeevCohen commented 6 months ago

@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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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

pydantic / pydantic