jsonatapy 2.2.5__tar.gz → 2.2.6__tar.gz

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/CHANGELOG.md

@@ -19,6 +19,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [2.2.6] - 2026-07-20
+
+### Added
+- Host-callable custom functions (Rust core): `Evaluator::register_fn` and
+  `Evaluator::register_fn_override` let a host register native functions callable
+  from an expression as `$name(...)` — the equivalent of jsonata-js's
+  `registerFunction`. Functions are plain closures
+  (`Fn(&[JValue]) -> Result<JValue, EvaluatorError>`) and resolve after the
+  expression's own bindings/lambdas and before built-ins. `register_fn` rejects
+  collisions with built-ins; `register_fn_override` allows deliberately replacing
+  the impure built-ins (`$now`, `$millis`, `$random`, `$eval`) for determinism
+  injection or sandboxing. Evaluation stays synchronous. See
+  `examples/host_functions.rs` and the Rust crate docs.
+- Host-callable custom functions (Python binding): `JsonataExpression.register(name,
+  func)` and `.register_override(name, func)` expose the above to Python. The callable
+  receives already-evaluated positional arguments and must return a JSON-compatible
+  value synchronously; an `async def` (coroutine) is rejected at call time with
+  guidance to await I/O outside jsonata and pass results via `bindings`. Collision and
+  compilable-builtin-override rules are validated at `register()` time.
+- Host-callable custom functions (C ABI): `jsonata_register_fn(expr, name, fn, user_data)`
+  and `jsonata_register_fn_override(...)` expose the feature to C and any language with C
+  interop. The callback receives its arguments as a JSON array string and returns a JSON
+  result string (jsonata copies it; the host retains ownership), or NULL to signal an error.
+  See `bindings/c/jsonata.h`, `bindings/c/README.md`, and `bindings/c/examples/smoke.c`.
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
 ## [2.2.5] - 2026-07-14
 
 ### Added

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/Cargo.lock

