pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/utils/iterators.py

@@ -0,0 +1,148 @@
+"""Iterator utilities for pkstruct linked lists."""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+def _get_list_types() -> tuple[type, type, type]:
+    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
+    return SinglyLinkedList, DoublyLinkedList, CircularLinkedList
+
+
+class ForwardIterator:
+    """Iterate over all node values in forward order.
+
+    Works with SinglyLinkedList, DoublyLinkedList, and CircularLinkedList.
+
+    Args:
+        list_instance: Any supported linked list instance.
+
+    Yields:
+        Node data values from head to tail.
+    """
+
+    def __init__(self, list_instance: Any) -> None:
+        self._list = list_instance
+
+    def __iter__(self) -> Iterator[Any]:
+        SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+        lst = self._list
+
+        if isinstance(lst, CircularLinkedList):
+            size = lst.size
+            current = lst.head
+            steps = 0
+            while current is not None and steps < size:
+                yield current.value
+                current = current.next
+                steps += 1
+        elif isinstance(lst, (SinglyLinkedList, DoublyLinkedList)):
+            current = lst.head
+            visited: set[int] = set()
+            while current is not None:
+                if id(current) in visited:
+                    break
+                visited.add(id(current))
+                yield current.value
+                current = current.next
+        else:
+            raise TypeError(
+                f"ForwardIterator does not support {type(lst).__name__}. "
+                "Use SinglyLinkedList, DoublyLinkedList, or CircularLinkedList."
+            )
+
+
+class BackwardIterator:
+    """Iterate over all node values in reverse order.
+
+    Only supported for DoublyLinkedList (which has .prev pointers).
+
+    Args:
+        list_instance: A DoublyLinkedList instance.
+
+    Yields:
+        Node data values from tail to head.
+
+    Raises:
+        TypeError: If *list_instance* is not a DoublyLinkedList.
+    """
+
+    def __init__(self, list_instance: Any) -> None:
+        self._list = list_instance
+
+    def __iter__(self) -> Iterator[Any]:
+        SinglyLinkedList, DoublyLinkedList, CircularLinkedList = _get_list_types()
+        lst = self._list
+
+        if isinstance(lst, DoublyLinkedList):
+            current = lst.tail
+            visited: set[int] = set()
+            while current is not None:
+                if id(current) in visited:
+                    break
+                visited.add(id(current))
+                yield current.value
+                current = current.prev
+        elif isinstance(lst, (SinglyLinkedList, CircularLinkedList)):
+            raise TypeError(
+                f"BackwardIterator is not supported for {type(lst).__name__}. "
+                "Only DoublyLinkedList supports backward iteration via .prev pointers."
+            )
+        else:
+            raise TypeError(
+                f"BackwardIterator does not support {type(lst).__name__}."
+            )
+
+
+class CircularIterator:
+    """Infinite (or bounded) circular iterator over a CircularLinkedList.
+
+    Args:
+        list_instance: A CircularLinkedList instance.
+        max_cycles: Maximum full cycles to iterate before stopping.
+            ``None`` means infinite (caller is responsible for breaking).
+
+    Yields:
+        Node data values, wrapping around indefinitely (or until *max_cycles*
+        full circuits have been completed).
+
+    Raises:
+        TypeError: If *list_instance* is not a CircularLinkedList.
+    """
+
+    def __init__(self, list_instance: Any, max_cycles: int | None = None, max_steps: int | None = None) -> None:
+        self._list = list_instance
+        self._max_cycles = max_cycles
+        self._max_steps = max_steps
+
+    def __iter__(self) -> Iterator[Any]:
+        _, _, CircularLinkedList = _get_list_types()
+        lst = self._list
+
+        if not isinstance(lst, CircularLinkedList):
+            raise TypeError(
+                f"CircularIterator requires a CircularLinkedList, got {type(lst).__name__}."
+            )
+
+        if lst.head is None or lst.size == 0:
+            return
+
+        size = lst.size
+        if self._max_steps is not None:
+            limit = self._max_steps
+        elif self._max_cycles is not None:
+            limit = self._max_cycles * size
+        else:
+            limit = None
+
+        current = lst.head
+        steps = 0
+        while limit is None or steps < limit:
+            yield current.value
+            current = current.next
+            steps += 1
+            if current is None:
+                break

