raise warnings when deprecated fields are filled

Author: changhc

python/pydantic_core/core_schema.py

@@ -2944,6 +2944,7 @@ class ModelField(TypedDict, total=False):
     serialization_alias: str
     serialization_exclude: bool  # default: False
     frozen: bool
+    deprecation_msg: str
     metadata: Dict[str, Any]
 
 
@@ -2954,6 +2955,7 @@ def model_field(
     serialization_alias: str | None = None,
     serialization_exclude: bool | None = None,
     frozen: bool | None = None,
+    deprecation_msg: str | None = None,
     metadata: Dict[str, Any] | None = None,
 ) -> ModelField:
     """
@@ -2971,6 +2973,7 @@ def model_field(
         serialization_alias: The alias to use as a key when serializing
         serialization_exclude: Whether to exclude the field when serializing
         frozen: Whether the field is frozen
+        deprecation_msg: A deprecation message indicating that the field is deprecated. `None` means that the field is not deprecated.
         metadata: Any other information you want to include with the schema, not used by pydantic-core
     """
     return _dict_not_none(
@@ -2980,6 +2983,7 @@ def model_field(
         serialization_alias=serialization_alias,
         serialization_exclude=serialization_exclude,
         frozen=frozen,
+        deprecation_msg=deprecation_msg,
         metadata=metadata,
     )
 

src/validators/model_fields.rs

@@ -23,6 +23,7 @@ struct Field {
     name_py: Py<PyString>,
     validator: CombinedValidator,
     frozen: bool,
+    deprecation_msg: Option<String>,
 }
 
 impl_py_gc_traverse!(Field { validator });
@@ -92,6 +93,7 @@ impl BuildValidator for ModelFieldsValidator {
                 name_py: field_name_py.into(),
                 validator,
                 frozen: field_info.get_as::<bool>(intern!(py, "frozen"))?.unwrap_or(false),
+                deprecation_msg: field_info.get_as::<String>(intern!(py, "deprecation_msg"))?,
             });
         }
 
@@ -123,6 +125,8 @@ impl Validator for ModelFieldsValidator {
         // this validator does not yet support partial validation, disable it to avoid incorrect results
         state.allow_partial = false.into();
 
+        let deprecation_warning_type = py.import_bound("builtins")?.getattr("DeprecationWarning")?;
+
         let strict = state.strict_or(self.strict);
         let from_attributes = state.extra().from_attributes.unwrap_or(self.from_attributes);
 
@@ -184,6 +188,9 @@ impl Validator for ModelFieldsValidator {
                         // extra logic either way
                         used_keys.insert(lookup_path.first_key());
                     }
+                    if let Some(msg) = &field.deprecation_msg {
+                        PyErr::warn_bound(py, &deprecation_warning_type, msg, 2)?;
+                    }
                     match field.validator.validate(py, value.borrow_input(), state) {
                         Ok(value) => {
                             model_dict.set_item(&field.name_py, value)?;

tests/validators/test_model_fields.py

@@ -1781,3 +1781,26 @@ def test_extra_behavior_ignore(config: Union[core_schema.CoreConfig, None], sche
         }
     ]
     assert 'not_f' not in m
+
+
+def test_deprecation_msg():
+    v = SchemaValidator(
+        {
+            'type': 'model-fields',
+            'fields': {
+                'a': {'type': 'model-field', 'schema': {'type': 'int'}},
+                'b': {
+                    'type': 'model-field',
+                    'schema': {'type': 'default', 'schema': {'type': 'int'}, 'default': 2},
+                    'deprecation_msg': 'hi',
+                },
+            },
+        }
+    )
+
+    # not touching the deprecated field: no warning
+    v.validate_python({'a': 1})
+
+    # validating the deprecated field: raise warning
+    with pytest.warns(DeprecationWarning, match='hi'):
+        v.validate_python({'a': 1, 'b': 1})