plain 0.56.0__tar.gz → 0.56.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.56.0
+Version: 0.56.1
 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.56.1}/plain/CHANGELOG.md

@@ -1,5 +1,15 @@
 # plain changelog
 
+## [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.56.1}/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.56.1}/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.56.1/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.1}/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.56.0 → plain-0.56.1}/pyproject.toml

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

plain-0.56.0/plain/cli/README.md

@@ -1,90 +0,0 @@
-# CLI
-
-**The `plain` CLI and how to add your own commands to it.**
-
-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.
-
-## Built-in commands
-
-### `plain build`
-
-Compile static assets (used in the deploy/production process).
-
-Automatically runs `plain tailwind build` if [plain.tailwind](/plain-tailwind/) is installed.
-
-### `plain create`
-
-Create a new local package.
-
-### `plain preflight`
-
-Run preflight checks to ensure your app is ready to run.
-
-### `plain run`
-
-Run a Python script in the context of your app.
-
-### `plain setting`
-
-View the runtime value of a named setting.
-
-### `plain help`
-
-Print help for all available commands and subcommands.
-Each command's help output is prefixed with the full command name for
-readability.
-
-### `plain shell`
-
-Open a Python shell with the Plain loaded.
-
-To auto-load models or run other code at shell launch,
-create an `app/shell.py` and it will be imported automatically.
-
-```python
-# app/shell.py
-from app.organizations.models import Organization
-
-__all__ = [
-    "Organization",
-]
-```
-
-### `plain urls list`
-
-List all the URL patterns in your app.
-
-### `plain utils generate-secret-key`
-
-Generate a new secret key for your app, to be used in `settings.SECRET_KEY`.
-
-## Adding commands
-
-The `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.