An exact decimal is a decimal.Decimal

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zudb-python"
-version = "0.0.1"
+version = "0.0.2"
 edition = "2024"
 rust-version = "1.98"
 license = "Apache-2.0"
@@ -18,14 +18,14 @@ crate-type = ["cdylib"]
 # with (ADR 0002), so a revision is the honest way to say which one.
 # A local checkout is used instead with a `paths` override in
 # `.cargo/config.toml`, which is untracked on purpose.
-zudb = { package = "zu", git = "https://github.com/tamnd/zu", rev = "9dcb7b42b50f3a802cae62b18d9e99f30efefad1" }
-zu-common = { git = "https://github.com/tamnd/zu", rev = "9dcb7b42b50f3a802cae62b18d9e99f30efefad1" }
+zudb = { package = "zu", git = "https://github.com/tamnd/zu", rev = "cfdc70f291719309b96a8300dc8425154d0fd5d5" }
+zu-common = { git = "https://github.com/tamnd/zu", rev = "cfdc70f291719309b96a8300dc8425154d0fd5d5" }
 # The one translation from a result into Arrow, which lives in the
 # engine tree so that every client agrees about what a column becomes.
 # `ffi` is the only feature this client turns on: what Python wants is
 # the C Data Interface, which is how a result reaches pyarrow, pandas
 # and polars without a Python object per cell.
-zu-arrow = { git = "https://github.com/tamnd/zu", rev = "9dcb7b42b50f3a802cae62b18d9e99f30efefad1", features = ["ffi"] }
+zu-arrow = { git = "https://github.com/tamnd/zu", rev = "cfdc70f291719309b96a8300dc8425154d0fd5d5", features = ["ffi"] }
 # `extension-module` is asked for by maturin, in pyproject.toml, and
 # not here. Only the build backend knows how an extension is linked on
 # the platform it is building for, and a crate that turns the feature

README.md

@@ -32,6 +32,7 @@ The interesting parts:
 - **Complete `.pyi` stubs inside the wheel**, checked against the runtime in CI, so mypy and pyright and your editor all work with no extra install.
 - **`import zudb` costs about 4 ms** on this machine and is gated at 50, and pandas, polars and pyarrow are imported when you ask for one and not before. Importing pandas costs 700 ms, which is most of why none of them is a dependency.
 - **Graph values are real classes.** `Node`, `Rel`, and `Path` have `.labels`, `.id`, `.properties`, and an HTML repr. Not dicts, because a dict cannot tell a property named `labels` apart from the label set.
+- **An exact decimal is a `decimal.Decimal`.** `CAST('1.20' AS DECIMAL(5, 2))` comes back with both places, and one goes in as a parameter the same way. Not a `float`, because a tenth is not a binary fraction and a price held as one is not the price.
 
 ## A database with no file
 

conformance/values.py

@@ -35,6 +35,7 @@
 from __future__ import annotations
 
 import datetime
+import decimal
 import math
 from dataclasses import dataclass
 
@@ -660,6 +661,13 @@ def same(want: object, got: object) -> bool:
         if math.isnan(want) and math.isnan(got):
             return True
         return math.copysign(1.0, want) == math.copysign(1.0, got) and want == got
+    # Two decimals of one number at two scales are equal to Python and
+    # print differently, and what a case asserts is what a reader would
+    # see, so the scale is compared as well. It has no case to read yet,
+    # since DECIMAL is a reserved name, and the rule is written where the
+    # reference writes it rather than left for the first one to discover.
+    if isinstance(want, decimal.Decimal) and isinstance(got, decimal.Decimal):
+        return want.as_tuple().exponent == got.as_tuple().exponent and want == got
     if isinstance(want, list) and isinstance(got, list):
         return len(want) == len(got) and all(same(a, b) for a, b in zip(want, got, strict=True))
     if isinstance(want, Walk) and isinstance(got, Walk):
@@ -681,6 +689,15 @@ def show(value: object) -> str:
         return f'INT64 "{value}"'
     if isinstance(value, float):
         return f'FLOAT64 "{_show_float(value)}"'
