PyDecisionGraph 0.3.2.post1__cp315-cp315-win_amd64.whl

decision_graph/decision_tree/bake/c_reconstruct.pxd

@@ -0,0 +1,63 @@
+from libc.stdint cimport uintptr_t
+
+from .c_action cimport ActionNode, CancelAction, ClearAction, LongAction, NoAction, ShortAction
+from .c_collections cimport AttrExpression
+from .c_const cimport ConstantNode, VariableNode
+from .c_expr cimport BinaryExpression, ExpressionNode, TernaryExpression, UnaryExpression
+from .c_hierarchy cimport BreakpointNode, RootLogicNode
+from .c_node cimport LogicNode, NODE_REGISTRY, PlaceholderNode, dcg_node
+
+
+cdef inline void c_dcg_node_attach_header(LogicNode node, dcg_node* header, bint owner):
+    cdef uintptr_t parent_address = 0
+
+    node.header = header
+    node.owner = owner
+    node.parent = None
+    if header.parent:
+        parent_address = <uintptr_t> header.parent
+        if parent_address in NODE_REGISTRY:
+            node.parent = NODE_REGISTRY[parent_address]
+
+
+# === Variant Reconstruct ===
+
+cdef ConstantNode c_dcg_node_reconstruct_const(dcg_node* header, bint owner=?)
+
+cdef VariableNode c_dcg_node_reconstruct_variable(dcg_node* header, bint owner=?)
+
+cdef AttrExpression c_dcg_node_reconstruct_attr(dcg_node* header, bint owner=?)
+
+cdef ExpressionNode c_dcg_node_reconstruct_expr(dcg_node* header, bint owner=?)
+
+cdef UnaryExpression c_dcg_node_reconstruct_unary(dcg_node* header, bint owner=?)
+
+cdef BinaryExpression c_dcg_node_reconstruct_binary(dcg_node* header, bint owner=?)
+
+cdef TernaryExpression c_dcg_node_reconstruct_ternary(dcg_node* header, bint owner=?)
+
+cdef ActionNode c_dcg_node_reconstruct_action(dcg_node* header, bint owner=?)
+
+cdef NoAction c_dcg_node_reconstruct_noaction(dcg_node* header, bint owner=?)
+
+cdef LongAction c_dcg_node_reconstruct_longaction(dcg_node* header, bint owner=?)
+
+cdef ShortAction c_dcg_node_reconstruct_shortaction(dcg_node* header, bint owner=?)
+
+cdef CancelAction c_dcg_node_reconstruct_cancelaction(dcg_node* header, bint owner=?)
+
+cdef ClearAction c_dcg_node_reconstruct_clearaction(dcg_node* header, bint owner=?)
+
+cdef PlaceholderNode c_dcg_node_reconstruct_placeholder(dcg_node* header, bint owner=?)
+
+cdef RootLogicNode c_dcg_node_reconstruct_root(dcg_node* header, bint owner=?)
+
+cdef BreakpointNode c_dcg_node_reconstruct_breakpoint(dcg_node* header, bint owner=?)
+
+# === Dispatch ===
+
+cdef LogicNode c_dcg_node_reconstruct(dcg_node* header, bint owner=?)
+
+cpdef LogicNode c_dcg_node_reconstruct_from_address(uintptr_t address, bint owner=?)
+
+cpdef LogicNode c_dcg_node_root_from_address(uintptr_t address, bint owner=?)

decision_graph/decision_tree/bake/c_reconstruct.pyi