pkstruct/linear/visualization/ascii_visualizer.py

@@ -0,0 +1,114 @@
+"""ASCII art visualization for linked list structures."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class AsciiVisualizer:
+    """Static methods for rendering linked lists as ASCII strings."""
+
+    @staticmethod
+    def singly(
+        head: Any,
+        node_repr: Callable[[Any], str] = str,
+    ) -> str:
+        """Render a singly linked list.
+
+        Args:
+            head: Head node (must have .value and .next attributes).
+            node_repr: Callable that converts a node's value to a string.
+
+        Returns:
+            String like ``"10 -> 20 -> 30 -> None"`` or ``"NULL (empty)"``
+            when the list is empty.
+        """
+        if head is None:
+            return "NULL (empty)"
+
+        parts: list[str] = []
+        current = head
+        visited: set[int] = set()
+
+        while current is not None:
+            node_id = id(current)
+            if node_id in visited:
+                parts.append("(cycle detected)")
+                break
+            visited.add(node_id)
+            parts.append(node_repr(current.value))
+            current = current.next
+
+        parts.append("None")
+        return " -> ".join(parts)
+
+    @staticmethod
+    def doubly(
+        head: Any,
+        tail: Any,
+        node_repr: Callable[[Any], str] = str,
+    ) -> str:
+        """Render a doubly linked list.
+
+        Args:
+            head: Head node (must have .value, .next, .prev attributes).
+            tail: Tail node.
+            node_repr: Callable that converts a node's value to a string.
+
+        Returns:
+            String like ``"None <- 10 <-> 20 <-> 30 -> None"`` or
+            ``"NULL <-> NULL"`` when the list is empty.
+        """
+        if head is None:
+            return "NULL <-> NULL"
+
+        parts: list[str] = []
+        current = head
+        visited: set[int] = set()
+
+        while current is not None:
+            node_id = id(current)
+            if node_id in visited:
+                parts.append("(cycle detected)")
+                break
+            visited.add(node_id)
+            parts.append(node_repr(current.value))
+            current = current.next
+
+        if not parts:
+            return "NULL <-> NULL"
+
+        inner = " <-> ".join(parts)
+        return f"None <- {inner} -> None"
+
+    @staticmethod
+    def circular(
+        head: Any,
+        size: int,
+        node_repr: Callable[[Any], str] = str,
+    ) -> str:
+        """Render a circular linked list.
+
+        Args:
+            head: Head node (must have .value and .next attributes).
+            size: Number of nodes (used as iteration guard).
+            node_repr: Callable that converts a node's value to a string.
+
+        Returns:
+            String like ``"10 -> 20 -> 30 -> (back to head)"`` or
+            ``"empty circular list"`` when the list is empty.
+        """
+        if head is None or size == 0:
+            return "empty circular list"
+
+        parts: list[str] = []
+        current = head
+        steps = 0
+
+        while steps < size:
+            parts.append(node_repr(current.value))
+            current = current.next
+            steps += 1
+
+        parts.append("(back to head)")
+        return " -> ".join(parts)

pkstruct/linear/visualization/linked_list_visualizer.py

@@ -0,0 +1,126 @@
+"""High-level visualizer that dispatches to AsciiVisualizer based on list type."""
+from __future__ import annotations
+
+from typing import Any
+
+from .ascii_visualizer import AsciiVisualizer
+
+
+class LinkedListVisualizer:
+    """Provides visualization and debug views for any pkstruct linked list."""
+
+    # Lazy imports to avoid circular dependencies at module load time.
+    @staticmethod
+    def _list_types() -> tuple[type, type, type]:
+        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
+        return SinglyLinkedList, DoublyLinkedList, CircularLinkedList
+
+    def visualize(self, list_instance: Any, style: str = "ascii") -> str:
+        """Return a string representation of *list_instance*.
+
+        Args:
+            list_instance: A SinglyLinkedList, DoublyLinkedList, or
+                CircularLinkedList instance.
+            style: Rendering style. Currently only ``"ascii"`` is supported.
+
+        Returns:
+            ASCII art string describing the list.
+
+        Raises:
+            TypeError: If *list_instance* is not a recognised list type.
+            ValueError: If *style* is not ``"ascii"``.
+        """
+        if style != "ascii":
+            raise ValueError(f"Unsupported visualisation style: {style!r}. Use 'ascii'.")
+
+        SinglyLinkedList, DoublyLinkedList, CircularLinkedList = self._list_types()
+
+        if isinstance(list_instance, CircularLinkedList):
+            return AsciiVisualizer.circular(
+                list_instance.head,
+                list_instance.size,
+            )
+        if isinstance(list_instance, DoublyLinkedList):
+            return AsciiVisualizer.doubly(
+                list_instance.head,
+                list_instance.tail,
+            )
+        if isinstance(list_instance, SinglyLinkedList):
+            return AsciiVisualizer.singly(list_instance.head)
+
+        raise TypeError(
+            f"Unsupported list type: {type(list_instance).__name__}. "
+            "Expected SinglyLinkedList, DoublyLinkedList, or CircularLinkedList."
+        )
+
+    def debug_view(self, list_instance: Any) -> dict[str, Any]:
+        """Return a diagnostic dictionary for *list_instance*.
+
+        The returned dict always contains:
+            - ``type``: class name string
+            - ``size``: integer node count
+            - ``head``: value of head node, or ``None``
+            - ``tail``: value of tail node, or ``None``
+            - ``values``: list of all values in forward order
+            - ``node_ids``: list of ``id()`` for each node
+
+        Args:
+            list_instance: Any supported linked list instance.
+
+        Returns:
+            Dictionary with debugging information.
+
+        Raises:
+            TypeError: If *list_instance* is not a recognised list type.
+        """
+        SinglyLinkedList, DoublyLinkedList, CircularLinkedList = self._list_types()
+
+        if not isinstance(list_instance, (SinglyLinkedList, DoublyLinkedList, CircularLinkedList)):
+            raise TypeError(
+                f"Unsupported list type: {type(list_instance).__name__}."
+            )
+
+        list_type = type(list_instance).__name__
+        size = list_instance.size
+
+        # Collect values and node ids safely
+        values: list[Any] = []
+        node_ids: list[int] = []
+
+        if isinstance(list_instance, CircularLinkedList):
+            current = list_instance.head
+            steps = 0
+            while current is not None and steps < size:
+                values.append(current.value)
+                node_ids.append(id(current))
+                current = current.next
+                steps += 1
+        else:
+            current = list_instance.head
+            visited: set[int] = set()
+            while current is not None:
+                if id(current) in visited:
+                    break
+                visited.add(id(current))
+                values.append(current.value)
+                node_ids.append(id(current))
+                current = current.next
+
+        head_value = list_instance.head.value if list_instance.head is not None else None
+
+        # Tail: DoublyLinkedList has .tail; others we derive
+        if isinstance(list_instance, (DoublyLinkedList, CircularLinkedList)):
+            tail_value = list_instance.tail.value if list_instance.tail is not None else None
+        else:
+            tail_value = values[-1] if values else None
+
+        return {
+            "type": list_type,
+            "size": size,
+            "head": head_value,
+            "tail": tail_value,
+            "values": values,
+            "node_ids": node_ids,
+        }

pkstruct/shared/__init__.py

@@ -0,0 +1,67 @@
+"""
+pkstruct.shared
+~~~~~~~~~~~~~~~
+Reusable infrastructure layer shared across all pkstruct modules.
+
+Sub-packages
+------------
+exceptions   — Base exception hierarchy
+validators   — Input validation helpers
+serializers  — Safe JSON serialization
+threading    — StructureLock (RLock wrapper)
+debugging    — DebugTracer for step-tracing
+benchmarking — timeit / compare helpers
+visualization— Visualizable protocol
+"""
+from pkstruct.shared.benchmarking import compare, timeit
+from pkstruct.shared.debugging import DebugTracer
+from pkstruct.shared.exceptions import (
+    ConcurrencyError,
+    EmptyStructureError,
+    IndexOutOfRangeError,
+    InvalidRangeError,
+    PkstructError,
+    SerializationError,
+    ValidationError,
+    ValueNotFoundError,
+)
+from pkstruct.shared.serializers import deserialize_from_json, serialize_to_json
+from pkstruct.shared.threading import StructureLock
+from pkstruct.shared.validators import (
+    validate_index,
+    validate_non_empty_list,
+    validate_non_negative_int,
+    validate_positive_int,
+    validate_range,
+)
+from pkstruct.shared.visualization import Visualizable
+
+__all__ = [
+    # exceptions
+    "PkstructError",
+    "ValidationError",
+    "IndexOutOfRangeError",
+    "ValueNotFoundError",
+    "EmptyStructureError",
+    "SerializationError",
+    "ConcurrencyError",
+    "InvalidRangeError",
+    # validators
+    "validate_index",
+    "validate_range",
+    "validate_non_empty_list",
+    "validate_positive_int",
+    "validate_non_negative_int",
+    # serializers
+    "serialize_to_json",
+    "deserialize_from_json",
+    # threading
+    "StructureLock",
+    # debugging
+    "DebugTracer",
+    # benchmarking
+    "timeit",
+    "compare",
+    # visualization
+    "Visualizable",
+]

pkstruct/shared/benchmarking/__init__.py

@@ -0,0 +1,78 @@
+"""
+pkstruct.shared.benchmarking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Micro-benchmarking utilities for pkstruct structures.
+"""
+from __future__ import annotations
+
+import statistics
+import time
+from collections.abc import Callable
+from typing import Any
+
+
+def timeit(
+    fn: Callable[..., Any],
+    *args: Any,
+    iterations: int = 1000,
+    **kwargs: Any,
+) -> dict[str, float]:
+    """Time *fn* over *iterations* calls and return statistics (in seconds).
+
+    Args:
+        fn:         The callable to benchmark.
+        *args:      Positional arguments forwarded to *fn*.
+        iterations: Number of repetitions.
+        **kwargs:   Keyword arguments forwarded to *fn*.
+
+    Returns:
+        A dict with keys ``min``, ``max``, ``mean``, ``median``, ``stdev``,
+        ``total``, and ``iterations``.
+    """
+    times: list[float] = []
+    for _ in range(iterations):
+        t0 = time.perf_counter()
+        fn(*args, **kwargs)
+        times.append(time.perf_counter() - t0)
+
+    return {
+        "min": min(times),
+        "max": max(times),
+        "mean": statistics.mean(times),
+        "median": statistics.median(times),
+        "stdev": statistics.pstdev(times),
+        "total": sum(times),
+        "iterations": iterations,
+    }
+
+
+def compare(
+    label_a: str,
+    fn_a: Callable[..., Any],
+    label_b: str,
+    fn_b: Callable[..., Any],
+    *,
+    iterations: int = 1000,
+) -> dict[str, Any]:
+    """Compare two callables head-to-head.
+
+    Args:
+        label_a: Name for the first callable.
+        fn_a:    First callable (no-arg).
+        label_b: Name for the second callable.
+        fn_b:    Second callable (no-arg).
+        iterations: Repetitions per callable.
+
+    Returns:
+        Dict with per-callable stats and a ``"winner"`` key.
+    """
+    stats_a = timeit(fn_a, iterations=iterations)
+    stats_b = timeit(fn_b, iterations=iterations)
+    winner = label_a if stats_a["median"] <= stats_b["median"] else label_b
+    return {
+        label_a: stats_a,
+        label_b: stats_b,
+        "winner": winner,
+        "speedup": max(stats_a["median"], stats_b["median"])
+        / max(min(stats_a["median"], stats_b["median"]), 1e-12),
+    }

pkstruct/shared/debugging/__init__.py

@@ -0,0 +1,69 @@
+"""
+pkstruct.shared.debugging
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Step-tracing and introspection helpers for pkstruct structures.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class DebugTracer:
+    """Lightweight operation tracer for debugging data structure mutations.
+
+    Keeps a bounded in-memory trace log (FIFO).  Disabled by default to avoid
+    any overhead in production paths.
+
+    Example::
+
+        tracer = DebugTracer(enabled=True, max_entries=50)
+        tracer.record("insert", position=0, value=42)
+        for entry in tracer.entries:
+            print(entry)
+    """
+
+    __slots__ = ("enabled", "max_entries", "_entries")
+
+    def __init__(self, *, enabled: bool = False, max_entries: int = 200) -> None:
+        self.enabled = enabled
+        self.max_entries = max_entries
+        self._entries: list[dict[str, Any]] = []
+
+    def record(self, operation: str, **kwargs: Any) -> None:
+        """Record a single operation event.
+
+        Args:
+            operation: Human-readable operation name (e.g. ``"insert"``).
+            **kwargs:  Arbitrary key-value context (e.g. ``position=2, value=99``).
+        """
+        if not self.enabled:
+            return
+        entry: dict[str, Any] = {
+            "op": operation,
+            "ts": time.monotonic(),
+            **kwargs,
+        }
+        self._entries.append(entry)
+        if len(self._entries) > self.max_entries:
+            self._entries.pop(0)
+
+    @property
+    def entries(self) -> list[dict[str, Any]]:
+        """Return a shallow copy of the trace log."""
+        return list(self._entries)
+
+    def clear(self) -> None:
+        """Clear the trace log."""
+        self._entries.clear()
+
+    def summary(self) -> dict[str, int]:
+        """Return a count of each operation type."""
+        counts: dict[str, int] = {}
+        for e in self._entries:
+            counts[e["op"]] = counts.get(e["op"], 0) + 1
+        return counts
+    
+    def get_events(self) -> list[dict[str, Any]]:
+        """Return all recorded events."""
+        return self._entries

