Merge pull request #3081 from litestar-org/develop

chore: Release 2.6.0

docs/conf.py

@@ -178,6 +178,7 @@
     ("py:exc", "InternalServerError"),
     ("py:exc", "HTTPExceptions"),
     (PY_CLASS, "litestar.template.Template"),
+    (PY_CLASS, "litestar.middleware.compression.gzip_facade.GzipCompression"),
 ]
 
 nitpick_ignore_regex = [

docs/examples/plugins/di_plugin.py

@@ -0,0 +1,31 @@
+from inspect import Parameter, Signature
+from typing import Any, Dict, Tuple
+
+from litestar import Litestar, get
+from litestar.di import Provide
+from litestar.plugins import DIPlugin
+
+
+class MyBaseType:
+    def __init__(self, param):
+        self.param = param
+
+
+class MyDIPlugin(DIPlugin):
+    def has_typed_init(self, type_: Any) -> bool:
+        return issubclass(type_, MyBaseType)
+
+    def get_typed_init(self, type_: Any) -> Tuple[Signature, Dict[str, Any]]:
+        signature = Signature([Parameter(name="param", kind=Parameter.POSITIONAL_OR_KEYWORD)])
+        annotations = {"param": str}
+        return signature, annotations
+
+
+@get("/", dependencies={"injected": Provide(MyBaseType, sync_to_thread=False)})
+async def handler(injected: MyBaseType) -> str:
+    return injected.param
+
+
+app = Litestar(route_handlers=[handler], plugins=[MyDIPlugin()])
+
+# run: /?param=hello

docs/examples/static_files/custom_router.py

@@ -0,0 +1,18 @@
+from litestar import Litestar
+from litestar.router import Router
+from litestar.static_files import create_static_files_router
+
+
+class MyRouter(Router):
+    pass
+
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(
+            path="/static",
+            directories=["assets"],
+            router_class=MyRouter,
+        )
+    ]
+)

docs/examples/static_files/file_system.py

@@ -0,0 +1,14 @@
+from fsspec.implementations.ftp import FTPFileSystem
+
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(
+            path="/static",
+            directories=["assets"],
+            file_system=FTPFileSystem(host="127.0.0.1"),
+        ),
+    ]
+)

docs/examples/static_files/full_example.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+ASSETS_DIR = Path("assets")
+
+
+def on_startup():
+    ASSETS_DIR.mkdir(exist_ok=True)
+    ASSETS_DIR.joinpath("hello.txt").write_text("Hello, world!")
+
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(path="/static", directories=["assets"]),
+    ],
+    on_startup=[on_startup],
+)
+
+
+#  run: /static/hello.txt

docs/examples/static_files/html_mode.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+HTML_DIR = Path("html")
+
+
+def on_startup() -> None:
+    HTML_DIR.mkdir(exist_ok=True)
+    HTML_DIR.joinpath("index.html").write_text("<strong>Hello, world!</strong>")
+    HTML_DIR.joinpath("404.html").write_text("<h1>Not found</h1>")
+
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(
+            path="/",
+            directories=["html"],
+            html_mode=True,
+        )
+    ],
+    on_startup=[on_startup],
+)
+
+
+# run: /
+# run: /index.html
+# run: /something

docs/examples/static_files/passing_options.py

@@ -0,0 +1,14 @@
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(
+            path="/",
+            directories=["assets"],
+            opt={"some": True},
+            include_in_schema=False,
+            tags=["static"],
+        )
+    ]
+)

docs/examples/static_files/route_reverse.py

@@ -0,0 +1,11 @@
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(path="/static", directories=["assets"]),
+    ]
+)
+
+
+print(app.route_reverse(name="static", file_path="/some_file.txt"))  # /static/some_file.txt

docs/examples/static_files/send_as_attachment.py

@@ -0,0 +1,12 @@
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(
+            path="/static",
+            directories=["assets"],
+            send_as_attachment=True,
+        )
+    ]
+)

docs/examples/static_files/upgrade_from_static_1.py

@@ -0,0 +1,8 @@
+from litestar import Litestar
+from litestar.static_files.config import StaticFilesConfig
+
+app = Litestar(
+    static_files_config=[
+        StaticFilesConfig(directories=["assets"], path="/static"),
+    ],
+)

docs/examples/static_files/upgrade_from_static_2.py

@@ -0,0 +1,8 @@
+from litestar import Litestar
+from litestar.static_files import create_static_files_router
+
+app = Litestar(
+    route_handlers=[
+        create_static_files_router(directories=["assets"], path="/static"),
+    ],
+)

docs/usage/cli.rst

@@ -107,6 +107,10 @@ Options
 +-------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------+
 | ``-R``\ , ``--reload-dir``                | ``LITESTAR_RELOAD_DIRS``                     | Specify directories to watch for reload.                                         |
 +-------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------+
