From 0b2b51f1317ee07f40b89c3321479ebccca07c7f Mon Sep 17 00:00:00 2001 From: Lucian Knock Date: Sat, 19 Jul 2025 21:24:41 -0400 Subject: [PATCH 1/5] Create a README for examples to make them easy to run --- examples/README.md | 129 +++++++++++++++++++++++++++++++++++++++ examples/litestar/app.py | 1 + examples/pyproject.toml | 20 ------ pyproject.toml | 1 + 4 files changed, 131 insertions(+), 20 deletions(-) create mode 100644 examples/README.md delete mode 100644 examples/pyproject.toml diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..8a1e514 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,129 @@ +# Datastar Python SDK Examples + +## How to Run These Examples with `uv` + +All of the examples here (except Django) include Inline Script Metadata (PEP 723), allowing them to be run with [uv](https://docs.astral.sh/uv/) without first installing dependencies. + +The following commands assume you are running them from the root of the repository. + +### Django + +We use the `--with` argument to declare depdencies to run our Django app. + +```sh +uv run --with django --with daphne ./examples/django/manage.py runserver +``` + +### FastAPI + +```sh +uv run ./examples/fastapi/app.py +``` + +### FastHTML + +```sh +uv run ./examples/fasthtml/simple.py +``` + +```sh +uv run ./examples/fasthtml/advanced.py +``` + +### Litestar + +```sh +uv run ./examples/litestar/app.py +``` + +### Quart + +```sh +uv run ./examples/quart/app.py +``` + +### Sanic + +```sh +uv run ./examples/sanic/app.py +``` + +## How to Run These Examples with `pip` + +### Setup + +```sh +python -m venv .venv +``` + +```sh +source .venv/bin/activate +``` + +### Django + +```sh +pip install . daphne django +``` + +```sh +python ./examples/django/manage.py runserver +``` + +### FastAPI + +```sh +pip install . uvicorn fastapi +``` + +```sh +python ./examples/fastapi/app.py +``` + +### FastHTML + +```sh +pip install . python-fasthtml +``` + +```sh +python ./examples/fasthtml/simple.py +``` + +```sh +pip install . python-fasthtml great-tables pandas polars +``` + +```sh +python ./examples/fasthtml/advanced.py +``` + +### Litestar + +```sh +pip install . uvicorn litestar +``` + +```sh +python ./examples/litestar/app.py +``` + +### Quart + +```sh +pip install . quart +``` + +```sh +python ./examples/quart/app.py +``` + +### Sanic + +```sh +pip install . sanic +``` + +```sh +python ./examples/sanic/app.py +``` diff --git a/examples/litestar/app.py b/examples/litestar/app.py index f2a8810..27424a5 100644 --- a/examples/litestar/app.py +++ b/examples/litestar/app.py @@ -2,6 +2,7 @@ # dependencies = [ # "datastar-py", # "litestar", +# "uvicorn", # ] # [tool.uv.sources] # datastar-py = { path = "../../" } diff --git a/examples/pyproject.toml b/examples/pyproject.toml deleted file mode 100644 index 501de88..0000000 --- a/examples/pyproject.toml +++ /dev/null @@ -1,20 +0,0 @@ -[tool.ruff] -line-length = 99 -lint.select = [ - # flake8-bugbear - "B", - # pycodestyle - "E", - # Pyflakes - "F", - # isort - "I", - # flake8-simplify - "SIM", - # pyupgrade - "UP", -] -lint.extend-ignore = [ - "E501", # line too long -] -lint.fixable = [ "ALL" ] diff --git a/pyproject.toml b/pyproject.toml index 37300e7..95d04ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ urls.GitHub = "https://github.com/starfederation/datastar-python" [dependency-groups] dev = [ + "daphne>=4.2.1", "django>=4.2.17", "fastapi[standard]>=0.115.4", "flask[async]>=3.0.3", From d29d0560241ab4b1c9003d2c8985b810652be1aa Mon Sep 17 00:00:00 2001 From: Lucian Knock Date: Sat, 19 Jul 2025 21:26:42 -0400 Subject: [PATCH 2/5] Fix spelling --- examples/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/README.md b/examples/README.md index 8a1e514..a6ea09e 100644 --- a/examples/README.md +++ b/examples/README.md @@ -8,7 +8,7 @@ The following commands assume you are running them from the root of the reposito ### Django -We use the `--with` argument to declare depdencies to run our Django app. +We use the `--with` argument to declare dependencies to run our Django app. ```sh uv run --with django --with daphne ./examples/django/manage.py runserver From 47480315c07cae6f6e4467baa87614036cc30269 Mon Sep 17 00:00:00 2001 From: Lucian Knock Date: Mon, 21 Jul 2025 21:18:46 -0400 Subject: [PATCH 3/5] Simplify running instructions, refactor dependencies --- examples/README.md | 126 +++++++-------------------------------------- pyproject.toml | 99 ++++++++++++++++++----------------- 2 files changed, 67 insertions(+), 158 deletions(-) diff --git a/examples/README.md b/examples/README.md index a6ea09e..342ed1a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,129 +1,39 @@ # Datastar Python SDK Examples -## How to Run These Examples with `uv` +## Running Examples with `uv` -All of the examples here (except Django) include Inline Script Metadata (PEP 723), allowing them to be run with [uv](https://docs.astral.sh/uv/) without first installing dependencies. +All examples (except Django) include Inline Script Metadata (PEP 723), allowing them to be run with [uv](https://docs.astral.sh/uv/) without first installing dependencies. -The following commands assume you are running them from the root of the repository. +### General Instructions -### Django - -We use the `--with` argument to declare dependencies to run our Django app. - -```sh -uv run --with django --with daphne ./examples/django/manage.py runserver -``` - -### FastAPI - -```sh -uv run ./examples/fastapi/app.py -``` - -### FastHTML - -```sh -uv run ./examples/fasthtml/simple.py -``` - -```sh -uv run ./examples/fasthtml/advanced.py -``` - -### Litestar - -```sh -uv run ./examples/litestar/app.py -``` - -### Quart - -```sh -uv run ./examples/quart/app.py -``` - -### Sanic - -```sh -uv run ./examples/sanic/app.py -``` - -## How to Run These Examples with `pip` - -### Setup +Navigate to the specific example directory and run: ```sh -python -m venv .venv +uv run ``` -```sh -source .venv/bin/activate -``` +For example: +- `cd examples/fastapi && uv run app.py` +- `cd examples/fasthtml && uv run simple.py` +- `cd examples/sanic && uv run app.py` ### Django -```sh -pip install . daphne django -``` +The Django example has its own `pyproject.toml` with dependencies. Navigate to the Django directory and run: ```sh -python ./examples/django/manage.py runserver +uv run manage.py runserver ``` -### FastAPI +## Alternative: Running with `pip` -```sh -pip install . uvicorn fastapi -``` - -```sh -python ./examples/fastapi/app.py -``` - -### FastHTML - -```sh -pip install . python-fasthtml -``` - -```sh -python ./examples/fasthtml/simple.py -``` - -```sh -pip install . python-fasthtml great-tables pandas polars -``` - -```sh -python ./examples/fasthtml/advanced.py -``` - -### Litestar +If you prefer using `pip`, you can create a virtual environment and install the dependencies listed in each script's metadata comments manually: ```sh -pip install . uvicorn litestar -``` - -```sh -python ./examples/litestar/app.py -``` - -### Quart - -```sh -pip install . quart -``` - -```sh -python ./examples/quart/app.py -``` - -### Sanic - -```sh -pip install . sanic +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate +pip install datastar-py +python ``` -```sh -python ./examples/sanic/app.py -``` +Refer to the `# dependencies = [...]` section at the top of each example script to see what packages to install. diff --git a/pyproject.toml b/pyproject.toml index 95d04ca..4bcdec8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,75 +1,74 @@ [build-system] build-backend = "hatchling.build" -requires = [ "hatchling" ] +requires = ["hatchling"] [project] name = "datastar-py" version = "0.6.3" description = "Helper functions and classes for the Datastar library (https://data-star.dev/)" readme = "README.md" -keywords = [ "datastar", "django", "fastapi", "fasthtml", "flask", "html", "litestar", "quart", "sanic", "starlette" ] +keywords = [ + "datastar", + "django", + "fastapi", + "fasthtml", + "flask", + "html", + "litestar", + "quart", + "sanic", + "starlette", +] license = "MIT" -license-files = [ "LICENSE.md" ] +license-files = ["LICENSE.md"] authors = [ - { name = "Felix Ingram", email = "f.ingram@gmail.com" }, - { name = "Lucian Knock", email = "git@lucianknock.com" }, - { name = "Chase Sterling", email = "chase.sterling@gmail.com" }, + { name = "Felix Ingram", email = "f.ingram@gmail.com" }, + { name = "Lucian Knock", email = "git@lucianknock.com" }, + { name = "Chase Sterling", email = "chase.sterling@gmail.com" }, ] requires-python = ">=3.9" classifiers = [ - "Development Status :: 4 - Beta", - "Environment :: Web Environment", - "Intended Audience :: Developers", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - "Programming Language :: Python", - "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3.13", + "Development Status :: 4 - Beta", + "Environment :: Web Environment", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", ] -dependencies = [ ] +dependencies = [] urls.Documentation = "https://github.com/starfederation/datastar-python/blob/develop/README.md" urls.GitHub = "https://github.com/starfederation/datastar-python" [dependency-groups] -dev = [ - "daphne>=4.2.1", - "django>=4.2.17", - "fastapi[standard]>=0.115.4", - "flask[async]>=3.0.3", - "litestar>=2.15.2", - "pre-commit>=4.2", - "python-fasthtml>=0.12; python_version>'3.10'", - "quart>=0.19.9", - "sanic>=24.6", - "starlette>=0.46.1", - "uvicorn>=0.32.1", -] +dev = ["pre-commit>=4.2"] [tool.ruff] line-length = 99 lint.select = [ - # Annotations - "ANN", - # flake8-bugbear - "B", - # pycodestyle - "E", - # Pyflakes - "F", - # isort - "I", - # Ruff specific - "RUF", - # flake8-simplify - "SIM", - # pyupgrade - "UP", + # Annotations + "ANN", + # flake8-bugbear + "B", + # pycodestyle + "E", + # Pyflakes + "F", + # isort + "I", + # Ruff specific + "RUF", + # flake8-simplify + "SIM", + # pyupgrade + "UP", ] -lint.ignore = [ "E501" ] -lint.fixable = [ "ALL" ] +lint.ignore = ["E501"] +lint.fixable = ["ALL"] From f36efe683d2c7e49176ab695937f33702d622bcf Mon Sep 17 00:00:00 2001 From: Lucian Knock Date: Mon, 21 Jul 2025 21:27:45 -0400 Subject: [PATCH 4/5] Exclude examples from annotations rules, sort imports --- examples/django/datastar/urls.py | 3 +-- examples/django/ds/views.py | 4 ++-- examples/fastapi/app.py | 6 +++--- examples/fasthtml/advanced.py | 7 ++++--- examples/fasthtml/simple.py | 4 ++-- examples/litestar/app.py | 6 +++--- examples/quart/app.py | 4 ++-- examples/sanic/app.py | 6 +++--- pyproject.toml | 3 +++ 9 files changed, 23 insertions(+), 20 deletions(-) diff --git a/examples/django/datastar/urls.py b/examples/django/datastar/urls.py index af132a1..0f163cc 100644 --- a/examples/django/datastar/urls.py +++ b/examples/django/datastar/urls.py @@ -15,10 +15,9 @@ 2. Add a URL to urlpatterns: path('blog/', include('blog.urls')) """ -from ds import views - from django.contrib import admin from django.urls import path +from ds import views urlpatterns = [ path("admin/", admin.site.urls), diff --git a/examples/django/ds/views.py b/examples/django/ds/views.py index 8032039..f0057ff 100644 --- a/examples/django/ds/views.py +++ b/examples/django/ds/views.py @@ -2,14 +2,14 @@ import time from datetime import datetime +from django.http import HttpResponse + from datastar_py.django import ( DatastarResponse, ServerSentEventGenerator, read_signals, ) -from django.http import HttpResponse - # ASGI Example HTML_ASGI = """\ diff --git a/examples/fastapi/app.py b/examples/fastapi/app.py index 88f81b8..fc231be 100644 --- a/examples/fastapi/app.py +++ b/examples/fastapi/app.py @@ -12,15 +12,15 @@ from datetime import datetime import uvicorn +from fastapi import FastAPI +from fastapi.responses import HTMLResponse + from datastar_py.fastapi import ( DatastarResponse, ReadSignals, ServerSentEventGenerator, ) -from fastapi import FastAPI -from fastapi.responses import HTMLResponse - app = FastAPI() diff --git a/examples/fasthtml/advanced.py b/examples/fasthtml/advanced.py index 74cb4ab..6322842 100644 --- a/examples/fasthtml/advanced.py +++ b/examples/fasthtml/advanced.py @@ -16,12 +16,13 @@ from datetime import datetime import polars as pl -from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator -from great_tables import GT -from great_tables.data import reactions # ruff: noqa: F403, F405 from fasthtml.common import * +from great_tables import GT +from great_tables.data import reactions + +from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator ###################################################################################################### # This demo shows how FastHTML can be integrated with Datastar for server-driven interaction with a # diff --git a/examples/fasthtml/simple.py b/examples/fasthtml/simple.py index 95cb28a..9206fd5 100644 --- a/examples/fasthtml/simple.py +++ b/examples/fasthtml/simple.py @@ -11,11 +11,11 @@ import json from datetime import datetime -from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator, read_signals - # ruff: noqa: F403, F405 from fasthtml.common import * +from datastar_py.fasthtml import DatastarResponse, ServerSentEventGenerator, read_signals + app, rt = fast_app( htmx=False, surreal=False, diff --git a/examples/litestar/app.py b/examples/litestar/app.py index 27424a5..b192732 100644 --- a/examples/litestar/app.py +++ b/examples/litestar/app.py @@ -13,6 +13,9 @@ from datetime import datetime import uvicorn +from litestar import Litestar, MediaType, get +from litestar.di import Provide + from datastar_py.litestar import ( DatastarResponse, ServerSentEventGenerator, @@ -20,9 +23,6 @@ ) from datastar_py.sse import DatastarEvent -from litestar import Litestar, MediaType, get -from litestar.di import Provide - HTML = """\ diff --git a/examples/quart/app.py b/examples/quart/app.py index d9363db..183d1e3 100644 --- a/examples/quart/app.py +++ b/examples/quart/app.py @@ -10,14 +10,14 @@ import asyncio from datetime import datetime +from quart import Quart + from datastar_py.quart import ( DatastarResponse, ServerSentEventGenerator, read_signals, ) -from quart import Quart - app = Quart(__name__) HTML = """\ diff --git a/examples/sanic/app.py b/examples/sanic/app.py index 1897158..5bd53e7 100644 --- a/examples/sanic/app.py +++ b/examples/sanic/app.py @@ -10,6 +10,9 @@ import asyncio from datetime import datetime +from sanic import Sanic +from sanic.response import html + from datastar_py.consts import ElementPatchMode from datastar_py.sanic import ( DatastarResponse, @@ -18,9 +21,6 @@ read_signals, ) -from sanic import Sanic -from sanic.response import html - app = Sanic("DataStarApp") HTML = """\ diff --git a/pyproject.toml b/pyproject.toml index 4bcdec8..0dd991b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,3 +72,6 @@ lint.select = [ ] lint.ignore = ["E501"] lint.fixable = ["ALL"] + +[tool.ruff.per-file-ignores] +"examples/**/*.py" = ["ANN"] From 412a67dcf877492bcb102b158082f8cf477ee9bb Mon Sep 17 00:00:00 2001 From: Lucian Knock Date: Mon, 21 Jul 2025 21:35:35 -0400 Subject: [PATCH 5/5] Apply pyproject-fmt rules --- pyproject.toml | 97 +++++++++++++++++++++++++------------------------- 1 file changed, 48 insertions(+), 49 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 0dd991b..24e3aaf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [build-system] build-backend = "hatchling.build" -requires = ["hatchling"] +requires = [ "hatchling" ] [project] name = "datastar-py" @@ -9,69 +9,68 @@ version = "0.6.3" description = "Helper functions and classes for the Datastar library (https://data-star.dev/)" readme = "README.md" keywords = [ - "datastar", - "django", - "fastapi", - "fasthtml", - "flask", - "html", - "litestar", - "quart", - "sanic", - "starlette", + "datastar", + "django", + "fastapi", + "fasthtml", + "flask", + "html", + "litestar", + "quart", + "sanic", + "starlette", ] license = "MIT" -license-files = ["LICENSE.md"] +license-files = [ "LICENSE.md" ] authors = [ - { name = "Felix Ingram", email = "f.ingram@gmail.com" }, - { name = "Lucian Knock", email = "git@lucianknock.com" }, - { name = "Chase Sterling", email = "chase.sterling@gmail.com" }, + { name = "Felix Ingram", email = "f.ingram@gmail.com" }, + { name = "Lucian Knock", email = "git@lucianknock.com" }, + { name = "Chase Sterling", email = "chase.sterling@gmail.com" }, ] requires-python = ">=3.9" classifiers = [ - "Development Status :: 4 - Beta", - "Environment :: Web Environment", - "Intended Audience :: Developers", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - "Programming Language :: Python", - "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3.13", + "Development Status :: 4 - Beta", + "Environment :: Web Environment", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", ] -dependencies = [] +dependencies = [ ] urls.Documentation = "https://github.com/starfederation/datastar-python/blob/develop/README.md" urls.GitHub = "https://github.com/starfederation/datastar-python" [dependency-groups] -dev = ["pre-commit>=4.2"] +dev = [ "pre-commit>=4.2" ] [tool.ruff] line-length = 99 lint.select = [ - # Annotations - "ANN", - # flake8-bugbear - "B", - # pycodestyle - "E", - # Pyflakes - "F", - # isort - "I", - # Ruff specific - "RUF", - # flake8-simplify - "SIM", - # pyupgrade - "UP", + # Annotations + "ANN", + # flake8-bugbear + "B", + # pycodestyle + "E", + # Pyflakes + "F", + # isort + "I", + # Ruff specific + "RUF", + # flake8-simplify + "SIM", + # pyupgrade + "UP", ] -lint.ignore = ["E501"] -lint.fixable = ["ALL"] +lint.ignore = [ "E501" ] +lint.fixable = [ "ALL" ] -[tool.ruff.per-file-ignores] -"examples/**/*.py" = ["ANN"] +per-file-ignores."examples/**/*.py" = [ "ANN" ]