pkstruct/shared/exceptions/__init__.py

@@ -0,0 +1,59 @@
+"""
+pkstruct.shared.exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Base exception hierarchy shared across all pkstruct modules.
+"""
+from __future__ import annotations
+
+
+class PkstructError(Exception):
+    """Root exception for all pkstruct errors."""
+
+
+class ValidationError(PkstructError):
+    """Raised when input validation fails."""
+
+
+class IndexOutOfRangeError(PkstructError, IndexError):
+    """Raised when a positional index is out of valid range."""
+
+    def __init__(self, index: int, size: int) -> None:
+        super().__init__(f"Index {index} is out of range for list of size {size}.")
+        self.index = index
+        self.size = size
+
+
+class ValueNotFoundError(PkstructError, ValueError):
+    """Raised when a value is not found in the structure."""
+
+    def __init__(self, value: object) -> None:
+        super().__init__(f"Value {value!r} not found in the structure.")
+        self.value = value
+
+
+class EmptyStructureError(PkstructError):
+    """Raised when an operation requires a non-empty structure."""
+
+    def __init__(self, operation: str = "operation") -> None:
+        super().__init__(f"Cannot perform '{operation}' on an empty structure.")
+        self.operation = operation
+
+
+class SerializationError(PkstructError):
+    """Raised when serialization or deserialization fails."""
+
+
+class ConcurrencyError(PkstructError):
+    """Raised on threading/locking issues."""
+
+
+class InvalidRangeError(PkstructError, ValueError):
+    """Raised when a range (start, end) is logically invalid."""
+
+    def __init__(self, start: int, end: int, size: int) -> None:
+        super().__init__(
+            f"Range ({start}, {end}) is invalid for structure of size {size}."
+        )
+        self.start = start
+        self.end = end
+        self.size = size