Support deserializing Python dataclass into structs / mappings

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Bump MSRV to 1.83.
 - Update `pyo3` to 0.28.
+- Support deserializing `dataclass` instances to struct-like Rust types.
 - Add `arbitrary_precision` feature
 
 ## 0.27.0 - 2025-11-07

src/de.rs

@@ -1,4 +1,5 @@
-use pyo3::{types::*, Bound};
+use pyo3::exceptions::PyKeyError;
+use pyo3::{intern, types::*, Bound};
 use serde::de::{self, IntoDeserializer};
 use serde::Deserialize;
 
@@ -7,7 +8,16 @@ use crate::error::{ErrorImpl, PythonizeError, Result};
 #[cfg(feature = "arbitrary_precision")]
 const TOKEN: &str = "$serde_json::private::Number";
 
-/// Attempt to convert a Python object to an instance of `T`
+/// Attempt to convert a Python object to an instance of `T`.
+///
+/// Generally this only supports Python types that match `serde`'s object model well:
+/// - integers (including arbitrary precision integers if the `arbitrary_precision` feature is enabled)
+/// - floats
+/// - strings
+/// - bytes
+/// - `collections.abc.Sequence` instances (as serde sequences)
+/// - `collections.abc.Mapping` instances (as serde maps)
+/// - dataclasses (as serde maps)
 pub fn depythonize<'a, 'py, T>(obj: &'a Bound<'py, PyAny>) -> Result<T>
 where
     T: Deserialize<'a>,
@@ -55,6 +65,14 @@ impl<'a, 'py> Depythonizer<'a, 'py> {
         PyMappingAccess::new(self.input.cast()?)
     }
 
+    fn dataclass_access(&self) -> Result<Option<PyDataclassAccess<'py>>> {
+        if let Some(dc) = DataclassCandidate::try_new(self.input) {
+            Some(PyDataclassAccess::new(dc)).transpose()
+        } else {
+            Ok(None)
+        }
+    }
+
     fn deserialize_any_int<'de, V>(&self, int: &Bound<'_, PyInt>, visitor: V) -> Result<V::Value>
     where
         V: de::Visitor<'de>,
