PyDecisionGraph 0.3.2.post1__cp315-cp315-win_amd64.whl

decision_graph/decision_tree/bake/c_logic_group.pxd

@@ -0,0 +1,162 @@
+from libcpp cimport bool as c_bool
+
+from cbase.allocator_protocol cimport allocator_protocol
+from cbase.bytemap cimport BoundByteMap, bytemap
+
+from .c_hierarchy cimport dcg_breakpoint_node, dcg_root_node
+from .c_node cimport LogicNode, dcg_node
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_logic_group.h":
+    const size_t DCG_LGM_DEFAULT_CAPACITY
+
+    ctypedef enum dcg_logic_group_type:
+        DCG_LG_BASE
+        DCG_LG_MAPPING
+
+    ctypedef struct dcg_logic_group:
+        dcg_logic_group_type lgtype
+        const char* name
+        dcg_logic_group* parent
+
+    ctypedef struct dcg_lgm_state:
+        dcg_logic_group** groups
+        size_t n_groups
+        size_t groups_capacity
+        dcg_node** nodes
+        size_t n_nodes
+        size_t nodes_capacity
+        dcg_breakpoint_node** breakpoints
+        size_t n_breakpoints
+        size_t breakpoints_capacity
+        c_bool inspection_mode
+        c_bool vigilant_mode
+
+    ctypedef struct dcg_action_node:
+        pass
+
+    ctypedef enum dcg_node_type:
+        DCG_NODE_NOACTION
+
+    ctypedef struct dcg_logic_group_manager:
+        allocator_protocol* allocator
+        bytemap registry
+        dcg_logic_group** groups
+        size_t n_groups
+        size_t groups_capacity
+        dcg_node** nodes
+        size_t n_nodes
+        size_t nodes_capacity
+        dcg_breakpoint_node** breakpoints
+        size_t n_breakpoints
+        size_t breakpoints_capacity
+        dcg_lgm_state* shelved
+        size_t n_shelved
+        size_t shelved_capacity
+        c_bool inspection_mode
+        c_bool vigilant_mode
+
+    const char* c_dcg_logic_group_type_name(dcg_logic_group_type lgtype) noexcept nogil
+
+    void* c_dcg_lgm_reserve(void** block, size_t* capacity, size_t count, size_t element_size, allocator_protocol* allocator) noexcept nogil
+    int c_dcg_lgm_push_group(dcg_logic_group_manager* mgr, dcg_logic_group* group) noexcept nogil
+    int c_dcg_lgm_push_node(dcg_logic_group_manager* mgr, dcg_node* node) noexcept nogil
+    int c_dcg_lgm_push_breakpoint(dcg_logic_group_manager* mgr, dcg_breakpoint_node* breakpoint) noexcept nogil
+
+    int c_dcg_logic_group_init(dcg_logic_group* group, dcg_logic_group_type lgtype, const char* name) noexcept nogil
+    dcg_logic_group* c_dcg_logic_group_new(dcg_logic_group_type lgtype, const char* name, allocator_protocol* allocator) noexcept nogil
+    void c_dcg_logic_group_dealloc(dcg_logic_group* group) noexcept nogil
+    void c_dcg_logic_group_free(dcg_logic_group* group) noexcept nogil
+
+    dcg_logic_group_manager* c_dcg_lgm_new(allocator_protocol* allocator) noexcept nogil
+    int c_dcg_lgm_init(dcg_logic_group_manager* mgr, allocator_protocol* allocator) noexcept nogil
+    void c_dcg_lgm_dealloc(dcg_logic_group_manager* mgr) noexcept nogil
+    void c_dcg_lgm_free(dcg_logic_group_manager* mgr) noexcept nogil
+    void c_dcg_lgm_clear(dcg_logic_group_manager* mgr) noexcept nogil
+
+    int c_dcg_lgm_register(dcg_logic_group_manager* mgr, dcg_logic_group* group) noexcept nogil
+    dcg_logic_group* c_dcg_lgm_find(const dcg_logic_group_manager* mgr, const char* name, size_t name_len) noexcept nogil
+
+    int c_dcg_lgm_enter_group(dcg_logic_group_manager* mgr, dcg_logic_group* group) noexcept nogil
+    int c_dcg_lgm_exit_group(dcg_logic_group_manager* mgr, dcg_logic_group* group) noexcept nogil
+    int c_dcg_lgm_enter_node(dcg_logic_group_manager* mgr, dcg_node* node) noexcept nogil
+    int c_dcg_lgm_connect_awaiting(dcg_logic_group_manager* mgr, dcg_node* node) noexcept nogil
+    int c_dcg_lgm_exit_node(dcg_logic_group_manager* mgr, dcg_node* node) noexcept nogil
+    int c_dcg_lgm_label_node(dcg_logic_group_manager* mgr, dcg_node* node) noexcept nogil
+    int c_dcg_lgm_install_breakpoint(dcg_logic_group_manager* mgr, dcg_breakpoint_node* breakpoint) noexcept nogil
+    int c_dcg_lgm_break_inspection(dcg_logic_group_manager* mgr, dcg_logic_group* group) noexcept nogil
+
+    int c_dcg_node_root_ctx_shelve(dcg_root_node* root, dcg_logic_group_manager* mgr) noexcept nogil
+    int c_dcg_node_root_ctx_unshelve(dcg_root_node* root, dcg_logic_group_manager* mgr) noexcept nogil
+    int c_dcg_lgm_shelve(dcg_logic_group_manager* mgr) noexcept nogil
+    int c_dcg_lgm_unshelve(dcg_logic_group_manager* mgr) noexcept nogil
+
+    dcg_logic_group* c_dcg_lgm_active_group(const dcg_logic_group_manager* mgr) noexcept nogil
+    dcg_node* c_dcg_lgm_active_node(const dcg_logic_group_manager* mgr) noexcept nogil
+    size_t c_dcg_lgm_breakpoint_count(const dcg_logic_group_manager* mgr) noexcept nogil
+
+    int c_dcg_node_auto_connect(dcg_node* node, dcg_logic_group_manager* mgr) noexcept nogil
+    dcg_action_node* c_dcg_node_connect_new_action(dcg_node_type action_type, const char* repr, c_bool auto_connect, ssize_t sig, void* action_data, dcg_logic_group_manager* mgr, allocator_protocol* allocator) noexcept nogil
+    dcg_action_node* c_dcg_node_connect_new_action_trade(dcg_node_type action_type, c_bool auto_connect, dcg_logic_group_manager* mgr, allocator_protocol* allocator) noexcept nogil
+    dcg_action_node* c_dcg_node_connect_new_action_clear(c_bool auto_connect, dcg_logic_group_manager* mgr, allocator_protocol* allocator) noexcept nogil
+    dcg_node* c_dcg_node_connect_new_placeholder(c_bool auto_connect, dcg_logic_group_manager* mgr, allocator_protocol* allocator) noexcept nogil
+
+
+cdef class LogicGroupNameRegistry(BoundByteMap):
+    cdef void* _ws_key_buf
+
+    @staticmethod
+    cdef LogicGroupNameRegistry c_from_header(dcg_logic_group_manager* header, bint owner=?)
+
+
+cdef class LogicGroupManager:
+    cdef dcg_logic_group_manager* header
+    cdef bint owner
+
+    cdef list node_stack
+
+    cdef readonly LogicGroupNameRegistry registry
+
+    cdef void c_register(self, dcg_logic_group* group)
+
+    cdef dcg_logic_group* c_find(self, const char* name)
+
+    cdef void c_enter_group(self, dcg_logic_group* group)
+
+    cdef void c_exit_group(self, dcg_logic_group* group)
+
+    cdef int c_label_node(self, dcg_node* node)
+
+    cdef void c_break_inspection(self, dcg_logic_group* group)
+
+    cdef void c_shelve(self)
+
+    cdef void c_unshelve(self)
+
+    cpdef void node_stack_append(self, LogicNode node)
+
+    cpdef void node_stack_pop(self, LogicNode node)
+
+
+cdef LogicGroupManager LGM
+
+
+cdef class LogicGroup:
+    cdef dcg_logic_group* header
+    cdef bint owner
+
+    @staticmethod
+    cdef inline LogicGroup c_from_header(dcg_logic_group* header, bint owner=False)
+
+    cdef void c_free_header(self)
+
+    cdef void c_break(self, dcg_logic_group* scope)
+
+
+cdef class LogicGroupWrapperRegistry(BoundByteMap):
+    cdef void* _ws_key_buf
+
+    @staticmethod
+    cdef LogicGroupWrapperRegistry c_from_header(bytemap* header, bint owner=?)
+
+cdef LogicGroupWrapperRegistry GROUP_REGISTRY

