Add UNSET sentinel

Author: Viicos

pyproject.toml

@@ -36,7 +36,7 @@ classifiers = [
     'Typing :: Typed',
 ]
 dependencies = [
-    'typing-extensions>=4.13.0',
+    'typing-extensions@git+https://github.com/python/typing_extensions',
 ]
 dynamic = ['license', 'readme', 'version']
 

python/pydantic_core/__init__.py

@@ -3,6 +3,8 @@
 import sys as _sys
 from typing import Any as _Any
 
+from typing_extensions import Sentinel
+
 from ._pydantic_core import (
     ArgsKwargs,
     MultiHostUrl,
@@ -40,6 +42,7 @@
 
 __all__ = [
     '__version__',
+    'UNSET',
     'CoreConfig',
     'CoreSchema',
     'CoreSchemaType',
@@ -140,3 +143,28 @@ class MultiHostHost(_TypedDict):
     """The host part of this host, or `None`."""
     port: int | None
     """The port part of this host, or `None`."""
+
+
+UNSET = Sentinel('UNSET')
+"""A singleton indicating a field value was not set during validation.
+
+This singleton can be used a default value, as an alternative to `None` when it has
+an explicit meaning. During serialization, any field with `UNSET` as a value is excluded
+from the output.
+
+Example:
+    ```python
+    from pydantic import BaseModel
+    from pydantic.experimental.unset import UNSET
+
+
+    class Configuration(BaseModel):
+        timeout: int | None | UNSET = UNSET
+
+
+    # configuration defaults, stored somewhere else:
+    defaults = {'timeout': 200}
+
+    conf = Configuration.model_validate({...})
+    timeout = conf.timeout if timeout.timeout is not UNSET else defaults['timeout']
+"""

src/serializers/computed_fields.rs

@@ -7,7 +7,7 @@ use crate::build_tools::py_schema_error_type;
 use crate::definitions::DefinitionsBuilder;
 use crate::py_gc::PyGcTraverse;
 use crate::serializers::filter::SchemaFilter;
-use crate::serializers::shared::{BuildSerializer, CombinedSerializer, PydanticSerializer};
+use crate::serializers::shared::{BuildSerializer, CombinedSerializer, PydanticSerializer, get_unset_sentinel_object};
 use crate::tools::SchemaDict;
 
 use super::errors::py_err_se_err;
@@ -148,6 +148,10 @@ impl ComputedFields {
             if extra.exclude_none && value.is_none() {
                 continue;
             }
+            let unset_obj = get_unset_sentinel_object(model.py());
+            if value.is(unset_obj) {
+                continue;
+            }
 
             let field_extra = Extra {
                 field_name: Some(&computed_field.property_name),

src/serializers/fields.rs

@@ -15,8 +15,7 @@ use super::errors::py_err_se_err;
 use super::extra::Extra;
 use super::filter::SchemaFilter;
 use super::infer::{infer_json_key, infer_serialize, infer_to_python, SerializeInfer};
-use super::shared::PydanticSerializer;
-use super::shared::{CombinedSerializer, TypeSerializer};
+use super::shared::{get_unset_sentinel_object, CombinedSerializer, PydanticSerializer, TypeSerializer};
 
 /// representation of a field for serialization
 #[derive(Debug)]
@@ -154,6 +153,7 @@ impl GeneralFieldsSerializer {
     ) -> PyResult<Bound<'py, PyDict>> {
         let output_dict = PyDict::new(py);
         let mut used_req_fields: usize = 0;
+        let unset_obj = get_unset_sentinel_object(py);
 
         // NOTE! we maintain the order of the input dict assuming that's right
         for result in main_iter {
@@ -163,6 +163,10 @@ impl GeneralFieldsSerializer {
             if extra.exclude_none && value.is_none() {
                 continue;
             }
+            if value.is(unset_obj) {
+                continue;
+            }
+
             let field_extra = Extra {
                 field_name: Some(key_str),
                 ..extra
@@ -238,9 +242,13 @@ impl GeneralFieldsSerializer {
 
         for result in main_iter {
             let (key, value) = result.map_err(py_err_se_err)?;
+            let unset_obj = get_unset_sentinel_object(value.py());
             if extra.exclude_none && value.is_none() {
                 continue;
             }
+            if value.is(unset_obj) {
+                continue;
+            }
             let key_str = key_str(&key).map_err(py_err_se_err)?;
             let field_extra = Extra {
                 field_name: Some(key_str),
@@ -326,6 +334,7 @@ impl TypeSerializer for GeneralFieldsSerializer {
         extra: &Extra,
     ) -> PyResult<PyObject> {
         let py = value.py();
+        let unset_obj = get_unset_sentinel_object(py);
         // If there is already a model registered (from a dataclass, BaseModel)
         // then do not touch it
         // If there is no model, we (a TypedDict) are the model
@@ -347,6 +356,9 @@ impl TypeSerializer for GeneralFieldsSerializer {
                 if extra.exclude_none && value.is_none() {
                     continue;
                 }
+                if value.is(unset_obj) {
+                    continue;
+                }
                 if let Some((next_include, next_exclude)) = self.filter.key_filter(&key, include, exclude)? {
                     let value = match &self.extra_serializer {
                         Some(serializer) => {
@@ -380,7 +392,7 @@ impl TypeSerializer for GeneralFieldsSerializer {
             extra.warnings.on_fallback_ser::<S>(self.get_name(), value, extra)?;
             return infer_serialize(value, serializer, include, exclude, extra);
         };
-
+        let unset_obj = get_unset_sentinel_object(value.py());
         // If there is already a model registered (from a dataclass, BaseModel)
         // then do not touch it
         // If there is no model, we (a TypedDict) are the model
@@ -407,6 +419,9 @@ impl TypeSerializer for GeneralFieldsSerializer {
                 if extra.exclude_none && value.is_none() {
                     continue;
                 }
+                if value.is(unset_obj) {
+                    continue;
+                }
                 let filter = self.filter.key_filter(&key, include, exclude).map_err(py_err_se_err)?;
                 if let Some((next_include, next_exclude)) = filter {
                     let output_key = infer_json_key(&key, extra).map_err(py_err_se_err)?;

src/serializers/shared.rs

@@ -34,6 +34,19 @@ pub(crate) trait BuildSerializer: Sized {
     ) -> PyResult<CombinedSerializer>;
 }
 
+static UNSET_SENTINEL_OBJECT: GILOnceCell<Py<PyAny>> = GILOnceCell::new();
+
+pub fn get_unset_sentinel_object(py: Python) -> &Bound<'_, PyAny> {
+    UNSET_SENTINEL_OBJECT
+        .get_or_init(py, || {
+            py.import(intern!(py, "pydantic_core"))
+                .and_then(|core_module| core_module.getattr(intern!(py, "UNSET")))
+                .unwrap()
+                .into()
+        })
+        .bind(py)
+}
+
 /// Build the `CombinedSerializer` enum and implement a `find_serializer` method for it.
 macro_rules! combined_serializer {
     (