PyDecisionGraph 0.3.2.post1__cp315-cp315t-win_amd64.whl

decision_graph/decision_tree/bake/c_var.pxd

@@ -0,0 +1,205 @@
+from libc.stdint cimport uint64_t
+from libc.stdio cimport FILE
+from libcpp cimport bool as c_bool
+
+from cbase.allocator_protocol cimport allocator_protocol
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_var.h":
+    const c_bool DCG_VAR_HAS_SESSION_TIME
+    const int DCG_VAR_STRING_MAXLEN
+    const c_bool DCG_VIGILANT
+
+    ctypedef enum dcg_ret_code:
+        DCG_OK
+        DCG_ERR_INVALID_ARG
+        DCG_ERR_INVALID_BUF
+        DCG_ERR_OOM
+        DCG_ERR_NOT_FOUND
+        DCG_ERR_FULL
+        DCG_ERR_BAD_CAST
+        DCG_ERR_FORMAT
+        DCG_ERR_TYPE
+        DCG_ERR_CYCLE
+        DCG_ERR_BUSY
+        DCG_ERR_DUPLICATE
+        DCG_ERR_EDGE
+        DCG_ERR_UNRESOLVED
+        DCG_ERR_RANGE
+        DCG_ERR_HOOK
+        DCG_ERR_NO_MATCH
+        DCG_ERR_MATH
+        DCG_ERR_UNBOUND
+
+    ctypedef enum dcg_var_numeric:
+        VAR_NUMERIC_NONE
+        VAR_NUMERIC_INT
+        VAR_NUMERIC_DOUBLE
+
+    ctypedef enum dcg_var_type_mask:
+        VAR_TYPE_BASE_MASK
+        VAR_TYPE_REF_MASK
+        VAR_TYPE_REF_SHIFT
+        VAR_TYPE_REF_LEVEL1
+        VAR_TYPE_REF_LEVEL2
+
+    ctypedef enum dcg_var_type:
+        VAR_TYPE_RAW_PTR
+        VAR_TYPE_STRING
+        VAR_TYPE_BOOL
+        VAR_TYPE_DOUBLE
+        VAR_TYPE_INT
+        VAR_TYPE_OFFSET
+        VAR_TYPE_TIME
+        VAR_TYPE_DATE
+        VAR_TYPE_DATETIME
+        VAR_TYPE_D_VECTOR
+        VAR_TYPE_D_MATRIX
+        VAR_TYPE_NODE
+        VAR_TYPE_RESERVED
+
+        VAR_TYPE_RAW_PTR_REF
+        VAR_TYPE_STRING_REF
+        VAR_TYPE_BOOL_REF
+        VAR_TYPE_DOUBLE_REF
+        VAR_TYPE_INT_REF
+        VAR_TYPE_OFFSET_REF
+        VAR_TYPE_TIME_REF
+        VAR_TYPE_DATE_REF
+        VAR_TYPE_DATETIME_REF
+        VAR_TYPE_D_VECTOR_REF
+        VAR_TYPE_D_MATRIX_REF
+        VAR_TYPE_NODE_REF
+        VAR_TYPE_INFERRED
+
+        VAR_TYPE_RAW_PTR_REF_REF
+        VAR_TYPE_STRING_REF_REF
+        VAR_TYPE_BOOL_REF_REF
+        VAR_TYPE_DOUBLE_REF_REF
+        VAR_TYPE_INT_REF_REF
+        VAR_TYPE_OFFSET_REF_REF
+        VAR_TYPE_TIME_REF_REF
+        VAR_TYPE_DATE_REF_REF
+        VAR_TYPE_DATETIME_REF_REF
+        VAR_TYPE_D_VECTOR_REF_REF
+        VAR_TYPE_D_MATRIX_REF_REF
+        VAR_TYPE_NODE_REF_REF
+
+    ctypedef struct dcg_d_vector_t:
+        double* data
+        size_t n
+
+    ctypedef struct dcg_d_matrix_t:
+        double* data
+        size_t n_rows
+        size_t n_cols
+        c_bool row_major
+
+    ctypedef union dcg_var_variant:
+        void* as_ptr
+        const char* as_string
+        c_bool as_bool
+        double as_double
+        ssize_t as_int
+        ssize_t as_offset
+        uint64_t as_bits
+        dcg_d_vector_t* as_dvector
+        dcg_d_matrix_t* as_dmatrix
+        const void* as_ref
+        void* as_node
+
+    ctypedef struct dcg_var_t:
+        dcg_var_type dtype
+        dcg_var_variant value
+
+    dcg_d_vector_t* c_dcg_d_vector_new(size_t n, allocator_protocol* allocator) noexcept nogil
+    dcg_d_vector_t* c_dcg_d_vector_new_child(size_t n, allocator_protocol* allocator, const void* parent) noexcept nogil
+    void c_dcg_d_vector_free(dcg_d_vector_t* vector) noexcept nogil
+    double* c_dcg_d_vector_data(const dcg_d_vector_t* vector) noexcept nogil
+    size_t c_dcg_d_vector_size(const dcg_d_vector_t* vector) noexcept nogil
+    double c_dcg_d_vector_at(const dcg_d_vector_t* vector, size_t index) noexcept nogil
+    int c_dcg_d_vector_set(dcg_d_vector_t* vector, size_t index, double value) noexcept nogil
+
+    dcg_d_matrix_t* c_dcg_d_matrix_new(size_t n_rows, size_t n_cols, c_bool row_major, allocator_protocol* allocator) noexcept nogil
+    dcg_d_matrix_t* c_dcg_d_matrix_new_child(size_t n_rows, size_t n_cols, c_bool row_major, allocator_protocol* allocator, const void* parent) noexcept nogil
+    void c_dcg_d_matrix_free(dcg_d_matrix_t* matrix) noexcept nogil
+    double* c_dcg_d_matrix_data(const dcg_d_matrix_t* matrix) noexcept nogil
+    size_t c_dcg_d_matrix_rows(const dcg_d_matrix_t* matrix) noexcept nogil
+    size_t c_dcg_d_matrix_cols(const dcg_d_matrix_t* matrix) noexcept nogil
+    double c_dcg_d_matrix_at(const dcg_d_matrix_t* matrix, size_t row, size_t col) noexcept nogil
+    int c_dcg_d_matrix_set(dcg_d_matrix_t* matrix, size_t row, size_t col, double value) noexcept nogil
+
+    dcg_var_t* c_dcg_var_new(allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_bool(c_bool value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_double(double value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_int(ssize_t value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_offset(ssize_t value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_string(const char* value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_ptr(void* value, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_dvector(size_t n, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_dmatrix(size_t n_rows, size_t n_cols, c_bool row_major, allocator_protocol* allocator) noexcept nogil
+    dcg_var_t* c_dcg_var_new_ref(const dcg_var_t* src, allocator_protocol* allocator) noexcept nogil
+    void c_dcg_var_free(dcg_var_t* var) noexcept nogil
+    void c_dcg_var_dealloc(dcg_var_t* var) noexcept nogil
+
+    int c_dcg_var_init(dcg_var_t* var) noexcept nogil
+    int c_dcg_var_init_reserved(dcg_var_t* var) noexcept nogil
+    int c_dcg_var_init_bool(dcg_var_t* var, c_bool value) noexcept nogil
+    int c_dcg_var_init_double(dcg_var_t* var, double value) noexcept nogil
+    int c_dcg_var_init_int(dcg_var_t* var, ssize_t value) noexcept nogil
+    int c_dcg_var_init_offset(dcg_var_t* var, ssize_t value) noexcept nogil
+    int c_dcg_var_init_string(dcg_var_t* var, const char* value) noexcept nogil
+    int c_dcg_var_init_ref_raw(dcg_var_t* var, dcg_var_type dtype, const void* ref) noexcept nogil
+    int c_dcg_var_init_ref(dcg_var_t* var, const dcg_var_t* src) noexcept nogil
+    int c_dcg_var_init_ptr(dcg_var_t* var, void* value) noexcept nogil
+    int c_dcg_var_init_node(dcg_var_t* var, const dcg_node* node) noexcept nogil
+    int c_dcg_var_init_dvector(dcg_var_t* var, double* value, size_t n, c_bool copy, allocator_protocol* allocator) noexcept nogil
+    int c_dcg_var_init_dmatrix(dcg_var_t* var, double* value, size_t n_rows, size_t n_cols, c_bool row_major, c_bool copy, allocator_protocol* allocator) noexcept nogil
+
+    int c_dcg_var_ref_level(dcg_var_type dtype) noexcept nogil
+    c_bool c_dcg_var_is_ref(dcg_var_type dtype) noexcept nogil
+    dcg_var_type c_dcg_var_ref_base(dcg_var_type dtype) noexcept nogil
+
+    const char* c_dcg_ret_code_name(dcg_ret_code code) noexcept nogil
+    const char* c_dcg_var_type_name(dcg_var_type dtype) noexcept nogil
+    c_bool c_dcg_var_is_numeric(const dcg_var_t* var) noexcept nogil
+    dcg_var_numeric c_dcg_var_numeric_of(const dcg_var_t* var) noexcept nogil
+    c_bool c_dcg_var_is_container(const dcg_var_t* var) noexcept nogil
+    c_bool c_dcg_var_is_null(const dcg_var_t* var) noexcept nogil
+    c_bool c_dcg_var_is_truthy(const dcg_var_t* var) noexcept nogil
+    c_bool c_dcg_var_equals(const dcg_var_t* lhs, const dcg_var_t* rhs) noexcept nogil
+
+    void c_dcg_var_vigilant_abort(const char* getter, dcg_var_type dtype, const char* what) noexcept nogil
+    const void* c_dcg_var_ref_slot(const dcg_var_t* var, const char* getter) noexcept nogil
+    c_bool c_dcg_var_as_bool(const dcg_var_t* var) noexcept nogil
+    double c_dcg_var_as_double(const dcg_var_t* var) noexcept nogil
+    ssize_t c_dcg_var_as_int(const dcg_var_t* var) noexcept nogil
+    ssize_t c_dcg_var_as_offset(const dcg_var_t* var) noexcept nogil
+    const char* c_dcg_var_as_string(const dcg_var_t* var) noexcept nogil
+    const void* c_dcg_var_as_ref(const dcg_var_t* var) noexcept nogil
+    void* c_dcg_var_as_ptr(const dcg_var_t* var) noexcept nogil
+    const dcg_node* c_dcg_var_as_node(const dcg_var_t* var) noexcept nogil
+    dcg_d_vector_t* c_dcg_var_as_dvector(const dcg_var_t* var) noexcept nogil
+    dcg_d_matrix_t* c_dcg_var_as_dmatrix(const dcg_var_t* var) noexcept nogil
+    int c_dcg_var_cast(dcg_var_t* out, const dcg_var_t* var, dcg_var_type dtype) noexcept nogil
+    void c_dcg_var_snapshot(dcg_var_t* snapshot, const dcg_var_t* slot) noexcept nogil
+
+    int c_dcg_var_format(const dcg_var_t* var, char* out, size_t cap) noexcept nogil
+    int c_dcg_var_print(const dcg_var_t* var, FILE* stream) noexcept nogil
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_node.h":
+    ctypedef struct dcg_node:
+        pass
+
+
+cdef class VarView:
+    cdef const dcg_var_t* header
+
+    @staticmethod
+    cdef inline VarView c_from_header(const dcg_var_t* var)
+
+
+cdef void c_dcg_var_pypack(dcg_var_t* out, object value) except *
+
+cdef object c_dcg_var_pyunpack(const dcg_var_t* var)

decision_graph/decision_tree/bake/c_var.pyi

@@ -0,0 +1,271 @@
+"""The value layer: tagged values, containers, references, casts and output.
+
+The unit of data that flows through a graph is a ``dcg_var_t``: a *tag* and a
+*payload*. The tag is what an evaluator dispatches on, the payload is read
+through the member the tag names, and everything else in this module is a reader
+over the two - which is what ``VarView`` below is the Python window into.
+
+Nothing else here is a Python object: the constructors, the initialisers, the
+containers, the references, the casts and the output helpers are all ``cdef``
+(``c_dcg_var_*``), plus the ``cdef extern`` declarations of the C header. A
+caller reaches a value through the wrapper it belongs to - a node's ``out``, a
+store's slot, a condition's payload - and reads it through ``VarView``.
+
+The two Cython-level bridges are not module attributes either:
+``c_dcg_var_pypack`` and ``c_dcg_var_pyunpack`` translate between a
+``dcg_var_t`` and a Python object, and are cimported by the modules that need
+them (``c_const``, ``c_collections``).
+"""
+
+from enum import IntEnum
+
+
+class VarType(IntEnum):
+    """The tag of a value: what it is, and whether it is a reference.
+
+    The members are the C enumerators by value, so a tag crosses the boundary as
+    itself and no translation table exists to fall out of step. The reference
+    ones are named as the C ones are - ``double_ref`` refers to a double,
+    ``double_ref_ref`` to a reference to one, one name per rung - and
+    ``inferred`` is a reference to a slot whose type is not known yet.
+
+    Attributes:
+        node: A node, held as its own address. It is what an action leaf's slot
+            carries - the node IS the value it stands for - and what unpacks back
+            into that node's wrapper.
+        reserved: A slot holding nothing yet: an entry whose value has not
+            arrived. ``is_null`` is true for one, and reading it refuses.
+        inferred: A reference to a ``reserved`` slot - "the type is the slot's to
+            say". It is what a read of a not-yet-filled store entry is born as.
+    """
+
+    raw_ptr: VarType
+    string: VarType
+    bool: VarType
+    double: VarType
+    int: VarType
+    offset: VarType
+    time: VarType
+    date: VarType
+    datetime: VarType
+    d_vector: VarType
+    d_matrix: VarType
+    reserved: VarType
+    node: VarType
+    raw_ptr_ref: VarType
+    string_ref: VarType
+    bool_ref: VarType
+    double_ref: VarType
+    int_ref: VarType
+    offset_ref: VarType
+    time_ref: VarType
+    date_ref: VarType
+    datetime_ref: VarType
+    d_vector_ref: VarType
+    d_matrix_ref: VarType
+    node_ref: VarType
+    inferred: VarType
+    raw_ptr_ref_ref: VarType
+    string_ref_ref: VarType
+    bool_ref_ref: VarType
+    double_ref_ref: VarType
+    int_ref_ref: VarType
+    offset_ref_ref: VarType
+    time_ref_ref: VarType
+    date_ref_ref: VarType
+    datetime_ref_ref: VarType
+    d_vector_ref_ref: VarType
+    d_matrix_ref_ref: VarType
+    node_ref_ref: VarType
+
+
+class VarNumeric(IntEnum):
+    """How a value reads as a number - the shape of the answer, not the value.
+
+    A value that is not a number at all is ``none``, which is what the numeric
+    operators refuse. The two that ARE numbers are what decides the type of an
+    arithmetic result: an operation with a double in it is a double, and one
+    without is whole.
+    """
+
+    none: VarNumeric
+    int: VarNumeric
+    double: VarNumeric
+
+
+class VarView:
+    """A read-only window onto a ``dcg_var_t``: the value layer's Python face.
+
+    A view is an ADDRESS, not a copy: it holds the slot it was taken over, and
+    every read answers for what that slot holds at the moment of the read. A
+    view owns nothing and frees nothing, so it must not outlive the value it
+    looks at - which the layer guarantees by handing one out only from a wrapper
+    that keeps that value alive (``LogicNode.out``).
+
+    It cannot write, and that is not a promise this docstring is making: the
+    view holds the value **const**, and every reader it exposes takes a const
+    pointer, so a write through a view does not compile. Reading a value that
+    another part of the layer is changing is what a view is for - it reports what
+    the slot holds now, never a snapshot taken when it was made.
+
+    The value type itself, which this class documents because it is its subject:
+
+    **The tag.** ``dcg_var_type`` names what the payload is - a raw pointer, a
+    string, a bool, a double, an int, an offset, a session time, date or
+    datetime, a contiguous double vector, or a matrix - and a tag with reference
+    bits set names a REFERENCE instead. The level in those bits is how many hops
+    the reference takes, and ``dtype & VAR_TYPE_BASE_MASK`` still names what sits
+    at the END of the walk: a reference to a double is a ``double_ref``, a
+    reference to that is a ``double_ref_ref``, and one more rung adds one more
+    star. A ``reserved`` slot is one that holds nothing yet - an entry created
+    before its value - and a reference to one is ``inferred``: the type is the
+    slot's to say, and a reader asks the slot.
+
+    **The payload.** One union, read through the member the tag calls for. A
+    container tag carries a pointer to a shape struct the value OWNS (allocated
+    as a child block, so one free releases the value and its container), a string
+    may be owned or borrowed, and a reference carries the address of the slot it
+    refers to and nothing else.
+
+    **References.** A reference owns nothing: the slot belongs to whoever set it
+    up, must outlive the reference, and must keep the shape the level assumes.
+    Reading through one is what the readers do - they follow the hops and read
+    what the tag says is at the end - so nothing in a payload is ever read as a
+    value header to find the way.
+
+    Attributes:
+        _header: The C value this view reads through.
+    """
+
+    def __init__(self, address: int) -> None:
+        """View the value at an address.
+
+        Args:
+            address: Address of a ``dcg_var_t``. The layer hands these out
+                itself (``LogicNode.out``); nothing here checks that the address
+                is a value, and the view keeps nothing alive.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """The view's own text: its class and the value's display text."""
+        ...
+
+    def format(self) -> str:
+        """The value as display text, as the C layer renders it.
+
+        Returns:
+            The text: a string quoted, a double with ``%g``, a pointer as an
+            address, a bool as true/false, a container as its shape.
+
+        Raises:
+            RuntimeError: When the view is uninitialised, or the C layer fails.
+        """
+        ...
+
+    @property
+    def address(self) -> int:
+        """The value's address - the slot this view reads through."""
+        ...
+
+    @property
+    def dtype(self) -> VarType:
+        """The value's tag."""
+        ...
+
+    @property
+    def type_name(self) -> str:
+        """The tag's stable name: ``'double'``, ``'double_ref'``, ``'inferred'``."""
+        ...
+
+    @property
+    def is_null(self) -> bool:
+        """Whether the value is absent: no payload of any type.
+
+        A live reference whose slot holds NULL is absent, like a NULL string or a
+        vector with no buffer, and so is a reserved slot. A reference that points
+        at nothing is not absent but broken: reading through it refuses.
+        """
+        ...
+
+    @property
+    def is_ref(self) -> bool:
+        """Whether the tag names a reference rather than a plain value."""
+        ...
+
+    @property
+    def ref_level(self) -> int:
+        """How many hops the tag refers through: 0, 1, 2, ... as far as it nests."""
+        ...
+
+    @property
+    def ref_base(self) -> VarType:
+        """The tag at the end of the walk - for a plain value, the tag itself."""
+        ...
+
+    @property
+    def numeric(self) -> VarNumeric:
+        """How the value reads as a number.
+
+        The question the arithmetic operators ask about an operand before they
+        apply themselves, and the answer that decides the type of what they
+        produce. A reference answers for what it refers to.
+        """
+        ...
+
+    @property
+    def value(self) -> bool | int | float | str | None:
+        """The value as a Python object, read by its own tag.
+
+        A reference is read through, as every reader reads one. None comes back
+        for a value that stands for nothing - unset, empty, or a tag with no
+        Python counterpart (a container, a session time).
+        """
+        ...
+
+    @property
+    def as_bool(self) -> bool:
+        """The value's truth, following Python's rules for its tag.
+
+        Never refuses: every tag has a truth value, so this is the one reader
+        that can always answer.
+        """
+        ...
+
+    @property
+    def as_int(self) -> int:
+        """The value as an integer, coercing: doubles truncate toward zero.
+
+        A non-numeric tag has no answer to give, and the layer's vigilant mode
+        reports the mistake where it is made rather than returning a 0 that
+        reads like a value.
+        """
+        ...
+
+    @property
+    def as_double(self) -> float:
+        """The value as a double, coercing from the numeric tags.
+
+        As with ``as_int``: a tag that is not a number is reported, not coerced.
+        """
+        ...
+
+    @property
+    def as_string(self) -> str | None:
+        """The text a string-shaped tag holds, or None when that text is NULL.
+
+        A tag that is not string-shaped is refused rather than answered
+        (vigilant mode names the reader and the tag on stderr and aborts), so a
+        caller asks ``type_name`` or ``is_null`` first.
+        """
+        ...
+
+    @property
+    def as_ptr(self) -> int:
+        """The pointer a pointer-shaped tag holds, as an address."""
+        ...
+
+    @property
+    def as_ref(self) -> int:
+        """The address a reference tag holds - the slot, one star per rung."""
+        ...