djc-core 1.1.1__cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

djc_core/__init__.py

@@ -0,0 +1,16 @@
+# This file is what maturin auto-generates. But it seems maturin omits it when we have a __init__.pyi file.
+# So we have to manually include it here.
+# Following block of code is what maturin would've generated
+
+from .djc_core import *
+
+__doc__ = djc_core.__doc__
+if hasattr(djc_core, "__all__"):
+    __all__ = djc_core.__all__
+
+# OVERRIDES START HERE
+# Add here any additional public API that we defined purely in Python
+from djc_core.djc_safe_eval import safe_eval, unsafe, SecurityError
+
+if hasattr(djc_core, "__all__"):
+    __all__ += ["safe_eval", "unsafe", "SecurityError"]

djc_core/__init__.pyi

@@ -0,0 +1,2 @@
+from djc_core.djc_html_transformer import *
+from djc_core.djc_safe_eval import *

djc_core/djc_html_transformer.pyi

@@ -0,0 +1,36 @@
+from typing import List, Dict, Optional
+
+def set_html_attributes(
+    html: str,
+    root_attributes: List[str],
+    all_attributes: List[str],
+    check_end_names: Optional[bool] = None,
+    watch_on_attribute: Optional[str] = None,
+) -> tuple[str, Dict[str, List[str]]]:
+    """
+    Transform HTML by adding attributes to root and all 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 (Optional[bool]): Whether to validate matching of end tags. Defaults to None.
+        watch_on_attribute (Optional[str]): If set, captures which attributes were added to elements with this attribute.
+
+    Returns:
+        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><p>Hello</p></div>'
+        >>> set_html_attributes(html, ['data-root-id'], ['data-v-123'])
+        '<div data-root-id="" data-v-123=""><p data-v-123="">Hello</p></div>'
+
+    Raises:
+        ValueError: If the HTML is malformed or cannot be parsed.
+    """
+    ...
+
+__all__ = ["set_html_attributes"]

djc_core/djc_safe_eval/__init__.py

@@ -0,0 +1,8 @@
+from .sandbox import unsafe
+from .eval import safe_eval, SecurityError
+
+__all__ = [
+    "safe_eval",
+    "SecurityError",
+    "unsafe",
+]

djc_core/djc_safe_eval/__init__.pyi

@@ -0,0 +1,79 @@
+# ruff: noqa
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+class SecurityError(Exception):
+    """An error raised when a security violation occurs."""
+
+
+def safe_eval(
+    source: str,
+    *,
+    validate_variable: Optional[Callable[[str], bool]] = None,
+    validate_attribute: Optional[Callable[[Any, str], bool]] = None,
+    validate_subscript: Optional[Callable[[Any, Any], bool]] = None,
+    validate_callable: Optional[Callable[[Callable], bool]] = None,
+    validate_assign: Optional[Callable[[str, Any], bool]] = None,
+) -> Callable[[Dict[str, Any]], Any]:
+    """
+    Compile a Python expression string into a safe evaluation function.
+
+    This function takes a Python expression string and transforms it into safe code
+    by wrapping potentially unsafe operations (like variable access, function calls,
+    attribute access, etc.) with sandboxed function calls.
+
+    This is the re-implementation of Jinja's sandboxed evaluation logic.
+
+    Args:
+        source: The Python expression string to transform.
+        validate_variable: Optional extra validation for variable lookups.
+        validate_attribute: Optional extra validation for attribute access.
+        validate_subscript: Optional extra validation for subscript access.
+        validate_callable: Optional extra validation for function calls.
+        validate_assign: Optional extra validation for variable assignments.
+
+    Returns:
+        A compiled function that takes a context dictionary and evaluates the expression.
+        The function signature is: `func(context: Dict[str, Any]) -> Any`
+
+        The returned function may raise SecurityError if the expression is unsafe.
+
+    Raises:
+        SyntaxError: If the input is not valid Python syntax or contains forbidden constructs.
+
+    Example:
+        >>> compiled = safe_eval("my_var + 1")
+        >>> result = compiled({"my_var": 5})
+        >>> print(result)
+        6
+
+        >>> compiled = safe_eval("lambda x: x + my_var")
+        >>> func = compiled({"my_var": 10})
+        >>> print(func(5))
+        15
+
+        >>> compiled = safe_eval("unsafe_var + 1", validate_variable=lambda name: name != "unsafe_var")
+        >>> result = compiled({"unsafe_var": 5})
+        SecurityError: variable 'unsafe_var' is unsafe
+    """
+
+
+def unsafe(f: F) -> F:
+    """
+    Marks a function or method as unsafe.
+
+    Example:
+    ```python
+    @unsafe
+    def delete(self):
+        pass
+    ```
+    """
+
+
+__all__ = [
+    "safe_eval",
+    "SecurityError",
+    "unsafe",
+]

djc_core/djc_safe_eval/error.py

