plain 0.83.0__tar.gz → 0.84.0__tar.gz

{plain-0.83.0 → plain-0.84.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.83.0
+Version: 0.84.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.83.0 → plain-0.84.0}/plain/CHANGELOG.md

@@ -1,5 +1,33 @@
 # plain changelog
 
+## [0.84.0](https://github.com/dropseed/plain/releases/plain@0.84.0) (2025-10-29)
+
+### What's changed
+
+- The `DEFAULT_RESPONSE_HEADERS` setting now supports format string placeholders (e.g., `{request.csp_nonce}`) for dynamic header values instead of requiring a callable function ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Views can now set headers to `None` to explicitly remove default response headers ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Added comprehensive documentation for customizing default response headers including override, remove, and extend patterns ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+
+### Upgrade instructions
+
+- If you have `DEFAULT_RESPONSE_HEADERS` configured as a callable function, convert it to a dictionary with format string placeholders:
+
+    ```python
+    # Before:
+    def DEFAULT_RESPONSE_HEADERS(request):
+        nonce = request.csp_nonce
+        return {
+            "Content-Security-Policy": f"script-src 'self' 'nonce-{nonce}'",
+        }
+
+    # After:
+    DEFAULT_RESPONSE_HEADERS = {
+        "Content-Security-Policy": "script-src 'self' 'nonce-{request.csp_nonce}'",
+    }
+    ```
+
+- If you were overriding default headers to empty strings (`""`) to remove them, change those to `None` instead
+
 ## [0.83.0](https://github.com/dropseed/plain/releases/plain@0.83.0) (2025-10-29)
 
 ### What's changed

plain-0.84.0/plain/http/README.md