@@ -147,6 +165,8 @@ impl<'de> de::Deserializer<'de> for &'_ mut Depythonizer<'_, '_> {
             self.deserialize_tuple(obj.len()?, visitor)
         } else if obj.cast::<PyMapping>().is_ok() {
             self.deserialize_map(visitor)
+        } else if let Some(dc) = DataclassCandidate::try_new(obj) {
+            visitor.visit_map(PyDataclassAccess::new(dc)?)
         } else {
             Err(obj.get_type().qualname().map_or_else(
                 |_| PythonizeError::unsupported_type("unknown"),
@@ -293,7 +313,11 @@ impl<'de> de::Deserializer<'de> for &'_ mut Depythonizer<'_, '_> {
     where
         V: de::Visitor<'de>,
     {
-        visitor.visit_map(self.dict_access()?)
+        if let Some(dc_access) = self.dataclass_access()? {
+            visitor.visit_map(dc_access)
+        } else {
+            visitor.visit_map(self.dict_access()?)
+        }
     }
 
     fn deserialize_struct<V>(
@@ -470,6 +494,79 @@ impl<'de> de::MapAccess<'de> for PyMappingAccess<'_> {
     }
 }
 
+/// Intermediate structure used to denote that `obj` is a dataclass with `fields`.
+struct DataclassCandidate<'a, 'py> {
+    obj: &'a Bound<'py, PyAny>,
+    fields: Bound<'py, PyAny>,
+}
+
+impl<'a, 'py> DataclassCandidate<'a, 'py> {
+    fn try_new(obj: &'a Bound<'py, PyAny>) -> Option<Self> {
+        let fields = obj
+            .getattr_opt(intern!(obj.py(), "__dataclass_fields__"))
+            .ok()
+            .flatten()?;
+        Some(Self { obj, fields })
+    }
+}
+
+struct PyDataclassAccess<'py> {
+    fields: Bound<'py, PyList>,
+    dict: Bound<'py, PyDict>,
+    field_idx: usize,
+    val_idx: usize,
+    len: usize,
+}
+
+impl<'py> PyDataclassAccess<'py> {
+    fn new(dc: DataclassCandidate<'_, 'py>) -> Result<Self> {
+        let fields = dc.fields.cast::<PyDict>()?.keys();
+        let dict = dc
+            .obj
+            .getattr(intern!(dc.obj.py(), "__dict__"))?
+            .cast_into()?;
+        let len = fields.len();
+        Ok(Self {
+            fields,
+            dict,
+            field_idx: 0,
+            val_idx: 0,
+            len,
+        })
+    }
+}
+
+impl<'de> de::MapAccess<'de> for PyDataclassAccess<'_> {
+    type Error = PythonizeError;
+
+    fn next_key_seed<K>(&mut self, seed: K) -> Result<Option<K::Value>>
+    where
+        K: de::DeserializeSeed<'de>,
+    {
+        if self.field_idx < self.len {
+            let item = self.fields.get_item(self.field_idx)?;
+            self.field_idx += 1;
+            seed.deserialize(&mut Depythonizer::from_object(&item))
+                .map(Some)
+        } else {
+            Ok(None)
+        }
+    }
+
+    fn next_value_seed<V>(&mut self, seed: V) -> Result<V::Value>
+    where
+        V: de::DeserializeSeed<'de>,
+    {
+        let key = self.fields.get_item(self.val_idx)?;
+        let value = self
+            .dict
+            .get_item(&key)?
+            .ok_or_else(|| PyKeyError::new_err(key.unbind()))?;
+        self.val_idx += 1;
+        seed.deserialize(&mut Depythonizer::from_object(&value))
+    }
+}
+
 struct PyEnumAccess<'a, 'py> {
     de: Depythonizer<'a, 'py>,
     variant: Bound<'py, PyString>,
@@ -558,7 +655,7 @@ impl<'de> de::MapAccess<'de> for NumberDeserializer {
 
 #[cfg(test)]
 mod test {
-    use std::ffi::CStr;
+    use std::{collections::HashMap, ffi::CStr};
 
     use super::*;
     use crate::error::ErrorImpl;
@@ -572,14 +669,21 @@ mod test {
     {
         Python::attach(|py| {
             let obj = py.eval(code, None, None).unwrap();
-            let actual: T = depythonize(&obj).unwrap();
-            assert_eq!(&actual, expected);
-
-            let actual_json: JsonValue = depythonize(&obj).unwrap();
-            assert_eq!(&actual_json, expected_json);
+            test_de_with_obj(&obj, expected, expected_json);
         });
     }
 
+    fn test_de_with_obj<T>(obj: &Bound<'_, PyAny>, expected: &T, expected_json: &JsonValue)
+    where
+        T: de::DeserializeOwned + PartialEq + std::fmt::Debug,
+    {
+        let actual: T = depythonize(obj).unwrap();
+        assert_eq!(&actual, expected);
+
+        let actual_json: JsonValue = depythonize(obj).unwrap();
+        assert_eq!(&actual_json, expected_json);
+    }
+
     #[test]
     fn test_empty_struct() {
         #[derive(Debug, Deserialize, PartialEq)]
@@ -930,4 +1034,101 @@ mod test {
             ));
         });
     }
+
+    #[test]
+    fn test_dataclass() {
+        let code = c"\
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+point = Point(1, 2)";
+
+        #[derive(Debug, Deserialize, PartialEq)]
+        struct Point {
+            x: i32,
+            y: i32,
+        }
+
+        let expected = Point { x: 1, y: 2 };
+        let expected_json = json!({"x": 1, "y": 2});
+
+        Python::attach(|py| {
+            let locals = PyDict::new(py);
+            py.run(code, None, Some(&locals)).unwrap();
+            let obj = locals.get_item("point").unwrap().unwrap();
+            test_de_with_obj(&obj, &expected, &expected_json);
+
+            let map: HashMap<String, i32> = depythonize(&obj).unwrap();
+            assert_eq!(map.len(), 2);
+            assert_eq!(*map.get("x").unwrap(), 1);
+            assert_eq!(*map.get("y").unwrap(), 2);
+        });
+    }
+
+    #[test]
+    fn test_dataclass_missing_field() {
+        let code = c"\
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+point = Point(1, 2)";
+
+        #[derive(Debug, Deserialize, PartialEq)]
+        struct Point {
+            x: i32,
+            y: i32,
+            z: i32,
+        }
+
+        Python::attach(|py| {
+            let locals = PyDict::new(py);
+            py.run(code, None, Some(&locals)).unwrap();
+            let obj = locals.get_item("point").unwrap().unwrap();
+            let err = depythonize::<Point>(&obj).unwrap_err();
+            assert!(matches!(
+                *err.inner,
+                ErrorImpl::Message(msg) if msg == "missing field `z`"
+            ));
+        });
+    }
+
+    #[test]
+    fn test_dataclass_extra_field() {
+        let code = c"\
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: int
+    y: int
+    z: int
+
+point = Point(1, 2, 3)";
+
+        #[derive(Debug, Deserialize, PartialEq)]
+        #[serde(deny_unknown_fields)]
+        struct Point {
+            x: i32,
+            y: i32,
+        }
+
+        Python::attach(|py| {
+            let locals = PyDict::new(py);
+            py.run(code, None, Some(&locals)).unwrap();
+            let obj = locals.get_item("point").unwrap().unwrap();
+            let err = depythonize::<Point>(&obj).unwrap_err();
+            assert!(matches!(
+                *err.inner,
+                ErrorImpl::Message(msg) if msg == "unknown field `z`, expected `x` or `y`"
+            ));
+        });
+    }
 }