@@ -0,0 +1,155 @@
+import functools
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T", bound=Callable)
+
+
+def _format_error_with_context(
+    error: Exception,
+    source: str,
+    start_index: int,
+    end_index: int,
+    func_name: str,
+    add_prefix: bool = True,
+) -> None:
+    """
+    Format an error with underlined source code context.
+
+    Modifies the exception's message to include:
+    - Up to 2 preceding lines
+    - The lines containing the error (start_index to end_index)
+    - Up to 2 following lines
+    - Underlined code with ^^^ characters
+
+    Example:
+    ```
+    (a := 1 + my_var)
+              ^^^^^^
+    NameError: name 'my_var' is not defined
+    ```
+    """
+    # Convert source to lines with line numbers
+    lines = source.split("\n")
+
+    # Find which lines contain the error
+    line_starts = [0]  # Cumulative character count at start of each line
+    for line in lines[:-1]:
+        line_starts.append(line_starts[-1] + len(line) + 1)  # +1 for newline
+
+    # Find start and end line numbers (0-indexed)
+    start_line = 0
+    for i, line_start in enumerate(line_starts):
+        if line_start > start_index:
+            start_line = max(0, i - 1)
+            break
+    else:
+        start_line = len(lines) - 1
+
+    end_line = start_line
+    for i, line_start in enumerate(line_starts):
+        if line_start > end_index:
+            end_line = max(0, i - 1)
+            break
+    else:
+        end_line = len(lines) - 1
+
+    # Calculate column positions within each line
+    def get_column(line_num: int, char_index: int) -> int:
+        """Get column number (0-indexed) for a character index in a specific line."""
+        if line_num >= len(line_starts):
+            return 0
+        line_start = line_starts[line_num]
+        return max(0, char_index - line_start)
+
+    start_col = get_column(start_line, start_index)
+    end_col = get_column(end_line, end_index)
+
+    # Collect lines to show (up to 2 before and 2 after)
+    show_start = max(0, start_line - 2)
+    show_end = min(len(lines), end_line + 3)  # +3 because end is inclusive
+
+    # Build the formatted error message
+    error_lines = []
+    if add_prefix:
+        error_lines.append(f"Error in {func_name}: {type(error).__name__}: {error}")
+    else:
+        # Just use the original error message
+        error_lines.append(str(error))
+    error_lines.append("")
+
+    # Add source lines with line numbers
+    for line_num in range(show_start, show_end):
+        line_content = lines[line_num]
+        line_display_num = line_num + 1  # 1-indexed for display
+
+        # Calculate underline range for this line
+        underline_start = 0
+        underline_end = len(line_content)
+
+        if line_num == start_line == end_line:
+            # Error spans single line
+            underline_start = start_col
+            underline_end = min(len(line_content), end_col)
+        elif line_num == start_line:
+            # Error starts on this line
+            underline_start = start_col
+            underline_end = len(line_content)
+        elif line_num == end_line:
+            # Error ends on this line
+            underline_start = 0
+            underline_end = min(len(line_content), end_col)
+        elif start_line < line_num < end_line:
+            # Error spans this entire line
+            underline_start = 0
+            underline_end = len(line_content)
+        else:
+            # No error on this line, don't underline
+            underline_start = -1
+            underline_end = -1
+
+        # Add line with number
+        line_prefix = f"  {line_display_num:4d} | "
+        error_lines.append(line_prefix + line_content)
+
+        # Add underline if error is on this line
+        if underline_start >= 0:
+            # Create underline: prefix spaces + spaces to column + ^ characters
+            prefix_len = len(line_prefix)  # "    4 | " = 9 characters
+            underline = " " * (prefix_len + underline_start) + "^" * max(
+                1, underline_end - underline_start
+            )
+            error_lines.append(underline)
+
+    # Update exception message
+    error.args = ("\n".join(error_lines),)
+    # Mark that this error has been processed by error_context
+    error._safe_eval_error_processed = True  # type: ignore[attr-defined]
+
+
+def error_context(func_name: str) -> Callable[[T], T]:
+    """
+    Decorator that wraps functions to add error context reporting.
+
+    Extracts token tuple (start_index, end_index) from the third positional argument,
+    and on error, formats the error with underlined source code.
+    """
+
+    def decorator(func: T) -> T:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Functions that use this decorator have signature
+            # (context: Mapping[str, Any], source: str, token: tuple[int, int], *args: Any, **kwargs: Any) -> Any
+            source = args[1]
+            start_index, end_index = args[2]
+
+            try:
+                # On success return result normally
+                return func(*args, **kwargs)
+            except Exception as e:
+                # On error, modify the error message to include the source code context
+                _format_error_with_context(e, source, start_index, end_index, func_name)
+                raise
+
+        return wrapper
+
+    return decorator

djc_core/djc_safe_eval/eval.py