+    # A decimal is a value a statement can hand back today even though
+    # DECIMAL is still a reserved name a case may not write, since CAST
+    # reaches one and no case declares one. That makes this the got side
+    # of a report and never the want side, and a report that could not
+    # print what it got would be the least useful moment to find out.
+    # Formatted rather than str()'d because Python prints some decimals
+    # with an exponent and the reference runner never does.
+    if isinstance(value, decimal.Decimal):
+        return f'DECIMAL "{format(value, "f")}"'
     if isinstance(value, str):
         return f"STRING {quote(value)}"
     # Upper case because ISO writes the literal that way, and a report

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "zudb"
-version = "0.0.1"
+version = "0.0.2"
 description = "zu: an embedded property-graph database, in your process"
 readme = "README.md"
 license = "Apache-2.0"

python/zudb/__init__.py

@@ -55,7 +55,7 @@
 )
 from .types import Value
 
-__version__ = "0.0.1"
+__version__ = "0.0.2"
 
 __all__ = [
     "connect",

python/zudb/dbapi.py

@@ -42,6 +42,7 @@
 
 import contextlib
 import datetime
+import decimal
 import os
 import time
 from collections import deque
@@ -298,7 +299,11 @@ def __repr__(self) -> str:
 
 STRING = _Type("STRING", (str,))
 BINARY = _Type("BINARY", (bytes, bytearray, memoryview))
-NUMBER = _Type("NUMBER", (int, float))
+# `decimal.Decimal` is in here because PEP 249 puts every numeric
+# column under NUMBER and a decimal is one. It is not in a set of its
+# own: a program asking whether a column holds a number should get yes
+# for a price, and the exact type is what the value already is.
+NUMBER = _Type("NUMBER", (int, float, decimal.Decimal))
 DATETIME = _Type("DATETIME", (datetime.date, datetime.time, datetime.datetime))
 #: The values that identify a row, which in a graph are the ones that
 #: carry a table and an offset in it.

python/zudb/types.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import datetime
+import decimal
 from typing import TypeAlias
 
 from ._zudb import Duration, Node, Path, Rel
@@ -22,12 +23,15 @@
 #: duration and hands one back, since a ``timedelta`` cannot hold every
 #: duration zu can. ``bytes`` and not ``bytearray``, because a parameter
 #: is read after the call that takes it returns and a mutable buffer is a
-#: promise the caller can break.
+#: promise the caller can break. A ``decimal.Decimal`` goes both ways
+#: and is the one exact number here: a price read into a ``float`` would
+#: not be the price, which is why the engine has a type for it at all.
 Value: TypeAlias = (
     None
     | bool
     | int
     | float
+    | decimal.Decimal
     | str
     | bytes
     | datetime.date

src/value.rs

@@ -10,8 +10,9 @@
 use std::collections::HashMap;
 
 use pyo3::prelude::*;
+use pyo3::sync::PyOnceLock;
 use pyo3::types::{
-    PyBool, PyBytes, PyDate, PyDateTime, PyDelta, PyDict, PyList, PyTime, PyTuple, PyTzInfo,
+    PyBool, PyBytes, PyDate, PyDateTime, PyDelta, PyDict, PyList, PyTime, PyTuple, PyType, PyTzInfo,
 };
 use zu_common::temporal::{NANOS_PER_DAY, NANOS_PER_MINUTE, civil_from_days, days_from_civil};
 use zu_common::{DurationKind, Temporal};
@@ -306,6 +307,26 @@ impl Duration {
     }
 }
 
+/// `decimal.Decimal`, imported once and kept.
+///
+/// The type object rather than the module, since both directions want
+/// it: one to build a decimal and one to recognise a parameter that is
+/// already one. `decimal` is in the standard library and importing it
+/// costs a few hundred microseconds the first time, which is a price
+/// worth paying once and not once a cell.
+static DECIMAL: PyOnceLock<Py<PyType>> = PyOnceLock::new();
+
+fn decimal_type(py: Python<'_>) -> PyResult<&Bound<'_, PyType>> {
+    DECIMAL
+        .get_or_try_init(py, || {
+            Ok(PyModule::import(py, "decimal")?
+                .getattr("Decimal")?
+                .cast_into::<PyType>()?
+                .unbind())
+        })
+        .map(|ty| ty.bind(py))
+}
+
 /// One engine value as the Python object it is.
 pub fn to_py<'py>(py: Python<'py>, value: &Value, names: &Names) -> PyResult<Bound<'py, PyAny>> {
     Ok(match value {
@@ -321,6 +342,19 @@ pub fn to_py<'py>(py: Python<'py>, value: &Value, names: &Names) -> PyResult<Bou
         // same one the loader takes for a byte string column, so a
         // round trip through any of the three is one type.
         Value::Bytes(b) => PyBytes::new(py, b).into_any(),
+        // `decimal.Decimal` and not `float`. The engine holds this
+        // exactly because a tenth is not a binary fraction, and handing
+        // it over as a float would lose both the value and the number
+        // of places on the last step of the journey. The standard
+        // library already has the type, so a notebook that reads a
+        // money column gets something it can add up without importing
+        // anything.
+        //
+        // Built from the text rather than from the digits and the
+        // scale, because `Decimal("1.20")` is the one constructor that
+        // is exact for both: it keeps two places where a float would
+        // keep neither, and the spelling is the one the engine prints.
+        Value::Decimal(d) => decimal_type(py)?.call1((d.to_string(),))?,
         Value::Node { table, offset } => Node {
             table: names.node(*table),
             offset: *offset,
@@ -474,6 +508,44 @@ fn datetime_of<'py>(
     )
 }
 
+/// A `decimal.Decimal` as the engine's, exactly or not at all.
+///
+/// Read through `format(d, "f")` rather than `str(d)`, because Python
+/// prints some decimals with an exponent and `Decimal("1E+2")` is a
+/// hundred at no places rather than a one at two of them. The `f`
+/// format is always the digits written out, so the number of them after
+/// the point is the scale and there is nothing left to interpret.
+///
+/// Every refusal here is a value the engine has no decimal for, and
+/// each says which: a NaN or an infinity is not an exact number at all,
+/// thirty eight digits is the largest precision `DECIMAL(p, s)` takes
+/// and the largest an i128 holds, and a scale past that is a number
+/// whose point is further right than any column could declare. Failing
+/// at the call is the point: a parameter that arrived as a float would
+/// be a query comparing a price against something that is not it.
+fn decimal_from_py(value: &Bound<'_, PyAny>) -> PyResult<Value> {
+    let plain: String = value.call_method1("__format__", ("f",))?.extract()?;
+    let scale = match plain.split_once('.') {
+        Some((_, fraction)) => fraction.len(),
+        None => 0,
+    };
+    if scale > usize::from(zu_common::decimal::MAX_DIGITS) {
+        return Err(pyo3::exceptions::PyValueError::new_err(format!(
+            "the decimal {plain} has {scale} digits after the point, and a decimal here holds at \
+             most {}",
+            zu_common::decimal::MAX_DIGITS
+        )));
+    }
+    match zu_common::Decimal::parse(&plain, scale as u16) {
+        Some(d) => Ok(Value::Decimal(d)),
+        None => Err(pyo3::exceptions::PyValueError::new_err(format!(
+            "{plain} is not a decimal this engine holds: it takes an exact number of at most {} \
+             digits, so a NaN, an infinity and anything wider are all outside it",
+            zu_common::decimal::MAX_DIGITS
+        ))),
+    }
+}
+
 /// An offset in minutes as a `datetime.timezone`.
 fn zone_of(py: Python<'_>, offset: i16) -> PyResult<Bound<'_, PyTzInfo>> {
     PyTzInfo::fixed_offset(py, PyDelta::new(py, 0, i32::from(offset) * 60, 0, true)?)
@@ -528,6 +600,15 @@ fn nested(value: &Bound<'_, PyAny>, depth: usize) -> PyResult<Value> {
     if let Ok(b) = value.cast::<PyBytes>() {
         return Ok(Value::Bytes(b.as_bytes().to_vec()));
     }
+    // Before the integer and the float arms, because a
+    // `decimal.Decimal` is neither and would go through `extract::<f64>`
+    // otherwise, which is the loss the caller picked the type to avoid.
+    // Read from `str(d)` for the reason it is built from a string: that
+    // is the spelling that carries both the digits and how many of them
+    // are after the point.
+    if value.is_instance(decimal_type(value.py())?.as_any())? {
+        return decimal_from_py(value);
+    }
     if let Ok(n) = value.extract::<i64>() {
         return Ok(Value::Int(n));
     }

tests/test_connection.py

@@ -78,7 +78,7 @@ def test_repr_names_the_file_and_says_when_it_is_closed(tmp_path: Path) -> None:
 
 
 def test_the_engine_and_abi_versions_are_reported(empty: zudb.Connection) -> None:
-    assert zudb.__version__ == "0.0.1"
+    assert zudb.__version__ == "0.0.2"
     assert zudb.__abi_version__.count(".") == 1