From 291bd49ca30953d0f59fedf867d43a245082b6d9 Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Mon, 21 Oct 2024 17:54:34 +0000 Subject: [PATCH] fix: updated documentation --- docs/conf.py | 1 + docs/reference/plugins/htmx.rst | 7 ++++ docs/reference/plugins/index.rst | 1 + docs/usage/htmx.rst | 57 +++++++++++++++++++++++--------- pdm.lock | 20 +++++------ pyproject.toml | 4 +-- 6 files changed, 63 insertions(+), 27 deletions(-) create mode 100644 docs/reference/plugins/htmx.rst diff --git a/docs/conf.py b/docs/conf.py index 75e59710e1..54f16e8739 100644 --- a/docs/conf.py +++ b/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"), diff --git a/docs/reference/plugins/htmx.rst b/docs/reference/plugins/htmx.rst new file mode 100644 index 0000000000..d13083ec7e --- /dev/null +++ b/docs/reference/plugins/htmx.rst @@ -0,0 +1,7 @@ +==== +htmx +==== + + +.. automodule:: litestar.plugins.htmx + :members: diff --git a/docs/reference/plugins/index.rst b/docs/reference/plugins/index.rst index d3bdcecc5b..3bc07cc757 100644 --- a/docs/reference/plugins/index.rst +++ b/docs/reference/plugins/index.rst @@ -10,6 +10,7 @@ plugins :hidden: flash_messages + htmx problem_details structlog sqlalchemy diff --git a/docs/usage/htmx.rst b/docs/usage/htmx.rst index 59ad9baa2c..7dd2b28374 100644 --- a/docs/usage/htmx.rst +++ b/docs/usage/htmx.rst @@ -8,16 +8,43 @@ HTMX is a JavaScript library that gives you access to AJAX, CSS Transitions, Web This section assumes that you have prior knowledge of HTMX. If you want to learn HTMX, we recommend consulting their `official tutorial `_. +HTMXPlugin +------------ + +a Litestar plugin ``HTMXPlugin`` is available to easily configure the default request class for all Litestar routes. + +.. code-block:: python + + from litestar.plugins.htmx import HTMXPlugin + from litestar import Litestar + + from litestar.contrib.jinja import JinjaTemplateEngine + from litestar.template.config import TemplateConfig + + from pathlib import Path + + app = Litestar( + route_handlers=[get_form], + debug=True, + plugins=[HTMXPlugin()], + template_config=TemplateConfig( + directory=Path("litestar_htmx/templates"), + engine=JinjaTemplateEngine, + ), + ) + +See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of +available properties. + HTMXRequest ------------ A special :class:`~litestar.connection.Request` class, providing interaction with the -HTMX client. +HTMX client. You can configure this globally by using the ``HTMXPlugin`` or by setting the `request_class` setting on any route, controller, router, or application. .. code-block:: python - from litestar.contrib.htmx.request import HTMXRequest - from litestar.contrib.htmx.response import HTMXTemplate + from litestar.plugins.htmx import HTMXRequest, HTMXTemplate from litestar import get, Litestar from litestar.response import Template @@ -45,7 +72,7 @@ HTMX client. ), ) -See :class:`~litestar.contrib.htmx.request.HTMXDetails` for a full list of +See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of available properties. @@ -57,11 +84,11 @@ HTMXTemplate Response Classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most common use-case for HTMX to render an html page or html snippet. Litestar makes this easy by providing -an :class:`~litestar.contrib.htmx.response.HTMXTemplate` response: +an :class:`~litestar.plugins.htmx.HTMXTemplate` response: .. code-block:: python - from litestar.contrib.htmx.response import HTMXTemplate + from litestar.plugins.htmx import HTMXTemplate from litestar.response import Template @@ -94,7 +121,7 @@ Litestar supports both of these: 1 - Responses that don't make any changes to DOM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use :class:`~litestar.contrib.htmx.response.HXStopPolling` to stop polling for a response. +Use :class:`~litestar.plugins.htmx.HXStopPolling` to stop polling for a response. .. code-block:: python @@ -103,7 +130,7 @@ Use :class:`~litestar.contrib.htmx.response.HXStopPolling` to stop polling for a ... return HXStopPolling() -Use :class:`~litestar.contrib.htmx.response.ClientRedirect` to redirect with a page reload. +Use :class:`~litestar.plugins.htmx.ClientRedirect` to redirect with a page reload. .. code-block:: python @@ -112,7 +139,7 @@ Use :class:`~litestar.contrib.htmx.response.ClientRedirect` to redirect with a p ... return ClientRedirect(redirect_to="/contact-us") -Use :class:`~litestar.contrib.htmx.response.ClientRefresh` to force a full page refresh. +Use :class:`~litestar.plugins.htmx.ClientRefresh` to force a full page refresh. .. code-block:: python @@ -124,7 +151,7 @@ Use :class:`~litestar.contrib.htmx.response.ClientRefresh` to force a full page 2 - Responses that may change DOM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use :class:`~litestar.contrib.htmx.response.HXLocation` to redirect to a new location without page reload. +Use :class:`~litestar.plugins.htmx.HXLocation` to redirect to a new location without page reload. .. note:: This class provides the ability to change ``target``, ``swapping`` method, the sent ``values``, and the ``headers``. @@ -144,7 +171,7 @@ Use :class:`~litestar.contrib.htmx.response.HXLocation` to redirect to a new loc values={"val": "one"}, ) # values to submit with response. -Use :class:`~litestar.contrib.htmx.response.PushUrl` to carry a response and push a url to the browser, optionally updating the ``history`` stack. +Use :class:`~litestar.plugins.htmx.PushUrl` to carry a response and push a url to the browser, optionally updating the ``history`` stack. .. note:: If the value for ``push_url`` is set to ``False`` it will prevent updating browser history. @@ -155,7 +182,7 @@ Use :class:`~litestar.contrib.htmx.response.PushUrl` to carry a response and pus ... return PushUrl(content="Success!", push_url="/about") -Use :class:`~litestar.contrib.htmx.response.ReplaceUrl` to carry a response and replace the url in the browser's ``location`` bar. +Use :class:`~litestar.plugins.htmx.ReplaceUrl` to carry a response and replace the url in the browser's ``location`` bar. .. note:: If the value to ``replace_url`` is set to ``False`` it will prevent updating the browser's location. @@ -166,7 +193,7 @@ Use :class:`~litestar.contrib.htmx.response.ReplaceUrl` to carry a response and ... return ReplaceUrl(content="Success!", replace_url="/contact-us") -Use :class:`~litestar.contrib.htmx.response.Reswap` to carry a response with a possible swap. +Use :class:`~litestar.plugins.htmx.Reswap` to carry a response with a possible swap. .. code-block:: python @@ -175,7 +202,7 @@ Use :class:`~litestar.contrib.htmx.response.Reswap` to carry a response with a p ... return Reswap(content="Success!", method="beforebegin") -Use :class:`~litestar.contrib.htmx.response.Retarget` to carry a response and change the target element. +Use :class:`~litestar.plugins.htmx.Retarget` to carry a response and change the target element. .. code-block:: python @@ -184,7 +211,7 @@ Use :class:`~litestar.contrib.htmx.response.Retarget` to carry a response and ch ... return Retarget(content="Success!", target="#new-target") -Use :class:`~litestar.contrib.htmx.response.TriggerEvent` to carry a response and trigger an event. +Use :class:`~litestar.plugins.htmx.TriggerEvent` to carry a response and trigger an event. .. code-block:: python diff --git a/pdm.lock b/pdm.lock index 7cce8bf30e..c4c2c6ef57 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "annotated-types", "attrs", "brotli", "cli", "cryptography", "dev", "dev-contrib", "docs", "full", "htmx", "jinja", "jwt", "linting", "mako", "minijinja", "opentelemetry", "piccolo", "picologging", "prometheus", "pydantic", "redis", "sqlalchemy", "standard", "structlog", "test"] strategy = ["inherit_metadata"] lock_version = "4.5.0" -content_hash = "sha256:7007c231002b8178dface123299b490c4ecd27e3fc00dc213ee5cc7a3fc2aa8a" +content_hash = "sha256:50a1dda60c649831173720ebfbdbc1252b4cb25bcb6f0b5db285bf0582469dba" [[metadata.targets]] requires_python = "~=3.8" @@ -1235,7 +1235,7 @@ files = [ [[package]] name = "faker" -version = "30.6.0" +version = "30.8.0" requires_python = ">=3.8" summary = "Faker is a Python package that generates fake data for you." groups = ["default"] @@ -1244,8 +1244,8 @@ dependencies = [ "typing-extensions", ] files = [ - {file = "Faker-30.6.0-py3-none-any.whl", hash = "sha256:37b5ab951f7367ea93edb865120e9717a7a649d6a4b223f1e4a47a8a20d9e85f"}, - {file = "faker-30.6.0.tar.gz", hash = "sha256:be0e548352c1be6f6d9c982003848a0d305868f160bb1fb7f945acffc347e676"}, + {file = "Faker-30.8.0-py3-none-any.whl", hash = "sha256:4cd0c5ea4bc1e4c902967f6e662f5f5da69f1674d9a94f54e516d27f3c2a6a16"}, + {file = "faker-30.8.0.tar.gz", hash = "sha256:3608c7fcac2acde0eaa6da28dae97628f18f14d54eaa2a92b96ae006f1621bd7"}, ] [[package]] @@ -1286,13 +1286,13 @@ files = [ [[package]] name = "fsspec" -version = "2024.9.0" +version = "2024.10.0" requires_python = ">=3.8" summary = "File-system specification" groups = ["dev"] files = [ - {file = "fsspec-2024.9.0-py3-none-any.whl", hash = "sha256:a0947d552d8a6efa72cc2c730b12c41d043509156966cca4fb157b0f2a0c574b"}, - {file = "fsspec-2024.9.0.tar.gz", hash = "sha256:4b0afb90c2f21832df142f292649035d80b421f60a9e1c027802e5a0da2b04e8"}, + {file = "fsspec-2024.10.0-py3-none-any.whl", hash = "sha256:03b9a6785766a4de40368b88906366755e2819e758b83705c88cd7cb5fe81871"}, + {file = "fsspec-2024.10.0.tar.gz", hash = "sha256:eda2d8a4116d4f2429db8550f2457da57279247dd930bb12f821b58391359493"}, ] [[package]] @@ -1908,7 +1908,7 @@ files = [ [[package]] name = "litestar-htmx" -version = "0.2.1" +version = "0.2.2" requires_python = "<4.0,>=3.8" summary = "HTMX Integration for Litesstar" groups = ["default", "htmx"] @@ -1916,8 +1916,8 @@ dependencies = [ "litestar", ] files = [ - {file = "litestar_htmx-0.2.1-py3-none-any.whl", hash = "sha256:1a502c1c4afbc29025207e64c61f7efddabf7fcf23738fd90aaeffa7008bbd68"}, - {file = "litestar_htmx-0.2.1.tar.gz", hash = "sha256:336f6888c257e51e37ada639d03fdd080155728661428c541767c505881d756b"}, + {file = "litestar_htmx-0.2.2-py3-none-any.whl", hash = "sha256:07ae864f92674d5974f5bc617b962f22609d6813eec4f0b302649a0e6af5d70f"}, + {file = "litestar_htmx-0.2.2.tar.gz", hash = "sha256:40d842329f93c55b1d97cefa719816f11815858f38d67e8f71fb259a8368584f"}, ] [[package]] diff --git a/pyproject.toml b/pyproject.toml index 91a952801a..ac5a3a1035 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,7 +45,7 @@ dependencies = [ "rich>=13.0.0", "rich-click", # default litestar plugins - "litestar-htmx>=0.2.1" + "litestar-htmx>=0.2.2" ] description = "Litestar - A production-ready, highly performant, extensible ASGI API Framework" keywords = ["api", "rest", "asgi", "litestar", "starlite"] @@ -78,7 +78,7 @@ Twitter = "https://twitter.com/LitestarAPI" [project.optional-dependencies] annotated-types = ["annotated-types"] attrs = ["attrs"] -htmx = ["litestar-htmx>=0.2.1"] +htmx = ["litestar-htmx>=0.2.2"] brotli = ["brotli"] cli = ["jsbeautifier", "uvicorn[standard]", "uvloop>=0.18.0; sys_platform != 'win32'"] cryptography = ["cryptography"]