pkstruct 0.1.0__py3-none-any.whl

pkstruct/__init__.py

@@ -0,0 +1,167 @@
+"""
+pkstruct - Production-grade modular data structures toolkit for Python.
+
+This package provides industrial-strength implementations of fundamental
+data structures with thread safety, serialization, visualization, and
+comprehensive algorithmic helpers.
+
+Modules
+-------
+graphs
+    Graph, DirectedGraph, WeightedGraph, traversal, shortest path, MST, SCC
+trees
+    BinarySearchTree, AVLTree, RedBlackTree, BTree, BPlusTree,
+    SegmentTree, FenwickTree, IntervalTree
+linear
+    SinglyLinkedList, DoublyLinkedList, CircularLinkedList
+shared
+    Infrastructure components (exceptions, validators, serializers, etc.)
+
+Example
+-------
+>>> from pkstruct import BinarySearchTree
+>>> bst = BinarySearchTree()
+>>> bst.insert(10)
+>>> bst.insert(5)
+>>> bst.insert(15)
+>>> list(bst)
+[5, 10, 15]
+"""
+
+from pkstruct.graphs import (
+    Graph,
+    DirectedGraph,
+    WeightedGraph,
+    bfs,
+    dfs,
+    dijkstra,
+    bellman_ford,
+    floyd_warshall,
+    kruskal,
+    prim,
+    connected_components,
+    is_bipartite,
+    has_cycle,
+    topological_sort_kahn,
+    topological_sort_dfs,
+    kosaraju,
+    tarjan,
+    visualize,
+    GraphError,
+    VertexNotFoundError,
+    EdgeNotFoundError,
+    InvalidGraphOperationError,
+    NegativeCycleError,
+    NoPathError,
+)
+from pkstruct.linear import (
+    ArrayStack,
+    CircularLinkedList,
+    CircularQueue,
+    ConcurrencyError,
+    DoublyLinkedList,
+    EmptyStructureError,
+    IndexOutOfRangeError,
+    InvalidRangeError,
+    LinkedDeque,
+    LinkedQueue,
+    LinkedStack,
+    PkstructError,
+    PriorityQueue,
+    QueueFullError,
+    SerializationError,
+    SinglyLinkedList,
+    ValidationError,
+    ValueNotFoundError,
+)
+from pkstruct.trees import (
+    AVLTree,
+    BinarySearchTree,
+    BPlusTree,
+    BTree,
+    DuplicateKeyError,
+    EmptyTreeError,
+    FenwickTree,
+    IndexOutOfBoundsError,
+    IntervalTree,
+    InvalidIntervalError,
+    InvalidOperationError,
+    InvalidOrderError,
+    KeyNotFoundError,
+    RedBlackTree,
+    SegmentTree,
+    TreeBalanceError,
+    TreeError,
+)
+from pkstruct.trees import (
+    SerializationError as TreeSerializationError,
+)
+
+__all__ = [
+    # Graphs
+    "Graph",
+    "DirectedGraph",
+    "WeightedGraph",
+    "bfs",
+    "dfs",
+    "dijkstra",
+    "bellman_ford",
+    "floyd_warshall",
+    "kruskal",
+    "prim",
+    "connected_components",
+    "is_bipartite",
+    "has_cycle",
+    "topological_sort_kahn",
+    "topological_sort_dfs",
+    "kosaraju",
+    "tarjan",
+    "visualize",
+    "GraphError",
+    "VertexNotFoundError",
+    "EdgeNotFoundError",
+    "InvalidGraphOperationError",
+    "NegativeCycleError",
+    "NoPathError",
+    # Linear
+    "SinglyLinkedList",
+    "DoublyLinkedList",
+    "CircularLinkedList",
+    "ArrayStack",
+    "LinkedStack",
+    "LinkedQueue",
+    "CircularQueue",
+    "PriorityQueue",
+    "LinkedDeque",
+    "QueueFullError",
+    "PkstructError",
+    "ValidationError",
+    "IndexOutOfRangeError",
+    "ValueNotFoundError",
+    "EmptyStructureError",
+    "SerializationError",
+    "ConcurrencyError",
+    "InvalidRangeError",
+    # Trees
+    "BinarySearchTree",
+    "AVLTree",
+    "RedBlackTree",
+    "BTree",
+    "BPlusTree",
+    "SegmentTree",
+    "FenwickTree",
+    "IntervalTree",
+    "TreeError",
+    "KeyNotFoundError",
+    "DuplicateKeyError",
+    "EmptyTreeError",
+    "InvalidOrderError",
+    "InvalidOperationError",
+    "TreeBalanceError",
+    "TreeSerializationError",
+    "InvalidIntervalError",
+    "IndexOutOfBoundsError",
+]
+
+__version__ = "0.1.0"
+__author__ = "pkstruct contributors"

