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