Merge pull request #13 from django-components/jo-refactor-move-rust-python-api-to-djc-core

Author: JuroOravec

Cargo.toml

@@ -6,11 +6,11 @@ members = [
 resolver = "2"
 
 [workspace.dependencies]
-pyo3 = { version = "0.27.0", features = ["extension-module"] }
+pyo3 = { version = "0.27.1", features = ["extension-module"] }
 quick-xml = "0.38.3"
 
 # https://ohadravid.github.io/posts/2023-03-rusty-python
 [profile.release]
-debug = true       # Debug symbols for profiler.
-lto = true         # Link-time optimization.
-codegen-units = 1  # Slower compilation but faster code. 
+debug = true      # Debug symbols for profiler.
+lto = true        # Link-time optimization.
+codegen-units = 1 # Slower compilation but faster code.

README.md

@@ -72,6 +72,24 @@ print(captured)
 # }
 ```
 
+## Architecture
+
+This project uses a multi-crate Rust workspace structure to maintain clean separation of concerns:
+
+### Crate structure
+
+- **`djc-html-transformer`**: Pure Rust library for HTML transformation
+- **`djc-template-parser`**: Pure Rust library for Django template parsing
+- **`djc-core`**: Python bindings that combines all other libraries
+
+### Design philosophy
+
+To make sense of the code, the Python API and Rust logic are defined separately:
+
+1. Each crate (AKA Rust package) has `lib.rs` (which is like Python's `__init__.py`). These files do not define the main logic, but only the public API of the crate. So the API that's to be used by other crates.
+2. The `djc-core` crate imports other crates
+3. And it is only this `djc-core` where we define the Python API using PyO3.
+
 ## Development
 
 1. Setup python env

crates/djc-core/Cargo.toml

@@ -1,5 +1,6 @@
 [package]
 name = "djc-core"
+description = "Singular Python API for Rust code used by django-components"
 version = "1.1.0"
 edition = "2021"
 

crates/djc-core/src/lib.rs

@@ -1,9 +1,76 @@
-use djc_html_transformer::set_html_attributes;
+use djc_html_transformer::{
+    set_html_attributes as set_html_attributes_rust, HtmlTransformerConfig,
+};
+use pyo3::exceptions::{PyValueError};
 use pyo3::prelude::*;
+use pyo3::types::{PyDict, PyTuple};
 
-/// A Python module implemented in Rust for high-performance transformations.
+/// Singular Python API that brings togther all the other Rust crates.
 #[pymodule]
 fn djc_core(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    // HTML transformer
     m.add_function(wrap_pyfunction!(set_html_attributes, m)?)?;
     Ok(())
 }
+
+/// Transform HTML by adding attributes to the elements.
+///
+/// Args:
+///     html (str): The HTML string to transform. Can be a fragment or full document.
+///     root_attributes (List[str]): List of attribute names to add to root elements only.
+///     all_attributes (List[str]): List of attribute names to add to all elements.
+///     check_end_names (bool, optional): Whether to validate matching of end tags. Defaults to false.
+///     watch_on_attribute (str, optional): If set, captures which attributes were added to elements with this attribute.
+///
+/// Returns:
+///     Tuple[str, Dict[str, List[str]]]: A tuple containing:
+///         - The transformed HTML string
+///         - A dictionary mapping captured attribute values to lists of attributes that were added
+///           to those elements. Only returned if watch_on_attribute is set, otherwise empty dict.
+///
+/// Example:
+///     >>> html = '<div data-id="123"><p>Hello</p></div>'
+///     >>> html, captured = set_html_attributes(html, ['data-root-id'], ['data-v-123'], watch_on_attribute='data-id')
+///     >>> print(captured)
+///     {'123': ['data-root-id', 'data-v-123']}
+///
+/// Raises:
+///     ValueError: If the HTML is malformed or cannot be parsed.
+#[pyfunction]
+#[pyo3(signature = (html, root_attributes, all_attributes, check_end_names=None, watch_on_attribute=None))]
+#[pyo3(
+    text_signature = "(html, root_attributes, all_attributes, *, check_end_names=False, watch_on_attribute=None)"
+)]
+pub fn set_html_attributes(
+    py: Python,
+    html: &str,
+    root_attributes: Vec<String>,
+    all_attributes: Vec<String>,
+    check_end_names: Option<bool>,
+    watch_on_attribute: Option<String>,
+) -> PyResult<Py<PyAny>> {
+    let config = HtmlTransformerConfig::new(
+        root_attributes,
+        all_attributes,
+        check_end_names.unwrap_or(false),
+        watch_on_attribute,
+    );
+
+    match set_html_attributes_rust(html, &config) {
+        Ok((html, captured)) => {
+            // Convert captured attributes to a Python dictionary
+            let captured_dict = PyDict::new(py);
+            for (id, attrs) in captured {
+                captured_dict.set_item(id, attrs)?;
+            }
+
+            // Convert items to Bound<PyAny> for the tuple
+            use pyo3::types::PyString;
+            let html_obj = PyString::new(py, &html).as_any().clone();
+            let dict_obj = captured_dict.as_any().clone();
+            let result = PyTuple::new(py, vec![html_obj, dict_obj])?;
+            Ok(result.into_any().unbind())
+        }
+        Err(e) => Err(PyValueError::new_err(e.to_string())),
+    }
+}

crates/djc-html-transformer/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "djc-html-transformer"
+description = "Apply attributes to HTML in a single pass"
 version = "1.0.3"
 edition = "2021"
 
 [dependencies]
-pyo3 = { workspace = true }
 quick-xml = { workspace = true }