pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/__init__.py

@@ -0,0 +1,95 @@
+"""
+pkstruct.linear
+===============
+
+Linear data structures module for the pkstruct ecosystem.
+
+Provides production-grade implementations of linked lists, stacks, queues,
+and deques with full thread safety, debug tracing, benchmarking, and
+ASCII visualization support.
+
+Classes
+-------
+SinglyLinkedList
+    A singly linked list with forward traversal.
+DoublyLinkedList
+    A doubly linked list with both forward and backward traversal.
+CircularLinkedList
+    A circular linked list maintaining the circular invariant.
+ArrayStack
+    LIFO stack backed by a dynamic array.
+LinkedStack
+    LIFO stack backed by ``SinglyLinkedList``.
+LinkedQueue
+    FIFO queue backed by ``SinglyLinkedList``.
+CircularQueue
+    Fixed-capacity FIFO queue backed by a ring buffer.
+PriorityQueue
+    Min-heap priority queue.
+LinkedDeque
+    Double-ended queue backed by ``DoublyLinkedList``.
+
+Exceptions
+----------
+PkstructError, ValidationError, IndexOutOfRangeError, ValueNotFoundError,
+EmptyStructureError, SerializationError, ConcurrencyError, InvalidRangeError,
+QueueFullError
+
+Example
+-------
+>>> from pkstruct.linear import SinglyLinkedList, LinkedStack
+>>> ll = SinglyLinkedList()
+>>> ll.insert(10)
+>>> s = LinkedStack([1, 2, 3])
+>>> s.pop()
+3
+"""
+
+from pkstruct.linear.deques.linked_deque import LinkedDeque
+from pkstruct.linear.exceptions import (
+    ConcurrencyError,
+    EmptyStructureError,
+    IndexOutOfRangeError,
+    InvalidRangeError,
+    PkstructError,
+    SerializationError,
+    ValidationError,
+    ValueNotFoundError,
+)
+from pkstruct.linear.linked_lists.circular_linked_list import CircularLinkedList
+from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+from pkstruct.linear.queues.circular_queue import CircularQueue, QueueFullError
+from pkstruct.linear.queues.linked_queue import LinkedQueue
+from pkstruct.linear.queues.priority_queue import PriorityQueue
+from pkstruct.linear.stacks.array_stack import ArrayStack
+from pkstruct.linear.stacks.linked_stack import LinkedStack
+
+__all__ = [
+    # Linked list classes
+    "SinglyLinkedList",
+    "DoublyLinkedList",
+    "CircularLinkedList",
+    # Stack classes
+    "ArrayStack",
+    "LinkedStack",
+    # Queue classes
+    "LinkedQueue",
+    "CircularQueue",
+    "PriorityQueue",
+    # Deque classes
+    "LinkedDeque",
+    # Exceptions
+    "PkstructError",
+    "ValidationError",
+    "IndexOutOfRangeError",
+    "ValueNotFoundError",
+    "EmptyStructureError",
+    "SerializationError",
+    "ConcurrencyError",
+    "InvalidRangeError",
+    "QueueFullError",
+]
+
+__version__ = "0.1.0"
+__author__ = "pkstruct contributors"

pkstruct/linear/deques/__init__.py

@@ -0,0 +1,33 @@
+"""
+pkstruct.linear.deques
+======================
+
+Double-ended queue (deque) data structures for the pkstruct ecosystem.
+
+Provides a concrete doubly-linked-list-backed deque and a shared abstract base.
+
+Classes
+-------
+Deque
+    Abstract base class defining the deque interface.
+LinkedDeque
+    Deque backed by ``DoublyLinkedList`` (O(1) at both ends, thread-safe).
+
+Example
+-------
+>>> from pkstruct.linear.deques import LinkedDeque
+>>> d = LinkedDeque([1, 2, 3])
+>>> d.append(0, side="left")
+>>> d.append(4, side="right")
+>>> list(d)
+[0, 1, 2, 3, 4]
+"""
+
+from pkstruct.linear.deques.deque import Deque
+from pkstruct.linear.deques.linked_deque import LinkedDeque
+
+__all__ = [
+    # Deque classes
+    "Deque",
+    "LinkedDeque",
+]

