fasthtml-tailwindcss 4.3.3__tar.gz

fasthtml_tailwindcss-4.3.3/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.cache/
+.coverage*
+coverage.xml
+htmlcov/
+.env
+.envrc
+.pypirc
+.env.*
+!.env.example
+*.log
+*.swp
+*.swo
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+/src/fasthtml_tailwindcss/bin/
+/source-dist/
+/unpacked/

fasthtml_tailwindcss-4.3.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpaceShaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fasthtml_tailwindcss-4.3.3/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: fasthtml-tailwindcss
+Version: 4.3.3
+Summary: Tailwind CSS for FastHTML with a persistent compiler across server reloads and watch mode for automatic CSS rebuilds.
+Project-URL: Documentation, https://github.com/SpaceShaman/fasthtml-tailwindcss#readme
+Project-URL: Homepage, https://github.com/SpaceShaman/fasthtml-tailwindcss
+Project-URL: Issues, https://github.com/SpaceShaman/fasthtml-tailwindcss/issues
+Project-URL: Repository, https://github.com/SpaceShaman/fasthtml-tailwindcss
+Author-email: SpaceShaman <spaceshaman@tuta.io>
+License-Expression: MIT
+License-File: LICENSE
+License-File: TAILWIND-LICENSE
+Keywords: components,css,fasthtml,tailwindcss,web
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: filelock>=3.16
+Requires-Dist: platformdirs>=4
+Requires-Dist: python-fasthtml>=0.14.13
+Description-Content-Type: text/markdown
+
+# fasthtml-tailwindcss
+
+[![License](https://img.shields.io/github/license/SpaceShaman/fasthtml-tailwindcss)](LICENSE)
+[![Release](https://img.shields.io/github/actions/workflow/status/SpaceShaman/fasthtml-tailwindcss/release.yml?label=release)](https://github.com/SpaceShaman/fasthtml-tailwindcss/actions/workflows/release.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/fasthtml-tailwindcss)](https://pypi.org/project/fasthtml-tailwindcss/)
+[![PyPI version](https://img.shields.io/pypi/v/fasthtml-tailwindcss)](https://pypi.org/project/fasthtml-tailwindcss/)
+[![FastHTML](https://img.shields.io/badge/framework-FastHTML-7854F7)](https://github.com/AnswerDotAI/fasthtml)
+[![Tailwind CSS](https://img.shields.io/badge/CSS-Tailwind_CSS-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Pytest](https://img.shields.io/badge/testing-pytest-0A9EDC?logo=pytest)](https://docs.pytest.org/)
+[![Ruff](https://img.shields.io/badge/linting-Ruff-D7FF64?logo=ruff)](https://github.com/astral-sh/ruff)
+
+Tailwind CSS for [FastHTML](https://github.com/AnswerDotAI/fasthtml) with a persistent compiler across server reloads and watch mode for automatic CSS rebuilds.
+
+## Installation
+
+Install with uv:
+
+```sh
+uv add fasthtml-tailwindcss
+```
+
+Or with pip:
+
+```sh
+pip install fasthtml-tailwindcss
+```
+
+On Alpine Linux, the standalone compiler also requires the system C++ runtime:
+
+```sh
+apk add --no-cache libstdc++ libgcc
+```
+
+## Usage
+
+```python
+from fasthtml.common import Div, FastHTML
+from fasthtml_tailwindcss import TailwindHead
+
+app = FastHTML(hdrs=[TailwindHead(watch=True)])
+
+
+@app.route("/")
+def get():
+    return Div("Hello", cls="rounded-lg bg-blue-500 p-4 text-white")
+```
+
+Run your application normally, for example with `uv run uvicorn main:app --reload`. The package bundles the official standalone Tailwind compiler: no Node.js, npm, CDN, CSS endpoint or additional command is needed.
+
+`TailwindHead` builds CSS when the component is constructed, usually while importing your application module, and waits for the first successful compilation. It embeds the result in a `<style>` element. Each full page receives the latest completed CSS. Refresh the browser to see updates; automatic browser refresh and updating styles during HTMX fragment swaps are not included.
+
+- `watch=True`: compile once, then watch source files. The compiler survives application reloads.
+- `watch=False` (default): compile once with minification, then reuse the result across reloads. Source changes do not rebuild CSS during that session.
+
+A local helper keeps the session alive while applications renew a shared heartbeat file, and shuts down 15 seconds after the last heartbeat. A quick manual restart is treated like a reload. A later start creates a fresh session and builds again. The session stays active while the component exists in a running Python process; it does not depend on ASGI lifespan.
+
+## Options
+
+All configuration is passed to `TailwindHead`:
+
+```python
+TailwindHead(
+    watch=True,
+    sources=["app"],
+    css="@theme { --color-brand: #7854f7; }",
+)
+```
+
+For a custom input stylesheet:
+
+```python
+TailwindHead(watch=True, input="assets/app.css")
+```
+
+- `sources`: source files or directories. Defaults to the project directory with the built-in input; with a custom input, its own source detection is used unless extra sources are supplied.
+- `input`: optional stylesheet replacing the built-in `@import "tailwindcss"`. Relative CSS imports resolve from that file.
+- `css`: optional inline CSS appended after the input. Useful for `@theme`, variants and explicit `@source inline(...)` declarations.
+
+Paths are resolved relative to the nearest `pyproject.toml` above the working directory, or the working directory if none exists. Sessions are shared by project, configuration and OS user. Reloads and application workers with identical options reuse the same session. Changing options, including `watch`, starts a separate session immediately; the unused session shuts down after 15 seconds.
+
+Tailwind scans complete class names in source files. Use `"bg-red-500"` rather than constructing names such as `f"bg-{color}-500"`. Classes inside installed component libraries need explicit sources or safelisting.
+
+Generated files and compiler diagnostics (`compiler.log`) live in the OS user cache under `fasthtml-tailwindcss`. Nothing is written into your application or installed package. Inline CSS requires an appropriate Content Security Policy if your application sets one.
+
+## Development
+
+```sh
+uv sync --group test
+uv run --group test pytest
+uv build
+```
+
+Wheel builds download and verify the matching official standalone executable. Wheels target Linux x64/ARM64 (glibc 2.28+ or musl 1.2+), macOS 13+ (Intel/Apple Silicon), and Windows x64. Source distributions contain the build hook and checksum manifest; building one requires network access unless the verified compiler is already present locally.
+
+The package version follows Tailwind, with `.postN` for Python-only fixes. The release workflow checks upstream daily, tests the platform wheels and publishes through PyPI Trusted Publishing. Configure the publisher for `SpaceShaman/fasthtml-tailwindcss`, workflow `release.yml`, environment `pypi`; allow workflow version commits on the default branch.
+
+## Links
+
+- [GitHub repository](https://github.com/SpaceShaman/fasthtml-tailwindcss)
+- [PyPI package](https://pypi.org/project/fasthtml-tailwindcss/)
+
+## License
+
+The wrapper and Tailwind CSS are MIT licensed. Both license notices are included in distributions.

fasthtml_tailwindcss-4.3.3/README.md

@@ -0,0 +1,105 @@
+# fasthtml-tailwindcss
+
+[![License](https://img.shields.io/github/license/SpaceShaman/fasthtml-tailwindcss)](LICENSE)
+[![Release](https://img.shields.io/github/actions/workflow/status/SpaceShaman/fasthtml-tailwindcss/release.yml?label=release)](https://github.com/SpaceShaman/fasthtml-tailwindcss/actions/workflows/release.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/fasthtml-tailwindcss)](https://pypi.org/project/fasthtml-tailwindcss/)
+[![PyPI version](https://img.shields.io/pypi/v/fasthtml-tailwindcss)](https://pypi.org/project/fasthtml-tailwindcss/)
+[![FastHTML](https://img.shields.io/badge/framework-FastHTML-7854F7)](https://github.com/AnswerDotAI/fasthtml)
+[![Tailwind CSS](https://img.shields.io/badge/CSS-Tailwind_CSS-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Pytest](https://img.shields.io/badge/testing-pytest-0A9EDC?logo=pytest)](https://docs.pytest.org/)
+[![Ruff](https://img.shields.io/badge/linting-Ruff-D7FF64?logo=ruff)](https://github.com/astral-sh/ruff)
+
+Tailwind CSS for [FastHTML](https://github.com/AnswerDotAI/fasthtml) with a persistent compiler across server reloads and watch mode for automatic CSS rebuilds.
+
+## Installation
+
+Install with uv:
+
+```sh
+uv add fasthtml-tailwindcss
+```
+
+Or with pip:
+
+```sh
+pip install fasthtml-tailwindcss
+```
+
+On Alpine Linux, the standalone compiler also requires the system C++ runtime:
+
+```sh
+apk add --no-cache libstdc++ libgcc
+```
+
+## Usage
+
+```python
+from fasthtml.common import Div, FastHTML
+from fasthtml_tailwindcss import TailwindHead
+
+app = FastHTML(hdrs=[TailwindHead(watch=True)])
+
+
+@app.route("/")
+def get():
+    return Div("Hello", cls="rounded-lg bg-blue-500 p-4 text-white")
+```
+
+Run your application normally, for example with `uv run uvicorn main:app --reload`. The package bundles the official standalone Tailwind compiler: no Node.js, npm, CDN, CSS endpoint or additional command is needed.
+
+`TailwindHead` builds CSS when the component is constructed, usually while importing your application module, and waits for the first successful compilation. It embeds the result in a `<style>` element. Each full page receives the latest completed CSS. Refresh the browser to see updates; automatic browser refresh and updating styles during HTMX fragment swaps are not included.
+
+- `watch=True`: compile once, then watch source files. The compiler survives application reloads.
+- `watch=False` (default): compile once with minification, then reuse the result across reloads. Source changes do not rebuild CSS during that session.
+
+A local helper keeps the session alive while applications renew a shared heartbeat file, and shuts down 15 seconds after the last heartbeat. A quick manual restart is treated like a reload. A later start creates a fresh session and builds again. The session stays active while the component exists in a running Python process; it does not depend on ASGI lifespan.
+
+## Options
+
+All configuration is passed to `TailwindHead`:
+
+```python
+TailwindHead(
+    watch=True,
+    sources=["app"],
+    css="@theme { --color-brand: #7854f7; }",
+)
+```
+
+For a custom input stylesheet:
+
+```python
+TailwindHead(watch=True, input="assets/app.css")
+```
+
+- `sources`: source files or directories. Defaults to the project directory with the built-in input; with a custom input, its own source detection is used unless extra sources are supplied.
+- `input`: optional stylesheet replacing the built-in `@import "tailwindcss"`. Relative CSS imports resolve from that file.
+- `css`: optional inline CSS appended after the input. Useful for `@theme`, variants and explicit `@source inline(...)` declarations.
+
+Paths are resolved relative to the nearest `pyproject.toml` above the working directory, or the working directory if none exists. Sessions are shared by project, configuration and OS user. Reloads and application workers with identical options reuse the same session. Changing options, including `watch`, starts a separate session immediately; the unused session shuts down after 15 seconds.
+
+Tailwind scans complete class names in source files. Use `"bg-red-500"` rather than constructing names such as `f"bg-{color}-500"`. Classes inside installed component libraries need explicit sources or safelisting.
+
+Generated files and compiler diagnostics (`compiler.log`) live in the OS user cache under `fasthtml-tailwindcss`. Nothing is written into your application or installed package. Inline CSS requires an appropriate Content Security Policy if your application sets one.
+
+## Development
+
+```sh
+uv sync --group test
+uv run --group test pytest
+uv build
+```
+
+Wheel builds download and verify the matching official standalone executable. Wheels target Linux x64/ARM64 (glibc 2.28+ or musl 1.2+), macOS 13+ (Intel/Apple Silicon), and Windows x64. Source distributions contain the build hook and checksum manifest; building one requires network access unless the verified compiler is already present locally.
+
+The package version follows Tailwind, with `.postN` for Python-only fixes. The release workflow checks upstream daily, tests the platform wheels and publishes through PyPI Trusted Publishing. Configure the publisher for `SpaceShaman/fasthtml-tailwindcss`, workflow `release.yml`, environment `pypi`; allow workflow version commits on the default branch.
+
+## Links
+
+- [GitHub repository](https://github.com/SpaceShaman/fasthtml-tailwindcss)
+- [PyPI package](https://pypi.org/project/fasthtml-tailwindcss/)
+
+## License
+
+The wrapper and Tailwind CSS are MIT licensed. Both license notices are included in distributions.

fasthtml_tailwindcss-4.3.3/TAILWIND-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fasthtml_tailwindcss-4.3.3/binaries.json

@@ -0,0 +1,12 @@
+{
+  "version": "4.3.3",
+  "sha256": {
+    "tailwindcss-linux-arm64": "55fd0b241214eff3de1e8ee4f22796662f2d2e7a49bcfca7477cfd0bac398195",
+    "tailwindcss-linux-arm64-musl": "71ea4be79c9de9827545682df3e040053fb535d37c71ed2cfdedf9385a0868e0",
+    "tailwindcss-linux-x64": "dc61b3ac6b8c9ca874c0cc4c57b2409791a64c5540404ca5f5367360babc313a",
+    "tailwindcss-linux-x64-musl": "a04d34ceacc8f52cbe8920ad846cdeb61d3d0021dba32db0d1f77c9d9fad7a6c",
+    "tailwindcss-macos-arm64": "cdf646702987a743464dff4d9c60fd4480d1c1e73dd819a9a67f1078815dce9d",
+    "tailwindcss-macos-x64": "7922e0953f2110c05976e3bf58f14e643d90427575e766b7d433f5f80cbee7e1",
+    "tailwindcss-windows-x64.exe": "e0e260ce048014e9268f6237ff18f8ccf02cef521cbd0ae04e82c2cdf7aa3955"
+  }
+}

fasthtml_tailwindcss-4.3.3/hatch_build.py

@@ -0,0 +1,73 @@
+import hashlib
+import json
+import os
+import platform
+import shutil
+import tempfile
+from pathlib import Path
+from urllib.request import urlopen
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+TARGETS = {
+    "linux-x64": "manylinux_2_28_x86_64",
+    "linux-arm64": "manylinux_2_28_aarch64",
+    "linux-x64-musl": "musllinux_1_2_x86_64",
+    "linux-arm64-musl": "musllinux_1_2_aarch64",
+    "macos-x64": "macosx_13_0_x86_64",
+    "macos-arm64": "macosx_13_0_arm64",
+    "windows-x64": "win_amd64",
+}
+
+
+def native_target():
+    system = {"Linux": "linux", "Darwin": "macos", "Windows": "windows"}.get(
+        platform.system()
+    )
+    arch = {"x86_64": "x64", "AMD64": "x64", "arm64": "arm64", "aarch64": "arm64"}.get(
+        platform.machine()
+    )
+    target = f"{system}-{arch}"
+    if system == "linux" and (
+        platform.libc_ver()[0] == "musl" or any(Path("/lib").glob("ld-musl-*.so.1"))
+    ):
+        target += "-musl"
+    return target
+
+
+def download_binary(url, binary, expected):
+    if binary.exists() and hashlib.sha256(binary.read_bytes()).hexdigest() == expected:
+        return
+    with tempfile.TemporaryDirectory() as temporary:
+        download = Path(temporary) / binary.name
+        with urlopen(url, timeout=120) as response, download.open("wb") as destination:
+            shutil.copyfileobj(response, destination)
+        if hashlib.sha256(download.read_bytes()).hexdigest() != expected:
+            raise RuntimeError(f"Checksum mismatch for {url}")
+        shutil.copyfile(download, binary)
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        if self.target_name != "wheel":
+            return
+        root = Path(self.root)
+        manifest = json.loads((root / "binaries.json").read_text())
+        if self.metadata.version.split(".post")[0] != manifest["version"]:
+            raise ValueError("Package version must match binaries.json")
+        target = os.environ.get("TAILWIND_BUILD_TARGET", native_target())
+        if target not in TARGETS:
+            raise RuntimeError(f"No official standalone Tailwind binary for {target}")
+        suffix = ".exe" if target.startswith("windows-") else ""
+        asset = f"tailwindcss-{target}{suffix}"
+        expected = manifest["sha256"][asset]
+        binary = root / "src" / "fasthtml_tailwindcss" / "bin" / f"tailwindcss{suffix}"
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        url = f"https://github.com/tailwindlabs/tailwindcss/releases/download/v{manifest['version']}/{asset}"
+        download_binary(url, binary, expected)
+        binary.chmod(0o755)
+        build_data["pure_python"] = False
+        build_data["tag"] = f"py3-none-{TARGETS[target]}"
+        build_data["artifacts"].append(
+            f"src/fasthtml_tailwindcss/bin/tailwindcss{suffix}"
+        )

fasthtml_tailwindcss-4.3.3/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "fasthtml-tailwindcss"
+version = "4.3.3"
+description = "Tailwind CSS for FastHTML with a persistent compiler across server reloads and watch mode for automatic CSS rebuilds."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "TAILWIND-LICENSE"]
+authors = [{ name = "SpaceShaman", email = "spaceshaman@tuta.io" }]
+keywords = ["components", "css", "fasthtml", "tailwindcss", "web"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["filelock>=3.16", "platformdirs>=4", "python-fasthtml>=0.14.13"]
+
+[project.urls]
+Documentation = "https://github.com/SpaceShaman/fasthtml-tailwindcss#readme"
+Homepage = "https://github.com/SpaceShaman/fasthtml-tailwindcss"
+Issues = "https://github.com/SpaceShaman/fasthtml-tailwindcss/issues"
+Repository = "https://github.com/SpaceShaman/fasthtml-tailwindcss"
+
+[dependency-groups]
+test = ["httpx", "pytest", "uvicorn"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fasthtml_tailwindcss"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/hatch_build.py", "/binaries.json", "/pyproject.toml", "/README.md", "/LICENSE", "/TAILWIND-LICENSE", "/tests"]
+exclude = ["/src/fasthtml_tailwindcss/bin"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

fasthtml_tailwindcss-4.3.3/src/fasthtml_tailwindcss/__init__.py

@@ -0,0 +1,33 @@
+from collections.abc import Sequence
+from pathlib import Path
+from weakref import finalize
+
+from fasthtml.common import Style
+
+from ._client import Session, configuration
+
+__all__ = ["TailwindHead"]
+
+
+class TailwindHead:
+    def __init__(
+        self,
+        *,
+        watch: bool = False,
+        sources: Sequence[str | Path] | None = None,
+        input: str | Path | None = None,
+        css: str | None = None,
+    ) -> None:
+        config = configuration(watch=watch, sources=sources, input=input, css=css)
+        self._session = Session(config)
+        self._session.start()
+        finalize(self, self._session.close)
+
+    def __deepcopy__(self, memo):
+        return self
+
+    def __ft__(self):
+        if self._session.error:
+            raise RuntimeError(self._session.error)
+        css = self._session.output.read_text(encoding="utf-8")
+        return Style(css.replace("</", "<\\/"))

fasthtml_tailwindcss-4.3.3/src/fasthtml_tailwindcss/_client.py

@@ -0,0 +1,156 @@
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from importlib.metadata import version
+from pathlib import Path
+from threading import Event, Thread
+
+from filelock import FileLock, Timeout
+from platformdirs import user_cache_path
+
+IDLE_TIMEOUT = 15
+
+
+def configuration(*, watch, sources, input, css):
+    if isinstance(sources, (str, Path)):
+        raise TypeError("sources must be a sequence of paths, for example ['app']")
+    cwd = Path.cwd().resolve()
+    root = next(
+        (p for p in (cwd, *cwd.parents) if (p / "pyproject.toml").is_file()), cwd
+    )
+    input_path = (root / input).resolve() if input is not None else None
+    if input_path is not None and not input_path.is_file():
+        raise FileNotFoundError(input_path)
+    if sources is None:
+        sources = [root] if input is None else []
+    return {
+        "root": str(root),
+        "watch": watch,
+        "sources": [str((root / path).resolve()) for path in sources],
+        "input": str(input_path) if input_path is not None else None,
+        "css": css or "",
+        "version": version("fasthtml-tailwindcss"),
+    }
+
+
+def cache_directory(config):
+    settings = json.dumps(config, sort_keys=True).encode()
+    key = hashlib.sha256(settings).hexdigest()[:24]
+    return user_cache_path("fasthtml-tailwindcss", appauthor=False) / key
+
+
+def running(directory):
+    try:
+        with FileLock(str(directory / "worker.lock"), timeout=0):
+            return False
+    except Timeout:
+        return True
+
+
+def stop_process(process):
+    if process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+
+
+class Session:
+    def __init__(self, config):
+        self.config = config
+        self.directory = cache_directory(config)
+        self.output = self.directory / "style.css"
+        self.error = ""
+        self._closed = Event()
+        self._thread = Thread(target=self.heartbeat, daemon=True)
+
+    def connect(self):
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        with FileLock(str(self.directory / "startup.lock"), timeout=30):
+            self.wait_for_previous_worker()
+            if not running(self.directory):
+                self.start_worker()
+            (self.directory / "heartbeat").touch()
+
+    def wait_for_previous_worker(self):
+        deadline = time.monotonic() + 10
+        while running(self.directory) and not (self.directory / "pid").exists():
+            if time.monotonic() > deadline:
+                raise RuntimeError("Tailwind helper is not responding")
+            time.sleep(0.05)
+
+    def start_worker(self):
+        for name in ("style.css", "error", "pid"):
+            (self.directory / name).unlink(missing_ok=True)
+        (self.directory / "config.json").write_text(
+            json.dumps(self.config), encoding="utf-8"
+        )
+        (self.directory / "heartbeat").touch()
+        flags = 0
+        if os.name == "nt":
+            flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        with (self.directory / "helper.log").open("w") as log:
+            process = subprocess.Popen(
+                [
+                    sys.executable,
+                    "-m",
+                    "fasthtml_tailwindcss._worker",
+                    str(self.directory),
+                ],
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=log,
+                start_new_session=os.name != "nt",
+                creationflags=flags,
+            )
+        deadline = time.monotonic() + 10
+        while not (self.directory / "pid").exists():
+            if process.poll() is not None or time.monotonic() > deadline:
+                stop_process(process)
+                raise RuntimeError(
+                    (self.directory / "helper.log").read_text()
+                    or "Cannot start Tailwind helper"
+                )
+            time.sleep(0.05)
+
+    def wait_for_css(self):
+        deadline = time.monotonic() + 120
+        while not self.output.exists():
+            if self.error:
+                raise RuntimeError(self.error)
+            if time.monotonic() > deadline:
+                raise RuntimeError(
+                    "Tailwind initial build timed out; see compiler.log in the cache"
+                )
+            time.sleep(0.05)
+
+    def heartbeat(self):
+        while not self._closed.is_set():
+            error = self.directory / "error"
+            if error.exists():
+                self.error = error.read_text(encoding="utf-8")
+            elif not running(self.directory):
+                self.error = "Tailwind helper stopped; restart the application"
+            if self.error:
+                return
+            (self.directory / "heartbeat").touch()
+            self._closed.wait(2)
+
+    def start(self):
+        self.connect()
+        self._thread.start()
+        try:
+            self.wait_for_css()
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self):
+        self._closed.set()
+        self._thread.join()

fasthtml_tailwindcss-4.3.3/src/fasthtml_tailwindcss/_worker.py

@@ -0,0 +1,133 @@
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from filelock import FileLock
+
+from ._client import IDLE_TIMEOUT, stop_process
+
+
+def input_css(config):
+    def quote(path):
+        return json.dumps(Path(path).as_posix(), ensure_ascii=False)
+
+    base = (
+        f"@import {quote(config['input'])};"
+        if config["input"]
+        else '@import "tailwindcss" source(none);'
+    )
+    sources = "\n".join(f"@source {quote(path)};" for path in config["sources"])
+    return f"{base}\n{sources}\n{config['css']}\n"
+
+
+class Worker:
+    def __init__(self, directory):
+        self.directory = directory
+        self.config = json.loads((directory / "config.json").read_text())
+        self.output = directory / "style.css"
+        self.stopping = False
+
+    def stop(self, *_):
+        self.stopping = True
+
+    def start_compiler(self):
+        source = self.directory / "input.css"
+        source.write_text(input_css(self.config), encoding="utf-8")
+        executable = "tailwindcss.exe" if os.name == "nt" else "tailwindcss"
+        binary = Path(__file__).parent / "bin" / executable
+        mode = "--watch=always" if self.config["watch"] else "--minify"
+        command = [
+            str(binary),
+            "-i",
+            str(source),
+            "-o",
+            str(self.directory / "building.css"),
+            mode,
+        ]
+        with (self.directory / "compiler.log").open("w") as log:
+            return subprocess.Popen(
+                command,
+                cwd=self.config["root"],
+                stdin=subprocess.DEVNULL,
+                stdout=log,
+                stderr=log,
+                env={**os.environ, "NO_COLOR": "1"},
+            )
+
+    def publish_css(self):
+        css = (self.directory / "building.css").read_bytes()
+        if self.output.exists() and self.output.read_bytes() == css:
+            return
+        temporary = self.directory / "published.tmp"
+        temporary.write_bytes(css)
+        temporary.replace(self.output)
+
+    def idle(self):
+        heartbeat = (self.directory / "heartbeat").stat().st_mtime
+        return time.time() - heartbeat > IDLE_TIMEOUT
+
+    def expired(self):
+        if not self.idle():
+            return False
+        with FileLock(str(self.directory / "startup.lock"), timeout=30):
+            if not self.idle():
+                return False
+            (self.directory / "pid").unlink(missing_ok=True)
+            return True
+
+    def check_exit(self, code):
+        if code is None:
+            return
+        if code == 0 and not self.config["watch"] and self.output.exists():
+            return
+        details = (self.directory / "compiler.log").read_text(
+            encoding="utf-8", errors="replace"
+        )
+        raise RuntimeError(f"Tailwind stopped (exit {code}):\n{details}")
+
+    def monitor(self, process):
+        with (self.directory / "compiler.log").open(
+            encoding="utf-8", errors="replace"
+        ) as log:
+            pending = ""
+            while not self.stopping:
+                code = process.poll()
+                pending += log.read()
+                message, _, pending = pending.rpartition("\n")
+                if re.search(r"\bDone in\b", message):
+                    self.publish_css()
+                self.check_exit(code)
+                if self.expired():
+                    return
+                time.sleep(0.1)
+
+    def run(self):
+        process = None
+        (self.directory / "pid").write_text(str(os.getpid()))
+        try:
+            process = self.start_compiler()
+            self.monitor(process)
+        except (OSError, RuntimeError) as error:
+            (self.directory / "error").write_text(str(error), encoding="utf-8")
+        finally:
+            if process is not None:
+                stop_process(process)
+            (self.directory / "pid").unlink(missing_ok=True)
+
+
+def main(directory):
+    worker = Worker(directory)
+    for name in ("SIGTERM", "SIGINT", "SIGBREAK"):
+        if signum := getattr(signal, name, None):
+            signal.signal(signum, worker.stop)
+    with FileLock(str(directory / "worker.lock"), timeout=0):
+        worker.run()
+
+
+if __name__ == "__main__":
+    main(Path(sys.argv[1]))

fasthtml_tailwindcss-4.3.3/tests/conftest.py

@@ -0,0 +1,51 @@
+import gc
+import time
+
+import pytest
+from fasthtml.common import Div, FastHTML
+
+from fasthtml_tailwindcss import TailwindHead, _client
+
+
+@pytest.fixture(scope="session")
+def helpers():
+    directories = []
+    yield directories
+    deadline = time.monotonic() + 25
+    while any((p / "pid").exists() for p in directories):
+        assert time.monotonic() < deadline, (
+            "Helper did not shut down after losing clients"
+        )
+        time.sleep(0.1)
+
+
+@pytest.fixture
+def project(tmp_path, monkeypatch, helpers):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(_client, "user_cache_path", lambda *a, **kw: tmp_path / "cache")
+    (tmp_path / "pyproject.toml").write_text(
+        '[project]\nname="example"\nversion="0.1.0"\n'
+    )
+    (tmp_path / "components.py").write_text('classes = "p-4 bg-blue-500"\n')
+    config = _client.configuration(
+        watch=False, sources=["components.py"], input=None, css=None
+    )
+    helpers.append(_client.cache_directory(config))
+    yield tmp_path
+    gc.collect()
+    helpers.extend(path.parent for path in (tmp_path / "cache").glob("*/pid"))
+
+
+@pytest.fixture
+def application(project):
+    def create_app(**options):
+        head = TailwindHead(sources=["components.py"], **options)
+        app = FastHTML(sess_cls=None, hdrs=[head])
+
+        @app.get("/")  # ty: ignore[unresolved-attribute]  # FastHTML registers HTTP methods dynamically.
+        def get():
+            return Div("Hello", cls="p-4 bg-blue-500")
+
+        return app, head
+
+    return create_app

fasthtml_tailwindcss-4.3.3/tests/test_component.py

@@ -0,0 +1,83 @@
+import gc
+import time
+
+import pytest
+from fasthtml.common import Div, FastHTML
+from starlette.testclient import TestClient
+
+from fasthtml_tailwindcss import TailwindHead
+
+
+def test_custom_input_relative_imports_and_inline_css(project, application):
+    assets = project / "assets"
+    assets.mkdir()
+    (assets / "theme.css").write_text(".custom { color: red; }\n")
+    (assets / "app.css").write_text(
+        '@import "tailwindcss" source(none);\n@import "./theme.css";\n'
+    )
+    app, _head = application(input="assets/app.css", css=".extra { color: blue; }")
+    with TestClient(app) as client:
+        html = client.get("/").text
+        assert ".custom{" in html
+        assert ".extra{" in html
+        assert ".p-4{" in html
+
+
+def test_first_compilation_error_blocks_construction(project):
+    with pytest.raises(RuntimeError, match="Tailwind stopped"):
+        TailwindHead(css=".broken { @apply definitely-not-a-tailwind-utility; }")
+
+
+def test_constructor_builds_without_asgi_lifespan(project):
+    head = TailwindHead(sources=["components.py"])
+    assert head._session.output.exists()
+    app = FastHTML(sess_cls=None, hdrs=[head])
+
+    @app.route("/")
+    def get():
+        return Div("Hello", cls="p-4")
+
+    client = TestClient(app)
+    assert ".p-4{" in client.get("/").text
+    client.close()
+
+
+def test_releasing_component_stops_heartbeat(project):
+    head = TailwindHead(sources=["components.py"])
+    session = head._session
+    del head
+    gc.collect()
+    assert not session._thread.is_alive()
+
+
+def test_default_sources_and_css_escaping(project):
+    head = TailwindHead(css='.closing::after { content: "</style>"; }')
+    app = FastHTML(sess_cls=None, hdrs=[head])
+    with TestClient(app):
+        from fasthtml.common import to_xml
+
+        result = str(to_xml(head))
+        assert ".p-4{" in result
+        assert result.count("</style>") == 1
+
+
+def test_invalid_sources_argument(project):
+    with pytest.raises(TypeError, match="sequence"):
+        TailwindHead(sources="app")
+
+
+def test_existing_lifespan_and_heartbeat(project):
+    events = []
+    head = TailwindHead(sources=["components.py"])
+    app = FastHTML(
+        hdrs=[head],
+        sess_cls=None,
+        on_startup=lambda: events.append("startup"),
+        on_shutdown=lambda: events.append("shutdown"),
+    )
+    with TestClient(app):
+        assert events == ["startup"]
+        time.sleep(16)
+        assert not head._session.error  # ty: ignore[unresolved-attribute]  # FastHTML defines hdrs dynamically.
+        assert head._session.output.exists()  # ty: ignore[unresolved-attribute]  # FastHTML defines hdrs dynamically.
+    assert events == ["startup", "shutdown"]

fasthtml_tailwindcss-4.3.3/tests/test_sessions.py

@@ -0,0 +1,95 @@
+import concurrent.futures
+import copy
+import time
+from pathlib import Path
+
+import pytest
+from starlette.testclient import TestClient
+
+from fasthtml_tailwindcss import _client
+
+
+def test_once_build_survives_reload(project, application):
+    app, head = application()
+    with TestClient(app) as client:
+        assert ".p-4{" in client.get("/").text
+        output = head._session.output
+        original = output.read_bytes()
+        timestamp = output.stat().st_mtime_ns
+        assert copy.deepcopy(head) is head
+    (project / "components.py").write_text('classes = "text-7xl"\n')
+    app, head = application()
+    with TestClient(app) as client:
+        assert head._session.output == output
+        assert output.stat().st_mtime_ns == timestamp
+        assert output.read_bytes() == original
+        assert "text-7xl" not in client.get("/").text
+
+
+def test_watch_rebuilds_and_survives_reload(project, application):
+    app, head = application(watch=True)
+    with TestClient(app) as client:
+        output = head._session.output
+        assert ".p-4" in client.get("/").text
+        (project / "components.py").write_text('classes = "text-7xl"\n')
+        deadline = time.monotonic() + 10
+        while ".text-7xl" not in output.read_text():
+            assert time.monotonic() < deadline, "Watcher did not rebuild"
+            time.sleep(0.05)
+        assert ".text-7xl" in client.get("/").text
+    before = output.stat().st_mtime_ns
+    app, head = application(watch=True)
+    with TestClient(app):
+        assert head._session.output == output
+        assert output.stat().st_mtime_ns == before
+
+
+@pytest.mark.parametrize("watch", [True, False])
+def test_immediate_restart_with_changed_watch(project, watch):
+    import json
+    import subprocess
+    import sys
+
+    script = """import json, sys
+from pathlib import Path
+from fasthtml.common import FastHTML
+from fasthtml_tailwindcss import TailwindHead, _client
+_client.user_cache_path = lambda *args, **kwargs: Path("cache").resolve()
+head = TailwindHead(watch=sys.argv[1] == "True", sources=["components.py"])
+app = FastHTML(hdrs=[head], sess_cls=None)
+print(json.dumps(str(head._session.directory)))
+"""
+
+    def start(mode):
+        result = subprocess.run(
+            [sys.executable, "-c", script, str(mode)],
+            cwd=project,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+        assert result.returncode == 0, result.stderr
+        return Path(json.loads(result.stdout))
+
+    previous = start(watch)
+    assert _client.running(previous)
+    (project / "components.py").write_text('classes = "text-7xl"\n')
+    current = start(not watch)
+    assert current != previous
+    assert ".text-7xl" in (current / "style.css").read_text()
+    assert _client.running(previous)
+    assert _client.running(current)
+
+
+def test_concurrent_workers_share_one_build(project):
+    config = _client.configuration(
+        watch=False, sources=["components.py"], input=None, css=None
+    )
+    sessions = [_client.Session(config) for _ in range(4)]
+    with concurrent.futures.ThreadPoolExecutor() as pool:
+        list(pool.map(lambda s: s.connect(), sessions))
+    assert len({s.output for s in sessions}) == 1
+    directory = _client.cache_directory(config)
+    assert (directory / "config.json").is_file()
+    assert int((directory / "pid").read_text()) > 0

fasthtml_tailwindcss-4.3.3/tests/test_uvicorn.py

@@ -0,0 +1,102 @@
+import time
+
+import pytest
+
+from fasthtml_tailwindcss import _client
+
+
+@pytest.mark.skipif(
+    __import__("os").name == "nt",
+    reason="POSIX process-group shutdown for this reload test",
+)
+@pytest.mark.parametrize("watch", [False, True])
+def test_real_uvicorn_reload(project, helpers, watch):
+    import os
+    import signal
+    import socket
+    import subprocess
+    import sys
+    from urllib.error import URLError
+    from urllib.request import urlopen
+
+    source = project / "main.py"
+    source.write_text(f"""import os
+from pathlib import Path
+from fasthtml.common import FastHTML, Div
+from fasthtml_tailwindcss import TailwindHead, _client
+_client.user_cache_path = lambda *a, **kw: Path({str(project / "cache")!r})
+app = FastHTML(sess_cls=None, hdrs=[TailwindHead(watch={watch!r}, sources=["main.py"])])
+@app.get("/")
+def get():
+    return Div("first", cls="p-4")
+@app.get("/pid")
+def pid():
+    return str(os.getpid())
+""")
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        port = sock.getsockname()[1]
+    base = f"http://127.0.0.1:{port}"
+
+    def response(path="/"):
+        try:
+            with urlopen(base + path, timeout=1) as res:
+                return res.read().decode()
+        except (OSError, URLError):
+            return ""
+
+    config = _client.configuration(
+        watch=watch, sources=["main.py"], input=None, css=None
+    )
+    directory = _client.cache_directory(config)
+    with (project / "uvicorn.log").open("w") as log:
+        process = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "uvicorn",
+                "main:app",
+                "--reload",
+                "--port",
+                str(port),
+            ],
+            cwd=project,
+            stdout=log,
+            stderr=log,
+            start_new_session=True,
+        )
+        try:
+            deadline = time.monotonic() + 20
+            while ">first</div>" not in response():
+                assert process.poll() is None, (project / "uvicorn.log").read_text()
+                assert time.monotonic() < deadline, (
+                    project / "uvicorn.log"
+                ).read_text()
+                time.sleep(0.1)
+            pid = response("/pid")
+            helper_pid = (directory / "pid").read_text()
+            output = directory / "style.css"
+            timestamp = output.stat().st_mtime_ns
+            source.write_text(
+                source.read_text().replace(
+                    '"first", cls="p-4"', '"second", cls="text-7xl"'
+                )
+            )
+            deadline = time.monotonic() + 20
+            while ">second</div>" not in response():
+                assert time.monotonic() < deadline, (
+                    project / "uvicorn.log"
+                ).read_text()
+                time.sleep(0.1)
+            assert response("/pid") != pid
+            assert (directory / "pid").read_text() == helper_pid
+            if watch:
+                while ".text-7xl" not in response():
+                    assert time.monotonic() < deadline
+                    time.sleep(0.1)
+            else:
+                assert output.stat().st_mtime_ns == timestamp
+                assert ".text-7xl" not in response()
+        finally:
+            os.killpg(process.pid, signal.SIGTERM)
+            process.wait(timeout=15)