Merge pull request a-luna#27 from a-luna/minor-release/v0.2.0

v0.2.0

Author: a-luna

.github/workflows/tox.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9"]
+        python-version: ["3.7", "3.8", "3.9"]
 
     steps:
       - uses: "actions/checkout@v2"

README.md

@@ -84,16 +84,59 @@ INFO:     127.0.0.1:61779 - "GET /immutable_data HTTP/1.1" 200 OK
 
 The log messages show two successful (**`200 OK`**) responses to the same request (**`GET /immutable_data`**). The first request executed the `get_immutable_data` function and stored the result in Redis under key `api.get_immutable_data()`. The second request _**did not**_ execute the `get_immutable_data` function, instead the cached result was retrieved and sent as the response.
 
-If data for an API endpoint needs to expire, you can specify the number of seconds before it is deleted by Redis using the `expire_after_seconds` parameter:
+In most situations, response data must expire in a much shorter period of time than one year. Using the `expire` parameter, You can specify the number of seconds before data is deleted:
 
 ```python
 # Will be cached for thirty seconds
 @app.get("/dynamic_data")
-@cache(expire_after_seconds=30)
+@cache(expire=30)
 def get_dynamic_data(request: Request, response: Response):
     return {"success": True, "message": "this data should only be cached temporarily"}
 ```
 
+> **NOTE!** `expire` can be either an `int` value or `timedelta` object. When the TTL is very short (like the example above) this results in a decorator that is expressive and requires minimal effort to parse visually. For durations an hour or longer (e.g., `@cache(expire=86400)`), IMHO, using a `timedelta` object is much easier to grok (`@cache(expire=timedelta(days=1))`).
+
+Additionally, the decorators listed below define several common durations and can be used in place of the `@cache` decorator:
+
+- `@cache_one_minute`
+- `@cache_one_hour`
+- `@cache_one_day`
+- `@cache_one_week`
+- `@cache_one_month`
+- `@cache_one_year`
+
+For example, instead of `@cache(expire=timedelta(days=1))`, you could use:
+
+```python
+from fastapi_redis_cache import cache_one_day
+
+@app.get("/cache_one_day")
+@cache_one_day()
+def partial_cache_one_day(response: Response):
+    return {"success": True, "message": "this data should be cached for 24 hours"}
+```
+
+If a duration that you would like to use throughout your project is missing from the list, you can easily create your own:
+
+```python
+from functools import partial, update_wrapper
+from fastapi_redis_cache import cache
+
+ONE_HOUR_IN_SECONDS = 3600
+
+cache_two_hours = partial(cache, expire=ONE_HOUR_IN_SECONDS * 2)
+update_wrapper(cache_two_hours, cache)
+```
+
+Then, simply import `cache_two_hours` and use it to decorate your API endpoint path functions:
+
+```python
+@app.get("/cache_two_hours")
+@cache_two_hours()
+def partial_cache_two_hours(response: Response):
+    return {"success": True, "message": "this data should be cached for two hours"}
+```
+
 #### Response Headers
 
 Below is an example HTTP response for the `/dynamic_data` endpoint. The `cache-control`, `etag`, `expires`, and `x-fastapi-cache` headers are added because of the `@cache` decorator:
@@ -117,7 +160,7 @@ $ http "http://127.0.0.1:8000/dynamic_data"
 ```
 
 - The `x-fastapi-cache` header field indicates that this response was found in the Redis cache (a.k.a. a `Hit`). The only other possible value for this field is `Miss`.
-- The `expires` field and `max-age` value in the `cache-control` field indicate that this response will be considered fresh for 29 seconds. This is expected since `expire_after_seconds=30` was specified in the `@cache` decorator.
+- The `expires` field and `max-age` value in the `cache-control` field indicate that this response will be considered fresh for 29 seconds. This is expected since `expire=30` was specified in the `@cache` decorator.
 - The `etag` field is an identifier that is created by converting the response data to a string and applying a hash function. If a request containing the `if-none-match` header is received, the `etag` value will be used to determine if the requested resource has been modified.
 
 If this request was made from a web browser, and a request for the same resource was sent before the cached response expires, the browser would automatically serve the cached version and the request would never even be sent to the FastAPI server.
@@ -126,27 +169,25 @@ Similarly, if a request is sent with the `cache-control` header containing `no-c
 
 #### Cache Keys
 