@@ -0,0 +1,142 @@
+# HTTP
+
+**HTTP request and response handling.**
+
+- [Overview](#overview)
+- [Content Security Policy (CSP)](#content-security-policy-csp)
+- [Customizing Default Response Headers](#customizing-default-response-headers)
+
+## Overview
+
+Typically you will interact with [Request](request.py#Request) and [Response](response.py#ResponseBase) objects in your views and middleware.
+
+```python
+from plain.views import View
+from plain.http import Response
+
+class ExampleView(View):
+    def get(self):
+        # Accessing a request header
+        print(self.request.headers.get("Example-Header"))
+
+        # Accessing a query parameter
+        print(self.request.query_params.get("example"))
+
+        # Creating a response
+        response = Response("Hello, world!", status_code=200)
+
+        # Setting a response header
+        response.headers["Example-Header"] = "Example Value"
+
+        return response
+```
+
+## Content Security Policy (CSP)
+
+Plain includes built-in support for Content Security Policy (CSP) through nonces, allowing you to use strict CSP policies without `'unsafe-inline'`.
+
+Each request generates a unique cryptographically secure nonce available via [`request.csp_nonce`](request.py#Request.csp_nonce):
+
+### Configuring CSP Headers
+
+Include CSP in `DEFAULT_RESPONSE_HEADERS` using `{request.csp_nonce}` placeholders for dynamic nonces:
+
+```python
+# app/settings.py
+DEFAULT_RESPONSE_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'self'; "
+        "script-src 'self' 'nonce-{request.csp_nonce}'; "
+        "style-src 'self' 'nonce-{request.csp_nonce}'; "
+        "img-src 'self' data:; "
+        "font-src 'self'; "
+        "connect-src 'self'; "
+        "frame-ancestors 'self'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    ),
+    # Other default headers...
+    "X-Frame-Options": "DENY",
+}
+```
+
+The `{request.csp_nonce}` placeholder will be replaced with a unique nonce for each request.
+
+Use tools like [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/) to analyze your CSP policy and identify potential security issues or misconfigurations.
+
+### Using Nonces in Templates
+
+Add the nonce attribute to inline scripts and styles in your templates:
+
+```html
+<!-- Inline script with nonce -->
+<script nonce="{{ request.csp_nonce }}">
+    console.log("This script is allowed by CSP");
+</script>
+
+<!-- Inline style with nonce -->
+<style nonce="{{ request.csp_nonce }}">
+    .example { color: red; }
+</style>
+```
+
+External scripts and stylesheets loaded from `'self'` don't need nonces:
+
+```html
+<!-- External scripts/styles work with 'self' directive -->
+<script src="/assets/app.js"></script>
+<link rel="stylesheet" href="/assets/app.css">
+```
+
+## Customizing Default Response Headers
+
+Plain applies default response headers to all responses via `DEFAULT_RESPONSE_HEADERS` in settings. Views can customize these headers in several ways:
+
+### Override Default Headers
+
+Set the header to a different value in your view:
+
+```python
+class MyView(View):
+    def get(self):
+        response = Response("content")
+        # Override the default X-Frame-Options: DENY
+        response.headers["X-Frame-Options"] = "SAMEORIGIN"
+        return response
+```
+
+### Remove Default Headers
+
+Set the header to `None` to prevent it from being applied:
+
+```python
+class EmbeddableView(View):
+    def get(self):
+        response = Response("content")
+        # Remove X-Frame-Options entirely to allow embedding
+        response.headers["X-Frame-Options"] = None
+        return response
+```
+
+### Extend Default Headers
+
+Read the default value from settings, modify it, then set it in your view:
+
+```python
+from plain.runtime import settings
+
+class MyView(View):
+    def get(self):
+        response = Response("content")
+
+        # Get the default CSP policy
+        if csp := settings.DEFAULT_RESPONSE_HEADERS.get("Content-Security-Policy"):
+            # Format it with the current request to resolve placeholders
+            csp = csp.format(request=self.request)
+            # Extend with additional sources
+            response.headers["Content-Security-Policy"] = (
+                f"{csp}; script-src https://analytics.example.com"
+            )
+
+        return response
+```

plain-0.84.0/plain/internal/middleware/headers.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plain.http import HttpMiddleware
+from plain.runtime import settings
+
+if TYPE_CHECKING:
+    from plain.http import Request, Response
+
+
+class DefaultHeadersMiddleware(HttpMiddleware):
+    """
+    Applies default response headers from settings.DEFAULT_RESPONSE_HEADERS.
+
+    This middleware runs after the view executes and applies default headers
+    to the response using setdefault(), which means:
+    - Headers already set by the view won't be overridden
+    - Headers not set by the view will use the default value
+
+    View Customization Patterns:
+    - Use default: Don't set the header (middleware applies it)
+    - Override: Set the header to a different value
+    - Remove: Set the header to None (middleware will delete it)
+    - Extend: Read from settings.DEFAULT_RESPONSE_HEADERS, modify, then set
+
+    Format Strings:
+    Header values can include {request.attribute} placeholders for dynamic
+    content. Example: 'nonce-{request.csp_nonce}' will be formatted with
+    the request's csp_nonce value. Headers without placeholders are used as-is.
+
+    None Removal:
+    Views can set a header to None to opt-out of that default header entirely.
+    The middleware will delete any header set to None, preventing the default
+    from being applied.
+    """
+
+    def process_request(self, request: Request) -> Response:
+        # Get the response from the view (and any inner middleware)
+        response = self.get_response(request)
+
+        # Apply default headers to the response
+        for header, value in settings.DEFAULT_RESPONSE_HEADERS.items():
+            if header not in response.headers:
+                # Header not set - apply default
+                if "{" in value:
+                    response.headers[header] = value.format(request=request)
+                else:
+                    response.headers[header] = value
+            elif response.headers[header] is None:
+                # Header explicitly set to None by view - remove it
+                del response.headers[header]
+
+        # Add the Content-Length header to non-streaming responses if not
+        # already set.
+        if not response.streaming and "Content-Length" not in response.headers:
+            response.headers["Content-Length"] = str(len(response.content))
+
+        return response

{plain-0.83.0 → plain-0.84.0}/plain/runtime/global_settings.py

@@ -27,8 +27,12 @@ URLS_ROUTER: str
 ALLOWED_HOSTS: list[str] = []
 
 # Default headers for all responses.
-DEFAULT_RESPONSE_HEADERS = {
-    # "Content-Security-Policy": "default-src 'self'",
+# Header values can include {request.attribute} placeholders for dynamic content.
+# Example: "script-src 'nonce-{request.csp_nonce}'" will use the request's nonce.
+# Views can override, remove, or extend these headers - see plain/http/README.md
+# for customization patterns.
+DEFAULT_RESPONSE_HEADERS: dict = {
+    # "Content-Security-Policy": "default-src 'self'; script-src 'self' 'nonce-{request.csp_nonce}'",
     # https://hstspreload.org/
     # "Strict-Transport-Security": "max-age=31536000; includeSubDomains; preload",
     "Cross-Origin-Opener-Policy": "same-origin",

{plain-0.83.0 → plain-0.84.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.83.0"
+version = "0.84.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain-0.83.0/plain/http/README.md

@@ -1,89 +0,0 @@
-# HTTP
-
-**HTTP request and response handling.**
-
-- [Overview](#overview)
-- [Content Security Policy (CSP)](#content-security-policy-csp)
-
-## Overview
-
-Typically you will interact with [Request](request.py#Request) and [Response](response.py#ResponseBase) objects in your views and middleware.
-
-```python
-from plain.views import View
-from plain.http import Response
-
-class ExampleView(View):
-    def get(self):
-        # Accessing a request header
-        print(self.request.headers.get("Example-Header"))
-
-        # Accessing a query parameter
-        print(self.request.query_params.get("example"))
-
-        # Creating a response
-        response = Response("Hello, world!", status_code=200)
-
-        # Setting a response header
-        response.headers["Example-Header"] = "Example Value"
-
-        return response
-```
-
-## Content Security Policy (CSP)
-
-Plain includes built-in support for Content Security Policy (CSP) through nonces, allowing you to use strict CSP policies without `'unsafe-inline'`.
-
-Each request generates a unique cryptographically secure nonce available via [`request.csp_nonce`](request.py#Request.csp_nonce):
-
-### Configuring CSP Headers
-
-Set `DEFAULT_RESPONSE_HEADERS` as a callable function to generate dynamic CSP headers with nonces:
-
-```python
-# app/settings.py
-def DEFAULT_RESPONSE_HEADERS(request):
-    """
-    Dynamic response headers with CSP nonces.
-    """
-    nonce = request.csp_nonce
-    return {
-        "Content-Security-Policy": (
-            f"default-src 'self'; "
-            f"script-src 'self' 'nonce-{nonce}'; "
-            f"style-src 'self' 'nonce-{nonce}'; "
-            f"img-src 'self' data:; "
-            f"font-src 'self'; "
-            f"connect-src 'self'; "
-            f"frame-ancestors 'self'; "
-            f"base-uri 'self'; "
-            f"form-action 'self'"
-        ),
-    }
-```
-
-Use tools like [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/) to analyze your CSP policy and identify potential security issues or misconfigurations.
-
-### Using Nonces in Templates
-
-Add the nonce attribute to inline scripts and styles in your templates:
-
-```html
-<!-- Inline script with nonce -->
-<script nonce="{{ request.csp_nonce }}">
-    console.log("This script is allowed by CSP");
-</script>
-
-<!-- Inline style with nonce -->
-<style nonce="{{ request.csp_nonce }}">
-    .example { color: red; }
-</style>
-```
-
-External scripts and stylesheets loaded from `'self'` don't need nonces:
-
-```html
-<!-- External scripts/styles work with 'self' directive -->
-<script src="/assets/app.js"></script>
-<link rel="stylesheet" href="/assets/app.css">
-```

plain-0.83.0/plain/internal/middleware/headers.py

@@ -1,37 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from plain.http import HttpMiddleware
-from plain.runtime import settings
-
-if TYPE_CHECKING:
-    from plain.http import Request, Response
-
-
-class DefaultHeadersMiddleware(HttpMiddleware):
-    def process_request(self, request: Request) -> Response:
-        response = self.get_response(request)
-
-        # Support callable DEFAULT_RESPONSE_HEADERS for dynamic header generation
-        # (e.g., CSP nonces that change per request)
-        if callable(settings.DEFAULT_RESPONSE_HEADERS):
-            default_headers = settings.DEFAULT_RESPONSE_HEADERS(request)
-        else:
-            default_headers = settings.DEFAULT_RESPONSE_HEADERS
-
-        for header, value in default_headers.items():
-            # Since we don't have a good way to *remove* default response headers,
-            # use allow users to set them to an empty string to indicate they should be removed.
-            if header in response.headers and response.headers[header] == "":
-                del response.headers[header]
-                continue
-
-            response.headers.setdefault(header, value)
-
-        # Add the Content-Length header to non-streaming responses if not
-        # already set.
-        if not response.streaming and "Content-Length" not in response.headers:
-            response.headers["Content-Length"] = str(len(response.content))
-
-        return response