PyDecisionGraph 0.3.2.post1__cp315-cp315-win_amd64.whl

decision_graph/decision_tree/bake/c_edge.pyi

@@ -0,0 +1,192 @@
+"""The edge layer: the condition a child carries about its parent.
+
+An edge is a condition, and a condition is a tagged value with a type of its
+own: five built-ins - unconditional, else, auto, true, false - and any other
+condition is a caller's, holding the value its parent's evaluated result is
+compared against.
+
+Identity is the condition's ``type`` field, which is what the predicates here
+read, and what the registry below is keyed by address for: a node's ``children``
+is a dict keyed by these, so two wrappers of one condition have to compare as
+one edge.
+"""
+
+from typing import Any
+
+from cbase.bytemap import BoundByteMap
+
+
+class NodeEdgeCondition:
+    """A condition an edge carries, as a tagged value.
+
+    An instance of this class is a **user condition**: it holds a value, and a
+    parent takes the edge when its evaluated result matches that value. The five
+    built-ins are instances of the subclasses below and are module constants.
+
+    Attributes:
+        _header: The C condition block the wrapper stands for.
+        _owner: Whether this wrapper may free that block.
+    """
+
+    def __init__(self, py_value: Any = ..., repr: str | None = None) -> None:
+        """Wrap a Python value as an edge condition.
+
+        Args:
+            py_value: The value the parent's result is compared against.
+            repr: Display text for the condition.
+
+        Raises:
+            ValueError: When no value is given - a user condition needs one.
+        """
+        ...
+
+    def __hash__(self) -> int:
+        """Hash by the C block's address, or by the type for a built-in."""
+        ...
+
+    def __eq__(self, other: NodeEdgeCondition) -> bool:
+        """Compare as edges: the tag first, then the payload.
+
+        Args:
+            other: Condition to compare against.
+
+        Returns:
+            True when both conditions are the same edge.
+        """
+        ...
+
+    def __ne__(self, other: NodeEdgeCondition) -> bool:
+        """The negation of ``__eq__``."""
+        ...
+
+    def __repr__(self) -> str:
+        """The condition's display text, class name included."""
+        ...
+
+    def __str__(self) -> str:
+        """The condition's display text."""
+        ...
+
+    @property
+    def address(self) -> int:
+        """The block this condition is, as the edge registry keys it."""
+        ...
+
+    @property
+    def is_none(self) -> bool:
+        """Whether this is the unconditional edge."""
+        ...
+
+    @property
+    def is_else(self) -> bool:
+        """Whether this is the fallback edge."""
+        ...
+
+    @property
+    def is_auto(self) -> bool:
+        """Whether this edge's arm is for the parent to infer."""
+        ...
+
+    @property
+    def is_binary(self) -> bool:
+        """Whether this is a two-way edge: the true or the false arm."""
+        ...
+
+    @property
+    def value(self) -> Any:
+        """The value this edge is taken by: what the parent's result must match.
+
+        A caller's condition carries the value it was built with, and it is read
+        here as the Python object it was. The three edges that stand for "no
+        particular value" - the unconditional, the else and the auto - hold none,
+        so reading one raises rather than answering with a value that says
+        nothing. The two arms of a branch are the exception the other way: they
+        DO answer, with the ``True`` and the ``False`` they are, which is what
+        makes a built-in edge usable without unpacking the C tag first.
+
+        Raises:
+            ValueError: When the condition holds no value.
+            RuntimeError: When the wrapper is uninitialised.
+        """
+        ...
+
+
+class ConditionAny(NodeEdgeCondition):
+    """The unconditional edge: a parent's single arm."""
+
+
+class ConditionElse(NodeEdgeCondition):
+    """The fallback edge: taken when nothing else matched, always last."""
+
+
+class ConditionAuto(NodeEdgeCondition):
+    """An unresolved edge: the parent infers the arm it belongs to."""
+
+
+class BinaryCondition(NodeEdgeCondition):
+    """A two-way edge: the true arm or the false arm of a branch."""
+
+
+class ConditionTrue(BinaryCondition):
+    """The true arm of a two-way branch."""
+
+    def __bool__(self) -> bool:
+        """True, as the arm it is."""
+        ...
+
+    def __int__(self) -> int:
+        """1, as the arm it is."""
+        ...
+
+    @property
+    def value(self) -> bool:
+        """True - the arm answers with the value it stands for."""
+        ...
+
+
+class ConditionFalse(BinaryCondition):
+    """The false arm of a two-way branch."""
+
+    def __bool__(self) -> bool:
+        """False, as the arm it is."""
+        ...
+
+    def __int__(self) -> int:
+        """0, as the arm it is."""
+        ...
+
+    @property
+    def value(self) -> bool:
+        """False - the arm answers with the value it stands for."""
+        ...
+
+
+class EdgeConditionRegistry(BoundByteMap):
+    """The wrapper every edge is looked up by, keyed by its block's address.
+
+    A lookup that finds the address answers with the instance held for it; one
+    that misses builds the condition its own **type** names - the derived class
+    for a built-in, the base for a caller's - over the address that was asked
+    for. Two conditions of one type are still two edges, so nothing here hands
+    out a shared instance for a different address.
+    """
+
+    def __getitem__(self, key: int) -> NodeEdgeCondition:
+        """The condition at an address, rebuilding it when it is not held.
+
+        Args:
+            key: Address of the C condition block.
+
+        Returns:
+            The condition wrapper for that address.
+        """
+        ...
+
+
+# The five built-ins, and the registry that holds them.
+NO_CONDITION: ConditionAny
+ELSE_CONDITION: ConditionElse
+AUTO_CONDITION: ConditionAuto
+TRUE_CONDITION: ConditionTrue
+FALSE_CONDITION: ConditionFalse
+EDGE_REGISTRY: EdgeConditionRegistry

