pythonstl 0.1.4__cp311-cp311-win_amd64.whl

pythonstl/__init__.py

@@ -0,0 +1,64 @@
+"""
+PythonSTL - Python Standard Template Library
+
+A Python package that replicates C++ STL-style data structures
+using the Facade Design Pattern.
+
+This package provides clean, STL-compliant interfaces for common
+data structures while hiding implementation details from users.
+"""
+
+__version__ = "0.1.4"
+__author__ = "PySTL Contributors"
+
+from pythonstl.facade.stack import stack
+from pythonstl.facade.queue import queue
+from pythonstl.facade.vector import vector
+from pythonstl.facade.set import stl_set
+from pythonstl.facade.map import stl_map
+from pythonstl.facade.priority_queue import priority_queue
+from pythonstl.facade.algorithms import (
+    next_permutation,
+    prev_permutation,
+    nth_element,
+    partition,
+    lower_bound,
+    upper_bound,
+    binary_search,
+    equal_range
+)
+
+# Also export exceptions for user error handling
+from pythonstl.core.exceptions import (
+    PySTLException,
+    EmptyContainerError,
+    OutOfRangeError,
+    KeyNotFoundError
+)
+
+__all__ = [
+    # Data structures
+    'stack',
+    'queue',
+    'vector',
+    'stl_set',
+    'stl_map',
+    'priority_queue',
+    # Algorithms
+    'next_permutation',
+    'prev_permutation',
+    'nth_element',
+    'partition',
+    'lower_bound',
+    'upper_bound',
+    'binary_search',
+    'equal_range',
+    # Exceptions
+    'PySTLException',
+    'EmptyContainerError',
+    'OutOfRangeError',
+    'KeyNotFoundError',
+    # Metadata
+    '__version__',
+    '__author__'
+]

pythonstl/core/__init__.py

@@ -0,0 +1,32 @@
+"""Core module for pystl package."""
+
+from .base import ContainerBase, T, K, V
+from .exceptions import (
+    PySTLException,
+    EmptyContainerError,
+    OutOfRangeError,
+    KeyNotFoundError
+)
+from .iterator import (
+    Iterator,
+    VectorIterator,
+    VectorReverseIterator,
+    SetIterator,
+    MapIterator
+)
+
+__all__ = [
+    'ContainerBase',
+    'T',
+    'K',
+    'V',
+    'PySTLException',
+    'EmptyContainerError',
+    'OutOfRangeError',
+    'KeyNotFoundError',
+    'Iterator',
+    'VectorIterator',
+    'VectorReverseIterator',
+    'SetIterator',
+    'MapIterator'
+]

pythonstl/core/base.py

