pythonstl 0.1.0__py3-none-any.whl

pythonstl/__init__.py

@@ -0,0 +1,45 @@
+"""
+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.0"
+__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
+
+# 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',
+    # 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, Any
+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']

pythonstl/facade/map.py

@@ -0,0 +1,270 @@
+"""
+Map facade class.
+
+This module provides the public-facing map class that users interact with.
+"""
+
+from typing import TypeVar, Iterator as TypingIterator, Tuple
+from copy import deepcopy
+from pythonstl.implementations.associative._map_impl import _MapImpl
+from pythonstl.core.iterator import MapIterator
+
+K = TypeVar('K')
+V = TypeVar('V')
+
+
+class stl_map:
+    """
+    A map data structure following C++ STL semantics.
+    
+    This is an associative container that stores key-value pairs.
+    Named 'stl_map' to avoid potential conflicts.
+    
+    Example:
+        >>> from pythonstl import stl_map
+        >>> m = stl_map()
+        >>> m.insert("key1", 100)
+        >>> m.insert("key2", 200)
+        >>> m.at("key1")
+        100
+        >>> "key1" in m
+        True
+        >>> len(m)
+        2
+    """
+    
+    def __init__(self) -> None:
+        """
+        Initialize an empty map.
+        
+        Time Complexity:
+            O(1)
+        """
+        self._impl = _MapImpl()
+    
+    def insert(self, key: K, value: V) -> None:
+        """
+        Insert a key-value pair into the map.
+        
+        Args:
+            key: The key to insert.
+            value: The value associated with the key.
+            
+        Note:
+            If the key already exists, the value is updated.
+            
+        Time Complexity:
+            O(1) average case
+        """
+        self._impl.insert(key, value)
+    
+    def erase(self, key: K) -> None:
+        """
+        Remove a key-value pair from the map.
+        
+        Args:
+            key: The key to remove.
+            
+        Note:
+            Does nothing if the key is not present (matches C++ STL behavior).
+            
+        Time Complexity:
+            O(1) average case
+        """
+        self._impl.erase(key)
+    
+    def find(self, key: K) -> bool:
+        """
+        Check if a key exists in the map.
+        
+        Args:
+            key: The key to search for.
+            
+        Returns:
+            True if the key exists, False otherwise.
+            
+        Time Complexity:
+            O(1) average case
+        """
+        return self._impl.find(key)
+    
+    def at(self, key: K) -> V:
+        """
+        Access the value associated with a key.
+        
+        Args:
+            key: The key to access.
+            
+        Returns:
+            The value associated with the key.
+            
+        Raises:
+            KeyNotFoundError: If the key does not exist.
+            
+        Time Complexity:
+            O(1) average case
+        """
+        return self._impl.at(key)
+    
+    def empty(self) -> bool:
+        """
+        Check if the map is empty.
+        
+        Returns:
+            True if the map is empty, False otherwise.
+            
+        Time Complexity:
+            O(1)
+        """
+        return self._impl.empty()
+    
+    def size(self) -> int:
+        """
+        Get the number of key-value pairs in the map.
+        
+        Returns:
+            The number of key-value pairs in the map.
+            
+        Time Complexity:
+            O(1)
+        """
+        return self._impl.size()
+    
+    def begin(self) -> MapIterator:
+        """
+        Get iterator to the beginning of the map.
+        
+        Returns:
+            Iterator pointing to the first key-value pair.
+            
+        Time Complexity:
+            O(1)
+        """
+        return self._impl.begin()
+    
+    def end(self) -> MapIterator:
+        """
+        Get iterator to the end of the map.
+        
+        Returns:
+            Iterator pointing past the last key-value pair.
+            
+        Time Complexity:
+            O(1)
+        """
+        return self._impl.end()
+    
+    def copy(self) -> 'stl_map':
+        """
+        Create a deep copy of the map.
+        
+        Returns:
+            A new map with copied key-value pairs.
+            
+        Time Complexity:
+            O(n) where n is the number of key-value pairs
+        """
+        new_map = stl_map()
+        for key, value in self:
+            new_map.insert(key, value)
+        return new_map
+    
+    # Python magic methods
+    
+    def __len__(self) -> int:
+        """
+        Get the number of key-value pairs (Python len() support).
+        
+        Returns:
+            The number of key-value pairs in the map.
+        """
+        return self.size()
+    
+    def __bool__(self) -> bool:
+        """
+        Check if map is non-empty (Python bool() support).
+        
+        Returns:
+            True if map is non-empty, False otherwise.
+        """
+        return not self.empty()
+    
+    def __contains__(self, key: K) -> bool:
+        """
+        Check if key exists in map (Python 'in' operator support).
+        
+        Args:
+            key: The key to search for.
+            
+        Returns:
+            True if key exists, False otherwise.
+            
+        Time Complexity:
+            O(1) average case
+        """
+        return self.find(key)
+    
+    def __repr__(self) -> str:
+        """
+        Get string representation of the map.
+        
+        Returns:
+            String representation showing all key-value pairs.
+        """
+        pairs = [f"{k}: {v}" for k, v in self]
+        return f"stl_map({{{', '.join(pairs)}}})"
+    
+    def __eq__(self, other: object) -> bool:
+        """
+        Check equality with another map.
+        
+        Args:
+            other: Another map to compare with.
+            
+        Returns:
+            True if maps are equal, False otherwise.
+        """
+        if not isinstance(other, stl_map):
+            return False
+        if self.size() != other.size():
+            return False
+        for key, value in self:
+            if not other.find(key) or other.at(key) != value:
+                return False
+        return True
+    
+    def __iter__(self) -> TypingIterator[Tuple[K, V]]:
+        """
+        Get Python iterator for the map.
+        
+        Returns:
+            Iterator over key-value pairs as tuples.
+        """
+        return iter(self._impl.get_data().items())
+    
+    def __copy__(self) -> 'stl_map':
+        """
+        Support for copy.copy().
+        
+        Returns:
+            A shallow copy of the map.
+        """
+        return self.copy()
+    
+    def __deepcopy__(self, memo) -> 'stl_map':
+        """
+        Support for copy.deepcopy().
+        
+        Args:
+            memo: Memoization dictionary for deepcopy.
+            
+        Returns:
+            A deep copy of the map.
+        """
+        new_map = stl_map()
+        for key, value in self:
+            new_map.insert(deepcopy(key, memo), deepcopy(value, memo))
+        return new_map
+
+
+__all__ = ['stl_map']