decision_graph/decision_tree/bake/c_edge.pyx

@@ -0,0 +1,270 @@
+from cpython.dict cimport PyDict_Contains
+from cpython.unicode cimport PyUnicode_AsUTF8, PyUnicode_FromString
+from libc.stdint cimport uintptr_t
+
+from cbase.bytemap cimport c_bytemap_gen_seq_id
+
+from .c_allocator_protocol cimport DCG_DEFAULT_ALLOCATOR
+from .c_var cimport c_dcg_var_is_null, c_dcg_var_pypack, c_dcg_var_pyunpack
+
+
+cdef class NodeEdgeCondition:
+    def __init__(self, object py_value=None, str repr=None):
+        if py_value is None:
+            raise ValueError('A user condition needs a value; the five built-ins are module constants.')
+
+        cdef dcg_var_t val
+        c_dcg_var_pypack(&val, py_value)
+
+        self.header = c_dcg_edge_new(val, PyUnicode_AsUTF8(repr) if repr is not None else NULL, DCG_DEFAULT_ALLOCATOR)
+        if not self.header:
+            raise MemoryError('Failed to allocate an edge condition.')
+
+        self.owner = True
+
+    def __dealloc__(self):
+        if not self.owner:
+            return
+
+        if self.header:
+            c_dcg_condition_free(self.header)
+
+    @staticmethod
+    cdef NodeEdgeCondition c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef NodeEdgeCondition instance = NodeEdgeCondition.__new__(NodeEdgeCondition)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+    # === Python Dunders ===
+
+    def __hash__(self):
+        if self.header == NULL:
+            return 0
+        if c_dcg_condition_is_sentinel(self.header):
+            return <uintptr_t> self.header.type
+        return <uintptr_t> self.header
+
+    def __eq__(self, NodeEdgeCondition other):
+        if not isinstance(other, NodeEdgeCondition):
+            return NotImplemented
+        return c_dcg_condition_equals(self.header, other.header)
+
+    def __ne__(self, NodeEdgeCondition other):
+        if not isinstance(other, NodeEdgeCondition):
+            return NotImplemented
+        return not c_dcg_condition_equals(self.header, other.header)
+
+    def __repr__(self):
+        if not self.header:
+            return f'<{self.__class__.__name__} (Uninitialized)>'
+        cdef char buf[DCG_NODE_STRING_MAXLEN]
+        c_dcg_condition_format(self.header, NULL, buf, sizeof(buf))
+        return f'<{self.__class__.__name__}>({PyUnicode_FromString(buf)})'
+
+    def __str__(self):
+        if not self.header:
+            return f'<{self.__class__.__name__} (Uninitialized)>'
+        cdef char buf[DCG_NODE_STRING_MAXLEN]
+        c_dcg_condition_format(self.header, NULL, buf, sizeof(buf))
+        return PyUnicode_FromString(buf)
+
+    property address:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return <uintptr_t> self.header
+
+    property is_none:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_condition_is_none(self.header)
+
+    property is_else:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_condition_is_else(self.header)
+
+    property is_auto:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_condition_is_auto(self.header)
+
+    property is_binary:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            return c_dcg_condition_is_binary(self.header)
+
+    property value:
+        def __get__(self):
+            if not self.header:
+                raise RuntimeError(f'<{self.__class__.__name__}> not initialized!')
+            if c_dcg_var_is_null(&self.header.value):
+                raise ValueError('Condition has no value assigned.')
+            return c_dcg_var_pyunpack(&self.header.value)
+
+
+cdef class ConditionAny(NodeEdgeCondition):
+    @staticmethod
+    cdef ConditionAny c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef ConditionAny instance = ConditionAny.__new__(ConditionAny)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+
+cdef class ConditionElse(NodeEdgeCondition):
+    @staticmethod
+    cdef ConditionElse c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef ConditionElse instance = ConditionElse.__new__(ConditionElse)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+
+cdef class ConditionAuto(NodeEdgeCondition):
+    @staticmethod
+    cdef ConditionAuto c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef ConditionAuto instance = ConditionAuto.__new__(ConditionAuto)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+
+cdef class BinaryCondition(NodeEdgeCondition):
+    @staticmethod
+    cdef BinaryCondition c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef BinaryCondition instance = BinaryCondition.__new__(BinaryCondition)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+
+cdef class ConditionTrue(BinaryCondition):
+    @staticmethod
+    cdef ConditionTrue c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef ConditionTrue instance = ConditionTrue.__new__(ConditionTrue)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+    def __bool__(self):
+        return True
+
+    def __int__(self):
+        return 1
+
+    property value:
+        def __get__(self):
+            return True
+
+
+cdef class ConditionFalse(BinaryCondition):
+    @staticmethod
+    cdef ConditionFalse c_from_header(dcg_node_edge_condition* header, bint owner=False):
+        cdef ConditionFalse instance = ConditionFalse.__new__(ConditionFalse)
+        instance.header = header
+        instance.owner = owner
+        return instance
+
+    def __bool__(self):
+        return False
+
+    def __int__(self):
+        return 0
+
+    property value:
+        def __get__(self):
+            return False
+
+
+cdef inline NodeEdgeCondition c_dcg_condition_reconstruct(dcg_node_edge_condition* edge):
+    if not edge:
+        return NO_CONDITION
+
+    cdef dcg_node_edge_type edge_type = edge.type
+
+    if edge_type == dcg_node_edge_type.DCG_NODE_EDGE_NONE:
+        return ConditionAny.c_from_header(edge, False)
+    if edge_type == dcg_node_edge_type.DCG_NODE_EDGE_ELSE:
+        return ConditionElse.c_from_header(edge, False)
+    if edge_type == dcg_node_edge_type.DCG_NODE_EDGE_AUTO:
+        return ConditionAuto.c_from_header(edge, False)
+    if edge_type == dcg_node_edge_type.DCG_NODE_EDGE_TRUE:
+        return ConditionTrue.c_from_header(edge, False)
+    if edge_type == dcg_node_edge_type.DCG_NODE_EDGE_FALSE:
+        return ConditionFalse.c_from_header(edge, False)
+    return NodeEdgeCondition.c_from_header(edge, False)
+
+
+cdef class EdgeConditionRegistry(BoundByteMap):
+    @staticmethod
+    cdef EdgeConditionRegistry c_from_header(bytemap* header, bint owner=False):
+        cdef EdgeConditionRegistry instance = EdgeConditionRegistry.__new__(EdgeConditionRegistry)
+        instance.owner = owner
+        instance.seq_id = c_bytemap_gen_seq_id(<void*> instance)
+        instance.c_bind(header)
+        return instance
+
+    cdef const char* c_serialize_key(self, object obj, size_t* key_len):
+        # A header address is provided in format of int (uintptr_t)
+        if isinstance(obj, int):
+            self._ws_key_buf = <void*> <uintptr_t> obj
+            if key_len:
+                key_len[0] = sizeof(void*)
+            return <const char*> &self._ws_key_buf
+        return BoundByteMap.c_serialize_key(self, obj, key_len)
+
+    cdef object c_deserialize_key(self, const char* key, size_t key_len):
+        return <uintptr_t> <void*> key
+
+    cdef const char* c_serialize_value(self, object obj, size_t* value_len):
+        cdef NodeEdgeCondition edge = <NodeEdgeCondition> obj
+        self._ws_ptr = <void*> edge.header
+        if value_len:
+            value_len[0] = sizeof(void*)
+        return <const char*> &self._ws_ptr
+
+    cdef object c_deserialize_value(self, const char* value, size_t value_len):
+        cdef void** vp = <void**> value
+        return c_dcg_condition_reconstruct(<dcg_node_edge_condition*> vp[0])
+
+    def __getitem__(self, object key):
+        cdef int ret_code = PyDict_Contains(<dict> self, key)
+        if ret_code == 0:
+            return c_dcg_condition_reconstruct(<dcg_node_edge_condition*> <uintptr_t> key)
+        return super().__getitem__(key)
+
+
+c_dcg_condition_init_globals()
+
+cdef dcg_node_edge_condition* C_NO_CONDITION    = &__DCG_NO_CONDITION
+cdef dcg_node_edge_condition* C_ELSE_CONDITION  = &__DCG_ELSE_CONDITION
+cdef dcg_node_edge_condition* C_AUTO_CONDITION  = &__DCG_AUTO_CONDITION
+cdef dcg_node_edge_condition* C_TRUE_CONDITION  = &__DCG_TRUE_CONDITION
+cdef dcg_node_edge_condition* C_FALSE_CONDITION = &__DCG_FALSE_CONDITION
+
+cdef ConditionAny NO_CONDITION                  = ConditionAny.c_from_header(C_NO_CONDITION, False)
+cdef ConditionElse ELSE_CONDITION               = ConditionElse.c_from_header(C_ELSE_CONDITION, False)
+cdef ConditionAuto AUTO_CONDITION               = ConditionAuto.c_from_header(C_AUTO_CONDITION, False)
+cdef ConditionTrue TRUE_CONDITION               = ConditionTrue.c_from_header(C_TRUE_CONDITION, False)
+cdef ConditionFalse FALSE_CONDITION             = ConditionFalse.c_from_header(C_FALSE_CONDITION, False)
+
+globals()['NO_CONDITION']                       = NO_CONDITION
+globals()['ELSE_CONDITION']                     = ELSE_CONDITION
+globals()['AUTO_CONDITION']                     = AUTO_CONDITION
+globals()['TRUE_CONDITION']                     = TRUE_CONDITION
+globals()['FALSE_CONDITION']                    = FALSE_CONDITION
+
+cdef EdgeConditionRegistry EDGE_REGISTRY        = EdgeConditionRegistry()
+EDGE_REGISTRY[<uintptr_t> C_NO_CONDITION]       = NO_CONDITION
+EDGE_REGISTRY[<uintptr_t> C_ELSE_CONDITION]     = ELSE_CONDITION
+EDGE_REGISTRY[<uintptr_t> C_AUTO_CONDITION]     = AUTO_CONDITION
+EDGE_REGISTRY[<uintptr_t> C_TRUE_CONDITION]     = TRUE_CONDITION
+EDGE_REGISTRY[<uintptr_t> C_FALSE_CONDITION]    = FALSE_CONDITION
+
+globals()['EDGE_REGISTRY']                      = EDGE_REGISTRY