Layer

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pythonstl"
-version = "0.1.4"
+version = "1.1.10"
 edition = "2021"
 description = "Rust backend extension for pythonstl data structures"
 

PUBLISHING.md

@@ -8,7 +8,7 @@ Install required tools:
 
 ```bash
 pip install --upgrade pip
-pip install build twine
+pip install maturin twine build
 ```
 
 ## Step 1: Clean Previous Builds
@@ -17,23 +17,30 @@ Remove any existing build artifacts:
 
 ```bash
 # Windows PowerShell
-Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
+Remove-Item -Recurse -Force dist, target, build, *.egg-info -ErrorAction SilentlyContinue
 
 # Linux/Mac
-rm -rf dist build *.egg-info
+rm -rf dist target build *.egg-info
 ```
 
 ## Step 2: Build the Distribution
 
-Build both source distribution and wheel:
+For hybrid Python/Rust packages using Maturin:
+
+```bash
+# Build wheel and sdist with maturin
+maturin build --release
+```
+
+Or using `python -m build` (which invokes maturin as the build backend defined in `pyproject.toml`):
 
 ```bash
 python -m build
 ```
 
-This creates:
-- `dist/pythonstl-0.1.0.tar.gz` (source distribution)
-- `dist/pythonstl-0.1.0-py3-none-any.whl` (wheel)
+This creates distribution artifacts in `target/wheels/` or `dist/`:
+- `dist/pythonstl-1.1.9.tar.gz` (source distribution)
+- `dist/pythonstl-1.1.9-*.whl` (compiled wheel)
 
 ## Step 3: Validate the Build
 

README.md

@@ -10,12 +10,12 @@
     <img width="500" height="500" alt="pythonstl-removebg-preview" src="https://github.com/user-attachments/assets/83bc0da7-50d5-489b-a19d-c8e04fe73cca" />
 </div><br>
 
-A Python package that replicates C++ STL-style data structures using the **Facade Design Pattern**. PythonSTL provides clean, familiar interfaces for developers coming from C++ while maintaining Pythonic best practices.
+A Python package that replicates C++ STL-style data structures using a modular **Containers**, **Engines**, and **Utility** architecture. PythonSTL provides clean, familiar interfaces for developers coming from C++ while maintaining Pythonic best practices.
 
 ## Features
 
 - **C++ STL Compliance**: Exact method names and semantics matching C++ STL
-- **Facade Design Pattern**: Clean separation between interface and implementation
+- **Modular Layered Architecture**: Clean separation between containers, execution engines, and utilities
 - **Iterator Support**: STL-style iterators (begin, end, rbegin, rend) and Python iteration
 - **Python Integration**: Magic methods (__len__, __bool__, __contains__, __repr__, __eq__)
 - **Type Safety**: Full type hints throughout the codebase
@@ -259,22 +259,22 @@ Container adapter providing priority-based access.
 
 ## 🏗️ Architecture
 
-PythonSTL follows the **Facade Design Pattern** with three layers:
+PythonSTL is structured into three distinct, specialized layers (**Containers**, **Engines**, **Utility**):
 
-1. **Core Layer** (`pythonstl/core/`)
-   - Base classes and type definitions
-   - Custom exceptions
-   - Iterator classes
+1. **Containers Layer** (`pythonstl/containers/`)
+   - Public-facing STL-compliant container classes and algorithms
+   - Dispatches operations to native Rust or Python engines
+   - Clean, C++ STL-compliant API
 
-2. **Implementation Layer** (`pythonstl/implementations/`)
-   - Private implementation classes (prefixed with `_`)
-   - Efficient use of Python built-ins
+2. **Engines Layer** (`pythonstl/engines/`)
+   - Internal execution and storage engine implementations (prefixed with `_`)
+   - Linear, associative, and heap structure engines
    - Not intended for direct user access
 
-3. **Facade Layer** (`pythonstl/facade/`)
-   - Public-facing classes
-   - Clean, STL-compliant API
-   - Delegates to implementation layer
+3. **Utility Layer** (`pythonstl/utility/`)
+   - Common utilities, base classes, and type definitions
+   - Custom exception types
+   - Iterator implementations and AVL tree building blocks
 
 This architecture ensures:
 - **Encapsulation**: Internal implementation is hidden