-Consider the `/get_user` API route defined below. This is the first path function we have seen where the response depends on the value of an argument (`user_id: int`). This is a typical CRUD operation where `user_id` is used to retrieve a `User` record from a SQLAlchemy database.
+Consider the `/get_user` API route defined below. This is the first path function we have seen where the response depends on the value of an argument (`user_id: int`). This is a typical CRUD operation where `user_id` is used to retrieve a `User` record from a database. The API route also includes a dependency that injects a `Session` object (`db`) into the function, [per the instructions from the FastAPI docs](https://fastapi.tiangolo.com/tutorial/sql-databases/#create-a-dependency):
 
 ```python
 @app.get("/get_user", response_model=schemas.User)
-@cache(expire_after_seconds=3600)
+@cache(expire=3600)
 def get_item(user_id: int, db: Session = Depends(get_db)):
     return db.query(models.User).filter(models.User.id == user_id).first()
 ```
 
-The API route also includes a dependency that injects a Session object (`db`) into the function, [per the instructions from the FastAPI docs](https://fastapi.tiangolo.com/tutorial/sql-databases/#create-a-dependency). This is used to query the database for the `User` corresponding to the `user_id` value.
-
 In the [Initialize Redis](#initialize-redis) section of this document, the `FastApiRedisCache.init` method was called with `ignore_arg_types=[Request, Response, Session]`. Why is it necessary to include `Session` in this list?
 
 Before we can answer that question, we must understand how a cache key is created. In order to create a unique identifier for the data sent in response to an API request, the following values are combined:
 
 1) The optional `prefix` value provided as an argument to the `FastApiRedisCache.init` method (`"myapi-cache"`).
 2) The module containing the path function (`"api"`).
 3) The name of the path function (`"get_user"`).
-4) The name and value of all arguments to the path function **EXCEPT for arguments with a type that exists in** `ignore_arg_types` (`"user_id=?"`).
+4) The name and value of all arguments to the path function **EXCEPT for arguments with a type that exists in** `ignore_arg_types` (`"user_id=1"`).
 
-Therefore, all response data for the `/get_user` endpoint will have a cache key equal to `"myapi-cache:api.get_user(user_id=?)"` (e.g., for `user_id=1`, the cache key will be `"myapi-cache:api.get_user(user_id=1)"`).
+Therefore, the cache key in this example will be `"myapi-cache:api.get_user(user_id=1)"`).
 
 Even though `db` is an argument to the path function, it is not included in the cache key because it is a `Session` type. If `Session` had not been included in the `ignore_arg_types` list, caching would be completely broken.
 
