feat: add cache store parameter on route level basis

.all-contributorsrc

@@ -1868,6 +1868,52 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "pogopaule",
+      "name": "Fabian",
+      "avatar_url": "https://avatars.githubusercontent.com/u/576949?v=4",
+      "profile": "https://github.com/pogopaule",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "mohammedbabelly20",
+      "name": "Mohammed Babelly",
+      "avatar_url": "https://avatars.githubusercontent.com/u/104768048?v=4",
+      "profile": "https://github.com/mohammedbabelly20",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "charles-dyfis-net",
+      "name": "Charles Duffy",
+      "avatar_url": "https://avatars.githubusercontent.com/u/22370?v=4",
+      "profile": "https://keybase.io/charlesdyfisnet",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "RenameMe1",
+      "name": "Evgeny Demchenko",
+      "avatar_url": "https://avatars.githubusercontent.com/u/165988121?v=4",
+      "profile": "https://github.com/RenameMe1",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "olzhasar",
+      "name": "Olzhas Arystanov",
+      "avatar_url": "https://avatars.githubusercontent.com/u/12471703?v=4",
+      "profile": "https://olzhasar.com",
+      "contributions": [
+        "bug",
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.devcontainer/Dockerfile

@@ -1,5 +1,5 @@
-# [Choice] Python version (use -bookworm or -bullseye variants on local arm64/Apple Silicon): 3, 3.11, 3.10, 3.9, 3.8, 3-bookworm, 3.11-bookworm, 3.10-bookworm, 3.9-bookworm, 3.8-bookworm, 3-bullseye, 3.11-bullseye, 3.10-bullseye, 3.9-bullseye, 3.8-bullseye, 3-buster, 3.11-buster, 3.10-buster, 3.9-buster, 3.8-buster
-ARG VARIANT=3-bookworm
+# [Choice] Python version (use -bookworm or -bullseye variants on local arm64/Apple Silicon): 3, 3.13, 3.12, 3.11, 3.10, 3.9, 3.8, 3-bookworm, 3.13-bookworm, 3.12-bookworm, 3.11-bookworm, 3.10-bookworm, 3.9-bookworm, 3.8-bookworm, 3-bullseye, 3.11-bullseye, 3.10-bullseye, 3.9-bullseye, 3.8-bullseye, 3-buster, 3.11-buster, 3.10-buster, 3.9-buster, 3.8-buster
+ARG VARIANT=3.12-bookworm
 FROM python:${VARIANT}
 
 RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \

.github/workflows/ci.yml

@@ -349,7 +349,7 @@ jobs:
         run: sed -i "s/home\/runner\/work\/litestar\/litestar/github\/workspace/g" coverage.xml
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           files: coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/pr-merged.yml

@@ -19,11 +19,8 @@ jobs:
           script: |
             const prNumber = context.payload.number
             const branch = context.baseRef
-            # TODO: `develop` no longer exists. Need a new way to determine if the
-            # change will be introduced in a major, minor, or patch release.
-            # possibly conventional commit standards in the PR title or by labels?
-            const isDevelop = branch === "develop"
-            const commentBody = `<!--closing-comment-->\nThis issue has been closed in #${prNumber}. The change will be included in the upcoming ${isDevelop ? "minor" : "patch"} release.`
+            // TODO: use semantic commits to specify the exact version, when it will be released
+            const commentBody = `<!--closing-comment-->\nThis issue has been closed in #${prNumber}. The change will be included in upcoming releases.`
 
             const query = `query($number: Int!, $owner: String!, $name: String!) { repository(owner: $owner, name: $name) {
                 pullRequest(number: $number) {

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 default_language_version:
-  python: "3.8"
+  python: "3"
 repos:
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v3.4.0
+    rev: v3.6.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
@@ -24,7 +24,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.6.2"
+    rev: "v0.7.3"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -43,7 +43,7 @@ repos:
         exclude: "test*|examples*|tools"
         args: ["--use-tuple"]
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: "v0.9.1"
+    rev: "v1.0.0"
     hooks:
       - id: sphinx-lint
   - repo: local

CONTRIBUTING.rst

@@ -276,6 +276,7 @@ Please follow the next guidelines when adding a new example:
    :caption: An example of how to use literal includes of external files
 
    .. literalinclude:: /examples/test_thing.py
+      :language: python
       :caption: All includes should have a descriptive caption
 
 Automatically execute examples

README.md

@@ -106,13 +106,11 @@ app = Litestar(route_handlers=[hello_world])
 <details>
 <summary>Pre-built Example Apps</summary>
 
-- [litestar-pg-redis-docker](https://github.com/litestar-org/litestar-pg-redis-docker): In addition to Litestar, this
-  demonstrates a pattern of application modularity, SQLAlchemy 2.0 ORM, Redis cache connectivity, and more. Like all
-  Litestar projects, this application is open to contributions, big and small.
-- [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack): A reference application that contains most of the boilerplate required for a web application.
-  It features a Litestar app configured with best practices, SQLAlchemy 2.0 and SAQ, a frontend integrated with Vitejs and Jinja2 templates, Docker, and more.
 - [litestar-hello-world](https://github.com/litestar-org/litestar-hello-world): A bare-minimum application setup. Great
 for testing and POC work.
+- [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack): A reference application that contains most of the boilerplate required for a web application.
+  It features a Litestar app configured with best practices, SQLAlchemy 2.0 and SAQ, a frontend integrated with Vitejs and Jinja2 templates, Docker, and more. Like all
+  Litestar projects, this application is open to contributions, big and small.
 </details>
 
 ## Sponsors
@@ -578,6 +576,13 @@ see [the contribution guide](CONTRIBUTING.rst).
       <td align="center" valign="top" width="14.28%"><a href="https://blog.trim21.me/"><img src="https://avatars.githubusercontent.com/u/13553903?v=4?s=100" width="100px;" alt="Trim21"/><br /><sub><b>Trim21</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=trim21" title="Code">💻</a> <a href="https://github.com/litestar-org/litestar/commits?author=trim21" title="Tests">⚠️</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://aarcex3.github.io"><img src="https://avatars.githubusercontent.com/u/59893355?v=4?s=100" width="100px;" alt="Agustin Arce"/><br /><sub><b>Agustin Arce</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=aarcex3" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/FarhanAliRaza"><img src="https://avatars.githubusercontent.com/u/62690310?v=4?s=100" width="100px;" alt="Farhan Ali Raza"/><br /><sub><b>Farhan Ali Raza</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=FarhanAliRaza" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/pogopaule"><img src="https://avatars.githubusercontent.com/u/576949?v=4?s=100" width="100px;" alt="Fabian"/><br /><sub><b>Fabian</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=pogopaule" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mohammedbabelly20"><img src="https://avatars.githubusercontent.com/u/104768048?v=4?s=100" width="100px;" alt="Mohammed Babelly"/><br /><sub><b>Mohammed Babelly</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=mohammedbabelly20" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://keybase.io/charlesdyfisnet"><img src="https://avatars.githubusercontent.com/u/22370?v=4?s=100" width="100px;" alt="Charles Duffy"/><br /><sub><b>Charles Duffy</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=charles-dyfis-net" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/RenameMe1"><img src="https://avatars.githubusercontent.com/u/165988121?v=4?s=100" width="100px;" alt="Evgeny Demchenko"/><br /><sub><b>Evgeny Demchenko</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=RenameMe1" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://olzhasar.com"><img src="https://avatars.githubusercontent.com/u/12471703?v=4?s=100" width="100px;" alt="Olzhas Arystanov"/><br /><sub><b>Olzhas Arystanov</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/issues?q=author%3Aolzhasar" title="Bug reports">🐛</a> <a href="https://github.com/litestar-org/litestar/commits?author=olzhasar" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>

docs/PYPI_README.md

@@ -103,13 +103,11 @@ app = Litestar(route_handlers=[hello_world])
 <details>
 <summary>Pre-built Example Apps</summary>
 
-- [litestar-pg-redis-docker](https://github.com/litestar-org/litestar-pg-redis-docker): In addition to Litestar, this
-  demonstrates a pattern of application modularity, SQLAlchemy 2.0 ORM, Redis cache connectivity, and more. Like all
-  Litestar projects, this application is open to contributions, big and small.
-- [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack): A reference application that contains most of the boilerplate required for a web application.
-  It features a Litestar app configured with best practices, SQLAlchemy 2.0 and SAQ, a frontend integrated with Vitejs and Jinja2 templates, Docker, and more.
 - [litestar-hello-world](https://github.com/litestar-org/litestar-hello-world): A bare-minimum application setup. Great
 for testing and POC work.
+- [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack): A reference application that contains most of the boilerplate required for a web application.
+  It features a Litestar app configured with best practices, SQLAlchemy 2.0 and SAQ, a frontend integrated with Vitejs and Jinja2 templates, Docker, and more. Like all
+  Litestar projects, this application is open to contributions, big and small.
 </details>
 
 ## Sponsors

docs/admonitions/sync-to-thread-info.rst

@@ -7,8 +7,11 @@
     running the event loop, and in turn block the whole application.
 
     To mitigate this, the ``sync_to_thread`` parameter can be set to ``True``, which
-    will result in the function being run in a thread pool. Should the function be
-    non-blocking, ``sync_to_thread`` should be set to ``False`` instead.
+    will result in the function being run in a thread pool.
+
+    If a synchronous function is non-blocking, setting ``sync_to_thread`` to ``False``
+    will tell Litestar that the user is sure about its behavior
+    and the function can be treated as non-blocking.
 
     If a synchronous function is passed, without setting an explicit ``sync_to_thread``
     value, a warning will be raised.

docs/conf.py

@@ -159,6 +159,7 @@
     (PY_CLASS, "litestar.contrib.sqlalchemy.dto.SQLAlchemyDTO"),
     (PY_CLASS, "litestar.contrib.sqlalchemy.types.BigIntIdentity"),
     (PY_CLASS, "litestar.contrib.sqlalchemy.types.JsonB"),
+    (PY_CLASS, "litestar.contrib.htmx.request.HTMXRequest"),
     (PY_CLASS, "litestar.typing.ParsedType"),
     (PY_METH, "litestar.dto.factory.DTOData.create_instance"),
     (PY_METH, "litestar.dto.interface.DTOInterface.data_to_encodable_type"),
@@ -191,6 +192,16 @@
     (PY_CLASS, "litestar.template.Template"),
     (PY_CLASS, "litestar.middleware.compression.gzip_facade.GzipCompression"),
     (PY_CLASS, "litestar.handlers.http_handlers.decorators._subclass_warning"),
+    (PY_CLASS, "litestar.background_tasks.P"),
+    (PY_CLASS, "P.args"),
+    (PY_CLASS, "P.kwargs"),
+    (PY_CLASS, "litestar.contrib.jinja.P"),
+    (PY_CLASS, "litestar.contrib.mako.P"),
+    (PY_CLASS, "JWTDecodeOptions"),
+    (PY_CLASS, "litestar.template.base.P"),
+    (PY_CLASS, "litestar.contrib.pydantic.PydanticDTO"),
+    (PY_CLASS, "litestar.contrib.pydantic.PydanticPlugin"),
+    (PY_CLASS, "typing.Self"),
 ]
 
 nitpick_ignore_regex = [

docs/examples/contrib/sqlalchemy/sqlalchemy_async_repository.py

@@ -34,8 +34,8 @@ class BaseModel(_BaseModel):
     model_config = {"from_attributes": True}
 
 
-# the SQLAlchemy base includes a declarative model for you to use in your models.
-# The `Base` class includes a `UUID` based primary key (`id`)
+# The SQLAlchemy base includes a declarative model for you to use in your models.
+# The `UUIDBase` class includes a `UUID` based primary key (`id`)
 class AuthorModel(base.UUIDBase):
     # we can optionally provide the table name instead of auto-generating it
     __tablename__ = "author"  #  type: ignore[assignment]
@@ -44,9 +44,9 @@ class AuthorModel(base.UUIDBase):
     books: Mapped[list[BookModel]] = relationship(back_populates="author", lazy="noload")
 
 
-# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2
-# additional columns: `created` and `updated`. `created` is a timestamp of when the
-# record created, and `updated` is the last time the record was modified.
+# The `UUIDAuditBase` class includes the same UUID` based primary key (`id`) and 2
+# additional columns: `created_at` and `updated_at`. `created_at` is a timestamp of when the
+# record created, and `updated_at` is the last time the record was modified.
 class BookModel(base.UUIDAuditBase):
     __tablename__ = "book"  #  type: ignore[assignment]
     title: Mapped[str]

docs/examples/contrib/sqlalchemy/sqlalchemy_declarative_models.py

@@ -14,15 +14,15 @@
 from litestar.contrib.sqlalchemy.plugins import AsyncSessionConfig, SQLAlchemyAsyncConfig, SQLAlchemyPlugin
 
 
-# the SQLAlchemy base includes a declarative model for you to use in your models.
-# The `Base` class includes a `UUID` based primary key (`id`)
+# The SQLAlchemy base includes a declarative model for you to use in your models.
+# The `UUIDBase` class includes a `UUID` based primary key (`id`)
 class Author(UUIDBase):
     name: Mapped[str]
     dob: Mapped[date]
     books: Mapped[List[Book]] = relationship(back_populates="author", lazy="selectin")
 
 
-# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2
+# The `UUIDAuditBase` class includes the same UUID` based primary key (`id`) and 2
 # additional columns: `created_at` and `updated_at`. `created_at` is a timestamp of when the
 # record created, and `updated_at` is the last time the record was modified.
 class Book(UUIDAuditBase):

docs/examples/contrib/sqlalchemy/sqlalchemy_repository_extension.py

@@ -96,9 +96,9 @@ async def _is_slug_unique(
         return await self.get_one_or_none(slug=slug) is None
 
 
-# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2
-# additional columns: `created` and `updated`. `created` is a timestamp of when the
-# record created, and `updated` is the last time the record was modified.
+# The `UUIDAuditBase` class includes the same UUID` based primary key (`id`) and 2
+# additional columns: `created_at` and `updated_at`. `created_at` is a timestamp of when the
+# record created, and `updated_at` is the last time the record was modified.
 class BlogPost(UUIDAuditBase, SlugKey):
     title: Mapped[str]
     content: Mapped[str]

docs/examples/contrib/sqlalchemy/sqlalchemy_sync_repository.py

@@ -30,8 +30,8 @@ class BaseModel(_BaseModel):
     model_config = {"from_attributes": True}
 
 
-# the SQLAlchemy base includes a declarative model for you to use in your models.
-# The `Base` class includes a `UUID` based primary key (`id`)
+# The SQLAlchemy base includes a declarative model for you to use in your models.
+# The `UUIDBase` class includes a `UUID` based primary key (`id`)
 class AuthorModel(UUIDBase):
     # we can optionally provide the table name instead of auto-generating it
     __tablename__ = "author"  #  type: ignore[assignment]
@@ -40,9 +40,9 @@ class AuthorModel(UUIDBase):
     books: Mapped[list[BookModel]] = relationship(back_populates="author", lazy="noload")
 
 
-# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2
-# additional columns: `created` and `updated`. `created` is a timestamp of when the
-# record created, and `updated` is the last time the record was modified.
+# The `UUIDAuditBase` class includes the same UUID` based primary key (`id`) and 2
+# additional columns: `created_at` and `updated_at`. `created_at` is a timestamp of when the
+# record created, and `updated_at` is the last time the record was modified.
 class BookModel(UUIDAuditBase):
     __tablename__ = "book"  #  type: ignore[assignment]
     title: Mapped[str]

docs/examples/data_transfer_objects/factory/patch_requests.py

@@ -20,17 +20,14 @@ class PatchDTO(DataclassDTO[Person]):
     config = DTOConfig(exclude={"id"}, partial=True)
 
 
-database = {
-    UUID("f32ff2ce-e32f-4537-9dc0-26e7599f1380"): Person(
-        id=UUID("f32ff2ce-e32f-4537-9dc0-26e7599f1380"), name="Peter", age=40
-    )
-}
+peter_uuid = UUID("f32ff2ce-e32f-4537-9dc0-26e7599f1380")
+database = {peter_uuid: Person(id=peter_uuid, name="Peter", age=40)}
 
 
 @patch("/person/{person_id:uuid}", dto=PatchDTO, return_dto=None, sync_to_thread=False)
 def update_person(person_id: UUID, data: DTOData[Person]) -> Person:
-    """Create a person."""
-    return data.update_instance(database.get(person_id))
+    """Partially update a person."""
+    return data.update_instance(database[person_id])
 
 
 app = Litestar(route_handlers=[update_person])

docs/examples/middleware/base.py

@@ -1,46 +1,38 @@
-from time import time
-from typing import TYPE_CHECKING, Dict
+import time
+from typing import Dict
 
-from litestar import Litestar, get, websocket
+from litestar import Litestar, WebSocket, get, websocket
 from litestar.datastructures import MutableScopeHeaders
 from litestar.enums import ScopeType
 from litestar.middleware import AbstractMiddleware
-
-if TYPE_CHECKING:
-    from litestar import WebSocket
-    from litestar.types import Message, Receive, Scope, Send
+from litestar.types import Message, Receive, Scope, Send
 
 
 class MyMiddleware(AbstractMiddleware):
     scopes = {ScopeType.HTTP}
     exclude = ["first_path", "second_path"]
-    exclude_opt_key = "exclude_from_middleware"
+    exclude_opt_key = "exclude_from_my_middleware"
 
-    async def __call__(
-        self,
-        scope: "Scope",
-        receive: "Receive",
-        send: "Send",
-    ) -> None:
-        start_time = time()
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        start_time = time.monotonic()
 
         async def send_wrapper(message: "Message") -> None:
             if message["type"] == "http.response.start":
-                process_time = time() - start_time
+                process_time = time.monotonic() - start_time
                 headers = MutableScopeHeaders.from_message(message=message)
                 headers["X-Process-Time"] = str(process_time)
-                await send(message)
+            await send(message)
 
         await self.app(scope, receive, send_wrapper)
 
 
 @websocket("/my-websocket")
-async def websocket_handler(socket: "WebSocket") -> None:
+async def websocket_handler(socket: WebSocket) -> None:
     """
     Websocket handler - is excluded because the middleware scopes includes 'ScopeType.HTTP'
     """
     await socket.accept()
-    await socket.send_json({"hello websocket"})
+    await socket.send_json({"hello": "websocket"})
     await socket.close()
 
 
@@ -56,10 +48,10 @@ def second_handler() -> Dict[str, str]:
     return {"hello": "second"}
 
 
-@get("/third_path", exclude_from_middleware=True, sync_to_thread=False)
+@get("/third_path", exclude_from_my_middleware=True, sync_to_thread=False)
 def third_handler() -> Dict[str, str]:
-    """Handler is excluded due to the opt key 'exclude_from_middleware' matching the middleware 'exclude_opt_key'."""
-    return {"hello": "second"}
+    """Handler is excluded due to the opt key 'exclude_from_my_middleware' matching the middleware 'exclude_opt_key'."""
+    return {"hello": "third"}
 
 
 @get("/greet", sync_to_thread=False)