@@ -0,0 +1,60 @@
+"""The way back: a node in C to the wrappers that stand for the graph it is in.
+
+A graph is built from Python but lives in C, so a caller holding nothing but an
+address - a process reading a graph out of memory another process shared, a
+callback naming a node the C layer grew - needs the Python side back before
+anything can be inspected or rendered.
+
+A reconstruction restores the neighbourhood, not just the block: the node as the
+class its type names, its children and their subtrees with the edges they hang
+by, its parent and through it the whole graph up to the root, and what a family
+carries beyond the edges - an expression's operands, a read's store, a
+breakpoint's group.
+
+Every wrapper the walk builds is registered, which is what makes one block one
+Python object and what lets the walk terminate: a child asking for its parent
+lands on the wrapper that is already there.
+
+The variants themselves - one function per class, and the dispatch over them -
+are ``cdef``, and not module attributes: this stub is the module's Python face.
+"""
+
+from .c_node import LogicNode
+
+
+def c_dcg_node_reconstruct_from_address(address: int, owner: bool = False) -> LogicNode:
+    """The wrapper for the node at an address, with its graph restored.
+
+    Args:
+        address: Address of the C node block. Zero is refused.
+        owner: Whether the wrapper for THAT node may free its block; the
+            wrappers the walk adds around it own nothing.
+
+    Returns:
+        The wrapper for the node, with its graph restored around it.
+
+    Raises:
+        ValueError: When the address is zero.
+    """
+    ...
+
+
+def c_dcg_node_root_from_address(address: int, owner: bool = False) -> LogicNode:
+    """The graph's entry point above a node: its root, reconstructed.
+
+    A node reached in the middle of a graph is not the graph, and what a caller
+    with only an address usually wants is the top of it. The root is found in C,
+    by the parent chain, and reconstructed like any other node - which also means
+    everything between it and the address comes back on the way.
+
+    Args:
+        address: Address of a node in the graph.
+        owner: Whether the wrapper for the ROOT may free its block.
+
+    Returns:
+        The root of the graph the node is in.
+
+    Raises:
+        ValueError: When the address is zero.
+    """
+    ...

decision_graph/decision_tree/bake/c_reconstruct.pyx