pkstruct/graphs/__init__.py

@@ -0,0 +1,127 @@
+"""
+pkstruct.graphs
+===============
+
+Graph data structures module for the pkstruct ecosystem.
+
+Provides production-grade implementations of graph representations and
+classic graph algorithms with thread safety and ASCII visualization.
+
+Classes
+-------
+Graph
+    Adjacency-list based graph supporting directed/undirected and weighted modes.
+DirectedGraph
+    Directed graph with in-degree, out-degree, reverse, sources, and sinks.
+WeightedGraph
+    Convenience subclass for weighted undirected graphs.
+
+Algorithms
+----------
+Traversal:
+    bfs, dfs, bfs_paths, dfs_paths
+Shortest Path:
+    dijkstra, bellman_ford, floyd_warshall
+Minimum Spanning Tree:
+    kruskal, prim
+Connectivity:
+    connected_components, is_connected, is_bipartite, has_cycle, has_cycle_directed
+Topological Sort:
+    topological_sort_kahn, topological_sort_dfs
+Strongly Connected Components:
+    kosaraju, tarjan
+
+Exceptions
+----------
+GraphError, VertexNotFoundError, EdgeNotFoundError, InvalidGraphOperationError,
+NegativeCycleError, NoPathError
+
+Example
+-------
+>>> from pkstruct.graphs import Graph
+>>> g = Graph()
+>>> g.add_edge("A", "B")
+>>> g.add_edge("B", "C")
+>>> g.add_edge("A", "C")
+>>> list(g.get_neighbors("A"))
+['B', 'C']
+>>> len(g)
+3
+"""
+
+from pkstruct.graphs.connectivity import (
+    connected_components,
+    has_cycle,
+    has_cycle_directed,
+    is_bipartite,
+    is_connected,
+)
+from pkstruct.graphs.directed import DirectedGraph
+from pkstruct.graphs.exceptions import (
+    EdgeNotFoundError,
+    GraphError,
+    InvalidGraphOperationError,
+    NegativeCycleError,
+    NoPathError,
+    VertexNotFoundError,
+)
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.mst import kruskal, prim
+from pkstruct.graphs.scc import kosaraju, tarjan
+from pkstruct.graphs.shortest_path import (
+    bellman_ford,
+    dijkstra,
+    floyd_warshall,
+    reconstruct_path,
+    reconstruct_path_fw,
+)
+from pkstruct.graphs.topo_sort import topological_sort_dfs, topological_sort_kahn
+from pkstruct.graphs.traversal import bfs, bfs_paths, dfs, dfs_paths
+from pkstruct.graphs.visualization import adjacency_matrix, visualize
+from pkstruct.graphs.weighted import WeightedGraph
+
+__all__ = [
+    # Graph classes
+    "Graph",
+    "DirectedGraph",
+    "WeightedGraph",
+    # Traversal
+    "bfs",
+    "dfs",
+    "bfs_paths",
+    "dfs_paths",
+    # Shortest Path
+    "dijkstra",
+    "bellman_ford",
+    "floyd_warshall",
+    "reconstruct_path",
+    "reconstruct_path_fw",
+    # MST
+    "kruskal",
+    "prim",
+    # Connectivity
+    "connected_components",
+    "is_connected",
+    "is_bipartite",
+    "has_cycle",
+    "has_cycle_directed",
+    # Topological Sort
+    "topological_sort_kahn",
+    "topological_sort_dfs",
+    # SCC
+    "kosaraju",
+    "tarjan",
+    # Visualization
+    "visualize",
+    "adjacency_matrix",
+    # Exceptions
+    "GraphError",
+    "VertexNotFoundError",
+    "EdgeNotFoundError",
+    "InvalidGraphOperationError",
+    "NegativeCycleError",
+    "NoPathError",
+]
+
+__version__ = "0.1.0"
+__author__ = "pkstruct contributors"

