littlegraph-python 0.2.1

Python extension module for the littlegraph embedded graph database
Documentation
use std::time::Duration;

use pyo3::exceptions::{PyTypeError, PyValueError};
use pyo3::prelude::*;
use pyo3::types::{PyAny, PyBool, PyFloat, PyInt};

const MIB: usize = 1024 * 1024;

#[pyclass(frozen, module = "littlegraph._littlegraph")]
#[derive(Clone, Debug)]
pub(crate) struct Limits {
    #[pyo3(get)]
    pub(crate) max_parameter_depth: usize,
    #[pyo3(get)]
    pub(crate) max_parameter_items: usize,
    #[pyo3(get)]
    pub(crate) max_parameter_string_bytes: usize,
    #[pyo3(get)]
    pub(crate) max_parameter_bytes: usize,
    #[pyo3(get)]
    pub(crate) max_result_rows: usize,
    #[pyo3(get)]
    pub(crate) max_result_bytes: usize,
    #[pyo3(get)]
    pub(crate) worker_command_capacity: usize,
    signal_poll_interval: Duration,
    #[pyo3(get)]
    pub(crate) default_query_memory_bytes: usize,
    #[pyo3(get)]
    pub(crate) default_transaction_workspace_bytes: usize,
    #[pyo3(get)]
    pub(crate) default_transaction_records: usize,
    #[pyo3(get)]
    pub(crate) default_spill_threshold_bytes: usize,
    #[pyo3(get)]
    pub(crate) default_max_spill_bytes: u64,
    #[pyo3(get)]
    pub(crate) default_max_journal_bytes: u64,
}

impl Default for Limits {
    fn default() -> Self {
        Self {
            max_parameter_depth: 64,
            max_parameter_items: 100_000,
            max_parameter_string_bytes: 16 * MIB,
            max_parameter_bytes: 64 * MIB,
            max_result_rows: 100_000,
            max_result_bytes: 64 * MIB,
            worker_command_capacity: 32,
            signal_poll_interval: Duration::from_millis(50),
            default_query_memory_bytes: 64 * MIB,
            default_transaction_workspace_bytes: 256 * MIB,
            default_transaction_records: 1_000_000,
            default_spill_threshold_bytes: 64 * MIB,
            default_max_spill_bytes: 1024 * MIB as u64,
            default_max_journal_bytes: 1024 * MIB as u64,
        }
    }
}

#[pymethods]
impl Limits {
    #[new]
    #[pyo3(signature = (
        *,
        max_parameter_depth=None,
        max_parameter_items=None,
        max_parameter_string_bytes=None,
        max_parameter_bytes=None,
        max_result_rows=None,
        max_result_bytes=None,
        worker_command_capacity=None,
        signal_poll_interval=None,
        default_query_memory_bytes=None,
        default_transaction_workspace_bytes=None,
        default_transaction_records=None,
        default_spill_threshold_bytes=None,
        default_max_spill_bytes=None,
        default_max_journal_bytes=None,
    ))]
    #[allow(clippy::too_many_arguments)]
    fn new(
        max_parameter_depth: Option<&Bound<'_, PyAny>>,
        max_parameter_items: Option<&Bound<'_, PyAny>>,
        max_parameter_string_bytes: Option<&Bound<'_, PyAny>>,
        max_parameter_bytes: Option<&Bound<'_, PyAny>>,
        max_result_rows: Option<&Bound<'_, PyAny>>,
        max_result_bytes: Option<&Bound<'_, PyAny>>,
        worker_command_capacity: Option<&Bound<'_, PyAny>>,
        signal_poll_interval: Option<&Bound<'_, PyAny>>,
        default_query_memory_bytes: Option<&Bound<'_, PyAny>>,
        default_transaction_workspace_bytes: Option<&Bound<'_, PyAny>>,
        default_transaction_records: Option<&Bound<'_, PyAny>>,
        default_spill_threshold_bytes: Option<&Bound<'_, PyAny>>,
        default_max_spill_bytes: Option<&Bound<'_, PyAny>>,
        default_max_journal_bytes: Option<&Bound<'_, PyAny>>,
    ) -> PyResult<Self> {
        let defaults = Self::default();
        let limits = Self {
            max_parameter_depth: usize_option(
                max_parameter_depth,
                "max_parameter_depth",
                defaults.max_parameter_depth,
            )?,
            max_parameter_items: usize_option(
                max_parameter_items,
                "max_parameter_items",
                defaults.max_parameter_items,
            )?,
            max_parameter_string_bytes: usize_option(
                max_parameter_string_bytes,
                "max_parameter_string_bytes",
                defaults.max_parameter_string_bytes,
            )?,
            max_parameter_bytes: usize_option(
                max_parameter_bytes,
                "max_parameter_bytes",
                defaults.max_parameter_bytes,
            )?,
            max_result_rows: usize_option(
                max_result_rows,
                "max_result_rows",
                defaults.max_result_rows,
            )?,
            max_result_bytes: usize_option(
                max_result_bytes,
                "max_result_bytes",
                defaults.max_result_bytes,
            )?,
            worker_command_capacity: usize_option(
                worker_command_capacity,
                "worker_command_capacity",
                defaults.worker_command_capacity,
            )?,
            signal_poll_interval: duration_option(
                signal_poll_interval,
                defaults.signal_poll_interval,
            )?,
            default_query_memory_bytes: usize_option(
                default_query_memory_bytes,
                "default_query_memory_bytes",
                defaults.default_query_memory_bytes,
            )?,
            default_transaction_workspace_bytes: usize_option(
                default_transaction_workspace_bytes,
                "default_transaction_workspace_bytes",
                defaults.default_transaction_workspace_bytes,
            )?,
            default_transaction_records: usize_option(
                default_transaction_records,
                "default_transaction_records",
                defaults.default_transaction_records,
            )?,
            default_spill_threshold_bytes: usize_option(
                default_spill_threshold_bytes,
                "default_spill_threshold_bytes",
                defaults.default_spill_threshold_bytes,
            )?,
            default_max_spill_bytes: u64_option(
                default_max_spill_bytes,
                "default_max_spill_bytes",
                defaults.default_max_spill_bytes,
            )?,
            default_max_journal_bytes: u64_option(
                default_max_journal_bytes,
                "default_max_journal_bytes",
                defaults.default_max_journal_bytes,
            )?,
        };
        limits.validate()?;
        Ok(limits)
    }

    #[getter]
    fn signal_poll_interval(&self) -> f64 {
        self.signal_poll_interval.as_secs_f64()
    }

    fn __repr__(&self) -> String {
        format!(
            "Limits(max_parameter_depth={}, max_result_rows={}, max_result_bytes={}, worker_command_capacity={})",
            self.max_parameter_depth,
            self.max_result_rows,
            self.max_result_bytes,
            self.worker_command_capacity,
        )
    }
}

