fastapi-cachex 0.1.3__tar.gz → 0.1.5__tar.gz

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.1.3
+Version: 0.1.5
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Author-email: Allen <s96016641@gmail.com>
 License-Expression: Apache-2.0
@@ -126,46 +126,10 @@ BackendProxy.set_backend(backend)
 
 Redis support is under development and will be available in future releases.
 
-## Development Guide
+## Documentation
 
-### Running Tests
-
-1. Run unit tests:
-
-```bash
-pytest
-```
-
-2. Run tests with coverage report:
-
-```bash
-pytest --cov=fastapi_cachex
-```
-
-### Using tox
-
-tox ensures the code works across different Python versions (3.10-3.13).
-
-1. Install all Python versions
-2. Run tox:
-
-```bash
-tox
-```
-
-To run for a specific Python version:
-
-```bash
-tox -e py310  # only run for Python 3.10
-```
-
-## Contributing
-
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Contributing Guidelines](docs/CONTRIBUTING.md)
 
 ## License
 

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/README.md

@@ -95,46 +95,10 @@ BackendProxy.set_backend(backend)
 
 Redis support is under development and will be available in future releases.
 
-## Development Guide
+## Documentation
 
-### Running Tests
-
-1. Run unit tests:
-
-```bash
-pytest
-```
-
-2. Run tests with coverage report:
-
-```bash
-pytest --cov=fastapi_cachex
-```
-
-### Using tox
-
-tox ensures the code works across different Python versions (3.10-3.13).
-
-1. Install all Python versions
-2. Run tox:
-
-```bash
-tox
-```
-
-To run for a specific Python version:
-
-```bash
-tox -e py310  # only run for Python 3.10
-```
-
-## Contributing
-
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Contributing Guidelines](docs/CONTRIBUTING.md)
 
 ## License
 

fastapi_cachex-0.1.5/fastapi_cachex/__init__.py

@@ -0,0 +1,4 @@
+from .cache import cache as cache
+from .dependencies import CacheBackend as CacheBackend
+from .dependencies import get_cache_backend as get_cache_backend
+from .proxy import BackendProxy as BackendProxy

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex/backends/base.py

@@ -25,3 +25,26 @@ class BaseCacheBackend(ABC):
     @abstractmethod
     async def clear(self) -> None:
         """Clear all cached responses."""
+
+    @abstractmethod
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path.
+
+        Args:
+            path: The path to clear cache for
+            include_params: Whether to clear all parameter variations of the path
+
+        Returns:
+            Number of cache entries cleared
+        """
+
+    @abstractmethod
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear cached responses matching a pattern.
+
+        Args:
+            pattern: A glob pattern to match cache keys against (e.g., "/users/*")
+
+        Returns:
+            Number of cache entries cleared
+        """

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex/backends/memcached.py

@@ -1,4 +1,5 @@
 import ast
+import warnings
 from typing import Optional
 
 from fastapi_cachex.backends.base import BaseCacheBackend
@@ -25,7 +26,7 @@ class MemcachedBackend(BaseCacheBackend):
                 "pymemcache is not installed. Please install it with 'pip install pymemcache'"
             )
 
