Create README for examples to make them simple to run (#9)

* Create a README for examples to make them easy to run

* Fix spelling

* Simplify running instructions, refactor dependencies

* Exclude examples from annotations rules, sort imports

* Apply pyproject-fmt rules

---------

Co-authored-by: Lucian Knock <[email protected]>

Author: axelknock

examples/README.md

@@ -0,0 +1,39 @@
+# Datastar Python SDK Examples
+
+## Running Examples with `uv`
+
+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.
+
+### General Instructions
+
+Navigate to the specific example directory and run:
+
+```sh
+uv run <script-name>
+```
+
+For example:
+- `cd examples/fastapi && uv run app.py`
+- `cd examples/fasthtml && uv run simple.py`
+- `cd examples/sanic && uv run app.py`
+
+### Django
+
+The Django example has its own `pyproject.toml` with dependencies. Navigate to the Django directory and run:
+
+```sh
+uv run manage.py runserver
+```
+
+## Alternative: Running with `pip`
+
+If you prefer using `pip`, you can create a virtual environment and install the dependencies listed in each script's metadata comments manually:
+
+```sh
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install datastar-py <other-dependencies-from-script>
+python <script-name>
+```
+
+Refer to the `# dependencies = [...]` section at the top of each example script to see what packages to install.

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),

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 = """\

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()
 
 

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  #

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,

examples/litestar/app.py

@@ -2,6 +2,7 @@
 # dependencies = [
 #   "datastar-py",
 #   "litestar",
+#   "uvicorn",
 # ]
 # [tool.uv.sources]
 # datastar-py = { path = "../../" }
@@ -12,16 +13,16 @@
 from datetime import datetime
 
 import uvicorn
+from litestar import Litestar, MediaType, get
+from litestar.di import Provide
+
 from datastar_py.litestar import (
     DatastarResponse,
     ServerSentEventGenerator,
     read_signals,
 )
 from datastar_py.sse import DatastarEvent
 
-from litestar import Litestar, MediaType, get
-from litestar.di import Provide
-
 HTML = """\
 	<!DOCTYPE html>
 	<html lang="en">

examples/pyproject.toml

@@ -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 = """\

examples/quart/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 = """\