+| ``-I``\ , ``--reload-include``            | ``LITESTAR_RELOAD_INCLUDES``                 | Specify glob patterns for files to include when watching for reload.             |
++-------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------+
+| ``-E``\ , ``--reload-exclude``            | ``LITESTAR_RELOAD_EXCLUDES``                 | Specify glob patterns for files to exclude when watching for reload.             |
++-------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------+
 | ``-p``\ , ``--port``                      | ``LITESTAR_PORT``                            | Bind the server to this port [default: 8000]                                     |
 +-------------------------------------------+----------------------------------------------+----------------------------------------------------------------------------------+
 | ``--wc``\ , ``--web-concurrency``         | ``WEB_CONCURRENCY``                          | The number of concurrent web workers to start [default: 1]                       |
@@ -143,6 +147,40 @@ To set multiple directories via an environment variable, use a comma-separated l
 
    LITESTAR_RELOAD_DIRS=.,../other-library/src
 
+--reload-include
+++++++++++++++++
+
+The ``--reload-include`` flag allows you to specify glob patterns to include when watching for file changes. If you specify this flag, the ``--reload`` flag is implied. Furthermore, ``.py`` files are included implicitly by default.
+
+You can specify multiple glob patterns by passing the flag multiple times:
+
+.. code-block:: shell
+
+   litestar run --reload-include="*.rst" --reload-include="*.yml"
+
+To set multiple directories via an environment variable, use a comma-separated list:
+
+.. code-block:: shell
+
+   LITESTAR_RELOAD_INCLUDES=*.rst,*.yml
+
+--reload-exclude
+++++++++++++++++
+
+The ``--reload-exclude`` flag allows you to specify glob patterns to exclude when watching for file changes. If you specify this flag, the ``--reload`` flag is implied.
+
+You can specify multiple glob patterns by passing the flag multiple times:
+
+.. code-block:: shell
+
+   litestar run --reload-exclude="*.py" --reload-exclude="*.yml"
+
+To set multiple directories via an environment variable, use a comma-separated list:
+
+.. code-block:: shell
+
+   LITESTAR_RELOAD_EXCLUDES=*.py,*.yml
+
 SSL
 +++
 

docs/usage/logging.rst

@@ -113,12 +113,12 @@ Using StructLog
 ^^^^^^^^^^^^^^^
 
 `StructLog <https://www.structlog.org/en/stable/>`_ is a powerful structured-logging library. Litestar ships with a dedicated
-logging config for using it:
+logging plugin and config for using it:
 
 .. code-block:: python
 
    from litestar import Litestar, Request, get
-   from litestar.logging import StructLoggingConfig
+   from litestar.plugins.structlog import StructlogPlugin
 
 
    @get("/")
@@ -127,9 +127,9 @@ logging config for using it:
        return None
 
 
-   logging_config = StructLoggingConfig()
+   structlog_plugin = StructlogPlugin()
 
-   app = Litestar(route_handlers=[my_router_handler], logging_config=logging_config)
+   app = Litestar(route_handlers=[my_router_handler], plugins=[StructlogPlugin()])
 
 Subclass Logging Configs
 ^^^^^^^^^^^^^^^^^^^^^^^^

docs/usage/plugins.rst

@@ -19,7 +19,7 @@ that can interact with the data that is used to instantiate the application inst
 the contract for plugins that extend serialization functionality of the application.
 
 InitPluginProtocol
-~~~~~~~~~~~~~~~~~~
+------------------
 
 ``InitPluginProtocol`` defines an interface that allows for customization of the application's initialization process.
 Init plugins can define dependencies, add route handlers, configure middleware, and much more!
@@ -37,7 +37,7 @@ they are provided in the ``plugins`` argument of the :class:`app <litestar.app.L
 authors should make it clear in their documentation if their plugin should be invoked before or after other plugins.
 
 Example
--------
++++++++
 
 The following example shows a simple plugin that adds a route handler, and a dependency to the application.
 
@@ -54,7 +54,7 @@ is provided by the ``get_name()`` function, and ``route_handlers`` is updated to
 function. The modified :class:`AppConfig <litestar.config.app.AppConfig>` instance is then returned.
 
 SerializationPluginProtocol
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 The SerializationPluginProtocol defines a contract for plugins that provide serialization functionality for data types
 that are otherwise unsupported by the framework.
@@ -79,7 +79,7 @@ the plugin, and doesn't otherwise have a ``dto`` or ``return_dto`` defined, the
 that annotation.
 
 Example
--------
++++++++
 
 The following example shows the actual implementation of the ``SerializationPluginProtocol`` for
 `SQLAlchemy <https://www.sqlalchemy.org/>`_ models that is is provided in ``advanced_alchemy``.
@@ -106,3 +106,20 @@ subtypes are not created for the same model.
 
 If the annotation is not in the ``_type_dto_map`` dictionary, the method creates a new DTO type for the annotation,
 adds it to the ``_type_dto_map`` dictionary, and returns it.
+
+
+DIPlugin
+--------
+
+:class:`~litestar.plugins.DIPlugin` can be used to extend Litestar's dependency
+injection by providing information about injectable types.
+
+Its main purpose it to facilitate the injection of callables with unknown signatures,
+for example Pydantic's ``BaseModel`` classes; These are not supported natively since,
+while they are callables, their type information is not contained within their callable
+signature (their :func:`__init__` method).
+
+
+.. literalinclude:: /examples/plugins/di_plugin.py
+   :language: python
+   :caption: Dynamically generating signature information for a custom type