pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/queues/queue.py

@@ -0,0 +1,174 @@
+"""
+pkstruct.linear.queues.queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Abstract base class for all queue implementations.
+
+Provides a formal interface contract. Every concrete queue in ``pkstruct``
+derives from this class and implements all abstract methods.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Queue(ABC, Generic[T]):
+    """
+    Abstract base class for FIFO (first-in, first-out) queue structures.
+
+    Subclasses must implement all abstract methods.  The interface is
+    consistent across array-backed, linked-list-backed, and heap-backed
+    implementations.
+
+    Parameters
+    ----------
+    No parameters required at the abstract level.
+    """
+
+    __slots__ = ()
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def enqueue(self, value: T) -> None:
+        """
+        Add *value* to the rear of the queue.
+
+        Parameters
+        ----------
+        value:
+            The element to enqueue.
+        """
+        ...
+
+    @abstractmethod
+    def dequeue(self) -> T:
+        """
+        Remove and return the front element.
+
+        Returns
+        -------
+        T
+            The element at the front of the queue.
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        ...
+
+    @abstractmethod
+    def front(self) -> T:
+        """
+        Return the front element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        ...
+
+    @abstractmethod
+    def rear(self) -> T:
+        """
+        Return the rear element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def is_empty(self) -> bool:
+        """
+        Return ``True`` if the queue contains no elements.
+
+        Returns
+        -------
+        bool
+        """
+        ...
+
+    @abstractmethod
+    def size(self) -> int:
+        """
+        Return the number of elements in the queue.
+
+        Returns
+        -------
+        int
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all elements from the queue."""
+        ...
+
+    @abstractmethod
+    def copy(self) -> Queue[T]:
+        """
+        Return a shallow copy of this queue.
+
+        Returns
+        -------
+        Queue[T]
+        """
+        ...
+
+    @abstractmethod
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from front to rear.
+
+        Returns
+        -------
+        list[T]
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[T]:
+        ...
+
+    @abstractmethod
+    def __len__(self) -> int:
+        ...
+
+    @abstractmethod
+    def __bool__(self) -> bool:
+        ...
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        ...
+
+    @abstractmethod
+    def __eq__(self, other: object) -> bool:
+        ...

pkstruct/linear/stacks/__init__.py

@@ -0,0 +1,38 @@
+"""
+pkstruct.linear.stacks
+======================
+
+LIFO (last-in, first-out) stack data structures for the pkstruct ecosystem.
+
+Provides two concrete stack implementations and a shared abstract base.
+
+Classes
+-------
+Stack
+    Abstract base class defining the stack interface.
+LinkedStack
+    Stack backed by ``SinglyLinkedList`` (node-based, thread-safe).
+ArrayStack
+    Stack backed by a Python ``list`` (compact, cache-local).
+
+Example
+-------
+>>> from pkstruct.linear.stacks import LinkedStack
+>>> s = LinkedStack([1, 2, 3])
+>>> s.push(4)
+>>> s.pop()
+4
+>>> list(s)
+[3, 2, 1]
+"""
+
+from pkstruct.linear.stacks.array_stack import ArrayStack
+from pkstruct.linear.stacks.linked_stack import LinkedStack
+from pkstruct.linear.stacks.stack import Stack
+
+__all__ = [
+    # Stack classes
+    "ArrayStack",
+    "LinkedStack",
+    "Stack",
+]

pkstruct/linear/stacks/array_stack.py

@@ -0,0 +1,165 @@
+"""
+pkstruct.linear.stacks.array_stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A LIFO stack backed by a dynamic Python ``list``.
+
+``ArrayStack`` offers compact memory (no per-node overhead) and excellent
+cache locality.  All operations are O(1) amortised.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TypeVar
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.stacks.stack import Stack
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+
+class ArrayStack(Stack[T]):
+    """
+    A thread-safe stack backed by a Python ``list``.
+
+    The underlying list grows and shrinks dynamically.  Push and pop at the
+    end of the list are O(1) amortised.
+
+    Parameters
+    ----------
+    items:
+        Optional iterable of initial values (bottom-to-top order).
+        If omitted the stack starts empty.
+
+    Examples
+    --------
+    >>> s = ArrayStack([1, 2, 3])
+    >>> s.push(4)
+    >>> s.pop()
+    4
+    >>> s.peek()
+    3
+    """
+
+    __slots__ = ("_data", "_lock")
+
+    def __init__(self, items: list[T] | None = None) -> None:
+        self._data: list[T] = list(items) if items is not None else []
+        self._lock: StructureLock = StructureLock()
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def push(self, value: T) -> None:
+        """
+        Push *value* onto the top of the stack.
+
+        Parameters
+        ----------
+        value:
+            The element to push.
+        """
+        with self._lock:
+            self._data.append(value)
+
+    def pop(self) -> T:
+        """
+        Remove and return the top element.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        with self._lock:
+            if not self._data:
+                raise EmptyStructureError("pop from an empty stack")
+            return self._data.pop()
+
+    def peek(self) -> T:
+        """
+        Return the top element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        with self._lock:
+            if not self._data:
+                raise EmptyStructureError("peek at an empty stack")
+            return self._data[-1]
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        """Return ``True`` if the stack contains no elements."""
+        return len(self._data) == 0
+
+    def size(self) -> int:
+        """Return the number of elements in the stack."""
+        return len(self._data)
+
+    def clear(self) -> None:
+        """Remove all elements from the stack."""
+        with self._lock:
+            self._data.clear()
+
+    def copy(self) -> ArrayStack[T]:
+        """
+        Return a shallow copy of this stack.
+
+        Returns
+        -------
+        ArrayStack[T]
+        """
+        with self._lock:
+            new = ArrayStack[T]()
+            new._data = self._data.copy()
+            return new
+
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from top to bottom.
+
+        Returns
+        -------
+        list[T]
+        """
+        with self._lock:
+            return list(reversed(self._data))
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    def __iter__(self) -> Iterator[T]:
+        with self._lock:
+            snapshot = self.to_list()
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __bool__(self) -> bool:
+        return not self.is_empty()
+
+    def __repr__(self) -> str:
+        return f"ArrayStack({self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ArrayStack):
+            return NotImplemented
+        return self.to_list() == other.to_list()