@@ -0,0 +1,51 @@
+"""
+Base classes and type definitions for pystl data structures.
+
+This module provides abstract base classes and common interfaces
+for all STL-style data structures in the package.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic
+
+# Type variable for generic container elements
+T = TypeVar('T')
+K = TypeVar('K')  # For map keys
+V = TypeVar('V')  # For map values
+
+
+class ContainerBase(ABC, Generic[T]):
+    """
+    Abstract base class for all STL-style containers.
+
+    Provides common interface methods that all containers must implement.
+    """
+
+    @abstractmethod
+    def empty(self) -> bool:
+        """
+        Check if the container is empty.
+
+        Returns:
+            bool: True if container is empty, False otherwise.
+
+        Time Complexity:
+            O(1)
+        """
+        pass
+
+    @abstractmethod
+    def size(self) -> int:
+        """
+        Get the number of elements in the container.
+
+        Returns:
+            int: Number of elements in the container.
+
+        Time Complexity:
+            O(1)
+        """
+        pass
+
+
+__all__ = ['ContainerBase', 'T', 'K', 'V']

pythonstl/core/exceptions.py

@@ -0,0 +1,57 @@
+"""
+Custom exceptions for pystl data structures.
+
+This module defines all custom exceptions used throughout the package
+to provide clear error messages matching C++ STL behavior.
+"""
+
+
+class PySTLException(Exception):
+    """Base exception class for all pystl exceptions."""
+    pass
+
+
+class EmptyContainerError(PySTLException):
+    """
+    Exception raised when attempting to access elements from an empty container.
+
+    This matches the behavior of C++ STL when accessing empty containers
+    (e.g., calling top() on an empty stack).
+    """
+
+    def __init__(self, container_type: str):
+        self.container_type = container_type
+        super().__init__(f"Cannot access element from empty {container_type}")
+
+
+class OutOfRangeError(PySTLException):
+    """
+    Exception raised when accessing an invalid index or position.
+
+    This matches C++ STL's std::out_of_range exception.
+    """
+
+    def __init__(self, index: int, size: int):
+        self.index = index
+        self.size = size
+        super().__init__(f"Index {index} is out of range for container of size {size}")
+
+
+class KeyNotFoundError(PySTLException):
+    """
+    Exception raised when a key is not found in an associative container.
+
+    This matches C++ STL behavior when accessing non-existent keys in maps.
+    """
+
+    def __init__(self, key):
+        self.key = key
+        super().__init__(f"Key '{key}' not found in container")
+
+
+__all__ = [
+    'PySTLException',
+    'EmptyContainerError',
+    'OutOfRangeError',
+    'KeyNotFoundError'
+]

pythonstl/core/iterator.py

@@ -0,0 +1,187 @@
+"""
+Iterator classes for pystl containers.
+
+This module provides iterator support for STL-style containers,
+enabling both C++ STL-style iteration and Python iteration protocols.
+"""
+
+from typing import TypeVar, Generic, List
+from abc import ABC, abstractmethod
+
+T = TypeVar('T')
+
+
+class Iterator(ABC, Generic[T]):
+    """
+    Abstract base class for iterators.
+
+    Provides the foundation for both forward and reverse iterators.
+    """
+
+    @abstractmethod
+    def __next__(self) -> T:
+        """Get the next element."""
+        pass
+
+    @abstractmethod
+    def __iter__(self):
+        """Return the iterator itself."""
+        pass
+
+
+class VectorIterator(Iterator[T]):
+    """
+    Forward iterator for vector.
+
+    This iterator traverses the vector from beginning to end.
+    """
+
+    def __init__(self, data: List[T], index: int = 0) -> None:
+        """
+        Initialize vector iterator.
+
+        Args:
+            data: Reference to the vector's internal data
+            index: Starting position
+        """
+        self._data = data
+        self._index = index
+
+    def __next__(self) -> T:
+        """
+        Get the next element.
+
+        Returns:
+            The next element in the vector.
+
+        Raises:
+            StopIteration: When iteration is complete.
+        """
+        if self._index >= len(self._data):
+            raise StopIteration
+        value = self._data[self._index]
+        self._index += 1
+        return value
+
+    def __iter__(self):
+        """Return the iterator itself."""
+        return self
+
+
+class VectorReverseIterator(Iterator[T]):
+    """
+    Reverse iterator for vector.
+
+    This iterator traverses the vector from end to beginning.
+    """
+
+    def __init__(self, data: List[T], index: int = -1) -> None:
+        """
+        Initialize reverse vector iterator.
+
+        Args:
+            data: Reference to the vector's internal data
+            index: Starting position (default: last element)
+        """
+        self._data = data
+        if index == -1:
+            self._index = len(data) - 1
+        else:
+            self._index = index
+
+    def __next__(self) -> T:
+        """
+        Get the next element (in reverse order).
+
+        Returns:
+            The next element in reverse order.
+
+        Raises:
+            StopIteration: When iteration is complete.
+        """
+        if self._index < 0:
+            raise StopIteration
+        value = self._data[self._index]
+        self._index -= 1
+        return value
+
+    def __iter__(self):
+        """Return the iterator itself."""
+        return self
+
+
+class SetIterator(Iterator[T]):
+    """
+    Iterator for set.
+
+    This iterator traverses the set elements.
+    Note: Order is not guaranteed (matches Python set behavior).
+    """
+
+    def __init__(self, data: set) -> None:
+        """
+        Initialize set iterator.
+
+        Args:
+            data: Reference to the set's internal data
+        """
+        self._iterator = iter(data)
+
+    def __next__(self) -> T:
+        """
+        Get the next element.
+
+        Returns:
+            The next element in the set.
+
+        Raises:
+            StopIteration: When iteration is complete.
+        """
+        return next(self._iterator)
+
+    def __iter__(self):
+        """Return the iterator itself."""
+        return self
+
+
+class MapIterator(Iterator):
+    """
+    Iterator for map.
+
+    This iterator traverses the map's key-value pairs.
+    Returns tuples of (key, value).
+    """
+
+    def __init__(self, data: dict) -> None:
+        """
+        Initialize map iterator.
+
+        Args:
+            data: Reference to the map's internal data
+        """
+        self._iterator = iter(data.items())
+
+    def __next__(self):
+        """
+        Get the next key-value pair.
+
+        Returns:
+            Tuple of (key, value).
+
+        Raises:
+            StopIteration: When iteration is complete.
+        """
+        return next(self._iterator)
+
+    def __iter__(self):
+        """Return the iterator itself."""
+        return self
+
+
+__all__ = [
+    'Iterator',
+    'VectorIterator',
+    'VectorReverseIterator',
+    'SetIterator',
+    'MapIterator'
+]

pythonstl/facade/__init__.py

@@ -0,0 +1,10 @@
+"""Facade layer for pystl data structures."""
+
+from .stack import stack
+from .queue import queue
+from .vector import vector
+from .set import stl_set
+from .map import stl_map
+from .priority_queue import priority_queue
+
+__all__ = ['stack', 'queue', 'vector', 'stl_set', 'stl_map', 'priority_queue']