feat: impl stack

.github/workflows/test.yml

@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
 
     steps:
@@ -62,7 +62,7 @@ jobs:
           key: ${{ runner.os }}-python-${{ matrix.python-version }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
             ${{ runner.os }}-python-${{ matrix.python-version }}-cargo-
-          
+
       - name: Install uv
         uses: astral-sh/setup-uv@v3
 
@@ -71,3 +71,6 @@ jobs:
           uv sync
           make test
           cargo test
+
+      - name: lint
+        run: make lint

Makefile

@@ -20,6 +20,7 @@ lint:
 	$(UV) run ruff check --exit-non-zero-on-fix
 	$(UV) run ruff format --check --diff
 	$(UV) run flake8 tests fast_collections
+	$(UV) run mypy --strict fast_collections
 
 build:
 	$(UV) run maturin build --release

fast_collections/stack.py

@@ -0,0 +1,117 @@
+from typing import Generic, TypeVar
+
+_T = TypeVar("_T")  # noqa: WPS111
+
+
+class Stack(Generic[_T]):
+    """
+    A last-in-first-out (LIFO) stack data structure.
+
+    Provides O(1) push and pop operations on the top of the stack.
+    The stack is generic: element types are determined
+    by the ``T`` type parameter.
+
+    Examples:
+        >>> s = Stack[int]()
+        >>> s.is_empty()
+        True
+        >>> s.push(1)
+        >>> s.push(2)
+        >>> s.pop()
+        2
+        >>> s.pick()
+        1
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty stack.
+
+        Examples:
+            >>> s = Stack[int]()
+            >>> s.is_empty()
+            True
+        """
+        self._stack: list[_T] = []
+
+    def is_empty(self) -> bool:
+        """
+        Check whether the stack is empty.
+
+        Returns:
+            True if there are no elements on the stack, False otherwise.
+
+        Complexity: O(1)
+
+        Examples:
+            >>> s = Stack[int]()
+            >>> s.is_empty()
+            True
+            >>> s.push(1)
+            >>> s.is_empty()
+            False
+        """
+        return len(self._stack) == 0
+
+    def pick(self) -> _T:
+        """
+        Return the top element of the stack without removing it.
+
+        Returns:
+            The value at the top of the stack.
+
+        Raises:
+            IndexError: If the stack is empty.
+
+        Complexity: O(1)
+
+        Examples:
+            >>> s = Stack[int]()
+            >>> s.push(1)
+            >>> s.push(2)
+            >>> s.pick()
+            2
+            >>> s.is_empty()
+            False
+        """
+        return self._stack[-1]
+
+    def pop(self) -> _T:
+        """
+        Remove and return the top element of the stack.
+
+        Returns:
+            The value at the top of the stack. The stack size decreases by one.
+
+        Raises:
+            IndexError: If the stack is empty.
+
+        Complexity: O(1)
+
+        Examples:
+            >>> s = Stack[int]()
+            >>> s.push(1)
+            >>> s.push(2)
+            >>> s.pop()
+            2
+            >>> s.pick()
+            1
+        """
+        return self._stack.pop()
+
+    def push(self, new_value: _T) -> None:
+        """
+        Push a new_value onto the top of the stack.
+
+        Args:
+            new_value: The value to add to the stack.
+
+        Complexity: O(1)
+
+        Examples:
+            >>> s = Stack[int]()
+            >>> s.push(1)
+            >>> s.pick()
+            1
+        """
+        self._stack.append(new_value)

pyproject.toml

@@ -13,8 +13,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -23,12 +21,14 @@ classifiers = [
     "Programming Language :: Rust",
     "Operating System :: OS Independent",
 ]
+
 [dependency-groups]
 dev = [
     "maturin>=1.14.1",
     "pytest>=8.3.5",
     "ruff>=0.15.22",
     "wemake-python-styleguide>=0.17.0",
+    "mypy>=1.14.1",
 ]
 docs = [
     "mkdocs>=1.6.1",
@@ -47,4 +47,4 @@ module-name = "fast_collections"
 include = ["fast_collections/"] 
 
 [tool.ruff]
-line-length = 80
+line-length = 80