pkstruct/linear/stacks/linked_stack.py

@@ -0,0 +1,168 @@
+"""
+pkstruct.linear.stacks.linked_stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A LIFO stack backed by a ``SinglyLinkedList``.
+
+``LinkedStack`` composes the existing production-grade linked list rather than
+reimplementing node management.  Push is O(1) amortised via head insertion;
+pop and peek are O(1).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TypeVar, cast
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+from pkstruct.linear.stacks.stack import Stack
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+
+class LinkedStack(Stack[T]):
+    """
+    A thread-safe stack implemented on top of ``SinglyLinkedList``.
+
+    The internal linked list stores elements with the top of the stack at
+    head position, so ``push``, ``pop``, and ``peek`` all operate at index 0.
+
+    Parameters
+    ----------
+    items:
+        Optional iterable of initial values (bottom-to-top order).
+        If omitted the stack starts empty.
+
+    Examples
+    --------
+    >>> s = LinkedStack([1, 2, 3])
+    >>> s.push(4)
+    >>> s.pop()
+    4
+    >>> s.peek()
+    3
+    """
+
+    __slots__ = ("_list", "_lock")
+
+    def __init__(self, items: list[T] | None = None) -> None:
+        self._list: SinglyLinkedList[T] = SinglyLinkedList()
+        self._lock: StructureLock = StructureLock()
+        if items is not None:
+            for item in items:
+                self._list.insert(item, position=0)
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def push(self, value: T) -> None:
+        """
+        Push *value* onto the top of the stack (head of the list).
+
+        Parameters
+        ----------
+        value:
+            The element to push.
+        """
+        with self._lock:
+            self._list.insert(value, position=0)
+
+    def pop(self) -> T:
+        """
+        Remove and return the top element.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("pop from an empty stack")
+            return cast(T, self._list.delete(position=0))
+
+    def peek(self) -> T:
+        """
+        Return the top element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("peek at an empty stack")
+            return self._list.get(0)
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        """Return ``True`` if the stack contains no elements."""
+        return self._list.is_empty()
+
+    def size(self) -> int:
+        """Return the number of elements in the stack."""
+        return self._list.size()
+
+    def clear(self) -> None:
+        """Remove all elements from the stack."""
+        self._list.clear()
+
+    def copy(self) -> LinkedStack[T]:
+        """
+        Return a shallow copy of this stack.
+
+        Returns
+        -------
+        LinkedStack[T]
+        """
+        with self._lock:
+            new = LinkedStack[T]()
+            new._list = cast(SinglyLinkedList[T], self._list.copy())
+            return new
+
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from top to bottom.
+
+        Returns
+        -------
+        list[T]
+        """
+        return self._list.to_list()
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    def __iter__(self) -> Iterator[T]:
+        with self._lock:
+            snapshot = self.to_list()
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __bool__(self) -> bool:
+        return not self.is_empty()
+
+    def __repr__(self) -> str:
+        return f"LinkedStack({self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, LinkedStack):
+            return NotImplemented
+        return self.to_list() == other.to_list()

pkstruct/linear/stacks/stack.py

@@ -0,0 +1,158 @@
+"""
+pkstruct.linear.stacks.stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Abstract base class for all stack implementations.
+
+Provides a formal interface contract. Every concrete stack in ``pkstruct``
+derives from this class and implements all abstract methods.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Stack(ABC, Generic[T]):
+    """
+    Abstract base class for LIFO (last-in, first-out) stack structures.
+
+    Subclasses must implement all abstract methods.  The interface is designed
+    to be consistent across both array-backed and linked-list-backed stacks.
+
+    Parameters
+    ----------
+    No parameters required at the abstract level.
+    """
+
+    __slots__ = ()
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def push(self, value: T) -> None:
+        """
+        Push *value* onto the top of the stack.
+
+        Parameters
+        ----------
+        value:
+            The element to push.
+        """
+        ...
+
+    @abstractmethod
+    def pop(self) -> T:
+        """
+        Remove and return the top element.
+
+        Returns
+        -------
+        T
+            The element at the top of the stack.
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        ...
+
+    @abstractmethod
+    def peek(self) -> T:
+        """
+        Return the top element without removing it.
+
+        Returns
+        -------
+        T
+            The element at the top of the stack.
+
+        Raises
+        ------
+        EmptyStructureError
+            If the stack is empty.
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def is_empty(self) -> bool:
+        """
+        Return ``True`` if the stack contains no elements.
+
+        Returns
+        -------
+        bool
+        """
+        ...
+
+    @abstractmethod
+    def size(self) -> int:
+        """
+        Return the number of elements in the stack.
+
+        Returns
+        -------
+        int
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all elements from the stack."""
+        ...
+
+    @abstractmethod
+    def copy(self) -> Stack[T]:
+        """
+        Return a shallow copy of this stack.
+
+        Returns
+        -------
+        Stack[T]
+        """
+        ...
+
+    @abstractmethod
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from top to bottom.
+
+        Returns
+        -------
+        list[T]
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[T]:
+        ...
+
+    @abstractmethod
+    def __len__(self) -> int:
+        ...
+
+    @abstractmethod
+    def __bool__(self) -> bool:
+        ...
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        ...
+
+    @abstractmethod
+    def __eq__(self, other: object) -> bool:
+        ...