@@ -299,11 +299,11 @@ def thread_safe_push(value):
 
 ## Design Decisions
 
-### Why Facade Pattern?
+### Why Containers, Engines & Utility?
 
-- **Clean API**: Users interact with simple, well-defined interfaces
-- **Flexibility**: Internal implementation can change without affecting users
-- **Type Safety**: Facade layer enforces type contracts
+- **Clean API**: Users interact with simple, well-defined container interfaces
+- **Flexibility**: Internal storage and execution engines can change without affecting users
+- **Type Safety**: Containers layer enforces type contracts
 - **Error Handling**: Consistent error messages across all containers
 
 ### Why STL Naming?
@@ -460,4 +460,4 @@ Contributions are welcome! Please:
 - Issues: [GitHub Issues](https://github.com/AnshMNSoni/PythonSTL/issues)
 - Linkedin: [@anshmnsoni](https://linkedin.com/in/anshmnsoni)
 
-**PythonSTL v1.1.9** - Bringing C++ STL elegance to Python
+**PythonSTL v1.1.10** - Bringing C++ STL elegance to Python

benchmarks/benchmark_algorithms.py

@@ -9,7 +9,7 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 from pythonstl import next_permutation, nth_element, partition, stl_set
-from pythonstl.facade.algorithms import RUST_AVAILABLE
+from pythonstl.containers.algorithms import RUST_AVAILABLE
 
 def run_py_permutation():
     arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]

benchmarks/benchmark_all_structures.py

@@ -13,12 +13,12 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 from pythonstl import stack, queue, vector, stl_set, stl_map, priority_queue
-from pythonstl.facade.stack import RUST_AVAILABLE as STACK_RUST_AVAILABLE
-from pythonstl.facade.queue import RUST_AVAILABLE as QUEUE_RUST_AVAILABLE
-from pythonstl.facade.vector import RUST_AVAILABLE as VECTOR_RUST_AVAILABLE
-from pythonstl.facade.set import RUST_AVAILABLE as SET_RUST_AVAILABLE
-from pythonstl.facade.map import RUST_AVAILABLE as MAP_RUST_AVAILABLE
-from pythonstl.facade.priority_queue import RUST_AVAILABLE as PQ_RUST_AVAILABLE
+from pythonstl.containers.stack import RUST_AVAILABLE as STACK_RUST_AVAILABLE
+from pythonstl.containers.queue import RUST_AVAILABLE as QUEUE_RUST_AVAILABLE
+from pythonstl.containers.vector import RUST_AVAILABLE as VECTOR_RUST_AVAILABLE
+from pythonstl.containers.set import RUST_AVAILABLE as SET_RUST_AVAILABLE
+from pythonstl.containers.map import RUST_AVAILABLE as MAP_RUST_AVAILABLE
+from pythonstl.containers.priority_queue import RUST_AVAILABLE as PQ_RUST_AVAILABLE
 
 
 def run_benchmark(name, py_func, rust_func, has_rust, native_func):

benchmarks/benchmark_binary_search.py

@@ -9,7 +9,7 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 from pythonstl import lower_bound
-from pythonstl.facade.algorithms import RUST_AVAILABLE
+from pythonstl.containers.algorithms import RUST_AVAILABLE
 
 def run_py_binary_search(arr, targets):
     sum_indices = 0

benchmarks/benchmark_rust_vs_py.py

@@ -7,7 +7,7 @@
 # Add project root to path to run directly from development folder
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
-from pythonstl.facade.stack import stack, RUST_AVAILABLE
+from pythonstl.containers.stack import stack, RUST_AVAILABLE
 
 # Try importing the bubble_sort function from the compiled Rust library
 try:

pyproject.toml

@@ -8,7 +8,7 @@ module-name = "pythonstl._rust"
 
 [project]
 name = "pythonstl"
-version = "1.1.9"
+version = "1.1.10"
 description = "C++ STL-style containers implemented in Python using the Facade Design Pattern"
 readme = "README.md"
 authors = [
@@ -38,7 +38,7 @@ Issues = "https://github.com/AnshMNSoni/STL/issues"
 Documentation = "https://github.com/AnshMNSoni/STL#readme"
 
 [tool.setuptools]
-packages = ["pythonstl", "pythonstl.core", "pythonstl.implementations", "pythonstl.implementations.linear", "pythonstl.implementations.associative", "pythonstl.implementations.heaps", "pythonstl.facade"]
+packages = ["pythonstl", "pythonstl.utility", "pythonstl.engines", "pythonstl.engines.linear", "pythonstl.engines.associative", "pythonstl.engines.heaps", "pythonstl.containers"]
 
 [tool.setuptools.package-data]
 pythonstl = ["py.typed"]

pythonstl/__init__.py

@@ -8,16 +8,16 @@
 data structures while hiding implementation details from users.
 """
 
-__version__ = "1.1.9"
+__version__ = "1.1.10"
 __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 (
+from pythonstl.containers.stack import stack
+from pythonstl.containers.queue import queue
+from pythonstl.containers.vector import vector
+from pythonstl.containers.set import stl_set
+from pythonstl.containers.map import stl_map
+from pythonstl.containers.priority_queue import priority_queue
+from pythonstl.containers.algorithms import (
     next_permutation,
     prev_permutation,
     nth_element,
@@ -29,7 +29,7 @@
 )
 
 # Also export exceptions for user error handling
-from pythonstl.core.exceptions import (
+from pythonstl.utility.exceptions import (
     PySTLException,
     EmptyContainerError,
     OutOfRangeError,

pythonstl/facade/__init__.py → pythonstl/containers/__init__.py

@@ -1,4 +1,4 @@
-"""Facade layer for pystl data structures."""
+"""Containers layer for pystl data structures."""
 
 from .stack import stack
 from .queue import queue

pythonstl/facade/map.py → pythonstl/containers/map.py

@@ -6,9 +6,9 @@
 
 from typing import TypeVar, Iterator as TypingIterator, Tuple
 from copy import deepcopy
-from pythonstl.core.exceptions import KeyNotFoundError
-from pythonstl.implementations.associative._map_impl import _MapImpl
-from pythonstl.core.iterator import MapIterator
+from pythonstl.utility.exceptions import KeyNotFoundError
+from pythonstl.engines.associative._map_impl import _MapImpl
+from pythonstl.utility.iterator import MapIterator
 
 try:
     from pythonstl._rust import RustMap

pythonstl/facade/priority_queue.py → pythonstl/containers/priority_queue.py

@@ -6,8 +6,8 @@
 
 from typing import TypeVar
 from copy import deepcopy
-from pythonstl.core.exceptions import EmptyContainerError
-from pythonstl.implementations.heaps._priority_queue_impl import _PriorityQueueImpl
+from pythonstl.utility.exceptions import EmptyContainerError
+from pythonstl.engines.heaps._priority_queue_impl import _PriorityQueueImpl
 
 try:
     from pythonstl._rust import RustPriorityQueue

pythonstl/facade/queue.py → pythonstl/containers/queue.py

@@ -6,8 +6,8 @@
 
 from typing import TypeVar
 from copy import deepcopy
-from pythonstl.core.exceptions import EmptyContainerError
-from pythonstl.implementations.linear._queue_impl import _QueueImpl
+from pythonstl.utility.exceptions import EmptyContainerError
+from pythonstl.engines.linear._queue_impl import _QueueImpl
 
 try:
     from pythonstl._rust import RustQueue

pythonstl/facade/set.py → pythonstl/containers/set.py

@@ -6,8 +6,8 @@
 
 from typing import TypeVar, Iterator as TypingIterator
 from copy import deepcopy
-from pythonstl.implementations.associative._set_impl import _SetImpl
-from pythonstl.core.iterator import SetIterator
+from pythonstl.engines.associative._set_impl import _SetImpl
+from pythonstl.utility.iterator import SetIterator
 
 try:
     from pythonstl._rust import RustSet

pythonstl/facade/stack.py → pythonstl/containers/stack.py

@@ -6,8 +6,8 @@
 
 from typing import TypeVar
 from copy import deepcopy
-from pythonstl.core.exceptions import EmptyContainerError
-from pythonstl.implementations.linear._stack_impl import _StackImpl
+from pythonstl.utility.exceptions import EmptyContainerError
+from pythonstl.engines.linear._stack_impl import _StackImpl
 
 try:
     from pythonstl._rust import RustStack

pythonstl/facade/vector.py → pythonstl/containers/vector.py

@@ -6,9 +6,9 @@
 
 from typing import TypeVar, Iterator as TypingIterator
 from copy import deepcopy
-from pythonstl.core.exceptions import EmptyContainerError, OutOfRangeError
-from pythonstl.implementations.linear._vector_impl import _VectorImpl
-from pythonstl.core.iterator import VectorIterator, VectorReverseIterator
+from pythonstl.utility.exceptions import EmptyContainerError, OutOfRangeError
+from pythonstl.engines.linear._vector_impl import _VectorImpl
+from pythonstl.utility.iterator import VectorIterator, VectorReverseIterator
 
 try:
     from pythonstl._rust import RustVector

pythonstl/implementations/associative/_map_impl.py → pythonstl/engines/associative/_map_impl.py

@@ -6,9 +6,9 @@
 """
 
 from typing import TypeVar, Dict
-from pythonstl.core.exceptions import KeyNotFoundError
-from pythonstl.core.iterator import MapIterator
-from pythonstl.core.avl_tree import AVLTree
+from pythonstl.utility.exceptions import KeyNotFoundError
+from pythonstl.utility.iterator import MapIterator
+from pythonstl.utility.avl_tree import AVLTree
 
 K = TypeVar('K')
 V = TypeVar('V')

pythonstl/implementations/associative/_set_impl.py → pythonstl/engines/associative/_set_impl.py

@@ -6,8 +6,8 @@
 """
 
 from typing import TypeVar, List
-from pythonstl.core.iterator import SetIterator
-from pythonstl.core.avl_tree import AVLTree
+from pythonstl.utility.iterator import SetIterator
+from pythonstl.utility.avl_tree import AVLTree
 
 T = TypeVar('T')
 

pythonstl/implementations/heaps/_priority_queue_impl.py → pythonstl/engines/heaps/_priority_queue_impl.py

@@ -7,7 +7,7 @@
 
 from typing import TypeVar, List
 import heapq
-from pythonstl.core.exceptions import EmptyContainerError
+from pythonstl.utility.exceptions import EmptyContainerError
 
 T = TypeVar('T')
 

pythonstl/implementations/linear/_queue_impl.py → pythonstl/engines/linear/_queue_impl.py

@@ -7,7 +7,7 @@
 
 from typing import TypeVar
 from collections import deque
-from pythonstl.core.exceptions import EmptyContainerError
+from pythonstl.utility.exceptions import EmptyContainerError
 
 T = TypeVar('T')
 

pythonstl/implementations/linear/_stack_impl.py → pythonstl/engines/linear/_stack_impl.py

@@ -6,7 +6,7 @@
 """
 
 from typing import TypeVar, List
-from pythonstl.core.exceptions import EmptyContainerError
+from pythonstl.utility.exceptions import EmptyContainerError
 
 T = TypeVar('T')
 

pythonstl/implementations/linear/_vector_impl.py → pythonstl/engines/linear/_vector_impl.py

@@ -6,8 +6,8 @@
 """
 
 from typing import TypeVar, List
-from pythonstl.core.exceptions import EmptyContainerError, OutOfRangeError
-from pythonstl.core.iterator import VectorIterator, VectorReverseIterator
+from pythonstl.utility.exceptions import EmptyContainerError, OutOfRangeError
+from pythonstl.utility.iterator import VectorIterator, VectorReverseIterator
 
 T = TypeVar('T')