pkstruct/graphs/connectivity.py

@@ -0,0 +1,157 @@
+"""
+pkstruct.graphs.connectivity
+============================
+Graph connectivity algorithms: connected components, bipartite check.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.exceptions import VertexNotFoundError
+
+
+def connected_components(graph: Graph) -> list[list[Any]]:
+    """Return all connected components of an undirected graph.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected graph.
+
+    Returns
+    -------
+    list[list[Any]]
+        List of components, each being a list of vertices.
+    """
+    visited: set[Any] = set()
+    components: list[list[Any]] = []
+
+    for v in graph:
+        if v not in visited:
+            component: list[Any] = []
+            queue: deque[Any] = deque([v])
+            visited.add(v)
+            while queue:
+                current = queue.popleft()
+                component.append(current)
+                for neighbor in graph.get_neighbors(current):
+                    if neighbor not in visited:
+                        visited.add(neighbor)
+                        queue.append(neighbor)
+            components.append(component)
+
+    return components
+
+
+def is_connected(graph: Graph) -> bool:
+    """Return *True* if the undirected graph is connected.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected graph.
+
+    Returns
+    -------
+    bool
+    """
+    if graph.is_empty():
+        return True
+    components = connected_components(graph)
+    return len(components) == 1
+
+
+def is_bipartite(graph: Graph) -> bool:
+    """Check if a graph is bipartite using BFS coloring.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected graph.
+
+    Returns
+    -------
+    bool
+        *True* if the graph is bipartite.
+    """
+    color: dict[Any, int] = {}
+
+    for start in graph:
+        if start not in color:
+            color[start] = 0
+            queue: deque[Any] = deque([start])
+            while queue:
+                v = queue.popleft()
+                for neighbor in graph.get_neighbors(v):
+                    if neighbor not in color:
+                        color[neighbor] = 1 - color[v]
+                        queue.append(neighbor)
+                    elif color[neighbor] == color[v]:
+                        return False
+    return True
+
+
+def has_cycle(graph: Graph) -> bool:
+    """Detect if an undirected graph contains a cycle.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected graph.
+
+    Returns
+    -------
+    bool
+    """
+    visited: set[Any] = set()
+
+    def _dfs(v: Any, parent: Any | None) -> bool:
+        visited.add(v)
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in visited:
+                if _dfs(neighbor, v):
+                    return True
+            elif neighbor != parent:
+                return True
+        return False
+
+    for v in graph:
+        if v not in visited:
+            if _dfs(v, None):
+                return True
+    return False
+
+
+def has_cycle_directed(graph: Graph) -> bool:
+    """Detect if a directed graph contains a cycle using DFS coloring.
+
+    Parameters
+    ----------
+    graph : Graph
+        A directed graph.
+
+    Returns
+    -------
+    bool
+    """
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[Any, int] = {v: WHITE for v in graph}
+
+    def _dfs(v: Any) -> bool:
+        color[v] = GRAY
+        for neighbor in graph.get_neighbors(v):
+            if color[neighbor] == GRAY:
+                return True
+            if color[neighbor] == WHITE and _dfs(neighbor):
+                return True
+        color[v] = BLACK
+        return False
+
+    for v in graph:
+        if color[v] == WHITE:
+            if _dfs(v):
+                return True
+    return False

pkstruct/graphs/directed.py

@@ -0,0 +1,95 @@
+"""
+pkstruct.graphs.directed
+========================
+Directed graph implementation with direction-specific operations.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from pkstruct.graphs.exceptions import VertexNotFoundError
+from pkstruct.graphs.graph import Graph
+
+
+class DirectedGraph(Graph):
+    """A directed graph (convenience subclass of ``Graph`` with ``directed=True``).
+
+    Provides additional methods specific to directed graphs such as
+    in-degree, out-degree, transpose, sources, and sinks.
+
+    Example
+    -------
+    >>> g = DirectedGraph()
+    >>> g.add_edge("A", "B")
+    >>> g.add_edge("B", "C")
+    >>> g.add_edge("A", "C")
+    >>> g.out_degree("A")
+    2
+    >>> g.in_degree("C")
+    2
+    """
+
+    def __init__(self) -> None:
+        super().__init__(directed=True)
+
+    def in_degree(self, v: Any) -> int:
+        """Return the number of incoming edges to *v*.
+
+        Raises
+        ------
+        VertexNotFoundError
+            If *v* is not in the graph.
+        """
+        with self._lock:
+            if v not in self._adj:
+                raise VertexNotFoundError(v)
+            count = 0
+            for u in self._adj:
+                if v in self._adj[u]:
+                    count += 1
+            return count
+
+    def out_degree(self, v: Any) -> int:
+        """Return the number of outgoing edges from *v*.
+
+        Raises
+        ------
+        VertexNotFoundError
+            If *v* is not in the graph.
+        """
+        return self.degree(v)
+
+    def sources(self) -> list[Any]:
+        """Return all vertices with in-degree 0."""
+        with self._lock:
+            return [v for v in self._adj if self.in_degree(v) == 0]
+
+    def sinks(self) -> list[Any]:
+        """Return all vertices with out-degree 0."""
+        with self._lock:
+            return [v for v in self._adj if self.out_degree(v) == 0]
+
+    def reverse(self) -> DirectedGraph:
+        """Return the transpose (reverse all edges).
+
+        Returns
+        -------
+        DirectedGraph
+            A new graph with every edge (u, v) replaced by (v, u).
+        """
+        with self._lock:
+            rev = DirectedGraph()
+            for u in self._adj:
+                rev.add_vertex(u)
+            for u in self._adj:
+                for v, w in self._adj[u].items():
+                    rev.add_edge(v, u, w)
+            return rev
+
+    def __repr__(self) -> str:
+        with self._lock:
+            vertices = list(self._adj.keys())
+            edges = self.get_edges()
+            return f"DirectedGraph(vertices={len(vertices)}, edges={len(edges)})"

