plain 0.56.0__tar.gz → 0.57.0__tar.gz

{plain-0.56.0 → plain-0.57.0}/PKG-INFO

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

{plain-0.56.0 → plain-0.57.0}/plain/CHANGELOG.md

@@ -1,5 +1,30 @@
 # plain changelog
 
+## [0.57.0](https://github.com/dropseed/plain/releases/plain@0.57.0) (2025-08-15)
+
+### What's changed
+
+- The `ResponsePermanentRedirect` class has been removed; use `ResponseRedirect` with `status_code=301` instead ([d5735ea](https://github.com/dropseed/plain/commit/d5735ea4f8))
+- The `RedirectView.permanent` attribute has been replaced with `status_code` for more flexible redirect status codes ([12dda16](https://github.com/dropseed/plain/commit/12dda16731))
+- Updated `RedirectView` initialization parameters: `url_name` replaces `pattern_name`, `preserve_query_params` replaces `query_string`, and removed 410 Gone functionality ([3b9ca71](https://github.com/dropseed/plain/commit/3b9ca713bf))
+
+### Upgrade instructions
+
+- Replace `ResponsePermanentRedirect` imports with `ResponseRedirect` and pass `status_code=301` to the constructor
+- Update `RedirectView` subclasses to use `status_code=301` instead of `permanent=True`
+- Replace `pattern_name` with `url_name` in RedirectView usage
+- Replace `query_string=True` with `preserve_query_params=True` in RedirectView usage
+
+## [0.56.1](https://github.com/dropseed/plain/releases/plain@0.56.1) (2025-07-30)
+
+### What's changed
+
+- Improved `plain install` command instructions to be more explicit about completing code modifications ([83292225db](https://github.com/dropseed/plain/commit/83292225db))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.56.0](https://github.com/dropseed/plain/releases/plain@0.56.0) (2025-07-25)
 
 ### What's changed

{plain-0.56.0 → plain-0.57.0}/plain/assets/README.md

@@ -2,7 +2,13 @@
 
 **Serve static assets (CSS, JS, images, etc.) directly or from a CDN.**
 
-## Usage
+- [Overview](#overview)
+- [Local development](#local-development)
+- [Production deployment](#production-deployment)
+- [Using `AssetView` directly](#using-assetview-directly)
+- [FAQs](#faqs)
+
+## Overview
 
 To serve assets, put them in `app/assets` or `app/{package}/assets`.
 
@@ -62,7 +68,7 @@ class AppRouter(Router):
 
 ## FAQs
 
-### How do you reference assets in Python code?
+#### How do you reference assets in Python code?
 
 There is a [`get_asset_url`](./urls.py#get_asset_url) function that you can use to get the URL of an asset in Python code. This is useful if you need to reference an asset in a non-template context, such as in a redirect or an API response.
 
@@ -72,7 +78,7 @@ from plain.assets.urls import get_asset_url
 url = get_asset_url("css/style.css")
 ```
 
-### What if I need the files in a different location?
+#### What if I need the files in a different location?
 
 The generated/copied files are stored in `{repo}/.plain/assets/compiled`. If you need them to be somewhere else, try simply moving them after compilation.
 
@@ -81,7 +87,7 @@ plain build
 mv .plain/assets/compiled /path/to/your/static
 ```
 
-### How do I upload the assets to a CDN?
+#### How do I upload the assets to a CDN?
 
 The steps for this will vary, but the general idea is to compile them, and then upload the compiled assets from their [compiled location](compile.py#get_compiled_path).
 
@@ -103,7 +109,7 @@ Use the [`ASSETS_BASE_URL`](../runtime/global_settings.py#ASSETS_BASE_URL) setti
 ASSETS_BASE_URL = "https://cdn.example.com/"
 ```
 
-### Why aren't the originals copied to the compiled directory?
+#### Why aren't the originals copied to the compiled directory?
 
 The default behavior is to fingerprint assets, which is an exact copy of the original file but with a different filename. The originals aren't copied over because you should generally always use this fingerprinted path (that automatically uses longer-lived caching).
 

{plain-0.56.0 → plain-0.57.0}/plain/chores/README.md

@@ -2,6 +2,12 @@
 
 **Routine maintenance tasks.**
 
+- [Overview](#overview)
+- [Running chores](#running-chores)
+- [Writing chores](#writing-chores)
+
+## Overview
+
 Chores are registered functions that can be run at any time to keep an app in a desirable state.
 
 ![](https://assets.plainframework.com/docs/plain-chores-run.png)

plain-0.57.0/plain/cli/README.md

@@ -0,0 +1,41 @@
+# CLI
+
+**The `plain` CLI and how to add your own commands to it.**
+
+- [Overview](#overview)
+- [Adding commands](#adding-commands)
+
+## Overview
+
+Commands are written using [Click](https://click.palletsprojects.com/en/8.1.x/)
+(one of Plain's few dependencies),
+which has been one of those most popular CLI frameworks in Python for a long time.
+
+## Adding commands
+
+The [`register_cli`](./registry.py#register_cli) decorator can be used to add your own commands to the `plain` CLI.
+
+```python
+import click
+from plain.cli import register_cli
+
+
+@register_cli("example-subgroup-name")
+@click.group()
+def cli():
+    """Custom example commands"""
+    pass
+
+@cli.command()
+def example_command():
+    click.echo("An example command!")
+```
+
+Then you can run the command with `plain`.
+
+```bash
+$ plain example-subgroup-name example-command
+An example command!
+```
+
+Technically you can register a CLI from anywhere, but typically you will do it in either `app/cli.py` or a package's `<pkg>/cli.py`, as those modules will be autoloaded by Plain.

{plain-0.56.0 → plain-0.57.0}/plain/cli/install.py

@@ -64,14 +64,15 @@ def install(
         "## Instructions",
         "",
         "For each package:",
-        "1. Run `uv run plain docs <package>` and follow any setup instructions",
-        "2. If the docs point out that it is a --dev tool, move it to dev dependencies: `uv remove <package> && uv add <package> --dev`",
+        "1. Run `uv run plain docs <package>` and read the installation instructions",
+        "2. If the docs point out that it is a --dev tool, move it to the dev dependencies in pyproject.toml: `uv remove <package> && uv add <package> --dev`",
+        "3. Go through the installation instructions and complete any code modifications that are needed",
         "",
         "DO NOT commit any changes",
         "",
         "Report back with:",
         "- Whether the setup completed successfully",
-        "- Any manual steps that still need to be completed",
+        "- Any manual steps that the user will need to complete",
         "- Any issues or errors encountered",
     ]
 

{plain-0.56.0 → plain-0.57.0}/plain/csrf/README.md

@@ -2,7 +2,12 @@
 
 **Cross-Site Request Forgery (CSRF) protection.**
 
-Plain protects against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) through a [middleware](middleware.py) that compares the generated `csrftoken` cookie with the CSRF token from the request (either `_csrftoken` in form data or the `CSRF-Token` header).
+- [Overview](#overview)
+- [Usage](#usage)
+
+## Overview
+
+Plain protects against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) through a [middleware](./middleware.py#CsrfViewMiddleware) that compares the generated `csrftoken` cookie with the CSRF token from the request (either `_csrftoken` in form data or the `CSRF-Token` header).
 
 ## Usage
 

{plain-0.56.0 → plain-0.57.0}/plain/exceptions.py

@@ -53,12 +53,6 @@ class DisallowedHost(SuspiciousOperation):
     pass
 
 
-class DisallowedRedirect(SuspiciousOperation):
-    """Redirect to scheme not in allowed list"""
-
-    pass
-
-
 class TooManyFieldsSent(SuspiciousOperation):
     """
     The number of fields in a GET or POST request exceeded

{plain-0.56.0 → plain-0.57.0}/plain/forms/README.md

@@ -2,6 +2,10 @@
 
 **HTML form handling and validation.**
 
+- [Overview](#overview)
+
+## Overview
+
 The `Form` and `Field` classes help output, parse, and validate form data from an HTTP request. Unlike other frameworks, the HTML inputs are not rendered automatically, though there are some helpers for you to do your own rendering.
 
 With forms, you will typically use one of the built-in view classes to tie everything together.

{plain-0.56.0 → plain-0.57.0}/plain/http/README.md

@@ -2,6 +2,10 @@
 
 **HTTP request and response handling.**
 
+- [Overview](#overview)
+
+## Overview
+
 Typically you will interact with [request](request.py#HttpRequest) and [response](response.py#ResponseBase) objects in your views and middleware.
 
 ```python

{plain-0.56.0 → plain-0.57.0}/plain/http/__init__.py

@@ -19,7 +19,6 @@ from plain.http.response import (
     ResponseNotAllowed,
     ResponseNotFound,
     ResponseNotModified,
-    ResponsePermanentRedirect,
     ResponseRedirect,
     ResponseServerError,
     StreamingResponse,
@@ -36,7 +35,6 @@ __all__ = [
     "ResponseBase",
     "StreamingResponse",
     "ResponseRedirect",
-    "ResponsePermanentRedirect",
     "ResponseNotModified",
     "ResponseBadRequest",
     "ResponseForbidden",

{plain-0.56.0 → plain-0.57.0}/plain/http/response.py

@@ -10,10 +10,8 @@ from email.header import Header
 from functools import cached_property
 from http.client import responses
 from http.cookies import SimpleCookie
-from urllib.parse import urlparse
 
 from plain import signals
-from plain.exceptions import DisallowedRedirect
 from plain.http.cookie import sign_cookie_value
 from plain.json import PlainJSONEncoder
 from plain.runtime import settings
@@ -566,19 +564,18 @@ class FileResponse(StreamingResponse):
             self.headers["Content-Disposition"] = content_disposition
 
 
-class ResponseRedirectBase(Response):
-    allowed_schemes = ["http", "https", "ftp"]
+class ResponseRedirect(Response):
+    """HTTP redirect response"""
+
+    status_code = 302
 
     def __init__(self, redirect_to, **kwargs):
         super().__init__(**kwargs)
         self.headers["Location"] = iri_to_uri(redirect_to)
-        parsed = urlparse(str(redirect_to))
-        if parsed.scheme and parsed.scheme not in self.allowed_schemes:
-            raise DisallowedRedirect(
-                f"Unsafe redirect to URL with protocol '{parsed.scheme}'"
-            )
 
-    url = property(lambda self: self.headers["Location"])
+    @property
+    def url(self):
+        return self.headers["Location"]
 
     def __repr__(self):
         return (
@@ -592,18 +589,6 @@ class ResponseRedirectBase(Response):
         )
 
 
-class ResponseRedirect(ResponseRedirectBase):
-    """HTTP 302 response"""
-
-    status_code = 302
-
-
-class ResponsePermanentRedirect(ResponseRedirectBase):
-    """HTTP 301 response"""
-
-    status_code = 301
-
-
 class ResponseNotModified(Response):
     """HTTP 304 response"""
 

{plain-0.56.0 → plain-0.57.0}/plain/internal/middleware/https.py

@@ -1,6 +1,6 @@
 import re
 
-from plain.http import ResponsePermanentRedirect
+from plain.http import ResponseRedirect
 from plain.runtime import settings
 
 
@@ -33,4 +33,6 @@ class HttpsRedirectMiddleware:
             and not any(pattern.search(path) for pattern in self.https_redirect_exempt)
         ):
             host = self.https_redirect_host or request.get_host()
-            return ResponsePermanentRedirect(f"https://{host}{request.get_full_path()}")
+            return ResponseRedirect(
+                f"https://{host}{request.get_full_path()}", status_code=301
+            )

{plain-0.56.0 → plain-0.57.0}/plain/internal/middleware/slash.py

@@ -1,4 +1,4 @@
-from plain.http import ResponsePermanentRedirect
+from plain.http import ResponseRedirect
 from plain.runtime import settings
 from plain.urls import Resolver404, get_resolver
 from plain.utils.http import escape_leading_slashes
@@ -22,7 +22,9 @@ class RedirectSlashMiddleware:
         # If the given URL is "Not Found", then check if we should redirect to
         # a path with a slash appended.
         if response.status_code == 404 and self.should_redirect_with_slash(request):
-            return ResponsePermanentRedirect(self.get_full_path_with_slash(request))
+            return ResponseRedirect(
+                self.get_full_path_with_slash(request), status_code=301
+            )
 
         return response
 

{plain-0.56.0 → plain-0.57.0}/plain/logs/README.md

@@ -2,6 +2,13 @@
 
 **Logging configuration and utilities.**
 
+- [Overview](#overview)
+- [`app_logger`](#app_logger)
+- [`app_logger.kv`](#app_loggerkv)
+- [Logging settings](#logging-settings)
+
+## Overview
+
 In Python, configuring logging can be surprisingly complex. For most use cases, Plain provides a [default configuration](./configure.py) that "just works".
 
 By default, both the `plain` and `app` loggers are set to the `INFO` level. You can quickly change this by using the `PLAIN_LOG_LEVEL` and `APP_LOG_LEVEL` environment variables.

{plain-0.56.0 → plain-0.57.0}/plain/packages/README.md

@@ -2,6 +2,13 @@
 
 **Install Python modules as Plain packages.**
 
+- [Overview](#overview)
+- [Creating app packages](#creating-app-packages)
+- [Package settings](#package-settings)
+- [Package `ready()` method](#package-ready-method)
+
+## Overview
+
 Most Python modules that you use with Plain will need to be installed via `settings.INSTALLED_PACKAGES`. This is what enables template detection, per-package settings, database models, and other features.
 
 A package can either be a local module inside of your `app`, or a third-party package from PyPI.

{plain-0.56.0 → plain-0.57.0}/plain/preflight/README.md

@@ -2,6 +2,14 @@
 
 **System checks for Plain applications.**
 
+- [Overview](#overview)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Custom preflight checks](#custom-preflight-checks)
+- [Silencing preflight checks](#silencing-preflight-checks)
+
+## Overview
+
 Preflight checks help identify issues with your settings or environment before running your application.
 
 ```bash

{plain-0.56.0 → plain-0.57.0}/plain/runtime/README.md

@@ -2,6 +2,15 @@
 
 **Access app and package settings at runtime.**
 
+- [Overview](#overview)
+- [Environment variables](#environment-variables)
+    - [.env files](#env-files)
+- [Package settings](#package-settings)
+- [Custom app-wide settings](#custom-app-wide-settings)
+- [Using Plain in other environments](#using-plain-in-other-environments)
+
+## Overview
+
 Plain is configured by "settings", which are ultimately just Python variables. Most settings have default values which can be overidden either by your `app/settings.py` file or by environment variables.
 
 ```python

{plain-0.56.0 → plain-0.57.0}/plain/signals/README.md

@@ -2,6 +2,10 @@
 
 **Run code when certain events happen.**
 
+- [Overview](#overview)
+
+## Overview
+
 ```python
 from plain.signals import request_finished
 

{plain-0.56.0 → plain-0.57.0}/plain/templates/README.md

@@ -2,6 +2,13 @@
 
 **Render HTML templates using Jinja.**
 
+- [Overview](#overview)
+- [Template files](#template-files)
+- [Extending Jinja](#extending-jinja)
+- [Rendering templates manually](#rendering-templates-manually)
+
+## Overview
+
 Plain uses Jinja2 for template rendering. You can refer to the [Jinja documentation](https://jinja.palletsprojects.com/en/stable/api/) for all of the features available.
 
 In general, templates are used in combination with `TemplateView` or a more specific subclass of it.
@@ -37,7 +44,7 @@ All template directories are "merged" together, allowing you to override templat
 
 ## Extending Jinja
 
-Plain includes a set of default [global variables](jinja/globals.py) and [filters](jinja/filters.py). You can register additional extensions, globals, or filters either in a package or in your app. Typically this will be in `app/templates.py` or `<pkg>/templates.py`, which are automatically imported.
+Plain includes a set of default [global variables](./jinja/globals.py) and [filters](./jinja/filters.py). You can register additional extensions, globals, or filters either in a package or in your app. Typically this will be in `app/templates.py` or `<pkg>/templates.py`, which are automatically imported.
 
 ```python
 # app/templates.py
@@ -71,7 +78,7 @@ class HTMXJSExtension(InclusionTagExtension):
 
 ## Rendering templates manually
 
-Templates can also be rendered manually using the [`Template` class](core.py#Template).
+Templates can also be rendered manually using the [`Template` class](./core.py#Template).
 
 ```python
 from plain.templates import Template

{plain-0.56.0 → plain-0.57.0}/plain/test/README.md

@@ -2,7 +2,11 @@
 
 **Testing utilities for Plain.**
 
-This module provides a the [`Client`](client.py#Client) and [`RequestFactory`](client.py#RequestFactory) classes to facilitate testing requests and responses.
+- [Overview](#overview)
+
+## Overview
+
+This module provides the [`Client`](client.py#Client) and [`RequestFactory`](client.py#RequestFactory) classes to facilitate testing requests and responses.
 
 ```python
 from plain.test import Client

{plain-0.56.0 → plain-0.57.0}/plain/urls/README.md

@@ -2,6 +2,13 @@
 
 **Route requests to views.**
 
+- [Overview](#overview)
+- [Reversing URLs](#reversing-urls)
+- [URL args and kwargs](#url-args-and-kwargs)
+- [Package routers](#package-routers)
+
+## Overview
+
 URLs are typically the "entrypoint" to your app. Virtually all request handling up to this point happens behind the scenes, and then you decide how to route specific URL patterns to your views.
 
 The `URLS_ROUTER` is the primary router that handles all incoming requests. It is defined in your `app/settings.py` file. This will typically point to a `Router` class in your `app.urls` module.

{plain-0.56.0 → plain-0.57.0}/plain/utils/README.md

@@ -1,5 +1,9 @@
-# Utilities
+# Utils
 
 **Various utilities for text manipulation, parsing, dates, and more.**
 
+- [Overview](#overview)
+
+## Overview
+
 The utilities aren't going to be documented in detail here. Take a look at the source code for more information.

{plain-0.56.0 → plain-0.57.0}/plain/views/README.md

@@ -2,6 +2,19 @@
 
 **Take a request, return a response.**
 
+- [Overview](#overview)
+- [HTTP methods -> class methods](#http-methods---class-methods)
+- [Return types](#return-types)
+- [Template views](#template-views)
+- [Form views](#form-views)
+- [Object views](#object-views)
+- [Response exceptions](#response-exceptions)
+- [Error views](#error-views)
+- [Redirect views](#redirect-views)
+- [CSRF exempt views](#csrf-exempt-views)
+
+## Overview
+
 Plain views are written as classes,
 with a straightforward API that keeps simple views simple,
 but gives you the power of a full class to handle more complex cases.
@@ -17,7 +30,7 @@ class ExampleView(View):
 
 ## HTTP methods -> class methods
 
-The HTTP methd of the request will map to a class method of the same name on the view.
+The HTTP method of the request will map to a class method of the same name on the view.
 
 If a request comes in and there isn't a matching method on the view,
 Plain will return a `405 Method Not Allowed` response.
@@ -46,7 +59,7 @@ class ExampleView(View):
         pass
 ```
 
-The [base `View` class](./base.py) defines default `options` and `head` behavior,
+The [base `View` class](./base.py#View) defines default `options` and `head` behavior,
 but you can override these too.
 
 ## Return types
@@ -87,9 +100,9 @@ class ExampleView(TemplateView):
         return context
 ```
 
-The `TemplateView` is also the base class for _most_ of the other built-in view classes.
+The [`TemplateView`](./templates.py#TemplateView) is also the base class for _most_ of the other built-in view classes.
 
-Template views that don't need any custom context can use `TemplateView.as_view()` direcly in the URL route.
+Template views that don't need any custom context can use `TemplateView.as_view()` directly in the URL route.
 
 ```python
 from plain.views import TemplateView
@@ -104,7 +117,7 @@ class AppRouter(Router):
 
 ## Form views
 
-Standard [forms](../forms) can be rendered and processed by a `FormView`.
+Standard [forms](../forms) can be rendered and processed by a [`FormView`](./forms.py#FormView).
 
 ```python
 from plain.views import FormView
@@ -218,7 +231,7 @@ class ExampleListView(ListView):
 ## Response exceptions
 
 At any point in the request handling,
-a view can raise a `ResponseException` to immediately exit and return the wrapped response.
+a view can raise a [`ResponseException`](./exceptions.py#ResponseException) to immediately exit and return the wrapped response.
 
 This isn't always necessary, but can be useful for raising rate limits or authorization errors when you're a couple layers deep in the view handling or helper functions.
 

plain-0.57.0/plain/views/redirect.py

@@ -0,0 +1,66 @@
+from plain.http import ResponseRedirect
+from plain.urls import reverse
+
+from .base import View
+
+
+class RedirectView(View):
+    """Provide a redirect on any GET request."""
+
+    status_code = 302
+    url: str | None = None
+    url_name: str | None = None
+    preserve_query_params = False
+
+    def __init__(
+        self, url=None, status_code=None, url_name=None, preserve_query_params=None
+    ):
+        # Allow attributes to be set in RedirectView.as_view(url="...", status_code=301, etc.)
+        self.url = url or self.url
+        self.status_code = status_code if status_code is not None else self.status_code
+        self.url_name = url_name or self.url_name
+        self.preserve_query_params = (
+            preserve_query_params
+            if preserve_query_params is not None
+            else self.preserve_query_params
+        )
+
+    def get_redirect_url(self):
+        """
+        Return the URL redirect to. Keyword arguments from the URL pattern
+        match generating the redirect request are provided as kwargs to this
+        method.
+        """
+        if self.url:
+            url = self.url % self.url_kwargs
+        elif self.url_name:
+            url = reverse(self.url_name, *self.url_args, **self.url_kwargs)
+        else:
+            raise ValueError("RedirectView requires either url or url_name to be set")
+
+        args = self.request.meta.get("QUERY_STRING", "")
+        if args and self.preserve_query_params:
+            url = f"{url}?{args}"
+        return url
+
+    def get(self):
+        url = self.get_redirect_url()
+        return ResponseRedirect(url, status_code=self.status_code)
+
+    def head(self):
+        return self.get()
+
+    def post(self):
+        return self.get()
+
+    def options(self):
+        return self.get()
+
+    def delete(self):
+        return self.get()
+
+    def put(self):
+        return self.get()
+
+    def patch(self):
+        return self.get()

{plain-0.56.0 → plain-0.57.0}/pyproject.toml

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