@@ -203,7 +244,6 @@ def get_scoreboard_for_date(
 
 The `game_date` argument is a `MLBGameDate` type. This is a custom type that parses the value from the querystring to a date, and determines if the parsed date is valid by checking if it is within a certain range. The implementation for `MLBGameDate` is given below:
 
-
 ```python
 class MLBGameDate:
     def __init__(
@@ -225,7 +265,7 @@ class MLBGameDate:
         return self.date.strftime("%Y-%m-%d")
 ```
 
-Please note the custom `__str__` method that overrides the default behavior. This way, instead of `<MLBGameDate object at 0x11c7e35e0>`, the value will be formatted as, for example, `2019-05-09`. You can use this strategy whenever you have an argument that has en effect on the response data but converting that argument to a string results in a value containing the object's memory location.
+Please note the `__str__` method that overrides the default behavior. This way, instead of `<MLBGameDate object at 0x11c7e35e0>`, the value will be formatted as, for example, `2019-05-09`. You can use this strategy whenever you have an argument that has en effect on the response data but converting that argument to a string results in a value containing the object's memory location.
 
 ### Questions/Contributions
 

requirements-dev.txt

@@ -1,69 +1,10 @@
-appdirs==1.4.4
-appnope==0.1.2
-asttokens==2.0.5
-async-timeout==3.0.1
-attrs==20.3.0
-backcall==0.2.0
 black==20.8b1
-certifi==2020.12.5
-chardet==4.0.0
-cheap-repr==0.4.5
-click==7.1.2
-colorclass==2.2.0
 coverage==5.5
-decorator==5.0.7
-distlib==0.3.1
-docopt==0.6.2
-executing==0.6.0
 fakeredis==1.5.0
-fastapi==0.63.0
-filelock==3.0.12
 flake8==3.9.1
-h11==0.12.0
-hiredis==2.0.0
-idna==2.10
-iniconfig==1.1.1
-ipython==7.22.0
-ipython-genutils==0.2.0
 isort==5.8.0
-jedi==0.18.0
-mccabe==0.6.1
-mypy-extensions==0.4.3
-packaging==20.9
-parso==0.8.2
-pathspec==0.8.1
-pexpect==4.8.0
-pickleshare==0.7.5
-pip-upgrader==1.4.15
-pluggy==0.13.1
-prompt-toolkit==3.0.18
-psutil==5.8.0
-ptyprocess==0.7.0
-py==1.10.0
-pycodestyle==2.7.0
-pydantic==1.8.1
-pyflakes==2.3.1
-Pygments==2.8.1
-pyparsing==2.4.7
 pytest==6.2.3
 pytest-cov==2.11.1
 pytest-flake8==1.0.7
 pytest-random-order==1.0.4
-python-dateutil==2.8.1
-redis==3.5.3
-regex==2021.4.4
 requests==2.25.1
-six==1.15.0
-snoop==0.3.0
-sortedcontainers==2.3.0
-starlette==0.13.6
-terminaltables==3.1.0
-toml==0.10.2
-tox==3.23.0
-traitlets==5.0.5
-typed-ast==1.4.3
-typing-extensions==3.7.4.3
-urllib3==1.26.4
-uvicorn==0.13.4
-virtualenv==20.4.4
-wcwidth==0.2.5

setup.cfg

@@ -12,13 +12,13 @@ addopts =
     --verbose
     # clear cache before each run
     --cache-clear
-    # randomize tests at the package level
-    --random-order-bucket=package
 norecursedirs =
     .git
     .pytest_cache
     .vscode
     venv
+    build
+    dist
     custom_scripts
 
 [flake8]

setup.py

@@ -21,6 +21,7 @@
     "Operating System :: MacOS :: MacOS X",
     "Operating System :: POSIX :: Linux",
     "Operating System :: Unix",
+    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3 :: Only",
@@ -31,6 +32,18 @@
     "python-dateutil",
     "redis",
 ]
+DEV_REQUIRES = [
+    "black",
+    "coverage",
+    "fakeredis",
+    "flake8",
+    "isort",
+    "pytest",
+    "pytest-cov",
+    "pytest-flake8",
+    "pytest-random-order",
+    "requests",
+]
 
 exec(open(str(APP_ROOT / "src/fastapi_redis_cache/version.py")).read())
 setup(
@@ -49,7 +62,8 @@
     packages=find_packages(where="src"),
     package_dir={"": "src"},
     include_package_data=True,
-    python_requires=">=3.8",
+    python_requires=">=3.7",
     classifiers=CLASSIFIERS,
     install_requires=INSTALL_REQUIRES,
+    extras_require={"dev": DEV_REQUIRES},
 )

src/fastapi_redis_cache/__init__.py

@@ -1,3 +1,11 @@
 # flake8: noqa
-from fastapi_redis_cache.cache import cache
+from fastapi_redis_cache.cache import (
+    cache,
+    cache_one_day,
+    cache_one_hour,
+    cache_one_minute,
+    cache_one_month,
+    cache_one_week,
+    cache_one_year,
+)
 from fastapi_redis_cache.client import FastApiRedisCache

src/fastapi_redis_cache/cache.py

@@ -1,28 +1,31 @@
 """cache.py"""
 import asyncio
 from datetime import timedelta
-from functools import wraps
+from functools import partial, update_wrapper, wraps
 from http import HTTPStatus
 from typing import Union
 
 from fastapi import Response
 
 from fastapi_redis_cache.client import FastApiRedisCache
