staticware 0.1.0__py3-none-any.whl

staticware/__init__.py

@@ -0,0 +1,5 @@
+"""Top-level package for Staticware."""
+
+from staticware.middleware import HashedStatic, StaticRewriteMiddleware
+
+__all__ = ["HashedStatic", "StaticRewriteMiddleware"]

staticware/middleware.py

@@ -0,0 +1,310 @@
+"""ASGI middleware for static file serving with content-based cache busting.
+
+Zero dependencies beyond the Python standard library. Works with any ASGI
+framework: Starlette, FastAPI, Air, Litestar, Django, or raw ASGI.
+
+    from staticware import HashedStatic, StaticRewriteMiddleware
+
+    static = HashedStatic("static")
+
+    # Wrap any ASGI app to rewrite /static/styles.css -> /static/styles.a1b2c3d4.css
+    app = StaticRewriteMiddleware(your_app, static=static)
+
+    # In templates:
+    static.url("styles.css")  # -> /static/styles.a1b2c3d4.css
+"""
+
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import re
+from pathlib import Path
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+# ASGI protocol types — inlined so we depend on nothing.
+type Scope = dict[str, Any]
+type Receive = Callable[[], Awaitable[dict[str, Any]]]
+type Send = Callable[[dict[str, Any]], Awaitable[None]]
+type ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+class HashedStatic:
+    """Serve static files with content-hashed filenames.
+
+    Computes SHA-256 hashes of every file in ``directory`` at startup.
+    Requests for hashed filenames (``styles.a1b2c3d4.css``) get
+    ``Cache-Control: public, max-age=31536000, immutable``.
+    Requests for original filenames still work, without aggressive caching.
+
+    This is a mountable ASGI app *and* a URL resolver::
+
+        static = HashedStatic("static")
+
+        # Mount it however your framework mounts sub-apps:
+        app.mount("/static", static)
+
+        # Resolve URLs:
+        static.url("styles.css")       # /static/styles.a1b2c3d4.css
+        static.url("images/logo.png")  # /static/images/logo.7e4f9a01.png
+    """
+
+    def __init__(
+        self,
+        directory: str | Path,
+        *,
+        prefix: str = "/static",
+        hash_length: int = 8,
+    ) -> None:
+        self.directory = Path(directory).resolve()
+        self.prefix = prefix.rstrip("/")
+        self.hash_length = hash_length
+
+        # original relative path -> hashed relative path
+        self.file_map: dict[str, str] = {}
+        # hashed relative path -> original relative path
+        self._reverse: dict[str, str] = {}
+        # original relative path -> ETag value (quoted hash)
+        self._etags: dict[str, bytes] = {}
+
+        self._hash_files()
+
+    def _hash_files(self) -> None:
+        """Walk directory and build the hash map for every file."""
+        if not self.directory.exists():
+            return
+
+        for file_path in self.directory.rglob("*"):
+            if not file_path.is_file():
+                continue
+            if not file_path.resolve().is_relative_to(self.directory):
+                continue
+
+            relative = file_path.relative_to(self.directory).as_posix()
+            content = file_path.read_bytes()
+            hash_val = hashlib.sha256(content).hexdigest()[: self.hash_length]
+
+            # styles.css -> styles.a1b2c3d4.css
+            # Makefile -> Makefile.a1b2c3d4
+            # .gitignore -> .gitignore.a1b2c3d4
+            name = file_path.name
+            dot = name.rfind(".")
+            if dot > 0:
+                hashed_name = f"{name[:dot]}.{hash_val}{name[dot:]}"
+            else:
+                hashed_name = f"{name}.{hash_val}"
+            parent = str(Path(relative).parent)
+            if parent != ".":
+                hashed = f"{parent}/{hashed_name}"
+            else:
+                hashed = hashed_name
+
+            self.file_map[relative] = hashed
+            self._reverse[hashed] = relative
+            self._etags[relative] = f'"{hash_val}"'.encode('latin-1')
+
+    def url(self, path: str) -> str:
+        """Return the cache-busted URL for a static file path.
+
+        Unknown paths are returned unchanged (with the prefix).
+        """
+        path = path.lstrip("/")
+        hashed = self.file_map.get(path, path)
+        return f"{self.prefix}/{hashed}"
+
+    # ── ASGI app ────────────────────────────────────────────────────────
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Serve a static file. Mount this under the prefix in your framework."""
+        if scope["type"] != "http":
+            return
+
+        request_path: str = scope["path"]
+        root_path: str = scope.get("root_path", "")
+
+        if root_path:
+            # Framework mount: use root_path to derive the local path.
+            if request_path.startswith(root_path + "/"):
+                # Starlette-style: path still includes the mount prefix.
+                relative_path = request_path[len(root_path) + 1 :]
+            else:
+                # Litestar-style: framework already stripped the prefix.
+                relative_path = request_path.lstrip("/")
+        else:
+            # Standalone raw ASGI: use self.prefix to find the local path.
+            if not request_path.startswith(self.prefix + "/"):
+                await _send_text(send, 404, b"Not Found")
+                return
+            relative_path = request_path[len(self.prefix) + 1 :]
+
+        # Hashed filename — serve with immutable caching
+        original_path = self._reverse.get(relative_path)
+        if original_path:
+            file_path = (self.directory / original_path).resolve()
+            if file_path.is_relative_to(self.directory) and file_path.exists():
+                await _send_file(
+                    send,
+                    file_path,
+                    extra_headers=[
+                        (b"cache-control", b"public, max-age=31536000, immutable"),
+                    ],
+                )
+                return
+
+        # Original filename — serve without aggressive caching
+        file_path = (self.directory / relative_path).resolve()
+        if not file_path.is_relative_to(self.directory):
+            await _send_text(send, 404, b"Not Found")
+            return
+        if file_path.exists() and file_path.is_file():
+            etag = self._etags.get(relative_path)
+            if etag:
+                # Check for conditional request (If-None-Match)
+                for hdr_name, hdr_value in scope.get("headers", []):
+                    if hdr_name == b"if-none-match" and hdr_value == etag:
+                        await _send_text(send, 304, b"")
+                        return
+                await _send_file(
+                    send, file_path, extra_headers=[(b"etag", etag)]
+                )
+            else:
+                await _send_file(send, file_path)
+            return
+
+        await _send_text(send, 404, b"Not Found")
+
+
+class StaticRewriteMiddleware:
+    """ASGI middleware that rewrites static paths in HTML responses.
+
+    Wraps any ASGI app. When the response content-type is ``text/html``,
+    rewrites occurrences of ``/static/styles.css`` to their hashed
+    equivalents. Non-HTML responses pass through untouched.
+
+    Works with any templating system, component library, or hand-written
+    HTML — no template function needed (though ``static.url()`` is there
+    if you want it).
+
+        app = StaticRewriteMiddleware(app, static=static)
+    """
+
+    def __init__(self, app: ASGIApp, *, static: HashedStatic) -> None:
+        self.app = app
+        self.static = static
+        escaped = re.escape(static.prefix)
+        self._pattern = re.compile(escaped + r"/([^\"'>\s)#?]+)")
+
+    def _replace(self, match: re.Match[str]) -> str:
+        path = match.group(1)
+        if path in self.static.file_map:
+            return f"{self.static.prefix}/{self.static.file_map[path]}"
+        return match.group(0)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        response_start: dict[str, Any] | None = None
+        body_parts: list[bytes] = []
+        is_html = False
+
+        async def send_wrapper(message: dict[str, Any]) -> None:
+            nonlocal response_start, is_html
+
+            if message["type"] == "http.response.start":
+                response_start = message
+                headers = dict(message.get("headers", []))
+                content_type = headers.get(b"content-type", b"").decode("latin-1")
+                is_html = "text/html" in content_type
+                if not is_html:
+                    # Not HTML — send the start immediately and short-circuit.
+                    await send(message)
+                return
+
+            if message["type"] == "http.response.body":
+                if response_start is None:
+                    raise RuntimeError(
+                        "http.response.body received before http.response.start"
+                    )
+                if not is_html:
+                    await send(message)
+                    return
+
+                body = message.get("body", b"")
+                more_body = message.get("more_body", False)
+                body_parts.append(body)
+
+                if not more_body:
+                    full_body = b"".join(body_parts)
+                    try:
+                        text = full_body.decode("utf-8")
+                        text = self._pattern.sub(self._replace, text)
+                        full_body = text.encode("utf-8")
+                    except UnicodeDecodeError:
+                        pass
+
+                    if response_start is None:
+                        raise RuntimeError(
+                            "http.response.body received before http.response.start"
+                        )
+                    new_headers = [
+                        (k, str(len(full_body)).encode("latin-1"))
+                        if k == b"content-length"
+                        else (k, v)
+                        for k, v in response_start.get("headers", [])
+                    ]
+                    response_start["headers"] = new_headers
+                    await send(response_start)
+                    await send({"type": "http.response.body", "body": full_body})
+                return
+
+        await self.app(scope, receive, send_wrapper)
+
+
+# ── Raw ASGI helpers ────────────────────────────────────────────────────
+
+
+async def _send_file(
+    send: Send,
+    path: Path,
+    *,
+    extra_headers: list[tuple[bytes, bytes]] | None = None,
+) -> None:
+    """Send a file as a raw ASGI response."""
+    content = path.read_bytes()
+    content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+
+    headers: list[tuple[bytes, bytes]] = [
+        (b"content-type", content_type.encode("latin-1")),
+        (b"content-length", str(len(content)).encode("latin-1")),
+    ]
+    if extra_headers:
+        headers.extend(extra_headers)
+
+    await send({
+        "type": "http.response.start",
+        "status": 200,
+        "headers": headers,
+    })
+    await send({
+        "type": "http.response.body",
+        "body": content,
+    })
+
+
+async def _send_text(send: Send, status: int, body: bytes) -> None:
+    """Send a plain-text ASGI response."""
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": [
+            (b"content-type", b"text/plain"),
+            (b"content-length", str(len(body)).encode("latin-1")),
+        ],
+    })
+    await send({
+        "type": "http.response.body",
+        "body": body,
+    })

staticware/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

staticware-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: staticware
+Version: 0.1.0
+Summary: ASGI middleware for static file serving with content-based cache busting
+Project-URL: Bugs, https://github.com/feldroy/staticware/issues
+Project-URL: Changelog, https://github.com/feldroy/staticware/releases
+Project-URL: Documentation, https://feldroy.github.io/staticware/
+Project-URL: Homepage, https://github.com/feldroy/staticware
+Project-URL: Source, https://github.com/feldroy/staticware
+Author-email: "Audrey M. Roy Greenfeld" <audrey@feldroy.com>
+Maintainer-email: "Audrey M. Roy Greenfeld" <audrey@feldroy.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Staticware
+
+![PyPI version](https://img.shields.io/pypi/v/staticware.svg)
+
+ASGI middleware for static file serving with content-based cache busting. Zero runtime dependencies.
+
+* Created by **[Audrey M. Roy Greenfeld](https://audrey.feldroy.com)**
+  * GitHub: https://github.com/audreyfeldroy
+  * PyPI: https://pypi.org/user/audreyr/
+* PyPI package: https://pypi.org/project/staticware/
+* Free software: MIT License
+
+## Features
+
+* Serves static files over ASGI with content-hashed filenames for cache busting
+* Hashed filenames get `Cache-Control: public, max-age=31536000, immutable`
+* Original filenames still work, without aggressive caching
+* `StaticRewriteMiddleware` automatically rewrites static paths in HTML responses
+* `static.url()` resolves cache-busted URLs for use in templates
+* Works with any ASGI framework: Starlette, FastAPI, Air, Litestar, Django, or raw ASGI
+* Zero runtime dependencies
+
+## Quick Start
+
+```python
+from staticware import HashedStatic, StaticRewriteMiddleware
+
+# Point at your static files directory
+static = HashedStatic("static")
+
+# Mount it however your framework mounts sub-apps:
+app.mount("/static", static)
+
+# Wrap any ASGI app to rewrite static paths in HTML responses
+app = StaticRewriteMiddleware(app, static=static)
+
+# In templates, resolve cache-busted URLs:
+static.url("styles.css")       # /static/styles.a1b2c3d4.css
+static.url("images/logo.png")  # /static/images/logo.7e4f9a01.png
+```
+
+## Documentation
+
+Documentation is built with [Zensical](https://zensical.org/) and deployed to GitHub Pages.
+
+* **Live site:** https://feldroy.github.io/staticware/
+* **Preview locally:** `just docs-serve` (serves at http://localhost:8000)
+* **Build:** `just docs-build`
+
+API documentation is auto-generated from docstrings using [mkdocstrings](https://mkdocstrings.github.io/).
+
+Docs deploy automatically on push to `main` via GitHub Actions. To enable this, go to your repo's Settings > Pages and set the source to **GitHub Actions**.
+
+## Development
+
+To set up for local development:
+
+```bash
+git clone git@github.com:feldroy/staticware.git
+cd staticware
+uv sync
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run quality checks (format, lint, type check, test):
+
+```bash
+just qa
+```
+
+## Author
+
+Staticware was created in 2026 by Audrey M. Roy Greenfeld.
+
+Built with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) project template.

staticware-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+staticware/__init__.py,sha256=zbw4qTdL35GQHxJDZtr0m1yJW5BJ2ubBZo8Le8KRDdI,168
+staticware/middleware.py,sha256=DSVbjNs5EOeMK4qS9hIMyeRp1Vpe7X7hHUT2FOUKmLc,11517
+staticware/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+staticware-0.1.0.dist-info/METADATA,sha256=t2CTdIPAFoa1IcSHuEGcEA6uGOcRDpNijpUO84WXA9Q,3532
+staticware-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+staticware-0.1.0.dist-info/licenses/LICENSE,sha256=bmXNe-6xu11QuI5rXH3hBOesEquzT2lKLMZg6nAUQkk,1081
+staticware-0.1.0.dist-info/RECORD,,

staticware-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

staticware-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Audrey M. Roy Greenfeld
+
+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.