pkstruct/graphs/exceptions.py

@@ -0,0 +1,63 @@
+"""
+pkstruct.graphs.exceptions
+==========================
+Custom exception hierarchy for the graphs module.
+
+All graph-specific exceptions inherit from :class:`GraphError` so callers
+can catch the entire family with a single ``except GraphError`` clause.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "GraphError",
+    "VertexNotFoundError",
+    "EdgeNotFoundError",
+    "InvalidGraphOperationError",
+    "NegativeCycleError",
+    "NoPathError",
+]
+
+
+class GraphError(Exception):
+    """Base exception for all graph-related errors."""
+
+
+class VertexNotFoundError(GraphError):
+    """Raised when a vertex does not exist in the graph."""
+
+    def __init__(self, vertex: object) -> None:
+        super().__init__(f"Vertex not found: {vertex!r}")
+        self.vertex = vertex
+
+
+class EdgeNotFoundError(GraphError):
+    """Raised when an edge does not exist in the graph."""
+
+    def __init__(self, u: object, v: object) -> None:
+        super().__init__(f"Edge not found: ({u!r}, {v!r})")
+        self.u = u
+        self.v = v
+
+
+class InvalidGraphOperationError(GraphError):
+    """Raised when an operation is invalid for the current graph state."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class NegativeCycleError(GraphError):
+    """Raised when a negative-weight cycle is detected."""
+
+    def __init__(self, message: str = "Graph contains a negative-weight cycle") -> None:
+        super().__init__(message)
+
+
+class NoPathError(GraphError):
+    """Raised when no path exists between two vertices."""
+
+    def __init__(self, source: object, target: object) -> None:
+        super().__init__(f"No path from {source!r} to {target!r}")
+        self.source = source
+        self.target = target