Skip to main content

pyforge_django/
lib.rs

1// Author: Abdulwahed Mansour
2//! # pyforge-django
3//!
4//! High-performance Django integration layer built on PyForge.
5//!
6//! Provides Rust-accelerated serialization, validation, and field mapping
7//! for Django 5.x+ projects. Designed for drop-in use with Django REST Framework.
8
9pub mod async_bridge;
10pub mod error;
11pub mod field_types;
12pub mod model;
13pub mod serializer;
14pub mod validator;
15
16use pyforge::prelude::*;
17use pyforge::types::{PyBool, PyDict, PyFloat, PyInt, PyList, PyString};
18
19use crate::error::DjangoError;
20use crate::field_types::{DjangoFieldType, FieldDescriptor, FieldValue};
21
22// ─── ModelSchema: compiled descriptor cache ─────────────────────────────────
23
24/// A compiled model schema that caches field descriptors for repeated use.
25///
26/// Built once at Django startup from a model class, then reused on every
27/// request. Eliminates per-request descriptor parsing overhead entirely.
28///
29/// Usage from Python:
30/// ```python
31/// schema = pyforge_django.ModelSchema(MyModel)
32/// result = pyforge_django.serialize_instance(instance, schema)
33/// ```
34#[pyclass]
35#[derive(Clone)]
36pub struct ModelSchema {
37    /// Cached field descriptors extracted from the Django model.
38    descriptors: Vec<FieldDescriptor>,
39    /// The model class name, for error messages.
40    model_name: String,
41    /// Field names in declaration order, for fast lookup.
42    field_names: Vec<String>,
43}
44
45#[pymethods]
46impl ModelSchema {
47    /// Compiles a schema from a Django model class.
48    ///
49    /// Introspects the model's `_meta` API once and caches the result.
50    /// Subsequent serialization/validation calls use the cached descriptors
51    /// with zero per-request parsing overhead.
52    ///
53    /// Args:
54    ///     model_class: A Django model class (e.g., `MyModel`).
55    ///
56    /// Raises:
57    ///     ValueError: If the class lacks a `_meta` attribute.
58    #[new]
59    fn new(py: Python<'_>, model_class: &Bound<'_, PyAny>) -> PyResult<Self> {
60        let model_name: String = model_class
61            .getattr("__name__")
62            .and_then(|n| n.extract())
63            .unwrap_or_else(|_| "UnknownModel".into());
64
65        let descriptors = model::extract_field_descriptors(py, model_class)
66            .map_err(|e| -> pyforge::PyErr { e.into() })?;
67
68        let field_names = descriptors.iter().map(|d| d.name.clone()).collect();
69
70        Ok(ModelSchema {
71            descriptors,
72            model_name,
73            field_names,
74        })
75    }
76
77    /// Returns the list of field names in this schema.
78    #[getter]
79    fn field_names_list(&self) -> Vec<String> {
80        self.field_names.clone()
81    }
82
83    /// Returns the model class name.
84    #[getter]
85    fn model_name_str(&self) -> &str {
86        &self.model_name
87    }
88
89    /// Returns the number of fields in the schema.
90    fn __len__(&self) -> usize {
91        self.descriptors.len()
92    }
93
94    fn __repr__(&self) -> String {
95        format!(
96            "ModelSchema({}, {} fields)",
97            self.model_name,
98            self.descriptors.len()
99        )
100    }
101
102    /// Returns the schema as a list of dicts (for compatibility with existing APIs).
103    fn to_descriptor_list<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyList>> {
104        descriptors_to_pylist(py, &self.descriptors)
105    }
106}
107
108// ─── Python-exposed functions ───────────────────────────────────────────────
109
110/// Serializes a single Django model instance using a precompiled schema.
111///
112/// This is the primary fast path: extracts all field values from the instance
113/// in a single Rust call via `getattr`, serializes them, and returns a dict.
114/// Eliminates multiple Python↔Rust boundary crossings.
115///
116/// Args:
117///     instance: A Django model instance (e.g., `my_obj`).
118///     schema: A `ModelSchema` compiled from the model class.
119///
120/// Returns:
121///     A dict of serialized field values (JSON-compatible).
122///
123/// Raises:
124///     ValueError: On serialization failure.
125///     TypeError: On type conversion failure.
126#[pyfunction]
127fn serialize_instance<'py>(
128    py: Python<'py>,
129    instance: &Bound<'py, PyAny>,
130    schema: &ModelSchema,
131) -> PyResult<Bound<'py, PyDict>> {
132    let mut field_values = Vec::with_capacity(schema.descriptors.len());
133
134    // Single-pass field extraction — all getattr calls happen here, in Rust
135    for desc in &schema.descriptors {
136        let py_val = instance.getattr(desc.name.as_str());
137        match py_val {
138            Ok(val) => {
139                let fv = model::convert_python_value_to_field(&val, desc)
140                    .map_err(|e| -> pyforge::PyErr { e.into() })?;
141                field_values.push(fv);
142            }
143            Err(_) => {
144                if desc.nullable || desc.has_default {
145                    field_values.push(FieldValue::Null);
146                } else {
147                    return Err(DjangoError::NullField {
148                        field: desc.name.clone(),
149                    }
150                    .into());
151                }
152            }
153        }
154    }
155
156    let record = serializer::serialize_model_fields(&schema.descriptors, &field_values)
157        .map_err(|e| -> pyforge::PyErr { e.into() })?;
158
159    record_to_pydict(py, &record)
160}
161
162/// Serializes a batch of Django model instances using a precompiled schema.
163///
164/// Processes all instances in a single call, returning a list of dicts.
165/// For batches above 64 records, consider using `async_serialize_batch`
166/// from an ASGI view to release the GIL during computation.
167///
168/// Args:
169///     instances: A list/queryset of Django model instances.
170///     schema: A `ModelSchema` compiled from the model class.
171///
172/// Returns:
173///     A list of dicts, one per instance.
174#[pyfunction]
175fn serialize_batch<'py>(
176    py: Python<'py>,
177    instances: &Bound<'py, PyList>,
178    schema: &ModelSchema,
179) -> PyResult<Bound<'py, PyList>> {
180    let result = PyList::empty(py);
181
182    for instance in instances.iter() {
183        let dict = serialize_instance(py, &instance, schema)?;
184        result.append(dict)?;
185    }
186
187    Ok(result)
188}
189
190/// Validates a Django model instance against its schema.
191///
192/// Extracts field values and runs them through the Rust validator.
193/// For batches above 64 fields, validation runs in parallel via Rayon.
194///
195/// Args:
196///     instance: A Django model instance.
197///     schema: A `ModelSchema` compiled from the model class.
198///
199/// Returns:
200///     A dict with `valid_count`, `error_count`, `errors`, and `is_valid`.
201#[pyfunction]
202fn validate_instance<'py>(
203    py: Python<'py>,
204    instance: &Bound<'py, PyAny>,
205    schema: &ModelSchema,
206) -> PyResult<Bound<'py, PyDict>> {
207    let mut batch = Vec::with_capacity(schema.descriptors.len());
208
209    for desc in &schema.descriptors {
210        let py_val = instance.getattr(desc.name.as_str());
211        let fv = match py_val {
212            Ok(val) if !val.is_none() => model::convert_python_value_to_field(&val, desc)
213                .map_err(|e| -> pyforge::PyErr { e.into() })?,
214            _ => FieldValue::Null,
215        };
216        batch.push((desc.clone(), fv));
217    }
218
219    let report = validator::validate_field_batch(&batch);
220    validation_report_to_pydict(py, &report)
221}
222
223/// Extracts field descriptors from a Django model class.
224///
225/// Returns a list of dicts. For repeated use, prefer `ModelSchema(model_class)`
226/// which caches the result.
227#[pyfunction]
228fn extract_model_fields<'py>(
229    py: Python<'py>,
230    model_class: &Bound<'py, PyAny>,
231) -> PyResult<Bound<'py, PyList>> {
232    let descriptors = model::extract_field_descriptors(py, model_class)
233        .map_err(|e| -> pyforge::PyErr { e.into() })?;
234    descriptors_to_pylist(py, &descriptors)
235}
236
237/// Serializes field values from a dict (legacy API — prefer `serialize_instance`).
238#[pyfunction]
239fn serialize_fields<'py>(
240    py: Python<'py>,
241    field_descriptors: &Bound<'py, PyList>,
242    values: &Bound<'py, PyDict>,
243) -> PyResult<Bound<'py, PyDict>> {
244    let descriptors = extract_descriptor_list(field_descriptors)?;
245
246    let mut field_values = Vec::with_capacity(descriptors.len());
247    for desc in &descriptors {
248        let py_val = values.get_item(&desc.name)?;
249        match py_val {
250            Some(val) => {
251                let fv = model::convert_python_value_to_field(&val, desc)
252                    .map_err(|e| -> pyforge::PyErr { e.into() })?;
253                field_values.push(fv);
254            }
255            None => {
256                if desc.nullable || desc.has_default {
257                    field_values.push(FieldValue::Null);
258                } else {
259                    return Err(DjangoError::NullField {
260                        field: desc.name.clone(),
261                    }
262                    .into());
263                }
264            }
265        }
266    }
267
268    let record = serializer::serialize_model_fields(&descriptors, &field_values)
269        .map_err(|e| -> pyforge::PyErr { e.into() })?;
270    record_to_pydict(py, &record)
271}
272
273/// Validates field values from a list (legacy API — prefer `validate_instance`).
274#[pyfunction]
275fn validate_fields<'py>(
276    py: Python<'py>,
277    descriptors: &Bound<'py, PyList>,
278    values: &Bound<'py, PyList>,
279) -> PyResult<Bound<'py, PyDict>> {
280    let descs = extract_descriptor_list(descriptors)?;
281
282    let mut batch = Vec::with_capacity(descs.len());
283    for (i, desc) in descs.into_iter().enumerate() {
284        let py_val = values.get_item(i)?;
285        let fv = if py_val.is_none() {
286            FieldValue::Null
287        } else {
288            model::convert_python_value_to_field(&py_val, &desc)
289                .map_err(|e| -> pyforge::PyErr { e.into() })?
290        };
291        batch.push((desc, fv));
292    }
293
294    let report = validator::validate_field_batch(&batch);
295    validation_report_to_pydict(py, &report)
296}
297
298/// Returns the pyforge-django version string.
299#[pyfunction]
300fn version() -> &'static str {
301    env!("CARGO_PKG_VERSION")
302}
303
304/// The `pyforge_django` Python module.
305#[pymodule]
306fn pyforge_django(m: &Bound<'_, PyModule>) -> PyResult<()> {
307    m.add_class::<ModelSchema>()?;
308    m.add_function(wrap_pyfunction!(serialize_instance, m)?)?;
309    m.add_function(wrap_pyfunction!(serialize_batch, m)?)?;
310    m.add_function(wrap_pyfunction!(validate_instance, m)?)?;
311    m.add_function(wrap_pyfunction!(extract_model_fields, m)?)?;
312    m.add_function(wrap_pyfunction!(serialize_fields, m)?)?;
313    m.add_function(wrap_pyfunction!(validate_fields, m)?)?;
314    m.add_function(wrap_pyfunction!(version, m)?)?;
315    Ok(())
316}
317
318// ─── Internal helpers ───────────────────────────────────────────────────────
319
320/// Converts a serialized record to a Python dict.
321fn record_to_pydict<'py>(
322    py: Python<'py>,
323    record: &serde_json::Map<String, serde_json::Value>,
324) -> PyResult<Bound<'py, PyDict>> {
325    let output = PyDict::new(py);
326    for (key, val) in record {
327        let py_val = json_value_to_pyobject(py, val)?;
328        output.set_item(key, py_val)?;
329    }
330    Ok(output)
331}
332
333/// Converts a ValidationReport to a Python dict.
334fn validation_report_to_pydict<'py>(
335    py: Python<'py>,
336    report: &validator::ValidationReport,
337) -> PyResult<Bound<'py, PyDict>> {
338    let result = PyDict::new(py);
339    result.set_item("valid_count", report.valid_count)?;
340    result.set_item("error_count", report.error_count)?;
341    result.set_item("is_valid", report.is_valid())?;
342
343    let errors = PyList::empty(py);
344    for err in &report.field_errors {
345        let err_dict = PyDict::new(py);
346        err_dict.set_item("field", &err.field_name)?;
347        err_dict.set_item("message", &err.message)?;
348        err_dict.set_item("code", &err.code)?;
349        let params = PyDict::new(py);
350        for (k, v) in &err.params {
351            params.set_item(k, v)?;
352        }
353        err_dict.set_item("params", params)?;
354        errors.append(err_dict)?;
355    }
356    result.set_item("errors", errors)?;
357
358    Ok(result)
359}
360
361/// Converts descriptors to a Python list of dicts.
362fn descriptors_to_pylist<'py>(
363    py: Python<'py>,
364    descriptors: &[FieldDescriptor],
365) -> PyResult<Bound<'py, PyList>> {
366    let list = PyList::empty(py);
367    for desc in descriptors {
368        let dict = PyDict::new(py);
369        dict.set_item("name", &desc.name)?;
370        dict.set_item("type", desc.field_type.django_type_name())?;
371        dict.set_item("nullable", desc.nullable)?;
372        dict.set_item("has_default", desc.has_default)?;
373        match &desc.field_type {
374            DjangoFieldType::CharField { max_length }
375            | DjangoFieldType::EmailField { max_length }
376            | DjangoFieldType::UrlField { max_length }
377            | DjangoFieldType::SlugField { max_length } => {
378                dict.set_item("max_length", *max_length)?;
379            }
380            DjangoFieldType::DecimalField {
381                max_digits,
382                decimal_places,
383            } => {
384                dict.set_item("max_digits", *max_digits)?;
385                dict.set_item("decimal_places", *decimal_places)?;
386            }
387            DjangoFieldType::BinaryField {
388                max_length: Some(ml),
389            } => {
390                dict.set_item("max_length", *ml)?;
391            }
392            _ => {}
393        }
394        list.append(dict)?;
395    }
396    Ok(list)
397}
398
399/// Extracts a list of `FieldDescriptor` from a Python list of dicts.
400fn extract_descriptor_list(py_list: &Bound<'_, PyList>) -> PyResult<Vec<FieldDescriptor>> {
401    let mut descriptors = Vec::with_capacity(py_list.len());
402
403    for item in py_list.iter() {
404        let name: String = item.get_item("name")?.extract()?;
405        let field_type_str: String = item.get_item("type")?.extract()?;
406        let nullable: bool = item.get_item("nullable")?.extract()?;
407        let has_default: bool = item.get_item("has_default")?.extract()?;
408
409        let max_length: Option<usize> = item
410            .get_item("max_length")
411            .ok()
412            .and_then(|v| v.extract().ok());
413        let max_digits: Option<u32> = item
414            .get_item("max_digits")
415            .ok()
416            .and_then(|v| v.extract().ok());
417        let decimal_places: Option<u32> = item
418            .get_item("decimal_places")
419            .ok()
420            .and_then(|v| v.extract().ok());
421
422        let field_type = parse_field_type_str(&field_type_str, max_length, max_digits, decimal_places);
423
424        descriptors.push(FieldDescriptor {
425            name,
426            field_type,
427            nullable,
428            has_default,
429        });
430    }
431
432    Ok(descriptors)
433}
434
435/// Parses a Django field type name string into a `DjangoFieldType`.
436fn parse_field_type_str(
437    s: &str,
438    max_length: Option<usize>,
439    max_digits: Option<u32>,
440    decimal_places: Option<u32>,
441) -> DjangoFieldType {
442    match s {
443        "CharField" => DjangoFieldType::CharField {
444            max_length: max_length.unwrap_or(255),
445        },
446        "TextField" => DjangoFieldType::TextField,
447        "IntegerField" => DjangoFieldType::IntegerField,
448        "BigIntegerField" => DjangoFieldType::BigIntegerField,
449        "FloatField" => DjangoFieldType::FloatField,
450        "DecimalField" => DjangoFieldType::DecimalField {
451            max_digits: max_digits.unwrap_or(10),
452            decimal_places: decimal_places.unwrap_or(2),
453        },
454        "BooleanField" => DjangoFieldType::BooleanField,
455        "DateField" => DjangoFieldType::DateField,
456        "TimeField" => DjangoFieldType::TimeField,
457        "DateTimeField" => DjangoFieldType::DateTimeField,
458        "UUIDField" => DjangoFieldType::UuidField,
459        "JSONField" => DjangoFieldType::JsonField,
460        "BinaryField" => DjangoFieldType::BinaryField { max_length },
461        "EmailField" => DjangoFieldType::EmailField {
462            max_length: max_length.unwrap_or(254),
463        },
464        "URLField" => DjangoFieldType::UrlField {
465            max_length: max_length.unwrap_or(200),
466        },
467        "SlugField" => DjangoFieldType::SlugField {
468            max_length: max_length.unwrap_or(50),
469        },
470        _ => DjangoFieldType::TextField,
471    }
472}
473
474/// Converts a `serde_json::Value` into a Python object.
475fn json_value_to_pyobject<'py>(
476    py: Python<'py>,
477    value: &serde_json::Value,
478) -> PyResult<Bound<'py, PyAny>> {
479    match value {
480        serde_json::Value::Null => Ok(py.None().into_bound(py)),
481        serde_json::Value::Bool(b) => Ok(PyBool::new(py, *b).to_owned().into_any()),
482        serde_json::Value::Number(n) => {
483            if let Some(i) = n.as_i64() {
484                Ok(PyInt::new(py, i).into_any())
485            } else if let Some(f) = n.as_f64() {
486                Ok(PyFloat::new(py, f).into_any())
487            } else {
488                Ok(PyString::new(py, &n.to_string()).into_any())
489            }
490        }
491        serde_json::Value::String(s) => Ok(PyString::new(py, s).into_any()),
492        serde_json::Value::Array(arr) => {
493            let list = PyList::empty(py);
494            for item in arr {
495                list.append(json_value_to_pyobject(py, item)?)?;
496            }
497            Ok(list.into_any())
498        }
499        serde_json::Value::Object(map) => {
500            let dict = PyDict::new(py);
501            for (k, v) in map {
502                dict.set_item(k, json_value_to_pyobject(py, v)?)?;
503            }
504            Ok(dict.into_any())
505        }
506    }
507}