impl Limits {
    pub(crate) fn poll_interval(&self) -> Duration {
        self.signal_poll_interval
    }

    fn validate(&self) -> PyResult<()> {
        if self.max_parameter_depth == 0 {
            return Err(PyValueError::new_err(
                "max_parameter_depth must be greater than zero",
            ));
        }
        if self.worker_command_capacity == 0 {
            return Err(PyValueError::new_err(
                "worker_command_capacity must be greater than zero",
            ));
        }
        if self.default_spill_threshold_bytes as u64 > self.default_max_spill_bytes {
            return Err(PyValueError::new_err(
                "default_spill_threshold_bytes cannot exceed default_max_spill_bytes",
            ));
        }
        Ok(())
    }
}

fn usize_option(value: Option<&Bound<'_, PyAny>>, name: &str, default: usize) -> PyResult<usize> {
    value.map_or(Ok(default), |value| exact_integer(value, name))
}

fn u64_option(value: Option<&Bound<'_, PyAny>>, name: &str, default: u64) -> PyResult<u64> {
    value.map_or(Ok(default), |value| exact_integer(value, name))
}

fn exact_integer<T>(value: &Bound<'_, PyAny>, name: &str) -> PyResult<T>
where
    for<'py> T: FromPyObject<'py>,
{
    if value.is_instance_of::<PyBool>() || !value.is_instance_of::<PyInt>() {
        return Err(PyTypeError::new_err(format!("{name} must be an integer")));
    }
    value
        .extract::<T>()
        .map_err(|_| PyValueError::new_err(format!("{name} is outside the supported range")))
}

fn duration_option(value: Option<&Bound<'_, PyAny>>, default: Duration) -> PyResult<Duration> {
    let Some(value) = value else {
        return Ok(default);
    };
    if value.is_instance_of::<PyBool>()
        || !(value.is_instance_of::<PyInt>() || value.is_instance_of::<PyFloat>())
    {
        return Err(PyTypeError::new_err(
            "signal_poll_interval must be a number",
        ));
    }
    let seconds = value.extract::<f64>().map_err(|_| {
        PyValueError::new_err("signal_poll_interval is outside the supported range")
    })?;
    if !seconds.is_finite() || !(0.001..=1.0).contains(&seconds) {
        return Err(PyValueError::new_err(
            "signal_poll_interval must be finite and between 0.001 and 1.0 seconds",
        ));
    }
    Ok(Duration::from_secs_f64(seconds))
}