PyDecisionGraph 0.3.2.post1__cp315-cp315-win_amd64.whl

decision_graph/decision_tree/bake/c_const.pyi

@@ -0,0 +1,305 @@
+"""The constant layer: the values a graph is given, and the reads of a store.
+
+Two node types, and they are opposites. A constant CARRIES a value: what it
+stands for is in the node, and a caller can let the Python object go the moment
+it is built. A variable READS one: its value lives elsewhere - in a store's
+entry, or in another node's slot it was bound to - and the node is the read of
+it, so what it answers with is what that place holds at the moment it is read.
+
+Both compose: an operand of an expression, a leaf of a branch.
+
+Both compose with a Python value as readily as with a node: a value with no node
+of its own becomes the literal that carries it, so ``5 + read`` and ``read + 5``
+build the same nodes as the forms written out with a ``ConstantNode``.
+"""
+
+from typing import Any
+
+from .c_expr import BinaryExpression, UnaryExpression
+from .c_logic_group import LogicGroup
+from .c_node import LogicNode
+
+
+class ConstantNode(LogicNode):
+    """A literal input: the value it stands for is in the node.
+
+    The C type follows the value - a bool is a true or a false node, an int an
+    int, a float a double, a str a string - so there is nothing for a caller to
+    say that the value does not already say.
+    """
+
+    def __init__(self, value: Any, *, repr: str | None = None) -> None:
+        """Build a literal for a Python value.
+
+        Args:
+            value: The literal: a bool, an int, a float or a str.
+            repr: Display text to copy; the value's own text when not given.
+
+        Raises:
+            TypeError: When the value has no node type - a container, None.
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def __add__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a sum expression with another node."""
+        ...
+
+    def __radd__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a sum expression with a Python value on the left."""
+        ...
+
+    def __sub__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a difference expression with another node."""
+        ...
+
+    def __rsub__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a difference expression with a Python value on the left."""
+        ...
+
+    def __mul__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a product expression with another node."""
+        ...
+
+    def __rmul__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a product expression with a Python value on the left."""
+        ...
+
+    def __truediv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a division expression with another node."""
+        ...
+
+    def __rtruediv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a division expression with a Python value on the left."""
+        ...
+
+    def __floordiv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a floor-division expression with another node."""
+        ...
+
+    def __rfloordiv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a floor-division expression with a Python value on the left."""
+        ...
+
+    def __pow__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a power expression with another node."""
+        ...
+
+    def __rpow__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a power expression with a Python value on the left."""
+        ...
+
+    def __neg__(self) -> UnaryExpression:
+        """Compose a negation of this literal."""
+        ...
+
+    def __eq__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose an equality CONDITION with another node.
+
+        Comparing two nodes builds the comparison node, as it does in the capi -
+        the result is a branch, not a bool.
+        """
+        ...
+
+    def __ne__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose an inequality condition with another node."""
+        ...
+
+    def __hash__(self) -> int:
+        """Hash by the C block's address, so a node can key a dict."""
+        ...
+
+    def __lt__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a less-than condition with another node."""
+        ...
+
+    def __le__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a less-or-equal condition with another node."""
+        ...
+
+    def __gt__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a greater-than condition with another node."""
+        ...
+
+    def __ge__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a greater-or-equal condition with another node."""
+        ...
+
+    def __and__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a conjunction with another node."""
+        ...
+
+    def __rand__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a conjunction with a Python value on the left."""
+        ...
+
+    def __or__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a disjunction with another node."""
+        ...
+
+    def __ror__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a disjunction with a Python value on the left."""
+        ...
+
+    def __invert__(self) -> UnaryExpression:
+        """Compose the negation of this literal as a condition."""
+        ...
+
+    @property
+    def value(self) -> Any:
+        """The value the literal holds, read by the value's own tag."""
+        ...
+
+
+class VariableNode(LogicNode):
+    """A variable input: a node that reads a value rather than holding one.
+
+    It holds no value of its own: what it reads is the slot it was bound to, and
+    the read is live - whatever that slot holds when the node is read is what the
+    node reports. A node built without a slot reflects nothing until one is
+    given.
+    """
+
+    def __init__(self, *, key: str | None = None, repr: str | None = None) -> None:
+        """Build a read of an entry.
+
+        Args:
+            key: Entry name in the group it is built inside, if any.
+            repr: Display text to copy.
+
+        Raises:
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def c_bind_const(self, node: ConstantNode) -> None:
+        """Read a literal's slot, so the read follows the value it holds.
+
+        Args:
+            node: The literal whose value this read reflects.
+
+        Raises:
+            RuntimeError: When the C layer refuses the binding.
+        """
+        ...
+
+    def __add__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a sum expression with another node."""
+        ...
+
+    def __radd__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a sum expression with a Python value on the left."""
+        ...
+
+    def __sub__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a difference expression with another node."""
+        ...
+
+    def __rsub__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a difference expression with a Python value on the left."""
+        ...
+
+    def __mul__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a product expression with another node."""
+        ...
+
+    def __rmul__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a product expression with a Python value on the left."""
+        ...
+
+    def __truediv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a division expression with another node."""
+        ...
+
+    def __rtruediv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a division expression with a Python value on the left."""
+        ...
+
+    def __floordiv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a floor-division expression with another node."""
+        ...
+
+    def __rfloordiv__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a floor-division expression with a Python value on the left."""
+        ...
+
+    def __pow__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a power expression with another node."""
+        ...
+
+    def __rpow__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a power expression with a Python value on the left."""
+        ...
+
+    def __neg__(self) -> UnaryExpression:
+        """Compose a negation of this read."""
+        ...
+
+    def __eq__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose an equality CONDITION with another node."""
+        ...
+
+    def __ne__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose an inequality condition with another node."""
+        ...
+
+    def __hash__(self) -> int:
+        """Hash by the C block's address, so a node can key a dict."""
+        ...
+
+    def __lt__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a less-than condition with another node."""
+        ...
+
+    def __le__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a less-or-equal condition with another node."""
+        ...
+
+    def __gt__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a greater-than condition with another node."""
+        ...
+
+    def __ge__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a greater-or-equal condition with another node."""
+        ...
+
+    def __and__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a conjunction with another node."""
+        ...
+
+    def __rand__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a conjunction with a Python value on the left."""
+        ...
+
+    def __or__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a disjunction with another node."""
+        ...
+
+    def __ror__(self, other: LogicNode | bool | int | float | str) -> BinaryExpression:
+        """Compose a disjunction with a Python value on the left."""
+        ...
+
+    def __invert__(self) -> UnaryExpression:
+        """Compose the negation of this read as a condition."""
+        ...
+
+    @property
+    def value(self) -> Any:
+        """The value the read stands for, read through its binding."""
+        ...
+
+    @property
+    def key(self) -> str | None:
+        """The store entry this read names, or None when it names none."""
+        ...
+
+    @property
+    def logic_group(self) -> LogicGroup | None:
+        """The group this read belongs to, or None for a standalone node.
+
+        The C field is an untyped pointer because the node layer cannot name a
+        group without an upward edge (DEPENDENCY.md 4.2); what it holds is the
+        group the read was built inside, which is a store's entry in the case
+        that matters - see ``c_collections.AttrExpression``.
+        """
+        ...

decision_graph/decision_tree/bake/c_const.pyx

@@ -0,0 +1,278 @@
+from cpython.unicode cimport PyUnicode_AsUTF8, PyUnicode_AsUTF8AndSize, PyUnicode_FromString
+
+from .c_allocator_protocol cimport DCG_DEFAULT_ALLOCATOR
+from .c_expr cimport BinaryExpression, UnaryExpression, dcg_op_code
+from .c_node cimport c_dcg_node_set_repr
+from .c_var cimport c_dcg_var_pypack, c_dcg_var_pyunpack, dcg_ret_code
+
+
+cdef class ConstantNode(LogicNode):
+    def __init__(self, object value, *, str repr=None):
+        cdef dcg_constant_node* node = NULL
+        cdef int ret_code
+
+        if isinstance(value, bool):
+            node = c_dcg_node_new_const_bool(value, DCG_DEFAULT_ALLOCATOR)
+        elif isinstance(value, int):
+            node = c_dcg_node_new_const_int(value, DCG_DEFAULT_ALLOCATOR)
+        elif isinstance(value, float):
+            node = c_dcg_node_new_const_double(value, DCG_DEFAULT_ALLOCATOR)
+        elif isinstance(value, str):
+            node = c_dcg_node_new_const_string(PyUnicode_AsUTF8(value), DCG_DEFAULT_ALLOCATOR)
+        else:
+            raise TypeError(f'A constant cannot hold {type(value).__name__}: bake has no node type for it.')
+
+        if not node:
+            raise MemoryError('Failed to allocate the ConstantNode.')
+
+        self.header = &node.base
+        self.owner = True
+
+        if repr is not None:
+            ret_code = c_dcg_node_set_repr(self.header, PyUnicode_AsUTF8(repr))
+            if ret_code != dcg_ret_code.DCG_OK:
+                raise RuntimeError(f'c_dcg_node_set_repr failed with err code: {ret_code}')
+
+        self.c_register_node()
+
+    # === Python Operators ===
+    #
+    # A constant composes into an expression the same way an expression does,
+    # and it names the expression classes directly: the two families are the
+    # concrete structures of one layer, and a sub-dependency inside a layer is
+    # allowed (DEPENDENCY.md rule 2). The operand is the node base, which is the
+    # one type both families can name.
+
+    def __add__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_ADD, self, c_dcg_node_pypack(other))
+
+    def __radd__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_ADD, c_dcg_node_pypack(other), self)
+
+    def __sub__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_SUB, self, c_dcg_node_pypack(other))
+
+    def __rsub__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_SUB, c_dcg_node_pypack(other), self)
+
+    def __mul__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_MUL, self, c_dcg_node_pypack(other))
+
+    def __rmul__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_MUL, c_dcg_node_pypack(other), self)
+
+    def __truediv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_DIV, self, c_dcg_node_pypack(other))
+
+    def __rtruediv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_DIV, c_dcg_node_pypack(other), self)
+
+    def __floordiv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_FLOORDIV, self, c_dcg_node_pypack(other))
+
+    def __rfloordiv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_FLOORDIV, c_dcg_node_pypack(other), self)
+
+    def __pow__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_POW, self, c_dcg_node_pypack(other))
+
+    def __rpow__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_POW, c_dcg_node_pypack(other), self)
+
+    def __neg__(self):
+        return UnaryExpression(dcg_op_code.DCG_OP_NEG, self)
+
+    def __eq__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_EQ, self, c_dcg_node_pypack(other))
+
+    def __ne__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_NE, self, c_dcg_node_pypack(other))
+
+    def __hash__(self):
+        return hash(self.address)
+
+    def __lt__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_LT, self, c_dcg_node_pypack(other))
+
+    def __le__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_LE, self, c_dcg_node_pypack(other))
+
+    def __gt__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_GT, self, c_dcg_node_pypack(other))
+
+    def __ge__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_GE, self, c_dcg_node_pypack(other))
+
+    def __and__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_AND, self, c_dcg_node_pypack(other))
+
+    def __rand__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_AND, c_dcg_node_pypack(other), self)
+
+    def __or__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_OR, self, c_dcg_node_pypack(other))
+
+    def __ror__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_OR, c_dcg_node_pypack(other), self)
+
+    def __invert__(self):
+        return UnaryExpression(dcg_op_code.DCG_OP_NOT, self)
+
+    # === Python Properties ===
+
+    property value:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_var_pyunpack(c_dcg_node_const_get(<dcg_constant_node*> self.header))
+
+        def __set__(self, object value):
+            import warnings
+            warnings.warn('[DBG] Updating a const node value is debug only, do not use this in prod env. after the value update, a PermissionError will be raised intensionally!')
+
+            cdef dcg_var_t slot
+            c_dcg_var_pypack(&slot, value)
+
+            cdef int ret_code = c_dcg_node_const_set(<dcg_constant_node*> self.header, slot)
+            if ret_code != dcg_ret_code.DCG_OK:
+                raise RuntimeError(f'c_dcg_node_const_set failed with err code: {ret_code}')
+
+            warnings.warn(f'[DBG] {self} value slot updated! Raising PermissionError!')
+            raise PermissionError(f'Must not update value of a {self.__class__.__name__}')
+
+
+cdef class VariableNode(LogicNode):
+    def __init__(self, *, str key=None, str repr=None):
+        cdef dcg_variable_node* node
+        cdef Py_ssize_t key_len = 0
+        cdef const char* c_key = PyUnicode_AsUTF8AndSize(key, &key_len) if key else NULL
+        cdef dcg_logic_group* active_logic_group = c_dcg_lgm_active_group(LogicNode.c_get_manager())
+
+        node = c_dcg_node_new_var(
+            PyUnicode_AsUTF8(repr) if repr is not None else NULL,
+            c_key,
+            key_len,
+            NULL,
+            active_logic_group,
+            DCG_DEFAULT_ALLOCATOR,
+        )
+        if not node:
+            raise MemoryError('Failed to allocate the VariableNode.')
+
+        self.header = &node.base
+        # With a group given the node is a block OF THAT GROUP, and the group
+        # releases it - so the wrapper owns nothing and must free nothing.
+        self.owner = active_logic_group == NULL
+        self.c_register_node()
+
+    # === Cython Internal Binding ===
+
+    cdef void c_bind_slot(self, dcg_var_t* slot):
+        cdef int ret_code = c_dcg_node_var_bind(<dcg_variable_node*> self.header, slot)
+        if ret_code != dcg_ret_code.DCG_OK:
+            raise RuntimeError(f'c_dcg_node_var_bind failed with err code: {ret_code}')
+
+    # === Python Interfaces ===
+
+    cpdef void c_bind_const(self, ConstantNode node):
+        self.c_bind_slot(&node.header.out)
+
+    # === Python Operators ===
+
+    def __add__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_ADD, self, c_dcg_node_pypack(other))
+
+    def __radd__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_ADD, c_dcg_node_pypack(other), self)
+
+    def __sub__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_SUB, self, c_dcg_node_pypack(other))
+
+    def __rsub__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_SUB, c_dcg_node_pypack(other), self)
+
+    def __mul__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_MUL, self, c_dcg_node_pypack(other))
+
+    def __rmul__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_MUL, c_dcg_node_pypack(other), self)
+
+    def __truediv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_DIV, self, c_dcg_node_pypack(other))
+
+    def __rtruediv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_DIV, c_dcg_node_pypack(other), self)
+
+    def __floordiv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_FLOORDIV, self, c_dcg_node_pypack(other))
+
+    def __rfloordiv__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_FLOORDIV, c_dcg_node_pypack(other), self)
+
+    def __pow__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_POW, self, c_dcg_node_pypack(other))
+
+    def __rpow__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_POW, c_dcg_node_pypack(other), self)
+
+    def __neg__(self):
+        return UnaryExpression(dcg_op_code.DCG_OP_NEG, self)
+
+    def __eq__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_EQ, self, c_dcg_node_pypack(other))
+
+    def __ne__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_NE, self, c_dcg_node_pypack(other))
+
+    def __hash__(self):
+        return hash(self.address)
+
+    def __lt__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_LT, self, c_dcg_node_pypack(other))
+
+    def __le__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_LE, self, c_dcg_node_pypack(other))
+
+    def __gt__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_GT, self, c_dcg_node_pypack(other))
+
+    def __ge__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_GE, self, c_dcg_node_pypack(other))
+
+    def __and__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_AND, self, c_dcg_node_pypack(other))
+
+    def __rand__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_AND, c_dcg_node_pypack(other), self)
+
+    def __or__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_OR, self, c_dcg_node_pypack(other))
+
+    def __ror__(self, object other):
+        return BinaryExpression(dcg_op_code.DCG_OP_OR, c_dcg_node_pypack(other), self)
+
+    def __invert__(self):
+        return UnaryExpression(dcg_op_code.DCG_OP_NOT, self)
+
+    # === Python Properties ===
+
+    property value:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_var_pyunpack(&self.header.out)
+
+    property key:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            cdef dcg_variable_node* node = <dcg_variable_node*> self.header
+            if not node.key:
+                return None
+            return PyUnicode_FromString(node.key)
+
+
+cdef LogicNode c_dcg_node_pypack(object value):
+    if isinstance(value, LogicNode):
+        return value
+    return ConstantNode(value)