decision_graph/decision_tree/bake/c_logic_group.pyi

@@ -0,0 +1,264 @@
+"""The logic group layer: the scopes a graph is built inside, and the manager.
+
+A logic group is a scope, not a node: it carries a name, a type and a parent, and
+a build entered into it is inside it. The manager is the build's state - which
+group is active, which node is active, what has been entered and not yet left -
+and it is what a `with` block talks to.
+
+Groups register themselves with the manager under their name, and by their
+address in the wrapper registry, so a group reached from C comes back as the
+instance the build made.
+"""
+
+from typing import Any, Self
+
+from cbase.bytemap import BoundByteMap
+
+from .c_node import LogicNode
+
+
+class LogicGroupNameRegistry(BoundByteMap):
+    """The manager's name index: a group's name to the group itself."""
+
+    def __getitem__(self, key: str) -> LogicGroup:
+        """The group registered under a name.
+
+        Args:
+            key: The group's name.
+
+        Returns:
+            The group wrapper registered under it.
+
+        Raises:
+            KeyError: When no group is registered under that name.
+        """
+        ...
+
+
+class LogicGroupManager:
+    """The state of a build: the stacks of groups, nodes and breakpoints.
+
+    It is the caller's struct, not an allocated block, and it keeps the
+    allocator it was initialised with. A node entered with the `with` statement
+    is placed by this manager - into the active node's reserved arm - and the
+    manager knows the group a node belongs to.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty manager: no groups, no nodes, no breakpoints."""
+        ...
+
+    def register(self, group: LogicGroup) -> None:
+        """Register a group under its name and its address.
+
+        Args:
+            group: Group to register - by name when it has one, always by
+                address.
+        """
+        ...
+
+    def find(self, name: str) -> LogicGroup | None:
+        """The group registered under a name.
+
+        Args:
+            name: The group's name.
+
+        Returns:
+            The group, or None when no group is registered under that name.
+        """
+        ...
+
+    def shelve(self) -> None:
+        """Put the current build away, to be taken back by ``unshelve``."""
+        ...
+
+    def unshelve(self) -> None:
+        """Take back a build that was shelved."""
+        ...
+
+    def clear(self) -> None:
+        """Empty the manager: every stack, shelved state included."""
+        ...
+
+    def label_node(self, node: LogicNode) -> None:
+        """Label a node with the names of the groups it was built inside.
+
+        Args:
+            node: Node to label.
+        """
+        ...
+
+    def node_stack_append(self, node: LogicNode) -> None:
+        """Push a node onto the manager's node stack.
+
+        Args:
+            node: Node being entered.
+        """
+        ...
+
+    def node_stack_pop(self, node: LogicNode) -> None:
+        """Pop a node off the manager's node stack.
+
+        Args:
+            node: Node being left.
+        """
+        ...
+
+    @property
+    def registry(self) -> LogicGroupNameRegistry:
+        """The manager's own name index."""
+        ...
+
+    @property
+    def inspection_mode(self) -> bool:
+        """Whether a build records the path an evaluation takes."""
+        ...
+
+    @inspection_mode.setter
+    def inspection_mode(self, value: bool) -> None:
+        """Set the inspection flag."""
+        ...
+
+    @property
+    def vigilant_mode(self) -> bool:
+        """Whether the layer reports a mistake where it is made."""
+        ...
+
+    @vigilant_mode.setter
+    def vigilant_mode(self, value: bool) -> None:
+        """Set the vigilant flag."""
+        ...
+
+    @property
+    def active_group(self) -> LogicGroup | None:
+        """The group a build is currently inside, or None outside any group."""
+        ...
+
+    @property
+    def active_node(self) -> LogicNode | None:
+        """The node a build is currently inside, or None outside any node."""
+        ...
+
+    @property
+    def address(self) -> int:
+        """The manager's own address, which is how the layer names it to C."""
+        ...
+
+    @property
+    def n_groups(self) -> int:
+        """How many groups are entered."""
+        ...
+
+    @property
+    def n_nodes(self) -> int:
+        """How many nodes are entered."""
+        ...
+
+    @property
+    def n_breakpoints(self) -> int:
+        """How many breakpoints are queued and waiting."""
+        ...
+
+
+class LogicGroup:
+    """A scope a graph is built inside.
+
+    A group carries a name, a type and a parent, and a build entered into it is
+    inside it - `with group:` enters, and leaving restores whatever was active
+    before.
+    """
+
+    def __init__(self, *, name: str | None = None, parent: LogicGroup | None = None, **kwargs: Any) -> None:
+        """Build a group of the base type.
+
+        Args:
+            name: The group's name.
+            parent: The group it is built inside, if any.
+
+        Raises:
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """The group's own text: its class and its name."""
+        ...
+
+    def __enter__(self) -> Self:
+        """Enter the group as the scope of the build inside it.
+
+        Returns:
+            This group.
+        """
+        ...
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> bool:
+        """Leave the group, restoring what was active before it.
+
+        Returns:
+            False, so an exception raised inside the block keeps travelling.
+        """
+        ...
+
+    def break_(self, scope: LogicGroup | None = None) -> None:
+        """Raise an inspection breakpoint inside this group.
+
+        Args:
+            scope: The group to break out of; this one when not given.
+        """
+        ...
+
+    @classmethod
+    def break_active(cls, scope: LogicGroup | None = None) -> None:
+        """Raise an inspection breakpoint in the build that is running.
+
+        Args:
+            scope: The group to break out of.
+        """
+        ...
+
+    @property
+    def name(self) -> str | None:
+        """The group's name, or None for a group that has none."""
+        ...
+
+    @property
+    def parent(self) -> LogicGroup | None:
+        """The group this one was built inside, or None."""
+        ...
+
+    @property
+    def lgtype(self) -> int:
+        """The group's C type, as the enumerator's value."""
+        ...
+
+    @property
+    def address(self) -> int:
+        """The group's C block, which is what the registry is keyed by."""
+        ...
+
+
+class LogicGroupWrapperRegistry(BoundByteMap):
+    """The wrapper every group is looked up by, keyed by its block's address.
+
+    The same rule the node registry keeps: a lookup that finds the address
+    answers with the wrapper the layer holds, and one that misses builds a new
+    wrapper over the block.
+    """
+
+    def __getitem__(self, key: int) -> LogicGroup:
+        """The wrapper at an address, rebuilding it when it is not held.
+
+        Args:
+            key: Address of the C group block.
+
+        Returns:
+            The group wrapper for that address.
+        """
+        ...
+
+
+# The manager every build runs through, and the registry every group is looked
+# up by.
+LGM: LogicGroupManager
+GROUP_REGISTRY: LogicGroupWrapperRegistry