Python SDK: Add a helper for constructing data-* attributes

sdk/python/README.md

@@ -2,19 +2,33 @@
 
 The `datastar-py` package provides backend helpers for the [Datastar](https://data-star.dev) JS library.
 
-Datastar requires all backend responses to use SSE. This allows the backend to
-send any number of responses, from zero to inifinity.
+Datastar sends responses back to the browser using SSE. This allows the backend to
+send any number of events, from zero to infinity in response to a single request.
 
-`datastar-py` helps with the formatting of these responses, while also
-providing helper functions for the different supported responses.
+`datastar-py` has helpers for creating those responses, formatting the events,
+reading signals from the frontend, and generating the data-* HTML attributes.
+
+The event generator can be used with any framework. There are also custom
+helpers included for the following frameworks:
+
+* [Django](https://www.djangoproject.com/)
+* [FastAPI](https://fastapi.tiangolo.com/)
+* [FastHTML](https://fastht.ml/)
+* [Litestar](https://litestar.dev/)
+* [Quart](https://quart.palletsprojects.com/en/stable/)
+* [Sanic](https://sanic.dev/en/)
+* [Starlette](https://www.starlette.io/)
+
+## Event Generation Helpers
 
 To use `datastar-py`, import the SSE generator in your app and then use
 it in your route handler:
 
 ```python
 from datastar_py import ServerSentEventGenerator as SSE
 
-# ... various app setup. The example below is for the Quart framework
+# ... various app setup.
+# The example below is for the Quart framework, and is only using the event generation helpers.
 
 @app.route("/updates")
 async def updates():
@@ -32,12 +46,42 @@ async def updates():
     return response
 ```
 
-There are also a number of custom responses/helpers for various frameworks. Currently the following frameworks are supported:
+## Response Helpers
 
-* [Django](https://www.djangoproject.com/)
-* [FastAPI](https://fastapi.tiangolo.com/)
-* [FastHTML](https://fastht.ml/)
-* [Litestar](https://litestar.dev/)
-* [Quart](https://quart.palletsprojects.com/en/stable/)
-* [Sanic](https://sanic.dev/en/)
-* [Starlette](https://www.starlette.io/)
+The response for the quart example above could be rewritten using the helpers:
+```python
+    return await make_datastar_response(time_updates())
+```
+
+## Signal Helpers
+The current state of the datastar signals is included by default in every 
+datastar request. A helper is included to load those signals for each
+framework. `read_signals`
+
+```python
+from datastar_py.quart import read_signals
+
+@app.route("/updates")
+async def updates():
+    signals = await read_signals()
+```
+
+## Attribute Generation Helper
+Datastar allows HTML generation to be done on the backend. datastar-py includes
+a helper to generate data-* attributes in your HTML with IDE completion and
+type checking. It can be used with many different HTML generation libraries.
+
+```python
+from datastar_py import attribute_generator as data
+
+# htpy
+button(data.on("click", "console.log('clicked')").debounce(1000).stop)["My Button"]
+# FastHTML
+Button("My Button", **data.on("click", "console.log('clicked')").debounce(1000).stop)
+# After next release of FastHTML you don't have to unpack the datastar helpers e.g.
+Button("My Button", data.on("click", "console.log('clicked')").debounce(1000).stop)
+# f-strings
+f"<button {data.on("click", "console.log('clicked')").debounce(1000).stop}>My Button</button>"
+# Jinja, but no editor completion :(
+<button {{data.on("click", "console.log('clicked')").debounce(1000).stop}}>My Button</button>
+```

sdk/python/src/datastar_py/__init__.py

@@ -5,8 +5,9 @@
 from typing import Any
 
 from .sse import SSE_HEADERS, ServerSentEventGenerator
+from .attributes import attribute_generator
 
-__all__ = ["ServerSentEventGenerator", "SSE_HEADERS"]
+__all__ = ["attribute_generator", "ServerSentEventGenerator", "SSE_HEADERS"]
 
 
 def _read_signals(