-        self.client = HashClient(servers)
+        self.client = HashClient(servers, connect_timeout=5, timeout=5)
 
     async def get(self, key: str) -> Optional[ETagContent]:
         """Get value from cache.
@@ -72,3 +73,29 @@ class MemcachedBackend(BaseCacheBackend):
     async def clear(self) -> None:
         """Clear all values from cache."""
         self.client.flush_all()
+
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path."""
+        if include_params:
+            warnings.warn(
+                "Memcached backend does not support pattern-based key clearing. "
+                "The include_params option will have no effect.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return 0
+
+        # If we're not including params, we can just try to delete the exact path
+        if self.client.delete(path, noreply=False):
+            return 1
+        return 0
+
+    async def clear_pattern(self, pattern: str) -> int:  # noqa: ARG002
+        """Clear cached responses matching a pattern."""
+        warnings.warn(
+            "Memcached backend does not support pattern matching. "
+            "Pattern-based cache clearing is not available.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return 0

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex/backends/memory.py

@@ -53,6 +53,40 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             self.cache.clear()
 
+    async def clear_path(self, path: str, include_params: bool = False) -> int:
+        """Clear cached responses for a specific path."""
+        cleared_count = 0
+        async with self.lock:
+            keys_to_delete = []
+            for key in self.cache:
+                cache_path, *params = key.split(":", 1)
+                if cache_path == path and (include_params or not params):
+                    keys_to_delete.append(key)
+                    cleared_count += 1
+
+            for key in keys_to_delete:
+                del self.cache[key]
+
+        return cleared_count
+
+    async def clear_pattern(self, pattern: str) -> int:
+        """Clear cached responses matching a pattern."""
+        import fnmatch
+
+        cleared_count = 0
+        async with self.lock:
+            keys_to_delete = []
+            for key in self.cache:
+                cache_path = key.split(":", 1)[0]  # Get path part only
+                if fnmatch.fnmatch(cache_path, pattern):
+                    keys_to_delete.append(key)
+                    cleared_count += 1
+
+            for key in keys_to_delete:
+                del self.cache[key]
+
+        return cleared_count
+
     async def _cleanup_task_impl(self) -> None:
         try:
             while True:

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex/cache.py

@@ -120,6 +120,43 @@ def cache(  # noqa: C901
         else:
             request_name = found_request.name
 
+        async def get_cache_control(cache_control: CacheControl) -> str:  # noqa: C901
+            # Set Cache-Control headers
+            if no_cache:
+                cache_control.add(DirectiveType.NO_CACHE)
+                if must_revalidate:
+                    cache_control.add(DirectiveType.MUST_REVALIDATE)
+            else:
+                # Handle normal cache control cases
+                # 1. Access scope (public/private)
+                if public:
+                    cache_control.add(DirectiveType.PUBLIC)
+                elif private:
+                    cache_control.add(DirectiveType.PRIVATE)
+
+                # 2. Cache time settings
+                if ttl is not None:
+                    cache_control.add(DirectiveType.MAX_AGE, ttl)
+
+                # 3. Validation related
+                if must_revalidate:
+                    cache_control.add(DirectiveType.MUST_REVALIDATE)
+
+                # 4. Stale response handling
+                if stale is not None and stale_ttl is None:
+                    raise CacheXError("stale_ttl must be set if stale is used")
+
+                if stale == "revalidate":
+                    cache_control.add(DirectiveType.STALE_WHILE_REVALIDATE, stale_ttl)
+                elif stale == "error":
+                    cache_control.add(DirectiveType.STALE_IF_ERROR, stale_ttl)
+
+                # 5. Special flags
+                if immutable:
+                    cache_control.add(DirectiveType.IMMUTABLE)
+
+            return str(cache_control)
+
         @wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Response:  # noqa: C901
             if found_request:
@@ -135,79 +172,72 @@ def cache(  # noqa: C901
             if req.method != "GET":
                 return await get_response(func, req, *args, **kwargs)
 
-            # Generate cache key
+            # Generate cache key and prepare headers
             cache_key = f"{req.url.path}:{req.query_params}"
-
-            # Check if the data is already in the cache
-            cached_data = await cache_backend.get(cache_key)
-
-            if cached_data and cached_data.etag == req.headers.get("if-none-match"):
-                return Response(
-                    status_code=HTTP_304_NOT_MODIFIED,
-                    headers={"ETag": cached_data.etag},
-                )
-
-            # Get the response
-            response = await get_response(func, req, *args, **kwargs)
-
-            # Generate ETag (hash based on response content)
-            etag = f'W/"{hashlib.md5(response.body).hexdigest()}"'  # noqa: S324
-
-            # Add ETag to response headers
-            response.headers["ETag"] = etag
-
-            # Handle Cache-Control header
-            cache_control = CacheControl()
+            client_etag = req.headers.get("if-none-match")
+            cache_control = await get_cache_control(CacheControl())
 
             # Handle special case: no-store (highest priority)
             if no_store:
-                cache_control.add(DirectiveType.NO_STORE)
-                response.headers["Cache-Control"] = str(cache_control)
+                response = await get_response(func, req, *args, **kwargs)
+                cc = CacheControl()
+                cc.add(DirectiveType.NO_STORE)
+                response.headers["Cache-Control"] = str(cc)
                 return response
 
-            # Handle special case: no-cache
-            if no_cache:
-                cache_control.add(DirectiveType.NO_CACHE)
-                if must_revalidate:
-                    cache_control.add(DirectiveType.MUST_REVALIDATE)
-                response.headers["Cache-Control"] = str(cache_control)
-                return response
+            # Check cache and handle ETag validation
+            cached_data = await cache_backend.get(cache_key)
 
-            # Handle normal cache control cases
-            # 1. Access scope (public/private)
-            if public:
-                cache_control.add(DirectiveType.PUBLIC)
-            elif private:
-                cache_control.add(DirectiveType.PRIVATE)
-
-            # 2. Cache time settings
-            if ttl is not None:
-                cache_control.add(DirectiveType.MAX_AGE, ttl)
-
-            # 3. Validation related
-            if must_revalidate:
-                cache_control.add(DirectiveType.MUST_REVALIDATE)
-
-            # 4. Stale response handling
-            if stale is not None and stale_ttl is None:
-                raise CacheXError("stale_ttl must be set if stale is used")
-
-            if stale == "revalidate":
-                cache_control.add(DirectiveType.STALE_WHILE_REVALIDATE, stale_ttl)
-            elif stale == "error":
-                cache_control.add(DirectiveType.STALE_IF_ERROR, stale_ttl)
-
-            # 5. Special flags
-            if immutable:
-                cache_control.add(DirectiveType.IMMUTABLE)
-
-            # Store the data in the cache
-            await cache_backend.set(
-                cache_key, ETagContent(etag, response.body), ttl=ttl
-            )
+            current_response = None
+            current_etag = None
+
+            if client_etag:
+                if no_cache:
+                    # Get fresh response first if using no-cache
+                    current_response = await get_response(func, req, *args, **kwargs)
+                    current_etag = (
+                        f'W/"{hashlib.md5(current_response.body).hexdigest()}"'  # noqa: S324
+                    )
+
+                    if client_etag == current_etag:
+                        # For no-cache, compare fresh data with client's ETag
+                        return Response(
+                            status_code=HTTP_304_NOT_MODIFIED,
+                            headers={
+                                "ETag": current_etag,
+                                "Cache-Control": cache_control,
+                            },
+                        )
+
+                # Compare with cached ETag
+                elif (
+                    cached_data and client_etag == cached_data.etag
+                ):  # pragma: no branch
+                    return Response(
+                        status_code=HTTP_304_NOT_MODIFIED,
+                        headers={
+                            "ETag": cached_data.etag,
+                            "Cache-Control": cache_control,
+                        },
+                    )
+
+            if not current_response or not current_etag:
+                # Retrieve the current response if not already done
+                current_response = await get_response(func, req, *args, **kwargs)
+                current_etag = f'W/"{hashlib.md5(current_response.body).hexdigest()}"'  # noqa: S324
+
+            # Set ETag header
+            current_response.headers["ETag"] = current_etag
+
+            # Update cache if needed
+            if not cached_data or cached_data.etag != current_etag:
+                # Store in cache if data changed
+                await cache_backend.set(
+                    cache_key, ETagContent(current_etag, current_response.body), ttl=ttl
+                )
 
-            response.headers["Cache-Control"] = str(cache_control)
-            return response
+            current_response.headers["Cache-Control"] = cache_control
+            return current_response
 
         # Update the wrapper with the new signature
         update_wrapper(wrapper, func)

fastapi_cachex-0.1.5/fastapi_cachex/dependencies.py

@@ -0,0 +1,14 @@
+from typing import Annotated
+
+from fastapi import Depends
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.proxy import BackendProxy
+
+
+def get_cache_backend() -> BaseCacheBackend:
+    """Dependency to get the current cache backend instance."""
+    return BackendProxy.get_backend()
+
+
+CacheBackend = Annotated[BaseCacheBackend, Depends(get_cache_backend)]

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.1.3
+Version: 0.1.5
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Author-email: Allen <s96016641@gmail.com>
 License-Expression: Apache-2.0
@@ -126,46 +126,10 @@ BackendProxy.set_backend(backend)
 
 Redis support is under development and will be available in future releases.
 
-## Development Guide
+## Documentation
 
-### Running Tests
-
-1. Run unit tests:
-
-```bash
-pytest
-```
-
-2. Run tests with coverage report:
-
-```bash
-pytest --cov=fastapi_cachex
-```
-
-### Using tox
-
-tox ensures the code works across different Python versions (3.10-3.13).
-
-1. Install all Python versions
-2. Run tox:
-
-```bash
-tox
-```
-
-To run for a specific Python version:
-
-```bash
-tox -e py310  # only run for Python 3.10
-```
-
-## Contributing
-
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Contributing Guidelines](docs/CONTRIBUTING.md)
 
 ## License
 

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/fastapi_cachex.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 fastapi_cachex/__init__.py
 fastapi_cachex/cache.py
+fastapi_cachex/dependencies.py
 fastapi_cachex/directives.py
 fastapi_cachex/exceptions.py
 fastapi_cachex/proxy.py
@@ -18,4 +19,5 @@ fastapi_cachex/backends/base.py
 fastapi_cachex/backends/memcached.py
 fastapi_cachex/backends/memory.py
 tests/test_cache.py
+tests/test_dependencies.py
 tests/test_proxybackend.py

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.1.3" # Initial release version
+version = "0.1.5" # Initial release version
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"

{fastapi_cachex-0.1.3 → fastapi_cachex-0.1.5}/tests/test_cache.py

@@ -27,6 +27,28 @@ def test_default_cache():
     assert "ETag" in response.headers
 
 
+def test_cache_with_ttl():
+    @app.get("/cache-with-ttl")
+    @cache(ttl=3)
+    async def cache_with_ttl_endpoint():
+        return Response(
+            content=b'{"message": "This endpoint has a TTL of 30 seconds"}',
+            media_type="application/json",
+        )
+
+    response = client.get("/cache-with-ttl")
+    assert response.status_code == 200
+    assert response.headers["Cache-Control"] == "max-age=3"
+    assert "ETag" in response.headers
+
+    response2 = client.get(
+        "/cache-with-ttl", headers={"If-None-Match": response.headers["ETag"]}
+    )
+    assert response2.status_code == 304
+    assert response2.headers["Cache-Control"] == "max-age=3"
+    assert response2.headers["ETag"] == response.headers["ETag"]
+
+
 def test_ttl_endpoint():
     @app.get("/ttl")
     @cache(60)
@@ -344,3 +366,63 @@ def test_response_class_with_etag():
     etag = response1.headers["ETag"]
     response2 = client.get("/html-etag", headers={"If-None-Match": etag})
     assert response2.status_code == 304  # Not Modified
+
+
+def test_no_cache_with_unchanged_data():
+    """Test no-cache behavior when data hasn't changed."""
+    counter = 0
+
+    @app.get("/no-cache-unchanged")
+    @cache(no_cache=True)
+    async def no_cache_unchanged_endpoint():
+        return {"message": "This endpoint uses no-cache", "counter": counter}
+
+    # First request should return 200
+    response1 = client.get("/no-cache-unchanged")
+    assert response1.status_code == 200
+    assert response1.json() == {"message": "This endpoint uses no-cache", "counter": 0}
+    etag1 = response1.headers["ETag"]
+    assert "no-cache" in response1.headers["Cache-Control"].lower()
+
+    # Second request with ETag should return 304 as data hasn't changed
+    response2 = client.get("/no-cache-unchanged", headers={"If-None-Match": etag1})
+    assert response2.status_code == 304
+    assert "ETag" in response2.headers
+    assert response2.headers["ETag"] == etag1
+
+    # Third request without ETag should return 200 but same data
+    response3 = client.get("/no-cache-unchanged")
+    assert response3.status_code == 200
+    assert response3.json() == {"message": "This endpoint uses no-cache", "counter": 0}
+    assert response3.headers["ETag"] == etag1
+
+
+def test_no_cache_with_changing_data():
+    """Test no-cache behavior when data changes between requests."""
+    counter = {"value": 0}
+
+    @app.get("/no-cache-changing")
+    @cache(no_cache=True)
+    async def no_cache_changing_endpoint():
+        counter["value"] += 1
+        return {"message": "This endpoint uses no-cache", "counter": counter["value"]}
+
+    # First request
+    response1 = client.get("/no-cache-changing")
+    assert response1.status_code == 200
+    assert response1.json() == {"message": "This endpoint uses no-cache", "counter": 1}
+    etag1 = response1.headers["ETag"]
+    assert "no-cache" in response1.headers["Cache-Control"].lower()
+
+    # Second request with previous ETag should still return 200 with new data
+    response2 = client.get("/no-cache-changing", headers={"If-None-Match": etag1})
+    assert response2.status_code == 200  # Not 304 because data changed
+    assert response2.json() == {"message": "This endpoint uses no-cache", "counter": 2}
+    etag2 = response2.headers["ETag"]
+    assert etag2 != etag1  # ETags should be different as content changed
+
+    # Third request with latest ETag
+    response3 = client.get("/no-cache-changing", headers={"If-None-Match": etag2})
+    assert response3.status_code == 200
+    assert response3.json() == {"message": "This endpoint uses no-cache", "counter": 3}
+    assert response3.headers["ETag"] != etag2  # ETag should change again

fastapi_cachex-0.1.5/tests/test_dependencies.py

@@ -0,0 +1,38 @@
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from fastapi_cachex import BackendProxy
+from fastapi_cachex import CacheBackend
+from fastapi_cachex.backends import MemoryBackend
+from fastapi_cachex.exceptions import BackendNotFoundError
+
+# Setup FastAPI application
+app = FastAPI()
+client = TestClient(app)
+
+
+# Define test endpoint (not a test function)
+@app.get("/test-backend")
+async def backend_endpoint(backend: CacheBackend):
+    return {"backend_type": backend.__class__.__name__}
+
+
+# Actual test functions
+@pytest.mark.asyncio
+async def test_get_cache_backend_no_backend():
+    """Test that get_cache_backend raises BackendNotFoundError when no backend is set."""
+    BackendProxy.set_backend(None)
+    with pytest.raises(BackendNotFoundError):
+        client.get("/test-backend")
+
+
+@pytest.mark.asyncio
+async def test_get_cache_backend_with_memory_backend():
+    """Test that get_cache_backend returns the configured backend."""
+    backend = MemoryBackend()
+    BackendProxy.set_backend(backend)
+
+    response = client.get("/test-backend")
+    assert response.status_code == 200
+    assert response.json() == {"backend_type": "MemoryBackend"}

fastapi_cachex-0.1.3/fastapi_cachex/__init__.py

@@ -1,2 +0,0 @@
-from .cache import cache as cache
-from .proxy import BackendProxy as BackendProxy