Add unset-sentinel validator/serializer

Author: Viicos

python/pydantic_core/core_schema.py

@@ -4075,6 +4075,7 @@ def definition_reference_schema(
         DatetimeSchema,
         TimedeltaSchema,
         LiteralSchema,
+        UnsetSentinelSchema,
         EnumSchema,
         IsInstanceSchema,
         IsSubclassSchema,
@@ -4133,6 +4134,7 @@ def definition_reference_schema(
     'datetime',
     'timedelta',
     'literal',
+    'unset-sentinel',
     'enum',
     'is-instance',
     'is-subclass',

src/common/mod.rs

@@ -1,2 +1,3 @@
 pub(crate) mod prebuilt;
 pub(crate) mod union;
+pub(crate) mod unset_sentinel;

src/common/unset_sentinel.rs

@@ -0,0 +1,16 @@
+use pyo3::intern;
+use pyo3::prelude::*;
+use pyo3::sync::GILOnceCell;
+
+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)
+}

src/errors/types.rs

@@ -316,6 +316,8 @@ error_types! {
         expected: {ctx_type: String, ctx_fn: field_from_context},
     },
     // ---------------------
+    // unset sentinel
+    UnsetSentinelError {},
     // date errors
     DateType {},
     DateParsing {
@@ -531,6 +533,7 @@ impl ErrorType {
             Self::AssertionError {..} => "Assertion failed, {error}",
             Self::CustomError {..} => "",  // custom errors are handled separately
             Self::LiteralError {..} => "Input should be {expected}",
+            Self::UnsetSentinelError { .. } => "Input should be the 'UNSET' sentinel",
             Self::DateType {..} => "Input should be a valid date",
             Self::DateParsing {..} => "Input should be a valid date in the format YYYY-MM-DD, {error}",
             Self::DateFromDatetimeParsing {..} => "Input should be a valid date or datetime, {error}",

src/serializers/computed_fields.rs

@@ -4,10 +4,11 @@ use pyo3::{intern, PyTraverseError, PyVisit};
 use serde::ser::SerializeMap;
 
 use crate::build_tools::py_schema_error_type;
+use crate::common::unset_sentinel::get_unset_sentinel_object;
 use crate::definitions::DefinitionsBuilder;
 use crate::py_gc::PyGcTraverse;
 use crate::serializers::filter::SchemaFilter;
-use crate::serializers::shared::{get_unset_sentinel_object, BuildSerializer, CombinedSerializer, PydanticSerializer};
+use crate::serializers::shared::{BuildSerializer, CombinedSerializer, PydanticSerializer};
 use crate::tools::SchemaDict;
 
 use super::errors::py_err_se_err;

src/serializers/fields.rs

@@ -7,6 +7,7 @@ use ahash::AHashMap;
 use serde::ser::SerializeMap;
 use smallvec::SmallVec;
 
+use crate::common::unset_sentinel::get_unset_sentinel_object;
 use crate::serializers::extra::SerCheck;
 use crate::PydanticSerializationUnexpectedValue;
 
@@ -15,7 +16,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::{get_unset_sentinel_object, CombinedSerializer, PydanticSerializer, TypeSerializer};
+use super::shared::{CombinedSerializer, PydanticSerializer, TypeSerializer};
 
 /// representation of a field for serialization
 #[derive(Debug)]

src/serializers/shared.rs

@@ -34,19 +34,6 @@ 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 {
     (
@@ -155,6 +142,7 @@ combined_serializer! {
         Union: super::type_serializers::union::UnionSerializer;
         TaggedUnion: super::type_serializers::union::TaggedUnionSerializer;
         Literal: super::type_serializers::literal::LiteralSerializer;
+        UnsetSentinel: super::type_serializers::unset_sentinel::UnsetSentinelSerializer;
         Enum: super::type_serializers::enum_::EnumSerializer;
         Recursive: super::type_serializers::definitions::DefinitionRefSerializer;
         Tuple: super::type_serializers::tuple::TupleSerializer;
@@ -356,6 +344,7 @@ impl PyGcTraverse for CombinedSerializer {
             CombinedSerializer::Union(inner) => inner.py_gc_traverse(visit),
             CombinedSerializer::TaggedUnion(inner) => inner.py_gc_traverse(visit),
             CombinedSerializer::Literal(inner) => inner.py_gc_traverse(visit),
+            CombinedSerializer::UnsetSentinel(inner) => inner.py_gc_traverse(visit),
             CombinedSerializer::Enum(inner) => inner.py_gc_traverse(visit),
             CombinedSerializer::Recursive(inner) => inner.py_gc_traverse(visit),
             CombinedSerializer::Tuple(inner) => inner.py_gc_traverse(visit),

src/serializers/type_serializers/mod.rs

@@ -25,6 +25,7 @@ pub mod timedelta;
 pub mod tuple;
 pub mod typed_dict;
 pub mod union;
+pub mod unset_sentinel;
 pub mod url;
 pub mod uuid;
 pub mod with_default;

src/serializers/type_serializers/unset_sentinel.rs

@@ -0,0 +1,76 @@
+// This serializer is defined so that building a schema serializer containing an
+// 'unset-sentinel' core schema doesn't crash. In practice, the serializer isn't
+// used for model-like classes, as the 'fields' serializer takes care of omitting
+// the fields from the output (the serializer can still be used if the 'unset-sentinel'
+// core schema is used standalone (e.g. with a Pydantic type adapter), but this isn't
+// something we explicitly support.
+
+use std::borrow::Cow;
+
+use pyo3::prelude::*;
+use pyo3::types::PyDict;
+
+use serde::ser::Error;
+
+use crate::common::unset_sentinel::get_unset_sentinel_object;
+use crate::definitions::DefinitionsBuilder;
+use crate::PydanticSerializationUnexpectedValue;
+
+use super::{BuildSerializer, CombinedSerializer, Extra, TypeSerializer};
+
+#[derive(Debug)]
+pub struct UnsetSentinelSerializer {}
+
+impl BuildSerializer for UnsetSentinelSerializer {
+    const EXPECTED_TYPE: &'static str = "unset-sentinel";
+
+    fn build(
+        _schema: &Bound<'_, PyDict>,
+        _config: Option<&Bound<'_, PyDict>>,
+        _definitions: &mut DefinitionsBuilder<CombinedSerializer>,
+    ) -> PyResult<CombinedSerializer> {
+        Ok(Self {}.into())
+    }
+}
+
+impl_py_gc_traverse!(UnsetSentinelSerializer {});
+
+impl TypeSerializer for UnsetSentinelSerializer {
+    fn to_python(
+        &self,
+        value: &Bound<'_, PyAny>,
+        _include: Option<&Bound<'_, PyAny>>,
+        _exclude: Option<&Bound<'_, PyAny>>,
+        _extra: &Extra,
+    ) -> PyResult<PyObject> {
+        let unset_obj = get_unset_sentinel_object(value.py());
+
+        if value.is(unset_obj) {
+            Ok(unset_obj.to_owned().into())
+        } else {
+            Err(
+                PydanticSerializationUnexpectedValue::new_from_msg(Some("Expected 'UNSET' sentinel".to_string()))
+                    .to_py_err(),
+            )
+        }
+    }
+
+    fn json_key<'a>(&self, key: &'a Bound<'_, PyAny>, extra: &Extra) -> PyResult<Cow<'a, str>> {
+        self.invalid_as_json_key(key, extra, Self::EXPECTED_TYPE)
+    }
+
+    fn serde_serialize<S: serde::ser::Serializer>(
+        &self,
+        _value: &Bound<'_, PyAny>,
+        _serializer: S,
+        _include: Option<&Bound<'_, PyAny>>,
+        _exclude: Option<&Bound<'_, PyAny>>,
+        _extra: &Extra,
+    ) -> Result<S::Ok, S::Error> {
+        Err(Error::custom("'UNSET' can't be serialized to JSON".to_string()))
+    }
+
+    fn get_name(&self) -> &str {
+        Self::EXPECTED_TYPE
+    }
+}

src/validators/mod.rs

@@ -59,6 +59,7 @@ mod timedelta;
 mod tuple;
 mod typed_dict;
 mod union;
+mod unset_sentinel;
 mod url;
 mod uuid;
 mod validation_state;
@@ -574,6 +575,8 @@ fn build_validator_inner(
         call::CallValidator,
         // literals
         literal::LiteralValidator,
+        // unset sentinel
+        unset_sentinel::UnsetSentinelValidator,
         // enums
         enum_::BuildEnumValidator,
         // any
@@ -741,6 +744,8 @@ pub enum CombinedValidator {
     FunctionCall(call::CallValidator),
     // literals
     Literal(literal::LiteralValidator),
+    // Unset sentinel
+    UnsetSentinel(unset_sentinel::UnsetSentinelValidator),
     // enums
     IntEnum(enum_::EnumValidator<enum_::IntEnumValidator>),
     StrEnum(enum_::EnumValidator<enum_::StrEnumValidator>),