Restore mypy usage

Author: shaypal5

.github/copilot-instructions.md

@@ -26,7 +26,7 @@ Welcome to the Cachier codebase! Please follow these guidelines to ensure code s
 
 ## 4. Coverage, Linting, and Typing
 
-- Code must pass `ruff` and `pytest`.
+- Code must pass `mypy`, `ruff`, and `pytest`.
 - Use per-file or per-line ignores for known, justified issues (e.g., SQLAlchemy model base class typing, intentional use of `pickle`).
 - All new code must include full type annotations and docstrings matching the style of the existing codebase.
 - All docstrings should follow numpy docstring conventions.

.pre-commit-config.yaml

@@ -65,6 +65,13 @@ repos:
         name: Ruff check
         args: ["--fix"]
 
+  # it needs to be after formatting hooks because the lines might be changed
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.16.1
+    hooks:
+      - id: mypy
+        files: "src/*"
+
 
   - repo: https://github.com/tox-dev/pyproject-fmt
     rev: v2.6.0

AGENTS.md

@@ -9,6 +9,7 @@
 - **Key Dependencies:** `portalocker`, `watchdog` (optional: `pymongo`, `sqlalchemy`, `redis`)
 - **Test Framework:** `pytest` with backend-specific markers
 - **Linting:** `ruff` (replaces black/flake8)
+- **Type Checking:** `mypy`
 - **CI:** GitHub Actions (matrix for backends/OS with Dockerized services)
 - **Issue Tracking:** GitHub Issues
 - **Additional Docs:** `.github/copilot-instructions.md` for contributor guidelines
@@ -64,10 +65,11 @@ ______________________________________________________________________
    pytest -m "not (mongo or sql)"  # Exclude external service backends
    ```
 
-3. **Lint:**
+3. **Lint and type-check:**
 
    ```bash
    ruff check .
+   mypy src/cachier/
    ```
 
 4. **Try an example:**
@@ -100,6 +102,7 @@ ______________________________________________________________________
 - **Type annotations** required for all new code.
 - **Docstrings:** Use numpy style, multi-line, no single-line docstrings.
 - **Lint:** Run `ruff` before PRs. Use per-line/file ignores only for justified cases.
+- **Type check:** Run `mypy` before PRs.
 - **Testing:** All public methods must have at least one test. Use `pytest.mark.<backend>` for backend-specific tests.
 - **No warnings/errors for missing optional dependencies at import time.** Only raise when backend is used.
 
@@ -501,6 +504,7 @@ ______________________________________________________________________
 - **If adding new dependencies, use context7 MCP to get latest versions.**
 - **Always check GitHub Issues before starting new features/PRs.**
 - **Create a relevant issue for every new PR.**
+- **Use per-file or per-line ignores for mypy/ruff only when justified.**
 - **All new code must have full type annotations and numpy-style docstrings.**
 
 ______________________________________________________________________
@@ -552,6 +556,7 @@ ______________________________________________________________________
 | Test multiple backends     | `pytest -m "redis or sql"`         |
 | Exclude backends           | `pytest -m "not mongo"`            |
 | Lint                       | `ruff check .`                     |
+| Type check                 | `mypy src/cachier/`                |
 | Format code                | `ruff format .`                    |
 | Build package              | `python -m build`                  |
 | Check docs                 | `python setup.py checkdocs`        |

CLAUDE.md

@@ -9,6 +9,7 @@
 - **Key Dependencies:** `portalocker`, `watchdog` (optional: `pymongo`, `sqlalchemy`, `redis`)
 - **Test Framework:** `pytest` with backend-specific markers
 - **Linting:** `ruff` (replaces black/flake8)
+- **Type Checking:** `mypy`
 - **CI:** GitHub Actions (matrix for backends/OS with Dockerized services)
 - **Issue Tracking:** GitHub Issues
 - **Additional Docs:** `.github/copilot-instructions.md` for contributor guidelines
@@ -68,6 +69,7 @@ ______________________________________________________________________
 
    ```bash
    ruff check .
