PyDecisionGraph 0.3.2.post1__cp315-cp315t-win_amd64.whl

decision_graph/decision_tree/bake/c_collections.pxd

@@ -0,0 +1,52 @@
+from libcpp cimport bool as c_bool
+
+from cbase.allocator_protocol cimport allocator_protocol
+from cbase.bytemap cimport bytemap
+
+from .c_const cimport VariableNode, dcg_variable_node
+from .c_logic_group cimport LogicGroup, dcg_logic_group
+from .c_node cimport dcg_node
+from .c_var cimport dcg_var_t, dcg_var_type
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_collections.h":
+    const size_t DCG_MAPPING_DEFAULT_CAPACITY
+
+    ctypedef struct dcg_mapping_lgroup:
+        dcg_logic_group base
+        bytemap idx_mapping
+        dcg_var_t* slots
+        size_t n_slots
+        size_t capacity
+        c_bool frozen
+
+    dcg_mapping_lgroup* c_dcg_mapping_lgroup_new(const char* name, size_t capacity, allocator_protocol* allocator) noexcept nogil
+    void c_dcg_mapping_lgroup_dealloc(dcg_mapping_lgroup* lgroup) noexcept nogil
+    void c_dcg_mapping_lgroup_free(dcg_mapping_lgroup* lgroup) noexcept nogil
+    void c_dcg_mapping_lgroup_clear(dcg_mapping_lgroup* lgroup) noexcept nogil
+
+    int c_dcg_mapping_lgroup_set(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, dcg_var_t* value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_ref(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, dcg_var_t* value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_ptr(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, void* value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_double(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, double value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_int(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, ssize_t value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_offset(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, ssize_t value) noexcept nogil
+    int c_dcg_mapping_lgroup_set_bool(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, c_bool value) noexcept nogil
+
+    dcg_variable_node* c_dcg_mapping_lgroup_get_node(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, allocator_protocol* allocator) noexcept nogil
+
+    int c_dcg_node_mapping_var_node_eval_hook(dcg_node* header, void* user_data) noexcept nogil
+
+    dcg_var_t* c_dcg_mapping_lgroup_get_slot(const dcg_mapping_lgroup* lgroup, const char* key, size_t key_len) noexcept nogil
+    int c_dcg_mapping_lgroup_get_create_slot(dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, const dcg_var_type* var_type, dcg_var_t** out) noexcept nogil
+    int c_dcg_mapping_lgroup_get_var_idx(const dcg_mapping_lgroup* lgroup, const char* key, size_t key_len, size_t* out_index) noexcept nogil
+
+
+cdef class LogicMapping(LogicGroup):
+    cdef dcg_var_t* c_get_slot(self, const char* key, size_t key_len)
+
+    cdef dcg_var_t* c_get_create_slot(self, const char* key, size_t key_len, const dcg_var_type* var_type) except NULL
+
+
+cdef class AttrExpression(VariableNode):
+    pass

decision_graph/decision_tree/bake/c_collections.pyi

@@ -0,0 +1,193 @@
+"""The collection layer: the store a build reads its inputs from.
+
+A mapping is a logic group whose entries are keyed by name - the store a build
+runs inside. What is wrapped here is the store, and the read of one entry: the
+capi's ``LogicMapping`` and its ``AttrExpression``, with the read changed from a
+Python expression evaluated later into a node of the graph, which is what a bake
+graph needs.
+"""
+
+from typing import Any
+
+from .c_const import VariableNode
+from .c_logic_group import LogicGroup
+
+
+class LogicMapping(LogicGroup):
+    """A group that holds values, keyed by name.
+
+    Reading is how entries come to exist: ``mapping[name]`` is a read, not a
+    lookup - an entry the store does not hold yet is reserved, and the read
+    points at the empty slot, so a graph can be written against a store that is
+    filled in later. An entry's type is decided when a value lands in it, which
+    is why a read of one is answered by the store rather than by the read's own
+    binding.
+
+    A store's shape is its own to close: ``frozen`` refuses a new entry from then
+    on, and leaves what the store already holds - values, reads, writes - working.
+    """
+
+    def __init__(self, *, name: str | None = None, capacity: int = 0, parent: LogicGroup | None = None, **kwargs: Any) -> None:
+        """Build a store.
+
+        Args:
+            name: The store's name - part of every read's display text, and
+                refused when it is long enough to overflow that text.
+            capacity: Initial room for entries; the layer's default when 0.
+            parent: The group it is built inside, if any.
+
+        Raises:
+            ValueError: When the name is too long for the display buffer.
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def __getitem__(self, key: str) -> AttrExpression:
+        """The read of an entry, reserving the entry when it is new.
+
+        Args:
+            key: Entry name.
+
+        Returns:
+            The read - a node of the graph, not the value.
+
+        Raises:
+            KeyError: When the store is frozen and the key is new.
+        """
+        ...
+
+    def __getattr__(self, key: str) -> AttrExpression:
+        """The same read, written as an attribute.
+
+        Args:
+            key: Entry name.
+
+        Returns:
+            The read of that entry.
+        """
+        ...
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Put a value in an entry, reserving the entry when it is new.
+
+        Args:
+            key: Entry name.
+            value: Value to store: a bool, int, float, str, or a node's value.
+
+        Raises:
+            RuntimeError: When the C layer refuses the write.
+            KeyError: When the store is frozen and the key is new.
+        """
+        ...
+
+    def __contains__(self, key: str) -> bool:
+        """Whether an entry is held. Asking does not reserve one.
+
+        Args:
+            key: Entry name.
+        """
+        ...
+
+    def __len__(self) -> int:
+        """The entries held, reserved ones included."""
+        ...
+
+    def __bool__(self) -> bool:
+        """True when the store holds an entry, reserved ones included."""
+        ...
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        """Write several entries at once, as :meth:`dict.update` does.
+
+        Accepts one positional argument - a mapping, or an iterable of key/value
+        pairs - and any number of keyword arguments, and writes each pair the way
+        ``store[key] = value`` does: an entry the store does not hold is reserved
+        for it.
+
+        Args:
+            *args: At most one mapping or iterable of pairs.
+            **kwargs: Entries to write, by name.
+
+        Raises:
+            TypeError: When more than one positional argument is given.
+            RuntimeError: When the C layer refuses a write.
+            KeyError: When the store is frozen and a key is new.
+        """
+        ...
+
+    def clear(self) -> None:
+        """Empty the store, entry by entry.
+
+        Every entry is dropped - its value released and its name forgotten -
+        while the store itself stays where it was, so ``len`` is 0 afterwards and
+        a key the store held is a new entry again. Freezing is not exempt: it
+        seals a store's SHAPE against new entries, and this is a store's contents
+        leaving.
+
+        The entries are emptied in place rather than the block being moved, so a
+        read built over one keeps a valid address - it reports an unfilled entry,
+        not rubbish. What it no longer reports is the value that was there.
+        """
+        ...
+
+    @property
+    def frozen(self) -> bool:
+        """Whether the store is sealed against new entries.
+
+        What the store already holds is unaffected: freezing seals its SHAPE,
+        not its contents.
+        """
+        ...
+
+    @frozen.setter
+    def frozen(self, value: bool) -> None:
+        """Seal or unseal the store."""
+        ...
+
+
+class AttrExpression(VariableNode):
+    """The read of one entry in the store a build is inside.
+
+    A variable node that names the group it reads, which is the whole of the
+    difference between this and a bare variable: an entry is what it reads, and
+    the store is what answers.
+
+    A read begins holding WHERE its entry is - the entry's offset in the store,
+    which no growth of the store can invalidate - and is resolved to the entry
+    itself by its FIRST evaluation, which is where its type comes from. From then
+    on the read holds that entry, and the values it reports are the entry's live
+    ones for as long as they keep the type it was resolved to.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Build the read of an entry in the active store.
+
+        Args:
+            name: Entry name.
+
+        Raises:
+            RuntimeError: When no group is active.
+            TypeError: When the active group is not a store.
+            KeyError: When the store is sealed and the entry is new.
+        """
+        ...
+
+    @property
+    def value(self) -> Any:
+        """The entry's value, read from the store of the moment.
+
+        The value is read live either way: through the entry's offset while the
+        read has not been evaluated, and through the entry itself once it has.
+        None when the entry holds nothing yet.
+        """
+        ...
+
+    @property
+    def logic_group(self) -> LogicMapping:
+        """The store this read names - never None for a read.
+
+        The base declares the field untyped (the node layer cannot name a group
+        without an upward edge, DEPENDENCY.md 4.2); a read is only ever built
+        against a store, which is what makes this precise rather than optional.
+        """
+        ...

decision_graph/decision_tree/bake/c_collections.pyx

@@ -0,0 +1,161 @@
+from cpython.unicode cimport PyUnicode_AsUTF8, PyUnicode_AsUTF8AndSize, PyUnicode_FromStringAndSize
+
+from .c_allocator_protocol cimport DCG_DEFAULT_ALLOCATOR
+from .c_logic_group cimport LGM
+from .c_node cimport DCG_NODE_STRING_MAXLEN
+from .c_var cimport c_dcg_var_pypack, c_dcg_var_pyunpack, dcg_ret_code, dcg_var_type
+
+
+cdef class LogicMapping(LogicGroup):
+    def __init__(self, *, str name=None, size_t capacity=0, LogicGroup parent=None, **kwargs):
+        if name is not None and len(name) > DCG_NODE_STRING_MAXLEN // 4:
+            raise ValueError(
+                f'A mapping name is part of its reads\' display text: {len(name)} characters leaves no room '
+                f'for an entry name. Keep it under {DCG_NODE_STRING_MAXLEN // 4}.'
+            )
+
+        cdef dcg_mapping_lgroup* lgroup = c_dcg_mapping_lgroup_new(
+            PyUnicode_AsUTF8(name) if name is not None else NULL,
+            capacity,
+            DCG_DEFAULT_ALLOCATOR,
+        )
+        if not lgroup:
+            raise MemoryError(f'Failed to allocate {self.__class__.__name__}({name!r}).')
+
+        # The base group is the first member, so a mapping IS a group.
+        self.header = <dcg_logic_group*> lgroup
+        self.owner = True
+        if parent is not None:
+            self.header.parent = parent.header
+        LGM.register(self)
+
+    cdef void c_free_header(self):
+        c_dcg_mapping_lgroup_free(<dcg_mapping_lgroup*> self.header)
+
+    # === Cython Internal Binding ===
+
+    cdef dcg_var_t* c_get_slot(self, const char* key, size_t key_len):
+        return c_dcg_mapping_lgroup_get_slot(<dcg_mapping_lgroup*> self.header, key, key_len)
+
+    cdef dcg_var_t* c_get_create_slot(self, const char* key, size_t key_len, const dcg_var_type* var_type) except NULL:
+        cdef dcg_mapping_lgroup* lgroup = <dcg_mapping_lgroup*> self.header
+        cdef dcg_var_t*          slot   = NULL
+        cdef int                 ret_code = c_dcg_mapping_lgroup_get_create_slot(lgroup, key, key_len, var_type, &slot)
+
+        if ret_code != dcg_ret_code.DCG_OK:
+            if ret_code == dcg_ret_code.DCG_ERR_BUSY:
+                raise KeyError(f'<{self.__class__.__name__}> is frozen: no entry named {PyUnicode_FromStringAndSize(key, key_len)!r}.')
+            raise RuntimeError(f'c_dcg_mapping_lgroup_get_create_slot failed with err code: {ret_code}')
+        return slot
+
+    # === Python Interfaces ===
+
+    def __getitem__(self, str key):
+        return AttrExpression(key)
+
+    def __getattr__(self, str key):
+        return AttrExpression(key)
+
+    def __setitem__(self, str key, object value):
+        cdef Py_ssize_t  key_len  = 0
+        cdef const char* c_key    = PyUnicode_AsUTF8AndSize(key, &key_len)
+        cdef dcg_var_t   packed
+
+        c_dcg_var_pypack(&packed, value)
+
+        cdef int ret_code = c_dcg_mapping_lgroup_set(<dcg_mapping_lgroup*> self.header, c_key, key_len, &packed)
+        if ret_code != dcg_ret_code.DCG_OK:
+            raise RuntimeError(f'c_dcg_mapping_lgroup_set failed with err code: {ret_code}')
+
+    def __contains__(self, str key):
+        cdef Py_ssize_t  key_len = 0
+        cdef const char* c_key   = PyUnicode_AsUTF8AndSize(key, &key_len)
+        return c_dcg_mapping_lgroup_get_slot(<dcg_mapping_lgroup*> self.header, c_key, key_len) != NULL
+
+    def __len__(self):
+        return (<dcg_mapping_lgroup*> self.header).n_slots
+
+    def __bool__(self):
+        return bool((<dcg_mapping_lgroup*> self.header).n_slots)
+
+    def update(self, *args, **kwargs):
+        if len(args) > 1:
+            raise TypeError(f'update expected at most 1 argument, got {len(args)}')
+
+        if args:
+            other = args[0]
+            if hasattr(other, 'keys'):
+                for key in other.keys():
+                    self[key] = other[key]
+            else:
+                for key, value in other:
+                    self[key] = value
+
+        for key, value in kwargs.items():
+            self[key] = value
+
+    def clear(self):
+        c_dcg_mapping_lgroup_clear(<dcg_mapping_lgroup*> self.header)
+
+    property frozen:
+        def __get__(self):
+            if not self.header:
+                return False
+            return bool((<dcg_mapping_lgroup*> self.header).frozen)
+
+        def __set__(self, bint value):
+            (<dcg_mapping_lgroup*> self.header).frozen = value
+
+
+cdef class AttrExpression(VariableNode):
+    def __init__(self, str name):
+        cdef object       active  = LGM.active_group
+        cdef LogicMapping mapping
+        cdef Py_ssize_t   key_len = 0
+
+        if active is None:
+            raise RuntimeError(f'No logic group is active: a {self.__class__.__name__} reads the store a build runs inside.')
+        if not isinstance(active, LogicMapping):
+            raise TypeError(f'The active group is a {type(active).__name__}, not a LogicMapping: there is no store to read {name!r} from.')
+
+        mapping = <LogicMapping> active
+
+        cdef const char* key = PyUnicode_AsUTF8AndSize(name, &key_len)
+
+        # A read names its entry, so the entry is created when the name is new -
+        # reserved, since the read names no type of its own.
+        mapping.c_get_create_slot(key, key_len, NULL)
+
+        cdef dcg_variable_node* node = c_dcg_mapping_lgroup_get_node(<dcg_mapping_lgroup*> mapping.header, key, key_len, DCG_DEFAULT_ALLOCATOR)
+        if not node:
+            raise MemoryError(f'Failed to allocate the {self.__class__.__name__}.')
+
+        self.header = &node.base
+        # The group owns the reads built over its store - it is what allocates
+        # them - so this wrapper releases nothing, and it holds the group instead,
+        # which is what keeps the store alive for as long as the read is.
+        self.owner = False
+        self.logic_group = mapping
+        self.c_register_node()
+
+    # === Python Properties ===
+
+    property value:
+        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
+
+            cdef dcg_mapping_lgroup* lgroup = <dcg_mapping_lgroup*> (<LogicMapping> self.logic_group).header
+            cdef dcg_var_t* slot = &node.base.out
+
+            # The read knows WHERE its entry is: until it has been evaluated that
+            # is an offset in its own slot - no name lookup, and nothing that a
+            # growth of the store can invalidate - and from then on the slot IS
+            # the entry, read through.
+            if slot.dtype == dcg_var_type.VAR_TYPE_INFERRED or slot.dtype == dcg_var_type.VAR_TYPE_OFFSET:
+                return c_dcg_var_pyunpack(&lgroup.slots[slot.value.as_offset])
+            return c_dcg_var_pyunpack(slot)