starlette-tailwindcss 0.1.0__tar.gz

starlette_tailwindcss-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: starlette-tailwindcss
+Version: 0.1.0
+Summary: TailwindCSS integration for Starlette apps
+Author: pyk
+Author-email: pyk <2213646+pyk@users.noreply.github.com>
+Requires-Dist: platformdirs>=4.9.4
+Requires-Dist: starlette>=1.0.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Starlette Tailwind CSS
+
+`starlette-tailwindcss` is a lightweight utility for
+[Starlette](https://starlette.dev/) that builds Tailwind CSS on startup with
+optional watch mode during development.
+
+It integrates directly with your Starlette app and provides:
+
+- Builds CSS on startup.
+- Automatically rebuilds on changes in watch mode.
+- Optional `tailwindcss` CLI binary auto-installation.
+- Fully typed, following Starlette patterns.
+
+## Installation
+
+```shell
+uv add starlette-tailwindcss
+# or
+pip install starlette-tailwindcss
+```
+
+## Example
+
+```python
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from starlette.staticfiles import StaticFiles
+
+from starlette_tailwindcss import TailwindCSS
+
+static_dir = Path(__file__).parent / "static"
+
+tailwind = TailwindCSS(
+    version="v4.2.2",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+
+@asynccontextmanager
+async def lifespan(app: Starlette):
+    async with tailwind.build(watch=app.debug):
+        yield
+
+routes = [
+    Mount("/static", app=StaticFiles(directory=static_dir), name="static"),
+]
+
+app = Starlette(
+    debug=True,
+    routes=routes,
+    lifespan=lifespan,
+)
+```
+
+Use the generated CSS file in your templates:
+
+```html
+<link rel="stylesheet" href="{{ url_for('static', path='css/output.css') }}" />
+```
+
+## How it works
+
+`starlette-tailwindcss` runs the Tailwind CLI alongside your app.
+
+- Builds CSS when the app starts.
+- Rebuilds CSS in watch mode during development.
+- Stops the process when the app shuts down.
+
+## Usage
+
+You can use an existing Tailwind CSS CLI binary:
+
+```python
+tailwind = TailwindCSS(
+    bin_path="/usr/local/bin/tailwindcss",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+```
+
+Or let the package download a release automatically:
+
+```python
+tailwind = TailwindCSS(
+    version="v4.2.2",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+```
+
+`bin_path` and `version` are mutually exclusive.
+
+## Debug logging
+
+To see Tailwind CSS CLI output:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+```
+
+## License
+
+MIT

starlette_tailwindcss-0.1.0/README.md

@@ -0,0 +1,108 @@
+# Starlette Tailwind CSS
+
+`starlette-tailwindcss` is a lightweight utility for
+[Starlette](https://starlette.dev/) that builds Tailwind CSS on startup with
+optional watch mode during development.
+
+It integrates directly with your Starlette app and provides:
+
+- Builds CSS on startup.
+- Automatically rebuilds on changes in watch mode.
+- Optional `tailwindcss` CLI binary auto-installation.
+- Fully typed, following Starlette patterns.
+
+## Installation
+
+```shell
+uv add starlette-tailwindcss
+# or
+pip install starlette-tailwindcss
+```
+
+## Example
+
+```python
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from starlette.staticfiles import StaticFiles
+
+from starlette_tailwindcss import TailwindCSS
+
+static_dir = Path(__file__).parent / "static"
+
+tailwind = TailwindCSS(
+    version="v4.2.2",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+
+@asynccontextmanager
+async def lifespan(app: Starlette):
+    async with tailwind.build(watch=app.debug):
+        yield
+
+routes = [
+    Mount("/static", app=StaticFiles(directory=static_dir), name="static"),
+]
+
+app = Starlette(
+    debug=True,
+    routes=routes,
+    lifespan=lifespan,
+)
+```
+
+Use the generated CSS file in your templates:
+
+```html
+<link rel="stylesheet" href="{{ url_for('static', path='css/output.css') }}" />
+```
+
+## How it works
+
+`starlette-tailwindcss` runs the Tailwind CLI alongside your app.
+
+- Builds CSS when the app starts.
+- Rebuilds CSS in watch mode during development.
+- Stops the process when the app shuts down.
+
+## Usage
+
+You can use an existing Tailwind CSS CLI binary:
+
+```python
+tailwind = TailwindCSS(
+    bin_path="/usr/local/bin/tailwindcss",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+```
+
+Or let the package download a release automatically:
+
+```python
+tailwind = TailwindCSS(
+    version="v4.2.2",
+    input="src/acme/web/style.css",
+    output=static_dir / "css" / "output.css",
+)
+```
+
+`bin_path` and `version` are mutually exclusive.
+
+## Debug logging
+
+To see Tailwind CSS CLI output:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+```
+
+## License
+
+MIT

starlette_tailwindcss-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "starlette-tailwindcss"
+version = "0.1.0"
+description = "TailwindCSS integration for Starlette apps"
+readme = "README.md"
+authors = [
+    { name = "pyk", email = "2213646+pyk@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "platformdirs>=4.9.4",
+    "starlette>=1.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "jinja2>=3.1.6",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.8",
+    "ty>=0.0.27",
+    "uvicorn>=0.42.0",
+]
+
+# ty - settings
+[tool.ty.src]
+exclude = ["external"]
+
+# ruff - settings
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # D212 and D213 are incompatible; we use D212 (summary on first line)
+    "D213",
+    # D203 and D211 are incompatible; we use D211 (no blank line before class)
+    "D203",
+    # Trailing comma rule conflict with formatter
+    "COM812",
+]
+exclude = ["external/**"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+
+[tool.ruff.lint.pylint]
+max-args = 5
+
+# pytest - settings
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+norecursedirs = [
+    "external"
+]

starlette_tailwindcss-0.1.0/src/starlette_tailwindcss/__init__.py

@@ -0,0 +1,5 @@
+"""Starlette integration for the Tailwind CSS CLI."""
+
+from .tailwindcss import TailwindCSS
+
+__all__ = ["TailwindCSS"]

starlette_tailwindcss-0.1.0/src/starlette_tailwindcss/installer.py

@@ -0,0 +1,202 @@
+"""Tailwind CSS binary installation helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import platform
+import stat
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from platformdirs import user_cache_dir
+
+if TYPE_CHECKING:
+    import os
+
+logger = logging.getLogger(__name__)
+
+_APP_NAME = "starlette-tailwindcss"
+_RELEASE_BASE_URL = "https://github.com/tailwindlabs/tailwindcss/releases/download"
+_PROGRESS_MAX = 100
+
+
+@dataclass(frozen=True, slots=True)
+class _Target:
+    """Resolved binary names for the current platform."""
+
+    asset_name: str
+    cache_name: str
+    binary_name: str
+
+
+def _normalize_machine(machine: str) -> str:
+    """Normalize platform machine names to Tailwind release names."""
+    value = machine.lower()
+    if value in {"x86_64", "amd64"}:
+        return "x64"
+    if value in {"aarch64", "arm64"}:
+        return "arm64"
+    msg = f"Unsupported machine architecture: {machine}"
+    raise RuntimeError(msg)
+
+
+def _is_musl() -> bool:
+    """Return `True` when the current Linux libc is musl."""
+    libc_name, _ = platform.libc_ver()
+    return libc_name.lower() == "musl"
+
+
+def _target_platform() -> _Target:
+    """Build the Tailwind release target for the current platform."""
+    system = platform.system().lower()
+    arch = _normalize_machine(platform.machine())
+
+    if system == "linux":
+        suffix = "-musl" if _is_musl() else ""
+        asset_name = f"tailwindcss-linux-{arch}{suffix}"
+        return _Target(
+            asset_name=asset_name,
+            cache_name=asset_name,
+            binary_name=asset_name,
+        )
+    if system == "darwin":
+        asset_name = f"tailwindcss-macos-{arch}"
+        return _Target(
+            asset_name=asset_name,
+            cache_name=f"macos-{arch}",
+            binary_name=asset_name,
+        )
+    if system == "windows":
+        asset_name = "tailwindcss-windows-x64.exe"
+        return _Target(
+            asset_name=asset_name,
+            cache_name="windows-x64",
+            binary_name=asset_name,
+        )
+
+    msg = f"Unsupported operating system: {platform.system()}"
+    raise RuntimeError(msg)
+
+
+def _sha256(path: Path) -> str:
+    """Calculate a SHA-256 digest for a file."""
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _read_url(url: str) -> bytes:
+    """Read the full contents of a URL."""
+    with urllib.request.urlopen(url) as response:  # noqa: S310
+        return response.read()
+
+
+def _download_to_path(url: str, path: Path) -> None:
+    """Download a URL into a file path atomically."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with (
+        urllib.request.urlopen(url) as response,  # noqa: S310
+        tempfile.NamedTemporaryFile(
+            delete=False,
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+        ) as file,
+    ):
+        total_bytes_raw = response.headers.get("Content-Length")
+        total_bytes = int(total_bytes_raw) if total_bytes_raw is not None else None
+        downloaded = 0
+        next_progress = 25
+        if total_bytes is not None:
+            logger.debug("Installing Tailwind CSS binary: 0%%")
+        while chunk := response.read(1024 * 1024):
+            file.write(chunk)
+            if total_bytes is None:
+                continue
+            downloaded += len(chunk)
+            percent = (downloaded * _PROGRESS_MAX) // total_bytes
+            while next_progress <= _PROGRESS_MAX and percent >= next_progress:
+                logger.debug(
+                    "Installing Tailwind CSS binary: %s%%",
+                    next_progress,
+                )
+                next_progress += 25
+        temp_path = Path(file.name)
+    temp_path.replace(path)
+
+
+def _parse_checksum_manifest(content: str) -> dict[str, str]:
+    """Parse Tailwind's checksum manifest into a mapping."""
+    checksums: dict[str, str] = {}
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        checksum, asset_name = line.split(maxsplit=1)
+        checksums[asset_name.removeprefix("./")] = checksum
+    return checksums
+
+
+def _ensure_executable(path: Path) -> None:
+    """Mark a file executable for the current user."""
+    mode = path.stat().st_mode
+    path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def download_binary(
+    version: str,
+    cache_dir: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Download, verify, and cache the Tailwind binary for a release version."""
+    logger.debug("Starting Tailwind CSS auto-install: version=%s", version)
+    target = _target_platform()
+    cache_root = (
+        Path(user_cache_dir(_APP_NAME))
+        if cache_dir is None
+        else Path(cache_dir).expanduser()
+    )
+    binary_path = cache_root / version / target.cache_name / target.binary_name
+    if binary_path.exists():
+        _ensure_executable(binary_path)
+        logger.debug("Using cached Tailwind CSS binary: %s", binary_path)
+        return binary_path
+
+    release_base = f"{_RELEASE_BASE_URL}/{version}"
+    logger.debug("Tailwind CSS binary cache miss: %s", binary_path)
+    try:
+        manifest = _parse_checksum_manifest(
+            _read_url(f"{release_base}/sha256sums.txt").decode("utf-8"),
+        )
+    except urllib.error.URLError as exc:
+        msg = f"Failed to download Tailwind CSS checksum manifest for {version}"
+        raise RuntimeError(msg) from exc
+    expected_checksum = manifest.get(target.asset_name)
+    if expected_checksum is None:
+        msg = f"Checksum for {target.asset_name} was not found in the release manifest"
+        raise RuntimeError(msg)
+
+    asset_url = f"{release_base}/{target.asset_name}"
+    try:
+        _download_to_path(asset_url, binary_path)
+    except urllib.error.URLError as exc:
+        msg = f"Failed to download Tailwind CSS binary for {version}"
+        raise RuntimeError(msg) from exc
+    actual_checksum = _sha256(binary_path)
+    if actual_checksum != expected_checksum:
+        binary_path.unlink(missing_ok=True)
+        msg = (
+            "Downloaded Tailwind CSS binary checksum mismatch: "
+            f"expected {expected_checksum}, got {actual_checksum}"
+        )
+        raise RuntimeError(msg)
+
+    _ensure_executable(binary_path)
+    logger.debug("Finished Tailwind CSS auto-install: %s", binary_path)
+    return binary_path

starlette_tailwindcss-0.1.0/src/starlette_tailwindcss/tailwindcss.py

@@ -0,0 +1,218 @@
+# ruff: noqa: A002
+"""Tailwind CSS CLI integration for Starlette applications."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import shutil
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, overload
+
+from .installer import download_binary
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import AsyncIterator
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BIN_NAME = "tailwindcss"
+_PROCESS_STOP_TIMEOUT = 5.0
+
+
+class TailwindCSS:
+    """Manage Tailwind CSS CLI build and watch mode."""
+
+    @overload
+    def __init__(
+        self,
+        *,
+        bin_path: str | os.PathLike[str],
+        input: str | os.PathLike[str],
+        output: str | os.PathLike[str],
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        version: str,
+        input: str | os.PathLike[str],
+        output: str | os.PathLike[str],
+        cache_dir: str | os.PathLike[str] | None = None,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        *,
+        input: str | os.PathLike[str],
+        output: str | os.PathLike[str],
+        bin_path: str | os.PathLike[str] | None = None,
+        version: str | None = None,
+        cache_dir: str | os.PathLike[str] | None = None,
+    ) -> None:
+        """Create a Tailwind CSS integration configuration."""
+        if bin_path is not None and version is not None:
+            msg = "`bin_path` and `version` are mutually exclusive"
+            raise ValueError(msg)
+        if cache_dir is not None and version is None:
+            msg = "`cache_dir` requires `version`"
+            raise ValueError(msg)
+        if cache_dir is not None and bin_path is not None:
+            msg = "`cache_dir` is only valid with `version`"
+            raise ValueError(msg)
+
+        self.input = Path(input)
+        self.output = Path(output)
+        self.bin_path = Path(bin_path).expanduser() if bin_path is not None else None
+        self.version = version
+        self.cache_dir = Path(cache_dir).expanduser() if cache_dir is not None else None
+
+    @asynccontextmanager
+    async def build(self, *, watch: bool = False) -> AsyncIterator[None]:
+        """Build Tailwind CSS once and optionally watch for changes."""
+        binary = await self._resolve_binary()
+        await self._build_once(binary)
+
+        watch_process: asyncio.subprocess.Process | None = None
+        stream_tasks: list[asyncio.Task[None]] = []
+        if watch:
+            watch_process, stream_tasks = await self._spawn_watch(binary)
+
+        try:
+            yield
+        finally:
+            await self._shutdown_watch(watch_process, stream_tasks)
+
+    async def _build_once(self, binary: Path) -> None:
+        """Run a one-time Tailwind build."""
+        logger.info(
+            "Building Tailwind CSS output: %s build -i %s -o %s",
+            binary,
+            self.input,
+            self.output,
+        )
+        self.output.parent.mkdir(parents=True, exist_ok=True)
+        process = await asyncio.create_subprocess_exec(
+            str(binary),
+            "build",
+            "-i",
+            str(self.input),
+            "-o",
+            str(self.output),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stream_tasks: list[asyncio.Task[None]] = []
+        if process.stdout is not None:
+            stream_tasks.append(
+                asyncio.create_task(self._forward_stream(process.stdout, logging.INFO))
+            )
+        if process.stderr is not None:
+            stream_tasks.append(
+                asyncio.create_task(self._forward_stream(process.stderr, logging.DEBUG))
+            )
+        return_code = await process.wait()
+        await self._drain_stream_tasks(stream_tasks)
+        if return_code != 0:
+            msg = f"Tailwind CSS build failed with exit code {return_code}"
+            raise RuntimeError(msg)
+
+    async def _spawn_watch(
+        self,
+        binary: Path,
+    ) -> tuple[asyncio.subprocess.Process, list[asyncio.Task[None]]]:
+        """Start the Tailwind watch process and stream its output."""
+        logger.info(
+            "Spawning Tailwind CSS CLI in background: %s -i %s -o %s --watch",
+            binary,
+            self.input,
+            self.output,
+        )
+        self.output.parent.mkdir(parents=True, exist_ok=True)
+        process = await asyncio.create_subprocess_exec(
+            str(binary),
+            "-i",
+            str(self.input),
+            "-o",
+            str(self.output),
+            "--watch",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stream_tasks: list[asyncio.Task[None]] = []
+        if process.stdout is not None:
+            stream_tasks.append(
+                asyncio.create_task(self._forward_stream(process.stdout, logging.INFO))
+            )
+        if process.stderr is not None:
+            stream_tasks.append(
+                asyncio.create_task(self._forward_stream(process.stderr, logging.DEBUG))
+            )
+        return process, stream_tasks
+
+    async def _shutdown_watch(
+        self,
+        process: asyncio.subprocess.Process | None,
+        stream_tasks: list[asyncio.Task[None]],
+    ) -> None:
+        """Stop the Tailwind watch process and cancel output tasks."""
+        if process is None:
+            return
+
+        logger.info("Killing spawned Tailwind CSS CLI process: pid=%s", process.pid)
+        if process.returncode is None:
+            process.terminate()
+            try:
+                await asyncio.wait_for(process.wait(), timeout=_PROCESS_STOP_TIMEOUT)
+            except TimeoutError:
+                process.kill()
+                await process.wait()
+
+        await self._drain_stream_tasks(stream_tasks)
+
+    async def _drain_stream_tasks(self, stream_tasks: list[asyncio.Task[None]]) -> None:
+        """Cancel process stream forwarders and wait for them to finish."""
+        for task in stream_tasks:
+            if not task.done():
+                task.cancel()
+        for task in stream_tasks:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+    async def _forward_stream(self, stream: asyncio.StreamReader, level: int) -> None:
+        """Forward a process stream into the configured logger."""
+        while True:
+            line = await stream.readline()
+            if not line:
+                return
+            message = line.decode("utf-8", errors="replace").rstrip()
+            if message:
+                logger.log(level, "%s", message)
+
+    async def _resolve_binary(self) -> Path:
+        """Return the binary to execute, resolving local or downloaded input."""
+        if self.version is None:
+            return self._resolve_local_binary()
+        return await asyncio.to_thread(download_binary, self.version, self.cache_dir)
+
+    def _resolve_local_binary(self) -> Path:
+        """Resolve a local Tailwind binary from `bin_path` or `PATH`."""
+        if self.bin_path is not None:
+            candidate = self.bin_path
+            if candidate.exists():
+                return candidate
+            resolved = shutil.which(str(candidate))
+            if resolved is not None:
+                return Path(resolved)
+            msg = f"Tailwind CSS binary not found: {candidate}"
+            raise FileNotFoundError(msg)
+
+        resolved = shutil.which(_DEFAULT_BIN_NAME)
+        if resolved is None:
+            msg = f"`{_DEFAULT_BIN_NAME}` was not found on PATH"
+            raise FileNotFoundError(msg)
+        return Path(resolved)