+   mypy src/cachier/
    ```
 
 4. **Try an example:**
@@ -100,6 +102,7 @@ ______________________________________________________________________
 - **Type annotations** required for all new code.
 - **Docstrings:** Use numpy style, multi-line, no single-line docstrings.
 - **Lint:** Run `ruff` before PRs. Use per-line/file ignores only for justified cases.
+- **Type check:** Run `mypy` before PRs.
 - **Testing:** All public methods must have at least one test. Use `pytest.mark.<backend>` for backend-specific tests.
 - **No warnings/errors for missing optional dependencies at import time.** Only raise when backend is used.
 
@@ -501,6 +504,7 @@ ______________________________________________________________________
 - **If adding new dependencies, use context7 MCP to get latest versions.**
 - **Always check GitHub Issues before starting new features/PRs.**
 - **Create a relevant issue for every new PR.**
+- **Use per-file or per-line ignores for mypy/ruff only when justified.**
 - **All new code must have full type annotations and numpy-style docstrings.**
 
 ______________________________________________________________________
@@ -552,6 +556,7 @@ ______________________________________________________________________
 | Test multiple backends     | `pytest -m "redis or sql"`         |
 | Exclude backends           | `pytest -m "not mongo"`            |
 | Lint                       | `ruff check .`                     |
+| Type check                 | `mypy src/cachier/`                |
 | Format code                | `ruff format .`                    |
 | Build package              | `python -m build`                  |
 | Check docs                 | `python setup.py checkdocs`        |

Makefile

@@ -5,7 +5,7 @@
         test-mongo-local test-mongo-docker test-mongo-inmemory test-mongo-also-local \
         test-redis-local test-sql-local \
         services-start services-stop services-logs \
-mongo-start mongo-stop mongo-logs lint format clean \
+        mongo-start mongo-stop mongo-logs lint type-check format clean \
         install install-dev install-all
 
 # Default target
@@ -30,6 +30,7 @@ help:
 	@echo ""
 	@echo "Code Quality:"
 	@echo "  make lint               - Run ruff linter"
+	@echo "  make type-check         - Run mypy type checker"
 	@echo "  make format             - Format code with ruff"
 	@echo ""
 	@echo "Installation:"
@@ -130,6 +131,8 @@ mongo-logs:
 lint:
 	ruff check .
 
+type-check:
+	mypy src/cachier/
 
 format:
 	ruff format .
@@ -142,6 +145,7 @@ clean:
 	rm -rf .coverage
 	rm -rf htmlcov/
 	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
 	rm -rf .ruff_cache/
 	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
 	find . -type f -name "*.pyc" -delete

pyproject.toml

@@ -198,5 +198,5 @@ show_missing = true
 exclude_lines = [
   "pragma: no cover",          # Have to re-enable the standard pragma
   "raise NotImplementedError", # Don't complain if tests don't hit defensive assertion code:
-  "if TYPE_CHECKING:",
+  "if TYPE_CHECKING:",         # Is only true when running mypy, not tests
 ]

src/cachier/cores/base.py

@@ -14,7 +14,7 @@
 from datetime import timedelta
 from typing import Any, Callable, Optional, Tuple
 
-from pympler import asizeof
+from pympler import asizeof  # type: ignore
 
 from .._types import HashFunc
 from ..config import CacheEntry, _update_with_defaults

src/cachier/cores/pickle.py

@@ -12,7 +12,7 @@
 import time
 from contextlib import suppress
 from datetime import datetime, timedelta
-from typing import Any, Dict, Optional, Tuple, Union
+from typing import Any, Dict, Optional, Tuple, Union, IO, cast
 
 import portalocker  # to lock on pickle cache IO
 from watchdog.events import PatternMatchingEventHandler
@@ -120,7 +120,7 @@ def _convert_legacy_cache_entry(
     def _load_cache_dict(self) -> Dict[str, CacheEntry]:
         try:
             with portalocker.Lock(self.cache_fpath, mode="rb") as cf:
-                cache = pickle.load(cf)
+                cache = pickle.load(cast(IO[bytes], cf))
             self._cache_used_fpath = str(self.cache_fpath)
         except (FileNotFoundError, EOFError):
             cache = {}
@@ -147,7 +147,7 @@ def _load_cache_by_key(
         fpath += f"_{hash_str or key}"
         try:
             with portalocker.Lock(fpath, mode="rb") as cache_file:
-                entry = pickle.load(cache_file)
+                entry = pickle.load(cast(IO[bytes], cache_file))
             return _PickleCore._convert_legacy_cache_entry(entry)
         except (FileNotFoundError, EOFError):
             return None
@@ -186,7 +186,7 @@ def _save_cache(
             fpath += f"_{hash_str}"
         with self.lock:
             with portalocker.Lock(fpath, mode="wb") as cf:
-                pickle.dump(cache, cf, protocol=4)
+                pickle.dump(cache, cast(IO[bytes], cf), protocol=4)
             # the same as check for separate_file, but changed for typing
             if isinstance(cache, dict):
                 self._cache_dict = cache

src/cachier/cores/sql.py

@@ -3,7 +3,7 @@
 import pickle
 import threading
 from datetime import datetime, timedelta
-from typing import Any, Callable, Optional, Tuple, Union
+from typing import Any, Callable, Optional, Tuple, Union, cast
 
 try:
     from sqlalchemy import (
@@ -112,10 +112,10 @@ def get_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
             value = pickle.loads(row.value) if row.value is not None else None
             entry = CacheEntry(
                 value=value,
-                time=row.timestamp,
-                stale=row.stale,
-                _processing=row.processing,
-                _completed=row.completed,
+                time=cast(datetime, row.timestamp),
+                stale=cast(bool, row.stale),
+                _processing=cast(bool, row.processing),
+                _completed=cast(bool, row.completed),
             )
             return key, entry