dj-serve 1.0.0__tar.gz

dj_serve-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Robles Fernández
+
+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.

dj_serve-1.0.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: dj-serve
+Version: 1.0.0
+Summary: Serve SPAs (Vue, React, Angular, vanilla HTML) directly from Django
+Keywords: django,spa,static,vue,react,angular,frontend
+Author: Ricardo Robles
+Author-email: Ricardo Robles <ricardo.r.f@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: django>=4.0
+Requires-Dist: whitesnout>=1.0 ; extra == 'asgi'
+Requires-Dist: aiofiles>=25.1.0 ; extra == 'async'
+Requires-Dist: pytest>=9.1.1 ; extra == 'dev'
+Requires-Dist: pytest-django>=4 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0 ; extra == 'dev'
+Requires-Dist: ruff==0.15.20 ; extra == 'dev'
+Requires-Dist: ty==0.0.56 ; extra == 'dev'
+Requires-Dist: django-stubs>=5 ; extra == 'dev'
+Requires-Dist: aiofiles>=25.1.0 ; extra == 'dev'
+Requires-Dist: whitenoise>=6.0 ; extra == 'dev'
+Requires-Dist: whitesnout>=1.0 ; extra == 'dev'
+Requires-Dist: httpx>=0.27.0 ; extra == 'dev'
+Requires-Dist: whitenoise>=6.0 ; extra == 'wsgi'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/rroblf01/dj-serve
+Project-URL: Repository, https://github.com/rroblf01/dj-serve
+Project-URL: Issues, https://github.com/rroblf01/dj-serve/issues
+Provides-Extra: asgi
+Provides-Extra: async
+Provides-Extra: dev
+Provides-Extra: wsgi
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://img.shields.io/pypi/v/dj-serve.svg)](https://pypi.org/project/dj-serve/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dj-serve.svg)](https://pypi.org/project/dj-serve/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Typing: Typed](https://img.shields.io/badge/typing-PEP%20561-brightgreen.svg)](https://peps.python.org/pep-0561/)
+[![CI](https://github.com/rroblf01/dj-serve/actions/workflows/test.yml/badge.svg)](https://github.com/rroblf01/dj-serve/actions/workflows/test.yml)
+
+# dj-serve
+
+Serve SPAs (Vue, React, Angular, Svelte, or vanilla HTML) directly from Django — no separate static server needed.
+
+```python
+from dj_serve import dj_serve
+
+urlpatterns = [
+    dj_serve("/", "dist/", "index.html", "dist/400.html", "dist/500.html"),
+]
+```
+
+## Why?
+
+Traditional Django + SPA setups require either:
+
+- **A separate static file server** (nginx, Apache, CDN) — adds deployment complexity.
+- **`django.contrib.staticfiles`** — not designed for SPAs; no client-side routing fallback, no custom error pages per frontend.
+
+`dj-serve` solves both:
+
+| Feature | `staticfiles` | `dj-serve` |
+|---------|---------------|----------|
+| SPA fallback (client-side routing) | ❌ | ✅ |
+| Custom 400/500 pages per SPA | ❌ | ✅ |
+| Isolated error handling (no global handlers) | ❌ | ✅ |
+| Path traversal protection | ❌ | ✅ |
+| Correct MIME types | ✅ | ✅ |
+| Works with any prefix | ✅ | ✅ |
+
+## Installation
+
+```bash
+pip install dj-serve
+```
+
+Requires **Django ≥ 4.0** and **Python ≥ 3.10**.
+
+## Usage
+
+### Basic SPA
+
+```python
+from django.urls import include, path
+from dj_serve import dj_serve
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+    path("api/", include("myapi.urls")),
+    dj_serve("/", "dist/"),
+]
+```
+
+`dj_serve("/", "dist/")` will:
+
+1. Serve files from `dist/` (e.g., `dist/style.css` at `/style.css`).
+2. For any other route under `/`, serve `dist/index.html` — this enables client-side routing (Vue Router, React Router, etc.).
+3. Return 404 if neither the file nor `index.html` exists.
+
+### With custom error pages
+
+```python
+dj_serve("/", "dist/", error_400="dist/400.html", error_500="dist/500.html")
+```
+
+Error pages are served **only for routes under this prefix** — your API and admin endpoints keep their default error handling.
+
+### With a prefix
+
+```python
+dj_serve("/app", "dist/", "index.html")
+```
+
+Serves the SPA at `/app/`, `/app/about`, `/app/dashboard`, etc.
+
+### Vanilla HTML site
+
+```python
+dj_serve("/", "site/", entry_point="index.html")
+```
+
+Works the same way — SPA fallback just means unknown routes serve `index.html`.
+
+### Cache-Control headers
+
+```python
+dj_serve("/", "dist/", cache_control="public, max-age=3600")
+```
+
+Apply the same value to all responses, or use a dict with glob patterns:
+
+```python
+dj_serve("/", "dist/", cache_control={
+    "*.html": "no-cache",
+    "*.css":  "public, max-age=31536000, immutable",
+    "*.js":   "public, max-age=31536000, immutable",
+    "*":      "public, max-age=3600",
+})
+```
+
+| `cache_control` | Behaviour |
+|-----------------|-----------|
+| `None` (default) | No `Cache-Control` header |
+| `str` | Same value for every response |
+| `dict[str, str]` | Glob patterns matched against the filename; first match wins |
+
+## API
+
+```python
+def dj_serve(
+    prefix: str,
+    dist_dir: str,
+    entry_point: str = "index.html",
+    error_400: str | None = None,
+    error_500: str | None = None,
+    cache_control: str | dict[str, str] | None = None,
+    async_mode: bool = False,
+) -> URLPattern:
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `prefix` | — | URL prefix (e.g., `/`, `/app`) |
+| `dist_dir` | — | Path to the directory with static files |
+| `entry_point` | `"index.html"` | HTML file to serve for SPA fallback (client-side routing) |
+| `error_400` | `None` | Path to a custom 400 error page |
+| `error_500` | `None` | Path to a custom 500 error page |
+| `cache_control` | `None` | `Cache-Control` header value. `str` for all files, `dict` for per-pattern (glob) |
+| `async_mode` | `False` | Use async I/O with `aiofiles`. Requires `pip install dj-serve[async]` |
+
+## How it works
+
+1. Django resolves the URL through the `re_path` pattern.
+2. The view looks for the requested file in `dist_dir`.
+3. If found → served with the correct MIME type.
+4. If not found → serves `entry_point` (SPA fallback).
+5. If the entry point is missing → serves the custom `error_400` page, or 404.
+6. If an exception occurs → serves the custom `error_500` page, or 500.
+
+All error handling is **contained within the view** — no global `handler400`/`handler500` configuration needed.
+
+## ASGI Support
+
+dj-serve works with both WSGI and ASGI servers (uvicorn, daphne, hypercorn).
+
+### Synchronous mode (default)
+
+```python
+dj_serve("/", "dist/")
+```
+
+Uses synchronous I/O. Django runs the view in a threadpool under ASGI.
+
+### Async mode
+
+```python
+dj_serve("/", "dist/", async_mode=True)
+```
+
+Uses non-blocking I/O with `aiofiles`. Best for ASGI servers under high concurrency.
+
+Install the async extra:
+
+```bash
+pip install dj-serve[async]
+```
+
+## Production Deployment
+
+For production, dj-serve provides `dj_serve_middleware()` which wraps your Django application with production-grade static file serving:
+
+- **WSGI** (gunicorn, waitress, uwsgi, etc.) → uses [WhiteNoise](https://whitenoise.readthedocs.io/)
+- **ASGI** (uvicorn, daphne, hypercorn, etc.) → uses [WhiteSnout](https://github.com/rroblf01/whitesnout)
+
+### Installation
+
+```bash
+# For WSGI deployments
+pip install dj-serve[wsgi]
+
+# For ASGI deployments
+pip install dj-serve[asgi]
+
+# For both
+pip install dj-serve[wsgi,asgi]
+```
+
+### WSGI Deployment
+
+In your `wsgi.py`:
+
+```python
+from django.core.wsgi import get_wsgi_application
+from dj_serve import dj_serve_middleware
+
+application = get_wsgi_application()
+application = dj_serve_middleware(application, "dist/")
+```
+
+### ASGI Deployment
+
+In your `asgi.py`:
+
+```python
+from django.core.asgi import get_asgi_application
+from dj_serve import dj_serve_middleware
+
+application = get_asgi_application()
+application = dj_serve_middleware(application, "dist/", async_mode=True)
+```
+
+### Advanced Configuration
+
+Pass additional options to the underlying middleware:
+
+```python
+# WSGI with WhiteNoise options
+application = dj_serve_middleware(
+    application,
+    "dist/",
+    max_age=86400,  # 1 day cache
+    allow_all_origins=True,
+)
+
+# ASGI with WhiteSnout options
+application = dj_serve_middleware(
+    application,
+    "dist/",
+    async_mode=True,
+    cache_max_age=86400,
+    security_headers=True,
+)
+```
+
+### How It Works
+
+The middleware and URL pattern work together:
+
+1. **Middleware** intercepts requests for static files (CSS, JS, images) and serves them with compression, caching, and security headers
+2. **`dj_serve()` URL pattern** handles SPA routing — when a file isn't found, it serves `index.html` for client-side routing
+
+```python
+# urls.py — SPA fallback (always needed)
+from dj_serve import dj_serve
+
+urlpatterns = [
+    dj_serve("/", "dist/"),
+]
+
+# wsgi.py or asgi.py — production static file serving
+from dj_serve import dj_serve_middleware
+
+application = dj_serve_middleware(application, "dist/", async_mode=True)
+```
+
+### Backend Comparison
+
+| Feature | Builtin | WhiteNoise (WSGI) | WhiteSnout (ASGI) |
+|---------|---------|-------------------|-------------------|
+| **SPA fallback** | ✅ | ❌ (needs dj-serve) | ❌ (needs dj-serve) |
+| **Compression** | ❌ | gzip + brotli | gzip + brotli |
+| **ETag / 304** | ❌ | ✅ | ✅ |
+| **Async native** | ❌ | ❌ (WSGI) | ✅ |
+| **Rust acceleration** | ❌ | ❌ | ✅ |
+| **Best for** | Development | WSGI production | ASGI production |
+
+### Development vs Production
+
+- **Development** (`DEBUG=True`): Use `dj_serve()` URL pattern only — no warning
+- **Production** (`DEBUG=False`): Configure `dj_serve_middleware()` in `wsgi.py` or `asgi.py` — otherwise a warning is logged
+
+## Testing locally
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

dj_serve-1.0.0/README.md

@@ -0,0 +1,287 @@
+[![PyPI version](https://img.shields.io/pypi/v/dj-serve.svg)](https://pypi.org/project/dj-serve/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dj-serve.svg)](https://pypi.org/project/dj-serve/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Typing: Typed](https://img.shields.io/badge/typing-PEP%20561-brightgreen.svg)](https://peps.python.org/pep-0561/)
+[![CI](https://github.com/rroblf01/dj-serve/actions/workflows/test.yml/badge.svg)](https://github.com/rroblf01/dj-serve/actions/workflows/test.yml)
+
+# dj-serve
+
+Serve SPAs (Vue, React, Angular, Svelte, or vanilla HTML) directly from Django — no separate static server needed.
+
+```python
+from dj_serve import dj_serve
+
+urlpatterns = [
+    dj_serve("/", "dist/", "index.html", "dist/400.html", "dist/500.html"),
+]
+```
+
+## Why?
+
+Traditional Django + SPA setups require either:
+
+- **A separate static file server** (nginx, Apache, CDN) — adds deployment complexity.
+- **`django.contrib.staticfiles`** — not designed for SPAs; no client-side routing fallback, no custom error pages per frontend.
+
+`dj-serve` solves both:
+
+| Feature | `staticfiles` | `dj-serve` |
+|---------|---------------|----------|
+| SPA fallback (client-side routing) | ❌ | ✅ |
+| Custom 400/500 pages per SPA | ❌ | ✅ |
+| Isolated error handling (no global handlers) | ❌ | ✅ |
+| Path traversal protection | ❌ | ✅ |
+| Correct MIME types | ✅ | ✅ |
+| Works with any prefix | ✅ | ✅ |
+
+## Installation
+
+```bash
+pip install dj-serve
+```
+
+Requires **Django ≥ 4.0** and **Python ≥ 3.10**.
+
+## Usage
+
+### Basic SPA
+
+```python
+from django.urls import include, path
+from dj_serve import dj_serve
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+    path("api/", include("myapi.urls")),
+    dj_serve("/", "dist/"),
+]
+```
+
+`dj_serve("/", "dist/")` will:
+
+1. Serve files from `dist/` (e.g., `dist/style.css` at `/style.css`).
+2. For any other route under `/`, serve `dist/index.html` — this enables client-side routing (Vue Router, React Router, etc.).
+3. Return 404 if neither the file nor `index.html` exists.
+
+### With custom error pages
+
+```python
+dj_serve("/", "dist/", error_400="dist/400.html", error_500="dist/500.html")
+```
+
+Error pages are served **only for routes under this prefix** — your API and admin endpoints keep their default error handling.
+
+### With a prefix
+
+```python
+dj_serve("/app", "dist/", "index.html")
+```
+
+Serves the SPA at `/app/`, `/app/about`, `/app/dashboard`, etc.
+
+### Vanilla HTML site
+
+```python
+dj_serve("/", "site/", entry_point="index.html")
+```
+
+Works the same way — SPA fallback just means unknown routes serve `index.html`.
+
+### Cache-Control headers
+
+```python
+dj_serve("/", "dist/", cache_control="public, max-age=3600")
+```
+
+Apply the same value to all responses, or use a dict with glob patterns:
+
+```python
+dj_serve("/", "dist/", cache_control={
+    "*.html": "no-cache",
+    "*.css":  "public, max-age=31536000, immutable",
+    "*.js":   "public, max-age=31536000, immutable",
+    "*":      "public, max-age=3600",
+})
+```
+
+| `cache_control` | Behaviour |
+|-----------------|-----------|
+| `None` (default) | No `Cache-Control` header |
+| `str` | Same value for every response |
+| `dict[str, str]` | Glob patterns matched against the filename; first match wins |
+
+## API
+
+```python
+def dj_serve(
+    prefix: str,
+    dist_dir: str,
+    entry_point: str = "index.html",
+    error_400: str | None = None,
+    error_500: str | None = None,
+    cache_control: str | dict[str, str] | None = None,
+    async_mode: bool = False,
+) -> URLPattern:
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `prefix` | — | URL prefix (e.g., `/`, `/app`) |
+| `dist_dir` | — | Path to the directory with static files |
+| `entry_point` | `"index.html"` | HTML file to serve for SPA fallback (client-side routing) |
+| `error_400` | `None` | Path to a custom 400 error page |
+| `error_500` | `None` | Path to a custom 500 error page |
+| `cache_control` | `None` | `Cache-Control` header value. `str` for all files, `dict` for per-pattern (glob) |
+| `async_mode` | `False` | Use async I/O with `aiofiles`. Requires `pip install dj-serve[async]` |
+
+## How it works
+
+1. Django resolves the URL through the `re_path` pattern.
+2. The view looks for the requested file in `dist_dir`.
+3. If found → served with the correct MIME type.
+4. If not found → serves `entry_point` (SPA fallback).
+5. If the entry point is missing → serves the custom `error_400` page, or 404.
+6. If an exception occurs → serves the custom `error_500` page, or 500.
+
+All error handling is **contained within the view** — no global `handler400`/`handler500` configuration needed.
+
+## ASGI Support
+
+dj-serve works with both WSGI and ASGI servers (uvicorn, daphne, hypercorn).
+
+### Synchronous mode (default)
+
+```python
+dj_serve("/", "dist/")
+```
+
+Uses synchronous I/O. Django runs the view in a threadpool under ASGI.
+
+### Async mode
+
+```python
+dj_serve("/", "dist/", async_mode=True)
+```
+
+Uses non-blocking I/O with `aiofiles`. Best for ASGI servers under high concurrency.
+
+Install the async extra:
+
+```bash
+pip install dj-serve[async]
+```
+
+## Production Deployment
+
+For production, dj-serve provides `dj_serve_middleware()` which wraps your Django application with production-grade static file serving:
+
+- **WSGI** (gunicorn, waitress, uwsgi, etc.) → uses [WhiteNoise](https://whitenoise.readthedocs.io/)
+- **ASGI** (uvicorn, daphne, hypercorn, etc.) → uses [WhiteSnout](https://github.com/rroblf01/whitesnout)
+
+### Installation
+
+```bash
+# For WSGI deployments
+pip install dj-serve[wsgi]
+
+# For ASGI deployments
+pip install dj-serve[asgi]
+
+# For both
+pip install dj-serve[wsgi,asgi]
+```
+
+### WSGI Deployment
+
+In your `wsgi.py`:
+
+```python
+from django.core.wsgi import get_wsgi_application
+from dj_serve import dj_serve_middleware
+
+application = get_wsgi_application()
+application = dj_serve_middleware(application, "dist/")
+```
+
+### ASGI Deployment
+
+In your `asgi.py`:
+
+```python
+from django.core.asgi import get_asgi_application
+from dj_serve import dj_serve_middleware
+
+application = get_asgi_application()
+application = dj_serve_middleware(application, "dist/", async_mode=True)
+```
+
+### Advanced Configuration
+
+Pass additional options to the underlying middleware:
+
+```python
+# WSGI with WhiteNoise options
+application = dj_serve_middleware(
+    application,
+    "dist/",
+    max_age=86400,  # 1 day cache
+    allow_all_origins=True,
+)
+
+# ASGI with WhiteSnout options
+application = dj_serve_middleware(
+    application,
+    "dist/",
+    async_mode=True,
+    cache_max_age=86400,
+    security_headers=True,
+)
+```
+
+### How It Works
+
+The middleware and URL pattern work together:
+
+1. **Middleware** intercepts requests for static files (CSS, JS, images) and serves them with compression, caching, and security headers
+2. **`dj_serve()` URL pattern** handles SPA routing — when a file isn't found, it serves `index.html` for client-side routing
+
+```python
+# urls.py — SPA fallback (always needed)
+from dj_serve import dj_serve
+
+urlpatterns = [
+    dj_serve("/", "dist/"),
+]
+
+# wsgi.py or asgi.py — production static file serving
+from dj_serve import dj_serve_middleware
+
+application = dj_serve_middleware(application, "dist/", async_mode=True)
+```
+
+### Backend Comparison
+
+| Feature | Builtin | WhiteNoise (WSGI) | WhiteSnout (ASGI) |
+|---------|---------|-------------------|-------------------|
+| **SPA fallback** | ✅ | ❌ (needs dj-serve) | ❌ (needs dj-serve) |
+| **Compression** | ❌ | gzip + brotli | gzip + brotli |
+| **ETag / 304** | ❌ | ✅ | ✅ |
+| **Async native** | ❌ | ❌ (WSGI) | ✅ |
+| **Rust acceleration** | ❌ | ❌ | ✅ |
+| **Best for** | Development | WSGI production | ASGI production |
+
+### Development vs Production
+
+- **Development** (`DEBUG=True`): Use `dj_serve()` URL pattern only — no warning
+- **Production** (`DEBUG=False`): Configure `dj_serve_middleware()` in `wsgi.py` or `asgi.py` — otherwise a warning is logged
+
+## Testing locally
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

dj_serve-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "dj-serve"
+version = "1.0.0"
+description = "Serve SPAs (Vue, React, Angular, vanilla HTML) directly from Django"
+readme = "README.md"
+keywords = ["django", "spa", "static", "vue", "react", "angular", "frontend"]
+authors = [
+    { name = "Ricardo Robles", email = "ricardo.r.f@hotmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = ["django>=4.0"]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.0",
+    "Framework :: Django :: 4.1",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/rroblf01/dj-serve"
+Repository = "https://github.com/rroblf01/dj-serve"
+Issues = "https://github.com/rroblf01/dj-serve/issues"
+
+[project.optional-dependencies]
+async = ["aiofiles>=25.1.0"]
+wsgi = ["whitenoise>=6.0"]
+asgi = ["whitesnout>=1.0"]
+dev = ["pytest>=9.1.1", "pytest-django>=4", "pytest-asyncio>=1.4.0", "ruff==0.15.20", "ty==0.0.56", "django-stubs>=5", "aiofiles>=25.1.0", "whitenoise>=6.0", "whitesnout>=1.0", "httpx>=0.27.0"]
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "pytest-django>=4", "pytest-asyncio>=1.4.0", "ruff==0.15.20", "ty==0.0.56", "django-stubs>=5", "aiofiles>=25.1.0", "whitenoise>=6.0", "whitesnout>=1.0", "httpx>=0.27.0"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

dj_serve-1.0.0/src/dj_serve/__init__.py

@@ -0,0 +1,77 @@
+__all__ = ["dj_serve", "dj_serve_middleware", "DjServeConfigError"]
+
+import logging
+from typing import Callable
+
+from django.conf import settings
+from django.urls import re_path
+from django.urls.resolvers import URLPattern
+
+from .config import DjServeConfigError, validate_config
+from .middleware import dj_serve_middleware
+from .views import CacheControl, async_serve_view, serve_view
+
+logger = logging.getLogger(__name__)
+
+
+def dj_serve(
+    prefix: str,
+    dist_dir: str,
+    entry_point: str = "index.html",
+    error_400: str | None = None,
+    error_500: str | None = None,
+    cache_control: CacheControl = None,
+    async_mode: bool = False,
+) -> URLPattern:
+    """Configure serve serving for Django.
+
+    Args:
+        prefix: URL prefix for the serve (e.g., "/" or "/app").
+        dist_dir: Path to the directory containing static files.
+        entry_point: Name of the entry point HTML file (default: "index.html").
+        error_400: Optional path to custom 400 error page.
+        error_500: Optional path to custom 500 error page.
+        cache_control: Optional cache control configuration.
+        async_mode: If True, use async view for ASGI servers (default: False).
+
+    Returns:
+        URLPattern for Django URL configuration.
+
+    Raises:
+        DjServeConfigError: If configuration is invalid.
+    """
+    logger.debug(f"Configuring dj-serve: prefix={prefix}, dist_dir={dist_dir}")
+    validate_config(dist_dir, entry_point, error_400, error_500)
+
+    # Warn if using builtin in production without static middleware
+    if not settings.DEBUG and not _has_static_middleware():
+        server_type = "asgi.py" if async_mode else "wsgi.py"
+        logger.warning(
+            f"dj-serve is using the builtin static file server in production. "
+            f"For better performance, configure dj_serve_middleware() in your "
+            f"{server_type} with the appropriate backend."
+        )
+
+    prefix = prefix.rstrip("/")
+    regex = rf"^{prefix}/(?P<path>.*)$"
+    view: Callable = async_serve_view if async_mode else serve_view
+    return re_path(
+        regex,
+        view,
+        kwargs={
+            "dist_dir": dist_dir,
+            "entry_point": entry_point,
+            "error_400_path": error_400,
+            "error_500_path": error_500,
+            "cache_control": cache_control,
+        },
+    )
+
+
+def _has_static_middleware() -> bool:
+    """Check if WhiteNoise or WhiteSnout is configured in Django middleware."""
+    middleware = getattr(settings, "MIDDLEWARE", [])
+    for mw in middleware:
+        if "whitenoise" in mw.lower() or "whitesnout" in mw.lower():
+            return True
+    return False

dj_serve-1.0.0/src/dj_serve/config.py

@@ -0,0 +1,46 @@
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class DjServeConfigError(Exception):
+    """Raised when dj-serve configuration is invalid."""
+
+
+def validate_config(
+    dist_dir: str,
+    entry_point: str,
+    error_400_path: str | None = None,
+    error_500_path: str | None = None,
+) -> None:
+    """Validate dj-serve configuration at startup.
+
+    Args:
+        dist_dir: Path to the directory containing static files.
+        entry_point: Name of the entry point HTML file (e.g., "index.html").
+        error_400_path: Optional path to custom 400 error page.
+        error_500_path: Optional path to custom 500 error page.
+
+    Raises:
+        DjServeConfigError: If configuration is invalid.
+    """
+    dist_path = Path(dist_dir)
+
+    if not dist_path.exists():
+        raise DjServeConfigError(f"dist_dir does not exist: {dist_dir}")
+
+    if not dist_path.is_dir():
+        raise DjServeConfigError(f"dist_dir is not a directory: {dist_dir}")
+
+    entry_path = dist_path / entry_point
+    if not entry_path.exists():
+        raise DjServeConfigError(
+            f"entry_point '{entry_point}' not found in dist_dir: {entry_path}"
+        )
+
+    if error_400_path and not Path(error_400_path).exists():
+        logger.warning(f"error_400_path does not exist: {error_400_path}")
+
+    if error_500_path and not Path(error_500_path).exists():
+        logger.warning(f"error_500_path does not exist: {error_500_path}")

dj_serve-1.0.0/src/dj_serve/middleware.py

@@ -0,0 +1,103 @@
+"""Production static file middleware integration for dj-serve.
+
+This module provides dj_serve_middleware() which wraps a Django application
+with WhiteNoise (WSGI) or WhiteSnout (ASGI) for production-grade static
+file serving.
+"""
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+def dj_serve_middleware(
+    app: Callable,
+    dist_dir: str,
+    async_mode: bool = False,
+    **kwargs: Any,
+) -> Callable:
+    """Wrap Django app with production static file middleware.
+
+    This function automatically selects the appropriate backend based on
+    async_mode:
+    - async_mode=False → WhiteNoise (WSGI)
+    - async_mode=True → WhiteSnout (ASGI)
+
+    Args:
+        app: Django WSGI or ASGI application to wrap
+        dist_dir: Path to the directory containing static files
+        async_mode: If True, use WhiteSnout (ASGI); if False, use WhiteNoise (WSGI)
+        **kwargs: Additional arguments passed to the backend constructor
+                  (e.g., cache_max_age, security_headers, etc.)
+
+    Returns:
+        Wrapped application with static file middleware
+
+    Raises:
+        ImportError: If the required backend is not installed
+
+    Examples:
+        WSGI (gunicorn, waitress, etc.):
+
+            from django.core.wsgi import get_wsgi_application
+            from dj_serve import dj_serve_middleware
+
+            application = get_wsgi_application()
+            application = dj_serve_middleware(application, "dist/")
+
+        ASGI (uvicorn, daphne, etc.):
+
+            from django.core.asgi import get_asgi_application
+            from dj_serve import dj_serve_middleware
+
+            application = get_asgi_application()
+            application = dj_serve_middleware(application, "dist/", async_mode=True)
+
+    """
+    if async_mode:
+        return _setup_whitesnout(app, dist_dir, **kwargs)
+    else:
+        return _setup_whitenoise(app, dist_dir, **kwargs)
+
+
+def _setup_whitenoise(app: Callable, dist_dir: str, **kwargs: Any) -> Callable:
+    """Setup WhiteNoise middleware for WSGI applications."""
+    try:
+        from whitenoise import WhiteNoise
+    except ImportError as exc:
+        raise ImportError(
+            "WhiteNoise is required for WSGI static file serving. "
+            "Install it with: pip install dj-serve[wsgi]"
+        ) from exc
+
+    logger.info(f"Configuring WhiteNoise for WSGI with dist_dir={dist_dir}")
+
+    # WhiteNoise configuration
+    # root: directory to serve files from
+    # Additional kwargs are passed through (e.g., max_age, autorefresh)
+    whitenoise_kwargs = {"root": dist_dir}
+    whitenoise_kwargs.update(kwargs)
+
+    return WhiteNoise(app, **whitenoise_kwargs)  # type: ignore
+
+
+def _setup_whitesnout(app: Callable, dist_dir: str, **kwargs: Any) -> Callable:
+    """Setup WhiteSnout middleware for ASGI applications."""
+    try:
+        from whitesnout import WhiteSnout
+    except ImportError as exc:
+        raise ImportError(
+            "WhiteSnout is required for ASGI static file serving. "
+            "Install it with: pip install dj-serve[asgi]"
+        ) from exc
+
+    logger.info(f"Configuring WhiteSnout for ASGI with dist_dir={dist_dir}")
+
+    # WhiteSnout configuration
+    # directory: directory to serve files from
+    # Additional kwargs are passed through (e.g., cache_max_age, security_headers)
+    whitesnout_kwargs = {"directory": dist_dir}
+    whitesnout_kwargs.update(kwargs)
+
+    return WhiteSnout(app, **whitesnout_kwargs)  # type: ignore

dj_serve-1.0.0/src/dj_serve/views.py

@@ -0,0 +1,191 @@
+import fnmatch
+import logging
+import mimetypes
+from io import BytesIO
+from pathlib import Path
+
+from django.http import (
+    FileResponse,
+    HttpRequest,
+    HttpResponseBase,
+    HttpResponseNotFound,
+)
+
+logger = logging.getLogger(__name__)
+
+CacheControl = str | dict[str, str] | None
+
+
+def serve_view(
+    request: HttpRequest,
+    path: str,
+    dist_dir: str,
+    entry_point: str,
+    error_400_path: str | None = None,
+    error_500_path: str | None = None,
+    cache_control: CacheControl = None,
+) -> HttpResponseBase:
+    try:
+        if ".." in path:
+            return HttpResponseNotFound("Not Found")
+
+        dist = Path(dist_dir).resolve()
+
+        if not path or path.strip("/") == "":
+            target = dist / entry_point
+            if not target.exists():
+                resp = _error_response(error_400_path, 400, cache_control)
+                if resp is not None:
+                    return resp
+                return HttpResponseNotFound("Not Found")
+            return _file_response(target, "text/html", cache_control)
+
+        target = (dist / path).resolve()
+        if not str(target).startswith(str(dist)):
+            return HttpResponseNotFound("Not Found")
+
+        if target.exists() and target.is_file():
+            return _file_response(target, cache_control=cache_control)
+
+        entry = dist / entry_point
+        if entry.exists():
+            return _file_response(entry, "text/html", cache_control)
+
+        resp = _error_response(error_400_path, 400, cache_control)
+        if resp is not None:
+            return resp
+        return HttpResponseNotFound("Not Found")
+    except Exception:
+        logger.exception("Error serving serve file")
+        resp = _error_response(error_500_path, 500, cache_control)
+        if resp is not None:
+            return resp
+        return HttpResponseNotFound("Server Error", status=500)
+
+
+async def async_serve_view(
+    request: HttpRequest,
+    path: str,
+    dist_dir: str,
+    entry_point: str,
+    error_400_path: str | None = None,
+    error_500_path: str | None = None,
+    cache_control: CacheControl = None,
+) -> HttpResponseBase:
+    try:
+        import aiofiles
+        import aiofiles.os
+    except ImportError as exc:
+        raise ImportError(
+            "Async mode requires aiofiles. Install it with: pip install dj-serve[async]"
+        ) from exc
+
+    try:
+        if ".." in path:
+            return HttpResponseNotFound("Not Found")
+
+        dist = Path(dist_dir).resolve()
+
+        if not path or path.strip("/") == "":
+            target = dist / entry_point
+            if not await aiofiles.os.path.exists(target):
+                resp = await _async_error_response(error_400_path, 400, cache_control)
+                if resp is not None:
+                    return resp
+                return HttpResponseNotFound("Not Found")
+            return await _async_file_response(target, "text/html", cache_control)
+
+        target = (dist / path).resolve()
+        if not str(target).startswith(str(dist)):
+            return HttpResponseNotFound("Not Found")
+
+        if await aiofiles.os.path.exists(target) and target.is_file():
+            return await _async_file_response(target, cache_control=cache_control)
+
+        entry = dist / entry_point
+        if await aiofiles.os.path.exists(entry):
+            return await _async_file_response(entry, "text/html", cache_control)
+
+        resp = await _async_error_response(error_400_path, 400, cache_control)
+        if resp is not None:
+            return resp
+        return HttpResponseNotFound("Not Found")
+    except Exception:
+        logger.exception("Error serving serve file (async)")
+        resp = await _async_error_response(error_500_path, 500, cache_control)
+        if resp is not None:
+            return resp
+        return HttpResponseNotFound("Server Error", status=500)
+
+
+def _file_response(
+    path: Path, forced_type: str | None = None, cache_control: CacheControl = None
+) -> FileResponse:
+    content_type = (
+        forced_type or mimetypes.guess_type(str(path))[0] or "application/octet-stream"
+    )
+    response = FileResponse(open(path, "rb"), content_type=content_type)
+    response["X-Content-Type-Options"] = "nosniff"
+    _apply_cache_control(response, cache_control, path.name)
+    return response
+
+
+async def _async_file_response(
+    path: Path, forced_type: str | None = None, cache_control: CacheControl = None
+) -> FileResponse:
+    import aiofiles
+
+    content_type = (
+        forced_type or mimetypes.guess_type(str(path))[0] or "application/octet-stream"
+    )
+    async with aiofiles.open(path, "rb") as f:
+        content = await f.read()
+    response = FileResponse(BytesIO(content), content_type=content_type)
+    response["X-Content-Type-Options"] = "nosniff"
+    _apply_cache_control(response, cache_control, path.name)
+    return response
+
+
+def _error_response(
+    error_path: str | None, status: int, cache_control: CacheControl = None
+) -> FileResponse | None:
+    if error_path and Path(error_path).exists():
+        response = FileResponse(
+            open(error_path, "rb"), content_type="text/html", status=status
+        )
+        response["X-Content-Type-Options"] = "nosniff"
+        _apply_cache_control(response, cache_control, Path(error_path).name)
+        return response
+    return None
+
+
+async def _async_error_response(
+    error_path: str | None, status: int, cache_control: CacheControl = None
+) -> FileResponse | None:
+    import aiofiles
+    import aiofiles.os
+
+    if error_path and await aiofiles.os.path.exists(error_path):
+        async with aiofiles.open(error_path, "rb") as f:
+            content = await f.read()
+        response = FileResponse(
+            BytesIO(content), content_type="text/html", status=status
+        )
+        response["X-Content-Type-Options"] = "nosniff"
+        _apply_cache_control(response, cache_control, Path(error_path).name)
+        return response
+    return None
+
+
+def _apply_cache_control(
+    response: FileResponse, cache_control: CacheControl, filename: str
+) -> None:
+    if cache_control is None:
+        return
+    if isinstance(cache_control, str):
+        response["Cache-Control"] = cache_control
+        return
+    for pattern, value in cache_control.items():
+        if fnmatch.fnmatch(filename, pattern):
+            response["Cache-Control"] = value
+            return