+from fastapi_redis_cache.util import (
+    deserialize_json,
+    ONE_DAY_IN_SECONDS,
+    ONE_HOUR_IN_SECONDS,
+    ONE_MONTH_IN_SECONDS,
+    ONE_WEEK_IN_SECONDS,
+    ONE_YEAR_IN_SECONDS,
+    serialize_json,
+)
 
 
-def cache(*, expire_after_seconds: Union[int, timedelta] = None):
+def cache(*, expire: Union[int, timedelta] = ONE_YEAR_IN_SECONDS):
     """Enable caching behavior for the decorated function.
 
-    If no arguments are provided, this marks the response data for the decorated
-    path function as "never expires". In this case, the `Expires` and
-    `Cache-Control: max-age`  headers will be set to expire after one year.
-    Historically, this was the furthest time in the future that was allowed for
-    these fields. This is no longer the case, but it is still not advisable to use
-    values greater than one year.
-
     Args:
-        expire_after_seconds (Union[int, timedelta], optional): The number of seconds
-            from now when the cached response should expire. Defaults to None.
+        expire (Union[int, timedelta], optional): The number of seconds
+            from now when the cached response should expire. Defaults to 31,536,000
+            seconds (i.e., the number of seconds in one year).
     """
 
     def outer_wrapper(func):
@@ -33,32 +36,32 @@ async def inner_wrapper(*args, **kwargs):
             func_kwargs = kwargs.copy()
             request = func_kwargs.pop("request", None)
             response = func_kwargs.pop("response", None)
-            create_response_directly = False
-            if not response:
+            create_response_directly = not response
+            if create_response_directly:
                 response = Response()
-                create_response_directly = True
             redis_cache = FastApiRedisCache()
-
-            # if the redis client is not connected or request is not cacheable, no caching behavior is performed.
             if redis_cache.not_connected or redis_cache.request_is_not_cacheable(request):
+                # if the redis client is not connected or request is not cacheable, no caching behavior is performed.
                 return await get_api_response_async(func, *args, **kwargs)
             key = redis_cache.get_cache_key(func, *args, **kwargs)
             ttl, in_cache = redis_cache.check_cache(key)
             if in_cache:
                 if redis_cache.requested_resource_not_modified(request, in_cache):
                     response.status_code = int(HTTPStatus.NOT_MODIFIED)
                     return response
-                cached_data = redis_cache.deserialize_json(in_cache)
+                cached_data = deserialize_json(in_cache)
                 redis_cache.set_response_headers(response, cache_hit=True, response_data=cached_data, ttl=ttl)
                 if create_response_directly:
                     return Response(content=in_cache, media_type="application/json", headers=response.headers)
                 return cached_data
             response_data = await get_api_response_async(func, *args, **kwargs)
-            redis_cache.add_to_cache(key, response_data, expire_after_seconds)
-            redis_cache.set_response_headers(response, cache_hit=False, response_data=response_data, ttl=ttl)
+            ttl = calculate_ttl(expire)
+            cached = redis_cache.add_to_cache(key, response_data, ttl)
+            if cached:
+                redis_cache.set_response_headers(response, cache_hit=False, response_data=response_data, ttl=ttl)
             if create_response_directly:
                 return Response(
-                    content=redis_cache.serialize_json(response_data),
+                    content=serialize_json(response_data),
                     media_type="application/json",
                     headers=response.headers,
                 )
@@ -72,3 +75,24 @@ async def inner_wrapper(*args, **kwargs):
 async def get_api_response_async(func, *args, **kwargs):
     """Helper function that allows decorator to work with both async and non-async functions."""
     return await func(*args, **kwargs) if asyncio.iscoroutinefunction(func) else func(*args, **kwargs)
+
+
+def calculate_ttl(expire: Union[int, timedelta]) -> int:
+    if isinstance(expire, timedelta):
+        expire = int(expire.total_seconds())
+    return min(expire, ONE_YEAR_IN_SECONDS)
+
+
+cache_one_minute = partial(cache, expire=60)
+cache_one_hour = partial(cache, expire=ONE_HOUR_IN_SECONDS)
+cache_one_day = partial(cache, expire=ONE_DAY_IN_SECONDS)
+cache_one_week = partial(cache, expire=ONE_WEEK_IN_SECONDS)
+cache_one_month = partial(cache, expire=ONE_MONTH_IN_SECONDS)
+cache_one_year = partial(cache, expire=ONE_YEAR_IN_SECONDS)
+
+update_wrapper(cache_one_minute, cache)
+update_wrapper(cache_one_hour, cache)
+update_wrapper(cache_one_day, cache)
+update_wrapper(cache_one_week, cache)
+update_wrapper(cache_one_month, cache)
+update_wrapper(cache_one_year, cache)