From 503d0b71704dd86f558a1eff048c1cd4dcbe5467 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 4 Mar 2024 09:39:18 -0600 Subject: [PATCH 1/5] docs: add plugin docs for flash messages --- docs/usage/Plugins/flash_messages.rst | 47 +++++++++++++++++++++++++++ docs/usage/index.rst | 2 +- litestar/plugins/flash.py | 33 ++++++++++++++++--- 3 files changed, 77 insertions(+), 5 deletions(-) create mode 100644 docs/usage/Plugins/flash_messages.rst diff --git a/docs/usage/Plugins/flash_messages.rst b/docs/usage/Plugins/flash_messages.rst new file mode 100644 index 0000000000..720a838e5b --- /dev/null +++ b/docs/usage/Plugins/flash_messages.rst @@ -0,0 +1,47 @@ +============== +Flash Messages +============== + +.. todo:: Document flash messages from https://github.com/litestar-org/litestar/pull/3145/ + +Registering the plugin +---------------------- + +.. todo:: Document registering the plugin from + +Adding Messages +--------------- + +.. todo:: Document adding messages to request scope + +Retrieving Messages +------------------- + +.. todo:: Document retrieving messages from request scope + +Using Messages in Templates +--------------------------- + +.. tab-set:: + + .. tab-item:: Jinja2 + + .. code-block:: html + :caption: Displaying flash messages in a Jinja2 template + + .. todo:: Add Jinja2 example + + .. tab-item:: Mako + + .. code-block:: html + :caption: Displaying flash messages in a Mako template + + + .. todo:: Add Mako example + + .. tab-item:: Mini-Jinja + + .. code-block:: html + :caption: Displaying flash messages in a Mini-Jinja template + + .. todo:: Add Mini-Jinja example diff --git a/docs/usage/index.rst b/docs/usage/index.rst index 632375c475..578797ee55 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -22,7 +22,7 @@ Usage metrics/index middleware/index openapi - plugins + plugins/indx responses security/index static-files diff --git a/litestar/plugins/flash.py b/litestar/plugins/flash.py index ff472b8077..6b61040120 100644 --- a/litestar/plugins/flash.py +++ b/litestar/plugins/flash.py @@ -1,3 +1,4 @@ +"""Plugin for creating and retrieving flash messages.""" from dataclasses import dataclass from typing import Any, Mapping @@ -21,11 +22,22 @@ class FlashPlugin(InitPluginProtocol): """Flash messages Plugin.""" def __init__(self, config: FlashConfig): - """Initialize the plugin.""" + """Initialize the plugin. + + Args: + config: Configuration for flash messages, including the template engine instance. + """ self.config = config def on_app_init(self, app_config: AppConfig) -> AppConfig: - """Register the message callable on the template engine instance.""" + """Register the message callable on the template engine instance. + + Args: + app_config: The application configuration. + + Returns: + The application configuration with the message callable registered. + """ if isinstance(self.config.template_config.engine_instance, MiniJinjaTemplateEngine): from litestar.contrib.minijinja import _transform_state @@ -38,12 +50,25 @@ def on_app_init(self, app_config: AppConfig) -> AppConfig: def flash(connection: ASGIConnection, message: str, category: str) -> None: - """Add a flash message to the request scope.""" + """Add a flash message to the request scope. + + Args: + connection: The connection instance. + message: The message to flash. + category: The category of the message. + """ scope_state = ScopeState.from_scope(connection.scope) scope_state.flash_messages.append({"message": message, "category": category}) def get_flashes(context: Mapping[str, Any]) -> Any: - """Get flash messages from the request scope, if any.""" + """Get flash messages from the request scope, if any. + + Args: + context: The context dictionary. + + Returns: + The flash messages, if any. + """ scope_state = ScopeState.from_scope(_get_request_from_context(context).scope) return scope_state.flash_messages From ef9bd5a05eacd3785e07f05af7e769fc07b273c2 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 4 Mar 2024 09:39:44 -0600 Subject: [PATCH 2/5] docs: add plugin docs for flash messages --- docs/usage/{plugins.rst => Plugins/index.rst} | 6 ++++++ 1 file changed, 6 insertions(+) rename docs/usage/{plugins.rst => Plugins/index.rst} (99%) diff --git a/docs/usage/plugins.rst b/docs/usage/Plugins/index.rst similarity index 99% rename from docs/usage/plugins.rst rename to docs/usage/Plugins/index.rst index 4911b8da23..4ba5ad2854 100644 --- a/docs/usage/plugins.rst +++ b/docs/usage/Plugins/index.rst @@ -1,3 +1,4 @@ +======= Plugins ======= @@ -123,3 +124,8 @@ signature (their :func:`__init__` method). .. literalinclude:: /examples/plugins/di_plugin.py :language: python :caption: Dynamically generating signature information for a custom type + +.. toctree:: + :titlesonly: + + flash_messages From 971e91fcc6622e685e668bcb3ddec2c51d743a10 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 4 Mar 2024 09:41:45 -0600 Subject: [PATCH 3/5] Update docs/usage/index.rst --- docs/usage/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/index.rst b/docs/usage/index.rst index 578797ee55..b19abc4ca4 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -22,7 +22,7 @@ Usage metrics/index middleware/index openapi - plugins/indx + plugins/index responses security/index static-files From 95aaa969bcf24deb479cc5537704b00e782c31a9 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 4 Mar 2024 09:47:09 -0600 Subject: [PATCH 4/5] fix: update file path --- docs/usage/Plugins/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/Plugins/index.rst b/docs/usage/Plugins/index.rst index 4ba5ad2854..ff0cdc1652 100644 --- a/docs/usage/Plugins/index.rst +++ b/docs/usage/Plugins/index.rst @@ -85,7 +85,7 @@ Example The following example shows the actual implementation of the ``SerializationPluginProtocol`` for `SQLAlchemy `_ models that is is provided in ``advanced_alchemy``. -.. literalinclude:: ../../litestar/contrib/sqlalchemy/plugins/serialization.py +.. literalinclude:: ../../../litestar/contrib/sqlalchemy/plugins/serialization.py :language: python :caption: ``SerializationPluginProtocol`` implementation example From 87e7d853cd160dc4bf4e9c4f7aac8439eb40d432 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Mon, 4 Mar 2024 09:49:33 -0600 Subject: [PATCH 5/5] fix: make sphinx gods happy --- docs/index.rst | 2 +- docs/usage/{Plugins => plugins}/flash_messages.rst | 0 docs/usage/{Plugins => plugins}/index.rst | 0 docs/usage/requests.rst | 2 +- 4 files changed, 2 insertions(+), 2 deletions(-) rename docs/usage/{Plugins => plugins}/flash_messages.rst (100%) rename docs/usage/{Plugins => plugins}/index.rst (100%) diff --git a/docs/index.rst b/docs/index.rst index be01d21e10..92953eec9b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ Litestar library documentation Litestar is a powerful, flexible, highly performant, and opinionated ASGI framework. -The Litestar framework supports :doc:`/usage/plugins`, ships +The Litestar framework supports :doc:`/usage/plugins/index`, ships with :doc:`dependency injection `, :doc:`security primitives `, :doc:`OpenAPI schema generation `, `MessagePack `_, :doc:`middlewares `, a great :doc:`CLI ` experience, and much more. diff --git a/docs/usage/Plugins/flash_messages.rst b/docs/usage/plugins/flash_messages.rst similarity index 100% rename from docs/usage/Plugins/flash_messages.rst rename to docs/usage/plugins/flash_messages.rst diff --git a/docs/usage/Plugins/index.rst b/docs/usage/plugins/index.rst similarity index 100% rename from docs/usage/Plugins/index.rst rename to docs/usage/plugins/index.rst diff --git a/docs/usage/requests.rst b/docs/usage/requests.rst index fdc65f2784..485748ac8c 100644 --- a/docs/usage/requests.rst +++ b/docs/usage/requests.rst @@ -17,7 +17,7 @@ The type of ``data`` an be any supported type, including * :class:`TypedDicts ` * Pydantic models * Arbitrary stdlib types -* Typed supported via :doc:`plugins ` +* Typed supported via :doc:`plugins ` .. literalinclude:: /examples/request_data/request_data_2.py :language: python