@@ -0,0 +1,428 @@
+import builtins
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+
+from djc_core.djc_core import safe_eval as safe_eval_rust
+from djc_core.djc_safe_eval.error import error_context, _format_error_with_context
+from djc_core.djc_safe_eval.sandbox import (
+    is_safe_attribute,
+    is_safe_callable,
+    is_safe_variable,
+)
+
+
+class SecurityError(Exception):
+    """An error raised when a security violation occurs."""
+
+    pass
+
+
+def safe_eval(
+    source: str,
+    *,
+    validate_variable: Optional[Callable[[str], bool]] = None,
+    validate_attribute: Optional[Callable[[Any, str], bool]] = None,
+    validate_subscript: Optional[Callable[[Any, Any], bool]] = None,
+    validate_callable: Optional[Callable[[Callable], bool]] = None,
+    validate_assign: Optional[Callable[[str, Any], bool]] = None,
+) -> Callable[[Dict[str, Any]], Any]:
+    """
+    Compile a Python expression string into a safe evaluation function.
+
+    This function takes a Python expression string and transforms it into safe code
+    by wrapping potentially unsafe operations (like variable access, function calls,
+    attribute access, etc.) with sandboxed function calls.
+
+    This is the re-implementation of Jinja's sandboxed evaluation logic.
+
+    Args:
+        source: The Python expression string to transform.
+        validate_variable: Optional extra validation for variable lookups.
+        validate_attribute: Optional extra validation for attribute access.
+        validate_subscript: Optional extra validation for subscript access.
+        validate_callable: Optional extra validation for function calls.
+        validate_assign: Optional extra validation for variable assignments.
+
+    Returns:
+        A compiled function that takes a context dictionary and evaluates the expression.
+        The function signature is: `func(context: Dict[str, Any]) -> Any`
+
+        The returned function may raise SecurityError if the expression is unsafe.
+
+    Raises:
+        SyntaxError: If the input is not valid Python syntax or contains forbidden constructs.
+
+    Example:
+        >>> compiled = safe_eval("my_var + 1")
+        >>> result = compiled({"my_var": 5})
+        >>> print(result)
+        6
+
+        >>> compiled = safe_eval("lambda x: x + my_var")
+        >>> func = compiled({"my_var": 10})
+        >>> print(func(5))
+        15
+
+        >>> compiled = safe_eval("unsafe_var + 1", validate_variable=lambda name: name != "unsafe_var")
+        >>> result = compiled({"unsafe_var": 5})
+        SecurityError: variable 'unsafe_var' is unsafe
+    """
+    # If user specified extra validation functions, wrap the original functions with them
+    if validate_variable is not None:
+
+        @error_context("variable")
+        def variable_fn(
+            __context: Mapping[str, Any],
+            __source: str,
+            __token: Tuple[int, int],
+            var_name: str,
+        ) -> Any:
+            if not validate_variable(var_name):
+                raise SecurityError(f"variable '{var_name}' is unsafe")
+            return variable(__context, __source, __token, var_name)
+    else:
+        variable_fn = variable
+
+    if validate_attribute is not None:
+
+        @error_context("attribute")
+        def attribute_fn(
+            __context: Mapping[str, Any],
+            __source: str,
+            __token: Tuple[int, int],
+            obj: Any,
+            attr_name: str,
+        ) -> Any:
+            if not validate_attribute(obj, attr_name):
+                raise SecurityError(
+                    f"attribute '{attr_name}' on object '{type(obj)}' is unsafe"
+                )
+            return attribute(__context, __source, __token, obj, attr_name)
+    else:
+        attribute_fn = attribute
+
+    if validate_subscript is not None:
+
+        @error_context("subscript")
+        def subscript_fn(
+            __context: Mapping[str, Any],
+            __source: str,
+            __token: Tuple[int, int],
+            obj: Any,
+            key: Any,
+        ) -> Any:
+            if not validate_subscript(obj, key):
+                raise SecurityError(f"key '{key}' on object '{type(obj)}' is unsafe")
+            return subscript(__context, __source, __token, obj, key)
+    else:
+        subscript_fn = subscript
+
+    if validate_callable is not None:
+
+        @error_context("call")
+        def call_fn(
+            __context: Mapping[str, Any],
+            __source: str,
+            __token: Tuple[int, int],
+            func: Callable,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Any:
+            if not validate_callable(func):
+                raise SecurityError(f"function '{func!r}' is unsafe")
+            return call(__context, __source, __token, func, *args, **kwargs)
+    else:
+        call_fn = call
+
+    if validate_assign is not None:
+
+        @error_context("assign")
+        def assign_fn(
+            __context: Mapping[str, Any],
+            __source: str,
+            __token: Tuple[int, int],
+            var_name: str,
+            value: Any,
+        ) -> Any:
+            if not validate_assign(var_name, value):
+                raise SecurityError(f"assignment to variable '{var_name}' is unsafe")
+            return assign(__context, __source, __token, var_name, value)
+    else:
+        assign_fn = assign
+
+    # Create evaluation namespace with wrapped functions
+    # These are captured in the closure of the lambda function we'll create
+    eval_namespace = {
+        "variable": variable_fn,
+        "attribute": attribute_fn,
+        "subscript": subscript_fn,
+        "call": call_fn,
+        "assign": assign_fn,
+        "slice": slice,
+        "interpolation": interpolation,
+        "template": template,
+        "format": format,
+        # Pass through the source string. This way we won't have to re-define
+        # the functions on each evaluation.
+        "source": source,
+    }
+
+    # Get transformed code from Rust
+    transformed_code = safe_eval_rust(source)
+
+    # Wrap the transformed code in a lambda that captures the helper functions
+    # This avoids the overhead of calling eval() and creating a dict on each evaluation
+    # NOTE: The lambda is assigned to a variable because we use `exec()` instead of `eval()`
+    #       to support triple-quoted multi-line strings (which `eval()` doesn't handle).
+    #       And while `eval()` returns its result directly, with `exec()` we need to assign it to a variable.
+    #       We wrap with parentheses and newlines to allow multi-line expressions and trailing comments:
+    #       the newlines ensure that trailing comments don't swallow the closing parenthesis.
+    lambda_code = f"_eval_expr = lambda context: (\n{transformed_code}\n)"
+    eval_locals = {}
+    try:
+        # Execute the function definition
+        exec(lambda_code, eval_namespace, eval_locals)
+        # Get the function from the namespace
+        eval_func = eval_locals["_eval_expr"]
+    except Exception as e:
+        # If the error hasn't been processed by error_context decorator,
+        # include the whole expression in the error message (without the "Error in..." prefix)
+        if not getattr(e, "_safe_eval_error_processed", False):
+            _format_error_with_context(
+                e, source, 0, len(source), "expression", add_prefix=False
+            )
+            # Mark it as processed to avoid double-formatting if re-raised
+            e._safe_eval_error_processed = True  # type: ignore[attr-defined]
+        raise
+
+    # Return a function that calls the compiled function directly
+    # This is much faster than calling exec() on each evaluation
+    def evaluate(context: Dict[str, Any]) -> Any:
+        """
+        Evaluate the compiled expression with the given context.
+
+        Args:
+            context: Dictionary of variables to use in evaluation.
+
+        Returns:
+            The result of evaluating the expression.
+        """
+        try:
+            return eval_func(context)
+        except Exception as e:
+            # If the error hasn't been processed by error_context decorator,
+            # include the whole expression in the error message (without the "Error in..." prefix)
+            if not getattr(e, "_safe_eval_error_processed", False):
+                _format_error_with_context(
+                    e, source, 0, len(source), "expression", add_prefix=False
+                )
+                # Mark it as processed to avoid double-formatting if re-raised
+                e._safe_eval_error_processed = True  # type: ignore[attr-defined]
+            raise
+
+    return evaluate
+
+
+# Following are the operations that we intercept. These functions are called by the transformed code.
+#
+# E.g.
+# ```python
+# my_var
+# obj := {"attr": 2}
+# ```
+#
+# is transformed into:
+# ```python
+# variable((0, 4), source, context, "my_var")
+# assign((0, 18), source, context, "obj", {"attr": 2})
+# ```
+#
+# Each interceptor function receives the same 3 first positional arguments:
+# - __context: Mapping[str, Any] - The evaluation context
+# - __source: str - The source code
+# - __token: Tuple[int, int] - The token tuple (start_index, end_index)
+#
+# The __source and __token arguments are used by `@error_context` decorator to add the position
+# where the error occurred to the error message.
+# E.g.
+# ```
+# obj := eval("unsafe code")
+#        ^^^^^^^^^^^^^^^^^^^
+# SecurityError: <built-in function eval> is unsafe
+# ```
+
+
+@error_context("variable")
+def variable(
+    __context: Mapping[str, Any], __source: str, __token: Tuple[int, int], var_name: str
+) -> Any:
+    """Look up a variable in the evaluation context, e.g. `my_var`"""
+    if not is_safe_variable(var_name):
+        raise SecurityError(f"variable '{var_name}' is unsafe")
+    return __context[var_name]
+
+
+@error_context("attribute")
+def attribute(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    obj: Any,
+    attr_name: str,
+) -> Any:
+    """Access an attribute of an object, e.g. `obj.attr`"""
+    if not is_safe_attribute(obj, attr_name):
+        raise SecurityError(
+            f"attribute '{attr_name}' on object '{type(obj)}' is unsafe"
+        )
+    return getattr(obj, attr_name)
+
+
+@error_context("subscript")
+def subscript(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    obj: Any,
+    key: Any,
+) -> Any:
+    """Access a key of an object, e.g. `obj[key]`"""
+    # NOTE: Right now subscript uses the same logic as attribute
+    if not is_safe_attribute(obj, key):
+        raise SecurityError(f"key '{key}' on object '{type(obj)}' is unsafe")
+    return obj[key]
+
+
+# NOTE: Our internal args are prefixed with `__` to avoid keyword argument conflicts with the original input.
+@error_context("call")
+def call(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    func: Callable,
+    *args: Any,
+    **kwargs: Any,
+) -> Any:
+    """Call a function, e.g. `func(arg1, arg2, ...)`"""
+    is_safe, replacement_message = is_safe_callable(func)
+    if not is_safe:
+        error_msg = f"function '{func!r}' is unsafe"
+        if replacement_message:
+            error_msg += f". {replacement_message}"
+        raise SecurityError(error_msg)
+    return func(*args, **kwargs)
+
+
+@error_context("assign")
+def assign(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    var_name: str,
+    value: Any,
+) -> Any:
+    """Assign a value to a variable in the evaluation context, e.g. `(x := 5)`"""
+    if not is_safe_variable(var_name):
+        raise SecurityError(f"variable '{var_name}' is unsafe")
+    __context[var_name] = value
+    return value
+
+
+# NOTE: We don't need to validate the slice arguments as they are always safe.
+#       Slice had to be redefined from bracket syntax `obj[lower:upper:step]` to function call syntax
+#       `slice(lower, upper, step)` because we convert brackets to function calls `subscript(obj, key)`.
+#       But since we had to intercept it, this function ensures we show the correct position in the error message.
+@error_context("slice")
+def slice(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    lower: Any = None,
+    upper: Any = None,
+    step: Any = None,
+) -> builtins.slice:
+    """Create a slice object, e.g. `obj[lower:upper:step]`"""
+    return builtins.slice(lower, upper, step)
+
+
+# For compatiblity with Python 3.14+:
+# - on 3.14+, t-strings are created as normal
+# - on >=3.13, using t-strings raises an error
+# See: https://docs.python.org/3.14/library/string.templatelib.html#template-strings
+@error_context("interpolation")
+def interpolation(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    value: Any,
+    expression: str,
+    conversion: Optional[str],
+    format_spec: str,
+) -> Any:
+    """Process t-string interpolation."""
+    try:
+        from string.templatelib import Interpolation  # type: ignore[import-untyped]
+    except ImportError:
+        raise NotImplementedError("t-string interpolation is not supported")
+    return Interpolation(value, expression, conversion, format_spec)
+
+
+@error_context("template")
+def template(
+    __context: Mapping[str, Any], __source: str, __token: Tuple[int, int], *parts: Any
+) -> Any:
+    """Construct a template from parts."""
+    try:
+        from string.templatelib import Template  # type: ignore[import-untyped]
+    except ImportError:
+        raise NotImplementedError("t-string template construction is not supported")
+    return Template(*parts)
+
+
+@error_context("format")
+def format(
+    __context: Mapping[str, Any],
+    __source: str,
+    __token: Tuple[int, int],
+    template_string: str,
+    *args: Any,
+) -> str:
+    """
+    Format a template string with arguments.
+
+    Each argument is a tuple (value, conversion_flag, format_spec) where:
+    - value: The expression value to format
+    - conversion_flag: "r", "s", "a", or None
+    - format_spec: A string for static specs, or a tuple (template, *args) for dynamic specs
+
+    This wraps the built-in str.format() method so that errors inside f-strings get nice
+    error reporting with underlining via the `@error_context` decorator.
+    """
+    processed_args = []
+    for value, conversion_flag, format_spec in args:
+        # Apply conversion flag if present
+        if conversion_flag == "r":
+            value = repr(value)
+        elif conversion_flag == "s":
+            value = str(value)
+        elif conversion_flag == "a":
+            value = ascii(value)
+        # If None, keep value as-is
+
+        # Apply format spec if present (non-empty string or tuple)
+        if format_spec:
+            if isinstance(format_spec, tuple):
+                # Dynamic format spec: (template, *args)
+                spec_template, *spec_args = format_spec
+                # Format the spec template with its args
+                format_spec_str = spec_template.format(*spec_args)
+            else:
+                # Static format spec: already a string
+                format_spec_str = format_spec
+
+            # Only apply format spec if it's non-empty
+            if format_spec_str:
+                value = builtins.format(value, format_spec_str)
+
+        processed_args.append(value)
+
+    return template_string.format(*processed_args)

djc_core/djc_safe_eval/sandbox.py

@@ -0,0 +1,227 @@
+"""
+A sandbox layer that ensures unsafe operations cannot be performed.
+Useful when the Python expression itself comes from an untrusted source.
+
+Based on the Jinja v3.1.6 sandbox implementation.
+See https://github.com/pallets/jinja/blob/5ef70112a1ff19c05324ff889dd30405b1002044/src/jinja2/sandbox.py
+
+We do NOT support:
+- Builtins. If you need to use `len()`, `str()`, `int()`, `list()`, `dict()`, etc.,
+  you'll have to pass them as variables.
+- "safe" range. Jinja puts limit on the number of items a range may produce.
+  We don't expose `range()` function to the sandboxed code at all.
+- "Immutable" sandbox (e.g. raising when mutating a list).
+- Async functions, coroutines, etc.
+- `str.format` and `str.format_map` are not allowed as they can be used to access unsafe variables.
+  Use f-strings instead.
+
+We add these safety features not present in Jinja:
+- Prevent users from calling unsafe builtins like `eval` even if they were passed as variables.
+
+To mark custom functions as unsafe, use the `@unsafe` decorator.
+
+Example:
+```python
+@unsafe
+def delete(self):
+    pass
+```
+"""
+
+import builtins
+import types
+from typing import Any, Callable, Dict, Optional, Set, Tuple, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+#: Unsafe function attributes.
+UNSAFE_FUNCTION_ATTRIBUTES: Set[str] = set()
+
+#: Unsafe method attributes. Function attributes are unsafe for methods too.
+UNSAFE_METHOD_ATTRIBUTES: Set[str] = set()
+
+#: unsafe generator attributes.
+UNSAFE_GENERATOR_ATTRIBUTES = {"gi_frame", "gi_code"}
+
+#: unsafe attributes on coroutines
+UNSAFE_COROUTINE_ATTRIBUTES = {"cr_frame", "cr_code"}
+
+#: unsafe attributes on async generators
+UNSAFE_ASYNC_GENERATOR_ATTRIBUTES = {"ag_code", "ag_frame"}
+
+# Builtin functions that users have no business calling in sandboxed code.
+# We check for these as it may happen that these functons were passed as variables,
+# and the user may try to call them.
+# Dictionary mapping unsafe functions to replacement messages.
+_UNSAFE_BUILTIN_FUNCTION_NAMES = {
+    "__build_class__": None,
+    "__import__": None,
+    "__loader__": None,
+    "aiter": None,
+    "anext": None,
+    "breakpoint": None,
+    "classmethod": None,
+    "compile": None,
+    "delattr": None,
+    "eval": None,
+    "exec": None,
+    "exit": None,
+    "getattr": None,
+    "globals": None,
+    "help": None,
+    "input": None,
+    "locals": None,
+    "memoryview": None,
+    "open": None,
+    "property": None,
+    "quit": None,
+    "setattr": None,
+    "staticmethod": None,
+    "super": None,
+    "vars": None,
+}
+UNSAFE_BUILTIN_FUNCTIONS: Dict[Any, Optional[str]] = {
+    getattr(builtins, attr): replacement
+    for attr, replacement in _UNSAFE_BUILTIN_FUNCTION_NAMES.items()
+    if hasattr(builtins, attr)
+}
+
+# These are not allowed as they can be used to access unsafe variables,
+# e.g. `"a{0.b.__builtins__[__import__]}b".format({"b": 42})`
+# Use f-strings instead.
+UNSAFE_FUNCTIONS: Dict[Any, Optional[str]] = {
+    str.format: "Use f-strings instead.",
+    str.format_map: "Use f-strings instead.",
+}
+
+
+def unsafe(f: F) -> F:
+    """
+    Marks a function or method as unsafe.
+
+    Example:
+    ```python
+    @unsafe
+    def delete(self):
+        pass
+    ```
+    """
+    f.unsafe_callable = True  # type: ignore
+    return f
+
+
+def _is_internal_attribute(obj: Any, attr: str) -> bool:
+    """
+    Test if the attribute is an internal Python attribute.
+
+    >>> _is_internal_attribute(str, "mro")
+    True
+    >>> _is_internal_attribute(str, "upper")
+    False
+    """
+    if isinstance(obj, types.FunctionType):
+        if attr in UNSAFE_FUNCTION_ATTRIBUTES:
+            return True
+    elif isinstance(obj, types.MethodType):
+        if attr in UNSAFE_FUNCTION_ATTRIBUTES or attr in UNSAFE_METHOD_ATTRIBUTES:
+            return True
+    elif isinstance(obj, type):
+        if attr == "mro":
+            return True
+    elif isinstance(obj, (types.CodeType, types.TracebackType, types.FrameType)):
+        return True
+    elif isinstance(obj, types.GeneratorType):
+        if attr in UNSAFE_GENERATOR_ATTRIBUTES:
+            return True
+    elif hasattr(types, "CoroutineType") and isinstance(obj, types.CoroutineType):
+        if attr in UNSAFE_COROUTINE_ATTRIBUTES:
+            return True
+    elif hasattr(types, "AsyncGeneratorType") and isinstance(
+        obj, types.AsyncGeneratorType
+    ):
+        if attr in UNSAFE_ASYNC_GENERATOR_ATTRIBUTES:
+            return True
+    return attr.startswith("__")
+
+
+def is_safe_attribute(obj: Any, attr: str) -> bool:
+    """
+    Check if the attribute of an object is safe to access.
+
+    Unsafe attributes are:
+    - Starting with an underscore `_`
+    - Internal attributes as set by `_is_internal_attribute`.
+    """
+    # Non-string subscripts should be fine, as they should be found only
+    # as list slices.
+    if not isinstance(attr, str):
+        return True
+    return not (attr.startswith("_") or _is_internal_attribute(obj, attr))
+
+
+def is_safe_callable(obj: Any) -> Tuple[bool, Optional[str]]:
+    """
+    Check if an object is safely callable.
+
+    Returns:
+        Tuple of (is_safe, replacement_message)
+        - is_safe: True if safe to call, False otherwise
+        - replacement_message: Optional string suggesting a replacement, None if not applicable
+
+    Unsafe callables are:
+    - Decorated with `@unsafe`
+    - Marked with `obj.alters_data = True` (Django convention)
+    - Unsafe builtins (e.g. `eval`)
+    - `str.format` or `str.format_map` (use f-strings instead)
+    """
+    # Check for bound methods (e.g., "string".format())
+    # Handle both regular methods (types.MethodType) and built-in methods (builtin_function_or_method)
+    underlying_func = None
+    if isinstance(obj, types.MethodType):
+        # Regular Python method - has __func__ attribute
+        underlying_func = obj.__func__
+    elif (
+        hasattr(obj, "__self__")
+        and hasattr(obj, "__name__")
+        and not hasattr(obj, "__func__")
+    ):
+        # Built-in method descriptor (e.g., str.format, str.format_map)
+        # These are bound methods that don't have __func__, but we can get the original descriptor
+        try:
+            underlying_func = getattr(type(obj.__self__), obj.__name__)
+        except (AttributeError, TypeError):
+            pass
+
+    if underlying_func is not None:
+        # Check marks on inner function (decorated with @unsafe or alters_data)
+        if getattr(underlying_func, "unsafe_callable", False) or getattr(
+            underlying_func, "alters_data", False
+        ):
+            return (False, None)
+        # Check if the underlying function is in our unsafe dictionaries
+        if underlying_func in UNSAFE_FUNCTIONS:
+            return (False, UNSAFE_FUNCTIONS[underlying_func])
+        if underlying_func in UNSAFE_BUILTIN_FUNCTIONS:
+            return (False, UNSAFE_BUILTIN_FUNCTIONS[underlying_func])
+
+    # Check marks on the outer function (decorated with @unsafe or alters_data)
+    if getattr(obj, "unsafe_callable", False) or getattr(obj, "alters_data", False):
+        return (False, None)
+
+    # Check identity for unbound functions
+    if obj in UNSAFE_FUNCTIONS:
+        return (False, UNSAFE_FUNCTIONS[obj])
+    if obj in UNSAFE_BUILTIN_FUNCTIONS:
+        return (False, UNSAFE_BUILTIN_FUNCTIONS[obj])
+
+    return (True, None)
+
+
+def is_safe_variable(var_name: str) -> bool:
+    """
+    Check if a variable is safe to access.
+
+    Unsafe variables are:
+    - Starting with an underscore `_`
+    """
+    return not var_name.startswith("_")

djc_core-1.1.1.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: djc_core
+Version: 1.1.1
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+License-File: LICENSE
+Summary: HTML parser used by django-components written in Rust.
+Keywords: django,components,html
+Author-email: Juro Oravec <juraj.oravec.josefson@gmail.com>
+License: MIT
+Requires-Python: >=3.8, <4.0
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/django-components/djc-core/blob/main/CHANGELOG.md
+Project-URL: Donate, https://github.com/sponsors/EmilStenstrom
+Project-URL: Homepage, https://github.com/django-components/djc-core/
+Project-URL: Issues, https://github.com/django-components/djc-core/issues
+
+# djc-core
+
+[![PyPI - Version](https://img.shields.io/pypi/v/djc-core)](https://pypi.org/project/djc-core/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/djc-core)](https://pypi.org/project/djc-core/) [![PyPI - License](https://img.shields.io/pypi/l/djc-core)](https://github.com/django-components/djc-core/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/djc-core)](https://pypistats.org/packages/djc-core) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/djc-core/tests.yml)](https://github.com/django-components/djc-core/actions/workflows/tests.yml)
+
+Rust-based parsers and toolings used by [django-components](https://github.com/django-components/django-components). Exposed as a Python package with [maturin](https://www.maturin.rs/).
+
+## Installation
+
+```sh
+pip install djc-core
+```
+
+## Packages
+
+### Safe eval
+
+Re-implementation of Jinja2's sandboxed evaluation logic, built in Rust using the Ruff Python parser.
+
+**Usage**
+
+```python
+from djc_core import safe_eval
+
+# Compile an expression
+compiled = safe_eval("my_var + 1")
+
+# Evaluate with a context
+result = compiled({"my_var": 5})
+print(result)  # 6
+```
+
+**Key Features**
+
+- **Security**: Blocks unsafe operations like `eval()`, `exec()`, accessing private attributes (`_private`), and dangerous builtins
+- **Variable tracking**: Reports which variables are used and which are assigned via walrus operator (`:=`)
+- **Error reporting**: Provides detailed error messages with underlined source code indicating where errors occurred
+- **Performance**: Implemented in Rust for fast parsing and transformation
+
+**Supported Syntax**
+
+Almost all Python expression features are supported:
+
+- Literals, data structures, operators
+- Comprehensions, lambdas, conditionals
+- F-strings and t-strings
+- Function calls, attribute/subscript access
+- Walrus operator for assignments
+
+**Security**
+
+By default, `safe_eval` blocks:
+
+- Unsafe builtins (`eval`, `exec`, `open`, etc.)
+- Private attributes (starting with `_`)
+- Dunder attributes (`__class__`, `__dict__`, etc.)
+- Functions decorated with `@unsafe`
+- Django methods marked with `alters_data = True`
+
+For more details, examples, and advanced usage, see [`crates/djc-safe-eval/README.md`](crates/djc-safe-eval/README.md).
+
+> **WARNING!** Just like Jinja2 and Django's templating, none of these are 100% bulletproof solutions!
+>
+> Because they work by blocking known unsafe scenarios. There can always be a new unknown scenario.
+>
+> If you expose a dangerous function to the template/expression, this can be potentially exploited.
+>
+> Safer approach would be to allow to call only those functions that have been explicitly tagged as safe.
+>
+> If you really need to render templates submitted from your users you should instead define the UI blocks yourself, and let your users pick and choose through JSON or similar:
+>
+> ```json
+> {
+>   "template": "my_template",
+>   "user_id": 123,
+>   "blocks": [
+>     {"type": "header", "title": "Hello!"},
+>     {"type": "paragraph", "text": "This is my blog"},
+>     {"type": "table", "data": [[1, 2, 3], [3, 4, 5]]},
+>   ]
+> }
+> ```
+
+### HTML transfomer
+
+Transform HTML in a single pass. This is a simple implementation.
+
+This implementation was found to be 40-50x faster than our Python implementation, taking ~90ms to parse 5 MB of HTML.
+
+**Usage**
+
+```python
+from djc_core import set_html_attributes
+
+html = '<div><p>Hello</p></div>'
+result, _ = set_html_attributes(
+  html,
+  # Add attributes to the root elements
+  root_attributes=['data-root-id'],
+  # Add attributes to all elements
+  all_attributes=['data-v-123'],
+)
+```
+
+To save ourselves from re-parsing the HTML, `set_html_attributes` returns not just the transformed HTML, but also a dictionary as the second item.
+
+This dictionary contains a record of which HTML attributes were written to which elemenents.
+
+To populate this dictionary, you need set `watch_on_attribute` to an attribute name.
+
+Then, during the HTML transformation, we check each element for this attribute. And if the element HAS this attribute, we:
+
+1. Get the value of said attribute
+2. Record the attributes that were added to the element, using the value of the watched attribute as the key.
+
+```python
+from djc_core import set_html_attributes
+
+html = """
+  <div data-watch-id="123">
+    <p data-watch-id="456">
+      Hello
+    </p>
+  </div>
+"""
+
+result, captured = set_html_attributes(
+  html,
+  # Add attributes to the root elements
+  root_attributes=['data-root-id'],
+  # Add attributes to all elements
+  all_attributes=['data-djc-tag'],
+  # Watch for this attribute on elements
+  watch_on_attribute='data-watch-id',
+)
+
+print(captured)
+# {
+#   '123': ['data-root-id', 'data-djc-tag'],
+#   '456': ['data-djc-tag'],
+# }
+```
+
+## 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
+
+   ```sh
+   python -m venv .venv
+   ```
+
+2. Install dependencies
+
+   ```sh
+   pip install -r requirements-dev.txt
+   ```
+
+   The dev requirements also include `maturin` which is used packaging a Rust project
+   as Python package.
+
+3. Install Rust
+
+   See https://www.rust-lang.org/tools/install
+
+4. Run Rust tests
+
+   ```sh
+   cargo test
+   ```
+
+5. Build the Python package
+
+   ```sh
+   maturin develop
+   ```
+
+   To build the production-optimized package, use `maturin develop --release`.
+
+6. Run Python tests
+
+   ```sh
+   pytest
+   ```
+
+   > NOTE: When running Python tests, you need to run `maturin develop` first.
+
+## Deployment
+
+Deployment is done automatically via GitHub Actions.
+
+To publish a new version of the package, you need to:
+
+1. Bump the version in `pyproject.toml` and `Cargo.toml`
+2. Open a PR and merge it to `main`.
+3. Create a new tag on the `main` branch with the new version number (e.g. `1.0.0`), or create a new release in the GitHub UI.
+

djc_core-1.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+djc_core/__init__.py,sha256=Ln1Cbt4owEeLpp3dEaqW3aittUD4NXRKubgRqRKgy5o,580
+djc_core/__init__.pyi,sha256=Md_d2R3hcxDpRnUMp7j2aaiGJcb_MLlPGWnYgvAwfGs,81
+djc_core/djc_core.cpython-314t-aarch64-linux-gnu.so,sha256=1aMA246JUNbIgHVGsPohTKBW2r2ZpkeZ32ZNi3_lcZs,22350952
+djc_core/djc_html_transformer.pyi,sha256=HY7-gMgzNOqUptGtNPl1yIEZ5zSPXpxCim0hN846kks,1465
+djc_core/djc_safe_eval/__init__.py,sha256=sd8eDySbeKk4Bu7d_cwMg6aQQcyOtD2IpAbJAZoOCiQ,137
+djc_core/djc_safe_eval/__init__.pyi,sha256=-iJZ4LrvzAZf1HiaPqXAR7sr9fHyKl2Zqn5mXuLpq6g,2555
+djc_core/djc_safe_eval/error.py,sha256=1iQRvbC6p9WNW33igCeP7qSEuCCPACRIrdH6CiC6Mmc,5306
+djc_core/djc_safe_eval/eval.py,sha256=6-ViPj8ILkhtabG6T_b-zBjmOABbbRgsPnKI-pl7Feo,15232
+djc_core/djc_safe_eval/sandbox.py,sha256=wFVPVgjK0Vcv1GgbuqAYo89bETl_ClibOWpDklI5K6g,7482
+djc_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djc_core-1.1.1.dist-info/METADATA,sha256=dpZWI3e_TkLbw52YCSLWxQX_PUr2DBs-fapiPZGjyVY,7873
+djc_core-1.1.1.dist-info/WHEEL,sha256=K42pU0cRVtxA8N2aGHpXHx_0G7KEA_mBkTgnb38YQKw,151
+djc_core-1.1.1.dist-info/licenses/LICENSE,sha256=flYqsTDuObp3YA1SgILjCKp6YxKDC6FcMVBpJNicRq0,1074
+djc_core-1.1.1.dist-info/RECORD,,

djc_core-1.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp314-cp314t-manylinux_2_17_aarch64
+Tag: cp314-cp314t-manylinux2014_aarch64

djc_core-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 django-components
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.