@@ -0,0 +1,252 @@
+from libc.stdio cimport fflush, fprintf, stderr
+
+from .c_const cimport dcg_variable_node
+from .c_edge cimport EDGE_REGISTRY, NodeEdgeCondition
+from .c_expr cimport dcg_expression_node
+from .c_hierarchy cimport NodeEvalPathView, dcg_breakpoint_node, dcg_root_node
+from .c_logic_group cimport GROUP_REGISTRY, dcg_logic_group
+from .c_node cimport c_dcg_node_root, dcg_node_type
+from .c_var cimport c_dcg_var_pyunpack
+
+
+# ========== The Variants ==========
+
+cdef ConstantNode c_dcg_node_reconstruct_const(dcg_node* header, bint owner=False):
+    cdef ConstantNode node = ConstantNode.__new__(ConstantNode)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef VariableNode c_dcg_node_reconstruct_variable(dcg_node* header, bint owner=False):
+    cdef VariableNode node = VariableNode.__new__(VariableNode)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef AttrExpression c_dcg_node_reconstruct_attr(dcg_node* header, bint owner=False):
+    cdef AttrExpression   node  = AttrExpression.__new__(AttrExpression)
+    cdef dcg_logic_group* group = (<dcg_variable_node*> header).logic_group
+
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    if group:
+        node.logic_group = <object> GROUP_REGISTRY[<uintptr_t> group]
+    return node
+
+
+cdef void c_dcg_node_restore_operands(ExpressionNode node, dcg_expression_node* header):
+    cdef size_t     i
+    cdef dcg_node** operands = header.components
+    cdef object     value    = None
+
+    node.c_components_alloc(header.n_args)
+    for i in range(header.n_args):
+        if operands and operands[i]:
+            node.c_components_assign(i, c_dcg_node_reconstruct(operands[i], False))
+            continue
+
+        value = c_dcg_var_pyunpack(&header.args[i])
+        if value is not None:
+            node.c_components_assign(i, ConstantNode(value))
+
+
+cdef ExpressionNode c_dcg_node_reconstruct_expr(dcg_node* header, bint owner=False):
+    cdef ExpressionNode node = ExpressionNode.__new__(ExpressionNode)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    c_dcg_node_restore_operands(node, <dcg_expression_node*> header)
+    return node
+
+
+cdef UnaryExpression c_dcg_node_reconstruct_unary(dcg_node* header, bint owner=False):
+    cdef UnaryExpression node = UnaryExpression.__new__(UnaryExpression)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    c_dcg_node_restore_operands(node, <dcg_expression_node*> header)
+    return node
+
+
+cdef BinaryExpression c_dcg_node_reconstruct_binary(dcg_node* header, bint owner=False):
+    cdef BinaryExpression node = BinaryExpression.__new__(BinaryExpression)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    c_dcg_node_restore_operands(node, <dcg_expression_node*> header)
+    return node
+
+
+cdef TernaryExpression c_dcg_node_reconstruct_ternary(dcg_node* header, bint owner=False):
+    cdef TernaryExpression node = TernaryExpression.__new__(TernaryExpression)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    c_dcg_node_restore_operands(node, <dcg_expression_node*> header)
+    return node
+
+
+cdef ActionNode c_dcg_node_reconstruct_action(dcg_node* header, bint owner=False):
+    cdef ActionNode node = ActionNode.__new__(ActionNode)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef NoAction c_dcg_node_reconstruct_noaction(dcg_node* header, bint owner=False):
+    cdef NoAction node = NoAction.__new__(NoAction)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef LongAction c_dcg_node_reconstruct_longaction(dcg_node* header, bint owner=False):
+    cdef LongAction node = LongAction.__new__(LongAction)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef ShortAction c_dcg_node_reconstruct_shortaction(dcg_node* header, bint owner=False):
+    cdef ShortAction node = ShortAction.__new__(ShortAction)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef CancelAction c_dcg_node_reconstruct_cancelaction(dcg_node* header, bint owner=False):
+    cdef CancelAction node = CancelAction.__new__(CancelAction)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef ClearAction c_dcg_node_reconstruct_clearaction(dcg_node* header, bint owner=False):
+    cdef ClearAction node = ClearAction.__new__(ClearAction)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef PlaceholderNode c_dcg_node_reconstruct_placeholder(dcg_node* header, bint owner=False):
+    cdef PlaceholderNode node = PlaceholderNode.__new__(PlaceholderNode)
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    return node
+
+
+cdef RootLogicNode c_dcg_node_reconstruct_root(dcg_node* header, bint owner=False):
+    cdef RootLogicNode  node = RootLogicNode.__new__(RootLogicNode)
+    cdef dcg_root_node* root = <dcg_root_node*> header
+    c_dcg_node_attach_header(node, header, owner)
+    node.eval_path = NodeEvalPathView.c_from_header(&root.eval_path)
+    node.c_register_node()
+    return node
+
+
+cdef BreakpointNode c_dcg_node_reconstruct_breakpoint(dcg_node* header, bint owner=False):
+    cdef BreakpointNode   node  = BreakpointNode.__new__(BreakpointNode)
+    cdef dcg_logic_group* group = (<dcg_breakpoint_node*> header).break_from
+
+    c_dcg_node_attach_header(node, header, owner)
+    node.c_register_node()
+    if group:
+        node.break_from = <object> GROUP_REGISTRY[<uintptr_t> group]
+    return node
+
+
+# ========== The Walk ==========
+
+cdef void c_dcg_node_restore_edges(LogicNode node, dcg_node* header):
+    cdef dcg_node*         child = header.children
+    cdef LogicNode         child_node
+    cdef NodeEdgeCondition condition
+
+    while child:
+        condition  = <NodeEdgeCondition> EDGE_REGISTRY[<uintptr_t> child.condition_to_parent]
+        child_node = c_dcg_node_reconstruct(child, False)
+
+        node.children[condition]       = child_node
+        child_node.parent              = node
+        child_node.condition_to_parent = condition
+
+        child = child.next_sibling
+
+    if header.parent:
+        node.parent = c_dcg_node_reconstruct(header.parent, False)
+
+
+cdef LogicNode c_dcg_node_reconstruct(dcg_node* header, bint owner=False):
+    if not header:
+        raise ValueError('A NULL header is not a node: there is nothing to reconstruct.')
+
+    cdef uintptr_t address = <uintptr_t> header
+    if address in NODE_REGISTRY:
+        return NODE_REGISTRY[address]
+
+    cdef dcg_node_type ntype = header.ntype
+    cdef LogicNode     node
+
+    # The input family: the literals, then the read.
+    if ntype == dcg_node_type.DCG_NODE_INPUT or ntype == dcg_node_type.DCG_NODE_TRUE or ntype == dcg_node_type.DCG_NODE_FALSE or ntype == dcg_node_type.DCG_NODE_DOUBLE or ntype == dcg_node_type.DCG_NODE_STRING or ntype == dcg_node_type.DCG_NODE_INT:
+        node = c_dcg_node_reconstruct_const(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_VARIABLE:
+        # A read names the group it reads and a plain variable names none, so
+        # the node's own state is what tells the two classes apart - the type
+        # they share cannot.
+        node = c_dcg_node_reconstruct_attr(header, owner) if (<dcg_variable_node*> header).logic_group else c_dcg_node_reconstruct_variable(header, owner)
+    # The operator family, by arity.
+    elif ntype == dcg_node_type.DCG_NODE_OP:
+        node = c_dcg_node_reconstruct_expr(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_UNARY:
+        node = c_dcg_node_reconstruct_unary(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_BINARY:
+        node = c_dcg_node_reconstruct_binary(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_TERNARY:
+        node = c_dcg_node_reconstruct_ternary(header, owner)
+    # The action family, by kind.
+    elif ntype == dcg_node_type.DCG_NODE_ACTION:
+        node = c_dcg_node_reconstruct_action(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_NOACTION:
+        node = c_dcg_node_reconstruct_noaction(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_LONGACTION:
+        node = c_dcg_node_reconstruct_longaction(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_SHORTACTION:
+        node = c_dcg_node_reconstruct_shortaction(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_CANCELACTION:
+        node = c_dcg_node_reconstruct_cancelaction(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_CLEARACTION:
+        node = c_dcg_node_reconstruct_clearaction(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_PLACEHOLDER:
+        node = c_dcg_node_reconstruct_placeholder(header, owner)
+    # The special family.
+    elif ntype == dcg_node_type.DCG_NODE_ROOT:
+        node = c_dcg_node_reconstruct_root(header, owner)
+    elif ntype == dcg_node_type.DCG_NODE_BREAKPOINT:
+        node = c_dcg_node_reconstruct_breakpoint(header, owner)
+    else:
+        # Nothing claims the type, and the difference matters. Two cases reach
+        # here with a reason, and both are answered by the generic view: a family
+        # head with no variant of its own (DCG_NODE_SPECIAL), and a CALL, whose
+        # callee is composed into the node's display text and stored nowhere - a
+        # rebuilt call node would not know what it calls. A variant nothing
+        # claims is a type this module was never taught, and that is reported
+        # rather than silently wrapped as something it is not.
+        if ntype != dcg_node_type.DCG_NODE_SPECIAL and ntype != dcg_node_type.DCG_NODE_CALL:
+            fprintf(
+                stderr, "[DCG] c_dcg_node_reconstruct: node type 0x%x has no reconstruction variant - wrapping it as the base node\n", <unsigned int> ntype
+            )
+            fflush(stderr)
+        node = LogicNode.c_from_header(header, owner)
+        node.c_register_node()
+
+    c_dcg_node_restore_edges(node, header)
+    return node
+
+
+# ========== The Proxies ==========
+
+cpdef LogicNode c_dcg_node_reconstruct_from_address(uintptr_t address, bint owner=False):
+    return c_dcg_node_reconstruct(<dcg_node*> address, owner)
+
+
+cpdef LogicNode c_dcg_node_root_from_address(uintptr_t address, bint owner=False):
+    return c_dcg_node_reconstruct(c_dcg_node_root(<dcg_node*> address), owner)