Add async clients support (#326)

* feat: Async functions support for the existing backends; Additional tests; Documentation update

* feat: Class async methods tests

* Organize test directories by cache backend; Add async pickle and memory tests

* fix: Attempt to fix the Mongo versioning across multiple versions of Mongo driver / server

* fix: Level code coverage

Author: gencurrent

.github/copilot-instructions.md

@@ -91,7 +91,15 @@ backend = _update_with_defaults(backend, "backend")
 mongetter = _update_with_defaults(mongetter, "mongetter")
 if callable(mongetter):
     backend = "mongo"
-...
+
+if backend == "pickle":
+    core = _PickleCore(...)
+elif backend == "mongo":
+    core = _MongoCore(...)
+elif backend == "memory":
+    core = _MemoryCore(...)
+elif backend == "sql":
+    core = _SQLCore(...)
 elif backend == "redis":
     core = _RedisCore(
         hash_func=hash_func,

.github/workflows/ci-test.yml

@@ -118,7 +118,7 @@ jobs:
       - name: Unit tests (SQL/Postgres)
         if: matrix.backend == 'postgres'
         env:
-          SQLALCHEMY_DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb
+          SQLALCHEMY_DATABASE_URL: postgresql+psycopg://testuser:testpass@localhost:5432/testdb
         run: pytest -m sql --cov=cachier --cov-report=term --cov-report=xml:cov.xml
 
       - name: Start Redis in docker

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
       - id: detect-private-key
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1
+    rev: v1.43.1
     hooks:
       - id: typos
         # empty to do not write fixes
@@ -55,7 +55,7 @@ repos:
         args: ["--print-width=79"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.10
+    rev: v0.15.0
     hooks:
       # use black formatting
       - id: ruff-format
@@ -73,11 +73,11 @@ repos:
         files: "src/.*"
 
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.11.1
+    rev: v2.12.1
     hooks:
       - id: pyproject-fmt
         additional_dependencies: [tox]
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.24.1
+    rev: v0.25
     hooks:
       - id: validate-pyproject

AGENTS.md

@@ -112,7 +112,7 @@ ______________________________________________________________________
 - **Others:** Memory, MongoDB, SQL, Redis
 - **Adding a backend:** Implement in `src/cachier/cores/`, subclass `BaseCore`, add tests with appropriate markers, update docs, and CI matrix if needed.
 - **Optional dependencies:** Code/tests must gracefully skip if backend deps are missing. Install backend-specific deps via `tests/requirements_*.txt`.
-- **Requirements files:** `tests/sql_requirements.txt`, `tests/redis_requirements.txt` for backend-specific dependencies.
+- **Requirements files:** `tests/requirements_mongodb.txt`, `tests/requirements_postgres.txt`, `tests/requirements_redis.txt` for backend-specific dependencies.
 
 ### 3. **Decorator Usage**
 
@@ -167,7 +167,15 @@ backend = _update_with_defaults(backend, "backend")
 mongetter = _update_with_defaults(mongetter, "mongetter")
 if callable(mongetter):
     backend = "mongo"
-...
+
+if backend == "pickle":
+    core = _PickleCore(...)
+elif backend == "mongo":
+    core = _MongoCore(...)
+elif backend == "memory":
+    core = _MemoryCore(...)
+elif backend == "sql":
+    core = _SQLCore(...)
 elif backend == "redis":
     core = _RedisCore(
         hash_func=hash_func,
@@ -399,7 +407,7 @@ ______________________________________________________________________
 - **Build package:** `python -m build`
 - **Check docs:** `python setup.py checkdocs`
 - **Run example:** `python examples/redis_example.py`
-- **Update requirements:** Edit `tests/requirements_*.txt` as needed (sql_requirements.txt, redis_requirements.txt).
+- **Update requirements:** Edit `tests/requirements_*.txt` as needed (`requirements_mongodb.txt`, `requirements_postgres.txt`, `requirements_redis.txt`).
 
 ### Local Testing with Docker
 
@@ -528,25 +536,25 @@ ______________________________________________________________________
 
 ## 🧭 Quick Reference
 
-| Task                       | Command/Location                   |
-| -------------------------- | ---------------------------------- |
-| Run all tests              | `pytest`                           |
-| Run backend-specific tests | `pytest -m <backend>`              |
-| 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`        |
-| Backend requirements       | `tests/sql_requirements.txt`, etc. |
-| Main decorator             | `src/cachier/core.py`              |
-| Backends                   | `src/cachier/cores/`               |
-| Global config              | `src/cachier/config.py`            |
-| Tests                      | `tests/`                           |
-| Examples                   | `examples/`                        |
-| Documentation              | `README.rst`                       |
-| Contributor guidelines     | `.github/copilot-instructions.md`  |
+| Task                       | Command/Location                  |
+| -------------------------- | --------------------------------- |
+| Run all tests              | `pytest`                          |
+| Run backend-specific tests | `pytest -m <backend>`             |
+| 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`       |
+| Backend requirements       | `tests/requirements_*.txt`        |
+| Main decorator             | `src/cachier/core.py`             |
+| Backends                   | `src/cachier/cores/`              |
+| Global config              | `src/cachier/config.py`           |
+| Tests                      | `tests/`                          |
+| Examples                   | `examples/`                       |
+| Documentation              | `README.rst`                      |
+| Contributor guidelines     | `.github/copilot-instructions.md` |
 
 ______________________________________________________________________
 

CLAUDE.md

@@ -112,7 +112,7 @@ ______________________________________________________________________
 - **Others:** Memory, MongoDB, SQL, Redis
 - **Adding a backend:** Implement in `src/cachier/cores/`, subclass `BaseCore`, add tests with appropriate markers, update docs, and CI matrix if needed.
 - **Optional dependencies:** Code/tests must gracefully skip if backend deps are missing. Install backend-specific deps via `tests/requirements_*.txt`.
-- **Requirements files:** `tests/sql_requirements.txt`, `tests/redis_requirements.txt` for backend-specific dependencies.
+- **Requirements files:** `tests/requirements_mongodb.txt`, `tests/requirements_postgres.txt`, `tests/requirements_redis.txt` for backend-specific dependencies.
 
 ### 3. **Decorator Usage**
 
@@ -191,7 +191,15 @@ backend = _update_with_defaults(backend, "backend")
 mongetter = _update_with_defaults(mongetter, "mongetter")
 if callable(mongetter):
     backend = "mongo"
-...
+
+if backend == "pickle":
+    core = _PickleCore(...)
+elif backend == "mongo":
+    core = _MongoCore(...)
+elif backend == "memory":
+    core = _MemoryCore(...)
+elif backend == "sql":
+    core = _SQLCore(...)
 elif backend == "redis":
     core = _RedisCore(
         hash_func=hash_func,
@@ -423,7 +431,7 @@ ______________________________________________________________________
 - **Build package:** `python -m build`
 - **Check docs:** `python setup.py checkdocs`
 - **Run example:** `python examples/redis_example.py`
-- **Update requirements:** Edit `tests/requirements_*.txt` as needed (sql_requirements.txt, redis_requirements.txt).
+- **Update requirements:** Edit `tests/requirements_*.txt` as needed (`requirements_mongodb.txt`, `requirements_postgres.txt`, `requirements_redis.txt`).
 
 ### Local Testing with Docker
 
@@ -552,25 +560,25 @@ ______________________________________________________________________
 
 ## 🧭 Quick Reference
 
-| Task                       | Command/Location                   |
-| -------------------------- | ---------------------------------- |
-| Run all tests              | `pytest`                           |
-| Run backend-specific tests | `pytest -m <backend>`              |
-| 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`        |
-| Backend requirements       | `tests/sql_requirements.txt`, etc. |
-| Main decorator             | `src/cachier/core.py`              |
-| Backends                   | `src/cachier/cores/`               |
-| Global config              | `src/cachier/config.py`            |
-| Tests                      | `tests/`                           |
-| Examples                   | `examples/`                        |
-| Documentation              | `README.rst`                       |
-| Contributor guidelines     | `.github/copilot-instructions.md`  |
+| Task                       | Command/Location                  |
+| -------------------------- | --------------------------------- |
+| Run all tests              | `pytest`                          |
+| Run backend-specific tests | `pytest -m <backend>`             |
+| 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`       |
+| Backend requirements       | `tests/requirements_*.txt`        |
+| Main decorator             | `src/cachier/core.py`             |
+| Backends                   | `src/cachier/cores/`              |
+| Global config              | `src/cachier/config.py`           |
+| Tests                      | `tests/`                          |
+| Examples                   | `examples/`                       |
+| Documentation              | `README.rst`                      |
+| Contributor guidelines     | `.github/copilot-instructions.md` |
 
 ______________________________________________________________________
 

Makefile

@@ -52,9 +52,9 @@ install-dev:
 install-all:
 	pip install -e .[all]
 	pip install -r tests/requirements.txt
-	pip install -r tests/mongodb_requirements.txt
-	pip install -r tests/redis_requirements.txt
-	pip install -r tests/sql_requirements.txt
+	pip install -r tests/requirements_mongodb.txt
+	pip install -r tests/requirements_redis.txt
+	pip install -r tests/requirements_postgres.txt
 
 # Testing targets
 test:

README.rst

@@ -418,7 +418,7 @@ Cachier supports a generic SQL backend via SQLAlchemy, allowing you to use SQLit
 
 .. code-block:: python
 
-    @cachier(backend="sql", sql_engine="postgresql://user:pass@localhost/dbname")
+    @cachier(backend="sql", sql_engine="postgresql+psycopg://user:pass@localhost/dbname")
     def my_func(x):
         return x * 2
 
@@ -530,9 +530,9 @@ Each additional core (MongoDB, Redis, SQL) requires additional dependencies. To
 
 .. code-block:: bash
 
-  pip install -r tests/mongodb_requirements.txt
-  pip install -r tests/redis_requirements.txt
-  pip install -r tests/sql_requirements.txt
+  pip install -r tests/requirements_mongodb.txt
+  pip install -r tests/requirements_redis.txt
+  pip install -r tests/requirements_postgres.txt
 
 Running the tests
 -----------------
@@ -661,8 +661,8 @@ Adding documentation
 
 This project is documented using the `numpy docstring conventions`_, which were chosen as they are perhaps the most widely-spread conventions that are both supported by common tools such as Sphinx and result in human-readable docstrings (in my personal opinion, of course). When documenting code you add to this project, please follow `these conventions`_.
 
-.. _`numpy docstring conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
-.. _`these conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+.. _`numpy docstring conventions`: https://numpydoc.readthedocs.io/en/latest/format.html
+.. _`these conventions`: https://numpydoc.readthedocs.io/en/latest/format.html
 
 Additionally, if you update this ``README.rst`` file, use ``python setup.py checkdocs`` to validate it compiles.
 

pyproject.toml

@@ -181,6 +181,14 @@ markers = [
   "asyncio: marks tests as async",
 ]
 
+[tool.coverage.report]
+show_missing = true
+# Regexes for lines to exclude from consideration
+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:",         # Is only true when running mypy, not tests
+]
 # --- coverage ---
 
 [tool.coverage.run]
@@ -192,11 +200,3 @@ omit = [
   "src/cachier/__init__.py",
   "**/scripts/**",
 ]
-[tool.coverage.report]
-show_missing = true
-# Regexes for lines to exclude from consideration
-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:",         # Is only true when running mypy, not tests
-]

scripts/README-local-testing.md

@@ -107,7 +107,7 @@ make services-start
 # Run tests manually
 CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true \
 CACHIER_TEST_REDIS_HOST=localhost CACHIER_TEST_REDIS_PORT=6379 CACHIER_TEST_VS_DOCKERIZED_REDIS=true \
-SQLALCHEMY_DATABASE_URL="postgresql://testuser:testpass@localhost:5432/testdb" \
+SQLALCHEMY_DATABASE_URL="postgresql+psycopg://testuser:testpass@localhost:5432/testdb" \
 pytest -m "mongo or redis or sql"
 
 # Stop all services
@@ -146,7 +146,7 @@ The script automatically sets the required environment variables:
 
 ### SQL/PostgreSQL
 
-- `SQLALCHEMY_DATABASE_URL=postgresql://testuser:testpass@localhost:5432/testdb`
+- `SQLALCHEMY_DATABASE_URL=postgresql+psycopg://testuser:testpass@localhost:5432/testdb`
 
 ## Prerequisites
 

scripts/docker-compose.all-cores.yml

@@ -76,6 +76,6 @@ networks:
 #   docker-compose -f scripts/docker-compose.all-cores.yml up -d
 #   CACHIER_TEST_HOST=localhost CACHIER_TEST_PORT=27017 CACHIER_TEST_VS_DOCKERIZED_MONGO=true \
 #   CACHIER_TEST_REDIS_HOST=localhost CACHIER_TEST_REDIS_PORT=6379 CACHIER_TEST_VS_DOCKERIZED_REDIS=true \
-#   SQLALCHEMY_DATABASE_URL="postgresql://testuser:testpass@localhost:5432/testdb" \
+#   SQLALCHEMY_DATABASE_URL="postgresql+psycopg://testuser:testpass@localhost:5432/testdb" \
 #   pytest -m "mongo or redis or sql"
 #   docker-compose -f scripts/docker-compose.all-cores.yml down