pkstruct/linear/deques/deque.py

@@ -0,0 +1,194 @@
+"""
+pkstruct.linear.deques.deque
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Abstract base class for all double-ended queue implementations.
+
+Provides a formal interface contract. Every concrete deque 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, Literal, TypeVar
+
+T = TypeVar("T")
+
+_Side = Literal["left", "right"]
+
+
+class Deque(ABC, Generic[T]):
+    """
+    Abstract base class for double-ended queue (deque) structures.
+
+    Subclasses must implement all abstract methods.  The interface supports
+    O(1) append and pop at both ends, plus rotation and reversal.
+
+    Parameters
+    ----------
+    No parameters required at the abstract level.
+    """
+
+    __slots__ = ()
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def append(self, value: T, side: _Side = "right") -> None:
+        """
+        Add *value* to one end of the deque.
+
+        Parameters
+        ----------
+        value:
+            The element to add.
+        side:
+            ``"left"`` to prepend (front), ``"right"`` to append (rear).
+        """
+        ...
+
+    @abstractmethod
+    def pop(self, side: _Side = "right") -> T:
+        """
+        Remove and return an element from one end.
+
+        Parameters
+        ----------
+        side:
+            ``"left"`` to remove from the front, ``"right"`` to remove from
+            the rear.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the deque is empty.
+        """
+        ...
+
+    @abstractmethod
+    def peek(self, side: _Side = "left") -> T:
+        """
+        Return an element from one end without removing it.
+
+        Parameters
+        ----------
+        side:
+            ``"left"`` to inspect the front, ``"right"`` to inspect the rear.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the deque is empty.
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Bulk operations                                                     #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def rotate(self, steps: int = 1) -> None:
+        """
+        Rotate the deque *steps* positions to the right.
+
+        Negative *steps* rotates to the left.
+
+        Parameters
+        ----------
+        steps:
+            Number of positions to rotate (default 1).
+        """
+        ...
+
+    @abstractmethod
+    def reverse(self) -> None:
+        """Reverse the order of all elements in the deque."""
+        ...
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def is_empty(self) -> bool:
+        """
+        Return ``True`` if the deque contains no elements.
+
+        Returns
+        -------
+        bool
+        """
+        ...
+
+    @abstractmethod
+    def size(self) -> int:
+        """
+        Return the number of elements in the deque.
+
+        Returns
+        -------
+        int
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all elements from the deque."""
+        ...
+
+    @abstractmethod
+    def copy(self) -> Deque[T]:
+        """
+        Return a shallow copy of this deque.
+
+        Returns
+        -------
+        Deque[T]
+        """
+        ...
+
+    @abstractmethod
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from left to right.
+
+        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/deques/linked_deque.py