@@ -586,7 +586,7 @@ dependencies = [
 
 [[package]]
 name = "jsonata-core"
-version = "2.2.5"
+version = "2.2.6"
 dependencies = [
  "assert_cmd",
  "base64",

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonata-core"
-version = "2.2.5"
+version = "2.2.6"
 edition = "2021"
 authors = ["txjmb <txjmb@users.noreply.github.com>"]
 description = "High-performance Rust implementation of JSONata query and transformation language"

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jsonatapy
-Version: 2.2.5
+Version: 2.2.6
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -47,19 +47,26 @@ Project-URL: Documentation, https://github.com/txjmb/jsonata-core
 Project-URL: Homepage, https://github.com/txjmb/jsonata-core
 Project-URL: Repository, https://github.com/txjmb/jsonata-core
 
-# jsonata-core + jsonatapy
+# jsonata-core (rust) + jsonatapy + jsonata C-ABI library + jsonata cli
+#### Pypi stats
+[![jsonatapy Downloads Last Month](https://assets.piptrends.com/get-last-month-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Month by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Downloads Last Week](https://assets.piptrends.com/get-last-week-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Week by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Average Daily Downloads](https://assets.piptrends.com/get-average-downloads-badge/jsonatapy.svg 'jsonatapy Average Daily Downloads by pip Trends')](https://piptrends.com/package/jsonatapy)
 
-High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python bindings.
+#### Crates.io stats
+![downloads](https://shieldcn.dev/crates/d/jsonata-core.svg)
+
+High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python binding and C ABI/library.  If you use this library, please add a github star!
 
 Much of this project was built using Claude Code with significant human oversight. There was no performant
 JSONata implementation in Python, so the goal was to port JSONata to Rust (with a PyO3 wrapper
 for Python) and see how fast it could go. The answer: faster than V8 for most expression
-workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.
+workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.  There is also a command-line binary and Python command-line available (works great with uvx) for use in scripting.  The Python library is also usable in a command-line fashion, and a C-compatible library is available for those who want to easily use jsonata in C/C++.
 
-Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
+Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ (1682/1682 passing for last build of this project) tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
 
 Release versions will follow the reference jsonata-js project major and minor release numbers, but not necessarily patches.  This will make it easier for adopters of this library to understand each release's JSONata API compatibility.  As an example, 2.1.7 should be compliant with 2.1.x jsonata-js tests, but may have fixes specific to this library.  If a patch release for jsonata-js is relevant for this project, it will be included in a patch release that may or may not follow the patch numbers of the upstream project.
 
+This project currently chooses not to implement async, because it has limited value for most of the most common use-cases.  We 
+
 [![Crates.io](https://img.shields.io/crates/v/jsonata-core.svg)](https://crates.io/crates/jsonata-core)
 [![PyPI version](https://badge.fury.io/py/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
 [![Python versions](https://img.shields.io/pypi/pyversions/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
@@ -141,7 +148,7 @@ Supports Python 3.10, 3.11, 3.12, 3.13, 3.14 on Linux, macOS (Intel & ARM), and
 
 ## Command-line quick start
 
-Both packages also ship a CLI, `jq`-shaped, with an identical contract:
+Both packages also ship a binary CLI and a Python-based CLI, `jq`-shaped, with an identical contract:
 
 ```bash
 pip install jsonatapy

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/README.md

@@ -1,16 +1,23 @@
-# jsonata-core + jsonatapy
+# jsonata-core (rust) + jsonatapy + jsonata C-ABI library + jsonata cli
+#### Pypi stats
+[![jsonatapy Downloads Last Month](https://assets.piptrends.com/get-last-month-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Month by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Downloads Last Week](https://assets.piptrends.com/get-last-week-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Week by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Average Daily Downloads](https://assets.piptrends.com/get-average-downloads-badge/jsonatapy.svg 'jsonatapy Average Daily Downloads by pip Trends')](https://piptrends.com/package/jsonatapy)
 
-High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python bindings.
+#### Crates.io stats
+![downloads](https://shieldcn.dev/crates/d/jsonata-core.svg)
+
+High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python binding and C ABI/library.  If you use this library, please add a github star!
 
 Much of this project was built using Claude Code with significant human oversight. There was no performant
 JSONata implementation in Python, so the goal was to port JSONata to Rust (with a PyO3 wrapper
 for Python) and see how fast it could go. The answer: faster than V8 for most expression
-workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.
+workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.  There is also a command-line binary and Python command-line available (works great with uvx) for use in scripting.  The Python library is also usable in a command-line fashion, and a C-compatible library is available for those who want to easily use jsonata in C/C++.
 
-Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
+Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ (1682/1682 passing for last build of this project) tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
 
 Release versions will follow the reference jsonata-js project major and minor release numbers, but not necessarily patches.  This will make it easier for adopters of this library to understand each release's JSONata API compatibility.  As an example, 2.1.7 should be compliant with 2.1.x jsonata-js tests, but may have fixes specific to this library.  If a patch release for jsonata-js is relevant for this project, it will be included in a patch release that may or may not follow the patch numbers of the upstream project.
 
+This project currently chooses not to implement async, because it has limited value for most of the most common use-cases.  We 
+
 [![Crates.io](https://img.shields.io/crates/v/jsonata-core.svg)](https://crates.io/crates/jsonata-core)
 [![PyPI version](https://badge.fury.io/py/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
 [![Python versions](https://img.shields.io/pypi/pyversions/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
@@ -92,7 +99,7 @@ Supports Python 3.10, 3.11, 3.12, 3.13, 3.14 on Linux, macOS (Intel & ARM), and
 
 ## Command-line quick start
 
-Both packages also ship a CLI, `jq`-shaped, with an identical contract:
+Both packages also ship a binary CLI and a Python-based CLI, `jq`-shaped, with an identical contract:
 
 ```bash
 pip install jsonatapy

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/bindings/c/README.md

@@ -132,7 +132,16 @@ Rust library rebuilds with your project.)
 6. **Variables:** `jsonata_bind_var(expr, "x", "[1,2,3]")` binds `$x` for
    all subsequent evaluations on that handle (values are JSON text;
    re-binding replaces).
-7. **Panics:** internal engine panics are caught at the boundary and
+7. **Host functions:** `jsonata_register_fn(expr, "name", fn, user_data)`
+   exposes a C callback to the expression as `$name(...)`. The callback
+   receives its arguments as a JSON array string and returns a JSON result
+   string that jsonata copies (you keep ownership — do not expect jsonata to
+   free it); returning NULL signals an error. A name colliding with a
+   built-in is rejected; `jsonata_register_fn_override` replaces a built-in
+   deliberately (e.g. a frozen `$now`, or a disabled `$eval`). `user_data`
+   must outlive the handle. Registering a host function routes evaluation
+   through the tree-walker, like variable bindings.
+8. **Panics:** internal engine panics are caught at the boundary and
    surface as errors prefixed `internal error:` — they will not abort
    your process.
 

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/bindings/c/examples/smoke.c

@@ -27,6 +27,31 @@ static int failures = 0;
 
 static char *take_error(void) { return jsonata_last_error_message(); }
 
+/*
+ * Host function: given the JSON array ["<name>"], returns "hello <name>".
+ * Uses a static buffer — valid until the next call, which is all jsonata needs
+ * (it copies the result before returning to the expression).
+ */
+static char host_buf[256];
+static const char *greet_cb(void *user_data, const char *args_json) {
+    (void)user_data;
+    const char *open = strchr(args_json, '"');
+    if (!open) return NULL;
+    const char *start = open + 1;
+    const char *end = strchr(start, '"');
+    if (!end) return NULL;
+    int len = (int)(end - start);
+    snprintf(host_buf, sizeof(host_buf), "\"hello %.*s\"", len, start);
+    return host_buf;
+}
+
+/* Host override for $now(): a frozen timestamp (static string, always valid). */
+static const char *frozen_now_cb(void *user_data, const char *args_json) {
+    (void)user_data;
+    (void)args_json;
+    return "\"2020-01-01T00:00:00.000Z\"";
+}
+
 int main(void) {
     /* version */
     const char *v = jsonata_version();
@@ -119,6 +144,39 @@ int main(void) {
         jsonata_free_expr(e);
     }
 
+    /* host function registration + call */
+    {
+        JsonataExpr *e = jsonata_compile("$greet(name)");
+        int rc = jsonata_register_fn(e, "greet", greet_cb, NULL);
+        CHECK(rc == 0, "register_fn succeeds");
+        char *r = jsonata_evaluate(e, "{\"name\":\"Ada\"}");
+        CHECK(r != NULL && strcmp(r, "\"hello Ada\"") == 0, "host function call");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* host function override of an impure built-in ($now) */
+    {
+        JsonataExpr *e = jsonata_compile("$now()");
+        int rc = jsonata_register_fn_override(e, "now", frozen_now_cb, NULL);
+        CHECK(rc == 0, "register_fn_override succeeds");
+        char *r = jsonata_evaluate(e, "null");
+        CHECK(r != NULL && strcmp(r, "\"2020-01-01T00:00:00.000Z\"") == 0,
+              "override $now");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* collision with a built-in is rejected */
+    {
+        JsonataExpr *e = jsonata_compile("$sum(x)");
+        int rc = jsonata_register_fn(e, "sum", greet_cb, NULL);
+        char *err = take_error();
+        CHECK(rc == -1 && err != NULL, "register_fn collision rejected");
+        jsonata_free_string(err);
+        jsonata_free_expr(e);
+    }
+
     /* NULL tolerance of free functions */
     jsonata_free_expr(NULL);
     jsonata_free_string(NULL);

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/bindings/c/jsonata.h

@@ -75,6 +75,41 @@ char *jsonata_evaluate(JsonataExpr *expr, const char *json_utf8);
 int jsonata_bind_var(JsonataExpr *expr, const char *name,
                      const char *json_value_utf8);
 
+/*
+ * A host function callback, callable from the expression as $name(...).
+ *   user_data: the pointer supplied at registration (opaque to jsonata).
+ *   args_json: a NUL-terminated UTF-8 JSON ARRAY of the (already evaluated)
+ *              arguments.
+ * Returns a NUL-terminated UTF-8 JSON string with the result, which must stay
+ * valid until the call returns — jsonata COPIES it and does NOT free it — or
+ * NULL to signal an error.
+ */
+typedef const char *(*jsonata_host_fn)(void *user_data, const char *args_json);
+
+/*
+ * Register a host function callable from the expression as $name(...) — the
+ * C equivalent of jsonata-js's registerFunction. Applies to every subsequent
+ * jsonata_evaluate() on this handle. A leading '$' in name is accepted and
+ * stripped; re-registering a name replaces it. Host functions resolve after
+ * the expression's own bindings/lambdas and before built-ins.
+ *
+ * user_data is passed back to the callback unchanged and must remain valid for
+ * the lifetime of the handle. Returns 0 on success, -1 on error (slot set) —
+ * including when name collides with a built-in (use
+ * jsonata_register_fn_override to replace a built-in deliberately).
+ */
+int jsonata_register_fn(JsonataExpr *expr, const char *name,
+                        jsonata_host_fn fn, void *user_data);
+
+/*
+ * Like jsonata_register_fn, but deliberately replaces a built-in of the same
+ * name — for determinism injection (a frozen $now, seeded $random) or
+ * sandboxing (disabling $eval). Overriding a built-in that participates in the
+ * compiled fast path returns -1 with an error.
+ */
+int jsonata_register_fn_override(JsonataExpr *expr, const char *name,
+                                 jsonata_host_fn fn, void *user_data);
+
 /* Free a handle returned by jsonata_compile(). NULL is a no-op. */
 void jsonata_free_expr(JsonataExpr *expr);
 

jsonatapy-2.2.6/examples/host_functions.rs

@@ -0,0 +1,113 @@
+// Host-callable custom functions
+//
+// Shows how a host application registers native Rust functions that a JSONata
+// expression can call as `$name(...)`:
+//   - enrichment/lookup functions (the canonical use case)
+//   - determinism injection: overriding an impure built-in ($now) with a frozen
+//     implementation for reproducible output
+//   - sandboxing: overriding a powerful built-in ($eval) to disable it
+//
+// Run with: cargo run --example host_functions
+
+use jsonata_core::value::JValue;
+use jsonata_core::{evaluator::Evaluator, parser::parse};
+use serde_json::json;
+
+fn main() {
+    demo_enrichment_lookup();
+    demo_multi_arg();
+    demo_override_now();
+    demo_sandbox_eval();
+    demo_collision_is_rejected();
+}
+
+fn eval(ev: &mut Evaluator, expr: &str, data: serde_json::Value) -> JValue {
+    let ast = parse(expr).expect("expression parses");
+    ev.evaluate(&ast, &JValue::from(data))
+        .expect("evaluation succeeds")
+}
+
+/// The canonical use case: a lookup backed by host-owned data. The expression
+/// stays a clean artifact; the host owns the (here trivial) data source.
+fn demo_enrichment_lookup() {
+    let mut ev = Evaluator::new();
+    ev.register_fn("productName", |args: &[JValue]| {
+        let sku = args.first().and_then(|v| v.as_str()).unwrap_or("");
+        let name = match sku {
+            "A-1" => "Widget",
+            "B-2" => "Gadget",
+            _ => "Unknown",
+        };
+        Ok(JValue::from(name))
+    })
+    .unwrap();
+
+    let out = eval(
+        &mut ev,
+        "items.{ 'sku': sku, 'name': $productName(sku) }",
+        json!({ "items": [ { "sku": "A-1" }, { "sku": "B-2" } ] }),
+    );
+    println!("enrichment lookup: {}", out.to_json_string().unwrap());
+}
+
+/// Host functions receive all arguments already evaluated.
+fn demo_multi_arg() {
+    let mut ev = Evaluator::new();
+    ev.register_fn("convert", |args: &[JValue]| {
+        let amount = args.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
+        let rate = match args.get(1).and_then(|v| v.as_str()) {
+            Some("EUR") => 1.1,
+            _ => 1.0,
+        };
+        Ok(JValue::from_f64(amount * rate))
+    })
+    .unwrap();
+
+    let out = eval(
+        &mut ev,
+        "$convert(amount, currency)",
+        json!({ "amount": 10, "currency": "EUR" }),
+    );
+    println!("multi-arg convert: {}", out.to_json_string().unwrap());
+}
+
+/// Determinism injection: freeze `$now()` so output is reproducible in tests.
+/// `$now` is a non-compilable (impure) built-in, so overriding it is allowed.
+fn demo_override_now() {
+    let mut ev = Evaluator::new();
+    ev.register_fn_override("now", |_args: &[JValue]| {
+        Ok(JValue::from("2020-01-01T00:00:00.000Z"))
+    })
+    .unwrap();
+
+    let out = eval(&mut ev, "{ 'generatedAt': $now() }", json!(null));
+    println!("frozen $now: {}", out.to_json_string().unwrap());
+}
+
+/// Sandboxing: disable the dynamic-evaluation built-in `$eval` when running
+/// semi-trusted expressions.
+fn demo_sandbox_eval() {
+    let mut ev = Evaluator::new();
+    ev.register_fn_override("eval", |_args: &[JValue]| {
+        Err(jsonata_core::evaluator::EvaluatorError::EvaluationError(
+            "$eval is disabled in this environment".to_string(),
+        ))
+    })
+    .unwrap();
+
+    let ast = parse("$eval('1 + 1')").unwrap();
+    match ev.evaluate(&ast, &JValue::Null) {
+        Ok(v) => println!("sandbox $eval: unexpectedly returned {v:?}"),
+        Err(e) => println!("sandbox $eval: blocked as expected -> {e}"),
+    }
+}
+
+/// Registering a name that collides with a built-in is refused; use
+/// `register_fn_override` to replace a built-in deliberately.
+fn demo_collision_is_rejected() {
+    let mut ev = Evaluator::new();
+    match ev.register_fn("sum", |_args: &[JValue]| Ok(JValue::Null)) {
+        Ok(()) => println!("collision: unexpectedly accepted"),
+        Err(e) => println!("collision: rejected as expected -> {e}"),
+    }
+}

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "jsonatapy"
-version = "2.2.5"
+version = "2.2.6"
 description = "High-performance Python/Rust implementation of JSONata query and transformation language"
 authors = [
     {name = "txjmb", email = "txjmb@users.noreply.github.com"}

{jsonatapy-2.2.5 → jsonatapy-2.2.6}/python/jsonatapy/__init__.py

@@ -16,6 +16,7 @@ Example:
 """
 
 import json as _json
+from collections.abc import Callable
 from typing import Any
 
 from ._jsonatapy import (
@@ -185,6 +186,73 @@ class JsonataExpression:
         """
         return self._expr.evaluate(data, bindings, timeout, max_stack_depth, max_sequence_length)
 
+    def register(self, name: str, func: Callable[..., Any]) -> "JsonataExpression":
+        """
+        Register a Python function callable from the expression as ``$name(...)``.
+
+        The function receives the (already-evaluated) arguments as positional
+        Python values and must return a JSON-compatible value **synchronously**.
+        This is the equivalent of jsonata-js's ``registerFunction`` — use it to
+        expose enrichment/lookup, formatting, or scoring logic to an expression.
+
+        Host functions resolve after the expression's own bindings/lambdas and
+        before built-ins. A name that collides with a built-in is rejected; use
+        :meth:`register_override` to replace a built-in deliberately.
+
+        Note:
+            The evaluator is synchronous, so an ``async def`` (which returns a
+            coroutine) is rejected at call time. For async I/O, await it outside
+            jsonata and pass the result in via ``bindings``.
+
+        Args:
+            name: The function name, called as ``$name(...)`` in the expression.
+            func: A callable ``(*args) -> JSON-compatible value``.
+
+        Returns:
+            self, to allow chaining.
+
+        Raises:
+            TypeError: If ``func`` is not callable.
+            ValueError: If ``name`` collides with a built-in function.
+
+        Example:
+            >>> expr = compile("$greet(name)")
+            >>> expr.register("greet", lambda n: f"hello {n}")
+            >>> expr.evaluate({"name": "Ada"})
+            'hello Ada'
+        """
+        self._expr.register(name, func)
+        return self
+
+    def register_override(self, name: str, func: Callable[..., Any]) -> "JsonataExpression":
+        """
+        Register a Python function that deliberately replaces a built-in.
+
+        The two legitimate uses are determinism injection for the impure
+        built-ins (``$now``, ``$millis``, ``$random``) — e.g. a frozen clock for
+        reproducible output — and sandboxing (disabling ``$eval``). Overriding a
+        built-in that participates in the compiled fast path is rejected.
+
+        Args:
+            name: The built-in name to replace (e.g. ``"now"``).
+            func: A callable ``(*args) -> JSON-compatible value``.
+
+        Returns:
+            self, to allow chaining.
+
+        Raises:
+            TypeError: If ``func`` is not callable.
+            ValueError: If the built-in cannot be safely overridden.
+
+        Example:
+            >>> expr = compile("$now()")
+            >>> expr.register_override("now", lambda: "2020-01-01T00:00:00.000Z")
+            >>> expr.evaluate(None)
+            '2020-01-01T00:00:00.000Z'
+        """
+        self._expr.register_override(name, func)
+        return self
+
     def evaluate_json(
         self,
         json_str: str,