Merge pull request #128 from ZeroIntensity/caching

Stabilize Caching

Author: ZeroIntensity

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `templates` and `TemplatesConfig` to config
 - Added the `templates` function
 - Added support for `attrs` in type validation
+- Added documentation for caching
+- Added the `cache_rate` parameter to routers
 - Removed `psutil` and `plotext` as a global dependency
 - Added `fancy` optional dependencies
 - Fixed route inputs with synchronous routes

docs/building-projects/responses.md

@@ -13,6 +13,46 @@ app = new_app()
 async def index():
     return "Hello, view.py", 201, {"x-my-header": "my_header"}
 ```
+
+## Caching
+
+Sometimes, computing the response for a route can be expensive or unnecessary. For this, view.py, along with many other web frameworks, provide the ability to cache responses.
+
+View lets you do this by using the `cache_rate` parameter on a router.
+
+For example:
+
+```py
+from view import new_app
+
+app = new_app()
+
+@app.get("/", cache_rate=10)  # reload this route every 10 requests
+async def index():
+    return "..."
+
+app.run()
+```
+
+You can see this in more detail by using a route that changes it's responses:
+
+```py
+from view import new_app
+
+app = new_app()
+count = 1
+
+@app.get("/", cache_rate=10)
+async def index():
+    global count
+    count += 1
+    return str(count)
+
+app.run()
+```
+
+In the above example, `index` is only called every 10 requests, so after 20 calls, `count` would be `2`.
+
 ## Response Protocol
 
 If you have some sort of object that you want to wrap a response around, view.py gives you the `__view_response__` protocol. The only requirements are:

mkdocs.yml

@@ -5,17 +5,15 @@ repo_name: ZeroIntensity/view.py
 
 nav:
     - Home: index.md
-    - Getting Started:
-        - Installation: getting-started/installation.md
-        - Configuration: getting-started/configuration.md
-        - Project Creation: getting-started/creating_a_project.md
-    - Building Projects:
-        - App Basics: building-projects/app_basics.md
-        - Routing: building-projects/routing.md
-        - Returning Responses: building-projects/responses.md
-        - Taking Parameters: building-projects/parameters.md
-        - HTML Templating: building-projects/templating.md
-        - Writing Documentation: building-projects/documenting.md
+    - Installation: getting-started/installation.md
+    - Configuration: getting-started/configuration.md
+    - Project Creation: getting-started/creating_a_project.md
+    - App Basics: building-projects/app_basics.md
+    - Routing: building-projects/routing.md
+    - Returning Responses: building-projects/responses.md
+    - Taking Parameters: building-projects/parameters.md
+    - HTML Templating: building-projects/templating.md
+    - Writing Documentation: building-projects/documenting.md
 
 theme:
   name: material
@@ -47,7 +45,19 @@ theme:
         name: Switch to system preference
 
 markdown_extensions:
-  - admonition
+    - pymdownx.highlight:
+          anchor_linenums: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - admonition
+    - pymdownx.details
+    - pymdownx.tabbed:
+          alternate_style: true
+    - pymdownx.superfences:
+          custom_fences:
+              - name: mermaid
+                class: mermaid
+                format: !!python/name:pymdownx.superfences.fence_code_format
 
 plugins:
     - mkdocstrings:

src/view/app.py

@@ -319,39 +319,40 @@ def _method_wrapper(
         self,
         path: str,
         doc: str | None,
+        cache_rate: int,
         target: Callable[..., Any],
         # i dont really feel like typing this properly
     ) -> Callable[[RouteOrCallable], Route]:
         def inner(route: RouteOrCallable) -> Route:
-            new_route = target(path, doc)(route)
+            new_route = target(path, doc, cache_rate=cache_rate)(route)
             self._push_route(new_route)
             return new_route
 
         return inner
 
-    def get(self, path: str, *, doc: str | None = None):
+    def get(self, path: str, doc: str | None = None, *, cache_rate: int = -1):
         """Set a GET route."""
-        return self._method_wrapper(path, doc, get)
+        return self._method_wrapper(path, doc, cache_rate, get)
 
-    def post(self, path: str, *, doc: str | None = None):
+    def post(self, path: str, doc: str | None = None, *, cache_rate: int = -1):
         """Set a POST route."""
-        return self._method_wrapper(path, doc, post)
+        return self._method_wrapper(path, doc, cache_rate, post)
 
-    def delete(self, path: str, *, doc: str | None = None):
+    def delete(self, path: str, doc: str | None = None, *, cache_rate: int = -1):
         """Set a DELETE route."""
-        return self._method_wrapper(path, doc, delete)
+        return self._method_wrapper(path, doc, cache_rate, delete)
 
-    def patch(self, path: str, *, doc: str | None = None):
+    def patch(self, path: str, doc: str | None = None, *, cache_rate: int = -1,):
         """Set a PATCH route."""
-        return self._method_wrapper(path, doc, patch)
+        return self._method_wrapper(path, doc, cache_rate, patch)
 
-    def put(self, path: str, *, doc: str | None = None):
+    def put(self, path: str, doc: str | None = None, *, cache_rate: int = -1):
         """Set a PUT route."""
-        return self._method_wrapper(path, doc, put)
+        return self._method_wrapper(path, doc, cache_rate, put)
 
-    def options(self, path: str, *, doc: str | None = None):
+    def options(self, path: str, doc: str | None = None, *, cache_rate: int = -1):
         """Set a OPTIONS route."""
-        return self._method_wrapper(path, doc, options)
+        return self._method_wrapper(path, doc, cache_rate, options)
 
     def _set_log_arg(self, kwargs: _LogArgs, key: str) -> None:
         if key not in kwargs:

src/view/routing.py

@@ -8,8 +8,6 @@
 from enum import Enum
 from typing import Any, Callable, Generic, Type, TypeVar, Union
 
-from typing_extensions import ParamSpec
-
 from ._util import LoadChecker, make_hint
 from .exceptions import InvalidRouteError, MistakeError
 from .typing import Validator, ValueType, ViewResponse, ViewRoute
@@ -24,7 +22,6 @@
     "query",
     "body",
     "route_types",
-    "cache",
     "BodyParam",
 )
 
@@ -59,21 +56,17 @@ class RouteInput(Generic[V]):
     validators: list[Validator[V]]
 
 
-P = ParamSpec("P")
-T = TypeVar("T", bound="ViewResponse")
-
-
 @dataclass
 class Part(Generic[V]):
     name: str
     type: type[V] | None
 
 
 @dataclass
-class Route(Generic[P, T], LoadChecker):
+class Route(LoadChecker):
     """Standard Route Wrapper"""
 
-    func: Callable[P, T]
+    func: Callable[..., ViewResponse]
     path: str | None
     method: Method
     inputs: list[RouteInput]
@@ -98,24 +91,24 @@ def __repr__(self):
 
     __str__ = __repr__
 
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
         return self.func(*args, **kwargs)
 
 
-RouteOrCallable = Union[Route[P, T], ViewRoute[P, T]]
+RouteOrCallable = Union[Route, ViewRoute]
 
 
-def _ensure_route(r: RouteOrCallable[..., Any]) -> Route[..., Any]:
+def _ensure_route(r: RouteOrCallable) -> Route:
     if isinstance(r, Route):
         return r
 
     return Route(r, None, Method.GET, [])
 
 
 def route_types(
-    r: RouteOrCallable[P, T],
+    r: RouteOrCallable,
     data: type[Any] | tuple[type[Any]] | dict[str, Any],
-) -> Route[P, T]:
+) -> Route:
     route = _ensure_route(r)
     if isinstance(data, tuple):
         for i in data:
@@ -134,13 +127,15 @@ def route_types(
 
 
 def _method(
-    r: RouteOrCallable[P, T],
+    r: RouteOrCallable,
     raw_path: str | None,
     doc: str | None,
     method: Method,
-) -> Route[P, T]:
+    cache_rate: int
+) -> Route:
     route = _ensure_route(r)
     route.method = method
+    route.cache_rate = cache_rate
     util_path = raw_path or "/"
 
     if not util_path.startswith("/"):
@@ -203,19 +198,20 @@ def _method(
     return route
 
 
-Path = Callable[[RouteOrCallable[P, T]], Route[P, T]]
+Path = Callable[[RouteOrCallable], Route]
 
 
 def _method_wrapper(
-    path_or_route: str | None | RouteOrCallable[P, T],
+    path_or_route: str | None | RouteOrCallable,
     doc: str | None,
     method: Method,
-) -> Path[P, T]:
-    def inner(r: RouteOrCallable[P, T]) -> Route[P, T]:
+    cache_rate: int
+) -> Path:
+    def inner(r: RouteOrCallable) -> Route:
         if (not isinstance(path_or_route, str)) and path_or_route:
             raise TypeError(f"{path_or_route!r} is not a string")
 
-        return _method(r, path_or_route, doc, method)
+        return _method(r, path_or_route, doc, method, cache_rate)
 
     if not path_or_route:
         return inner
@@ -227,45 +223,57 @@ def inner(r: RouteOrCallable[P, T]) -> Route[P, T]:
 
 
 def get(
-    path_or_route: str | None | RouteOrCallable[P, T] = None,
+    path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
-) -> Path[P, T]:
-    return _method_wrapper(path_or_route, doc, Method.GET)
+    *,
+    cache_rate: int = -1,
+) -> Path:
+    return _method_wrapper(path_or_route, doc, Method.GET, cache_rate)
 
 
 def post(
     path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
+    *,
+    cache_rate: int = -1,
 ):
-    return _method_wrapper(path_or_route, doc, Method.POST)
+    return _method_wrapper(path_or_route, doc, Method.POST, cache_rate)
 
 
 def patch(
     path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
+    *,
+    cache_rate: int = -1,
 ):
-    return _method_wrapper(path_or_route, doc, Method.PATCH)
+    return _method_wrapper(path_or_route, doc, Method.PATCH, cache_rate)
 
 
 def put(
     path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
+    *,
+    cache_rate: int = -1,
 ):
-    return _method_wrapper(path_or_route, doc, Method.PUT)
+    return _method_wrapper(path_or_route, doc, Method.PUT, cache_rate)
 
 
 def delete(
     path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
+    *,
+    cache_rate: int = -1,
 ):
-    return _method_wrapper(path_or_route, doc, Method.DELETE)
+    return _method_wrapper(path_or_route, doc, Method.DELETE, cache_rate)
 
 
 def options(
     path_or_route: str | None | RouteOrCallable = None,
     doc: str | None = None,
+    *,
+    cache_rate: int = -1,
 ):
-    return _method_wrapper(path_or_route, doc, Method.OPTIONS)
+    return _method_wrapper(path_or_route, doc, Method.OPTIONS, cache_rate)
 
 
 class _NoDefault:
@@ -314,11 +322,3 @@ def inner(r: RouteOrCallable) -> Route:
 
     return inner
 
-
-def cache(amount: int):
-    def inner(r: RouteOrCallable) -> Route:
-        route = _ensure_route(r)
-        route.cache_rate = amount
-        return route
-
-    return inner

tests/test_app.py

@@ -5,7 +5,7 @@
 from typing_extensions import NotRequired
 from ward import test
 
-from view import BodyParam, Response, body, new_app, query
+from view import BodyParam, Response, body, new_app, query, get
 
 
 @test("responses")
@@ -541,6 +541,31 @@ async def index(test: Test):
         assert (await test.get("/", query={"test": {"a": "b", "b": 0, "c": [], "d": {"a": "b"}}})).status == 400
         assert (await test.get("/", query={"test": {"a": "b", "b": 0, "c": [], "d": {"a": 0}}})).message == "b"
 
+@test("caching")
+async def _():
+    app = new_app()
+    count = 0
+
+    @app.get("/param", cache_rate=10)
+    async def param():
+        nonlocal count
+        count += 1
+        return str(count)
+    
+    @get("/param_std", cache_rate=10)
+    async def param_std():
+        nonlocal count
+        count += 1
+        return str(count)
+    
+    
+    async with app.test() as test:
+        results = [(await test.get("/param")).message for _ in range(10)]
+        assert all(i == results[0] for i in results)
+        
+        results = [(await test.get("/param_std")).message for _ in range(10)]
+        assert all(i == results[0] for i in results)
+
 @test("synchronous route inputs")
 async def _():
     app = new_app()
@@ -565,3 +590,4 @@ def both(a: str, b: str):
         assert (await test.get("/", query={"test": "a"})).message == "a"
         assert (await test.get("/body", body={"test": "b"})).message == "b"
         assert (await test.get("/both", body={"a": "a"}, query={"b": "b"})).message == "ab"
+