@@ -0,0 +1,198 @@
+"""
+pkstruct.linear.deques.linked_deque
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A double-ended queue backed by a ``DoublyLinkedList``.
+
+``LinkedDeque`` composes the existing production-grade doubly-linked list,
+giving O(1) append and pop at both ends without any node-management code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Literal, TypeVar, cast
+
+from pkstruct.linear.deques.deque import Deque
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+_Side = Literal["left", "right"]
+
+
+class LinkedDeque(Deque[T]):
+    """
+    A thread-safe double-ended queue implemented on top of ``DoublyLinkedList``.
+
+    The internal list stores elements from left to right.  ``append(side="left")``
+    inserts at the head, ``append(side="right")`` appends at the tail — both O(1).
+
+    Parameters
+    ----------
+    items:
+        Optional iterable of initial values (left-to-right order).
+        If omitted the deque starts empty.
+
+    Examples
+    --------
+    >>> d = LinkedDeque([1, 2, 3])
+    >>> d.append(0, side="left")
+    >>> d.append(4, side="right")
+    >>> d.pop(side="left")
+    0
+    >>> d.pop(side="right")
+    4
+    >>> list(d)
+    [1, 2, 3]
+    """
+
+    __slots__ = ("_list", "_lock")
+
+    def __init__(self, items: list[T] | None = None) -> None:
+        self._list: DoublyLinkedList[T] = DoublyLinkedList()
+        self._lock: StructureLock = StructureLock()
+        if items is not None:
+            for item in items:
+                self._list.insert(item)
+
+    # ------------------------------------------------------------------ #
+    #  Core operations                                                     #
+    # ------------------------------------------------------------------ #
+
+    def append(self, value: T, side: _Side = "right") -> None:
+        """
+        Add *value* to one end of the deque.
+
+        Parameters
+        ----------
+        value:
+            The element to add.
+        side:
+            ``"left"`` to prepend, ``"right"`` to append (default).
+        """
+        with self._lock:
+            if side == "left":
+                self._list.insert(value, position=0)
+            else:
+                self._list.insert(value)
+
+    def pop(self, side: _Side = "right") -> T:
+        """
+        Remove and return an element from one end.
+
+        Parameters
+        ----------
+        side:
+            ``"left"`` to remove from the front, ``"right"`` to remove from
+            the rear (default).
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the deque is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("pop from an empty deque")
+            if side == "left":
+                return cast(T, self._list.delete(position=0))
+            sz = self._list.size()
+            return cast(T, self._list.delete(position=sz - 1))
+
+    def peek(self, side: _Side = "left") -> T:
+        """
+        Return an element from one end without removing it.
+
+        Parameters
+        ----------
+        side:
+            ``"left"`` to inspect the front (default), ``"right"`` to inspect
+            the rear.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the deque is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("peek at an empty deque")
+            if side == "left":
+                return self._list.get(0)
+            sz = self._list.size()
+            return self._list.get(sz - 1)
+
+    # ------------------------------------------------------------------ #
+    #  Bulk operations                                                     #
+    # ------------------------------------------------------------------ #
+
+    def rotate(self, steps: int = 1) -> None:
+        with self._lock:
+            sz = self._list.size()
+            if sz <= 1:
+                return
+            steps = steps % sz
+            if steps == 0:
+                return
+            for _ in range(steps):
+                val: T = cast(T, self._list.delete(position=sz - 1))
+                self._list.insert(val, position=0)
+
+    def reverse(self) -> None:
+        with self._lock:
+            self._list.reverse()
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        return self._list.is_empty()
+
+    def size(self) -> int:
+        return self._list.size()
+
+    def clear(self) -> None:
+        self._list.clear()
+
+    def copy(self) -> LinkedDeque[T]:
+        with self._lock:
+            new = LinkedDeque[T]()
+            new._list = cast(DoublyLinkedList[T], self._list.copy())
+            return new
+
+    def to_list(self) -> 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"LinkedDeque({self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, LinkedDeque):
+            return NotImplemented
+        return self.to_list() == other.to_list()

pkstruct/linear/exceptions.py

@@ -0,0 +1,26 @@
+"""
+pkstruct.linear.exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Re-exports the shared exception hierarchy with linear-specific aliases.
+"""
+from pkstruct.shared.exceptions import (
+    ConcurrencyError,
+    EmptyStructureError,
+    IndexOutOfRangeError,
+    InvalidRangeError,
+    PkstructError,
+    SerializationError,
+    ValidationError,
+    ValueNotFoundError,
+)
+
+__all__ = [
+    "PkstructError",
+    "ValidationError",
+    "IndexOutOfRangeError",
+    "ValueNotFoundError",
+    "EmptyStructureError",
+    "SerializationError",
+    "ConcurrencyError",
+    "InvalidRangeError",
+]

pkstruct/linear/linked_lists/__init__.py

@@ -0,0 +1,5 @@
+from pkstruct.linear.linked_lists.circular_linked_list import CircularLinkedList
+from pkstruct.linear.linked_lists.doubly_linked_list import DoublyLinkedList
+from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+
+__all__ = ["SinglyLinkedList", "DoublyLinkedList", "CircularLinkedList"]