plain 0.32.1__tar.gz → 0.33.0__tar.gz

plain-0.33.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: plain
+Version: 0.33.0
+Summary: A web framework for building products with Python.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.1.2
+Description-Content-Type: text/markdown
+
+# Plain
+
+**Plain is a web framework for building products with Python.**
+
+The core `plain` package provides the backbone of a Python web application (similar to [Flask](https://flask.palletsprojects.com/en/stable/)), while the additional first-party packages can power a more fully-featured database-backed app (similar to [Django](https://www.djangoproject.com/)).
+
+All Plain packages are designed to work together and use [PEP 420](https://peps.python.org/pep-0420/) to share the `plain` namespace.
+
+To quickly get started with Plain, visit [plainframework.com/start/](https://plainframework.com/start/).
+
+## Core Modules
+
+The `plain` package includes everything you need to start handling web requests with Python:
+
+- [assets](assets/README.md) - Serve static files and assets.
+- [cli](cli/README.md) - The `plain` CLI, powered by Click.
+- [csrf](csrf/README.md) - Cross-Site Request Forgery protection.
+- [forms](forms/README.md) - HTML forms and form validation.
+- [http](http/README.md) - HTTP request and response handling.
+- [logs](logs/README.md) - Logging configuration and utilities.
+- [preflight](preflight/README.md) - Preflight checks for your app.
+- [runtime](runtime/README.md) - Runtime settings and configuration.
+- [templates](templates/README.md) - Jinja2 templates and rendering.
+- [test](test/README.md) - Test utilities and fixtures.
+- [urls](urls/README.md) - URL routing and request dispatching.
+- [views](views/README.md) - Class-based views and request handlers.
+
+## Foundational Packages
+
+- [plain.models](/plain-models/README.md) - Define and interact with your database models.
+- [plain.cache](/plain-cache/README.md) - A database-driven general purpose cache.
+- [plain.mail](/plain-mail/README.md) - Send emails with SMTP or custom backends.
+- [plain.sessions](/plain-sessions/README.md) - User sessions and cookies.
+- [plain.worker](/plain-worker/README.md) - Backgrounb jobs stored in the database.
+- [plain.api](/plain-api/README.md) - Build APIs with Plain views.
+
+## Auth Packages
+
+- [plain.auth](/plain-auth/README.md) - User authentication and authorization.
+- [plain.oauth](/plain-oauth/README.md) - OAuth authentication and API access.
+- [plain.passwords](/plain-passwords/README.md) - Password-based login and registration.
+- [plain.loginlink](/plain-loginlink/README.md) - Login links for passwordless authentication.
+
+## Admin Packages
+
+- [plain.admin](/plain-admin/README.md) - An admin interface for back-office tasks.
+- [plain.flags](/plain-flags/README.md) - Feature flags.
+- [plain.support](/plain-support/README.md) - Customer support forms.
+- [plain.redirection](/plain-redirection/README.md) - Redirects managed in the database.
+- [plain.pageviews](/plain-pageviews/README.md) - Basic self-hosted page view tracking and reporting.
+
+## Dev Packages
+
+- [plain.dev](/plain-dev/README.md) - A single command for local development.
+- [plain.pytest](/plain-pytest/README.md) - Pytest fixtures and helpers.
+- [plain.code](/plain-code/README.md) - Code formatting and linting.
+- [plain.tunnel](/plain-tunnel/README.md) - Expose your local server to the internet.
+
+## Frontend Packages
+
+- [plain.tailwind](/plain-tailwind/README.md) - Tailwind CSS integration without Node.js.
+- [plain.htmx](/plain-htmx/README.md) - HTMX integrated into views and templates.
+- [plain.elements](/plain-elements/README.md) - Server-side HTML components.
+- [plain.pages](/plain-pages/README.md) - Static pages with Markdown and Jinja2.
+- [plain.esbuild](/plain-esbuild/README.md) - Simple JavaScript bundling and minification.
+- [plain.vendor](/plain-vendor/README.md) - Vendor JavaScript and CSS libraries.

plain-0.33.0/plain/README.md

@@ -0,0 +1,66 @@
+# Plain
+
+**Plain is a web framework for building products with Python.**
+
+The core `plain` package provides the backbone of a Python web application (similar to [Flask](https://flask.palletsprojects.com/en/stable/)), while the additional first-party packages can power a more fully-featured database-backed app (similar to [Django](https://www.djangoproject.com/)).
+
+All Plain packages are designed to work together and use [PEP 420](https://peps.python.org/pep-0420/) to share the `plain` namespace.
+
+To quickly get started with Plain, visit [plainframework.com/start/](https://plainframework.com/start/).
+
+## Core Modules
+
+The `plain` package includes everything you need to start handling web requests with Python:
+
+- [assets](assets/README.md) - Serve static files and assets.
+- [cli](cli/README.md) - The `plain` CLI, powered by Click.
+- [csrf](csrf/README.md) - Cross-Site Request Forgery protection.
+- [forms](forms/README.md) - HTML forms and form validation.
+- [http](http/README.md) - HTTP request and response handling.
+- [logs](logs/README.md) - Logging configuration and utilities.
+- [preflight](preflight/README.md) - Preflight checks for your app.
+- [runtime](runtime/README.md) - Runtime settings and configuration.
+- [templates](templates/README.md) - Jinja2 templates and rendering.
+- [test](test/README.md) - Test utilities and fixtures.
+- [urls](urls/README.md) - URL routing and request dispatching.
+- [views](views/README.md) - Class-based views and request handlers.
+
+## Foundational Packages
+
+- [plain.models](/plain-models/README.md) - Define and interact with your database models.
+- [plain.cache](/plain-cache/README.md) - A database-driven general purpose cache.
+- [plain.mail](/plain-mail/README.md) - Send emails with SMTP or custom backends.
+- [plain.sessions](/plain-sessions/README.md) - User sessions and cookies.
+- [plain.worker](/plain-worker/README.md) - Backgrounb jobs stored in the database.
+- [plain.api](/plain-api/README.md) - Build APIs with Plain views.
+
+## Auth Packages
+
+- [plain.auth](/plain-auth/README.md) - User authentication and authorization.
+- [plain.oauth](/plain-oauth/README.md) - OAuth authentication and API access.
+- [plain.passwords](/plain-passwords/README.md) - Password-based login and registration.
+- [plain.loginlink](/plain-loginlink/README.md) - Login links for passwordless authentication.
+
+## Admin Packages
+
+- [plain.admin](/plain-admin/README.md) - An admin interface for back-office tasks.
+- [plain.flags](/plain-flags/README.md) - Feature flags.
+- [plain.support](/plain-support/README.md) - Customer support forms.
+- [plain.redirection](/plain-redirection/README.md) - Redirects managed in the database.
+- [plain.pageviews](/plain-pageviews/README.md) - Basic self-hosted page view tracking and reporting.
+
+## Dev Packages
+
+- [plain.dev](/plain-dev/README.md) - A single command for local development.
+- [plain.pytest](/plain-pytest/README.md) - Pytest fixtures and helpers.
+- [plain.code](/plain-code/README.md) - Code formatting and linting.
+- [plain.tunnel](/plain-tunnel/README.md) - Expose your local server to the internet.
+
+## Frontend Packages
+
+- [plain.tailwind](/plain-tailwind/README.md) - Tailwind CSS integration without Node.js.
+- [plain.htmx](/plain-htmx/README.md) - HTMX integrated into views and templates.
+- [plain.elements](/plain-elements/README.md) - Server-side HTML components.
+- [plain.pages](/plain-pages/README.md) - Static pages with Markdown and Jinja2.
+- [plain.esbuild](/plain-esbuild/README.md) - Simple JavaScript bundling and minification.
+- [plain.vendor](/plain-vendor/README.md) - Vendor JavaScript and CSS libraries.

{plain-0.32.1 → plain-0.33.0}/plain/assets/README.md

@@ -1,38 +1,37 @@
 # Assets
 
-Serve static assets (CSS, JS, images, etc.) directly from your app.
-
+**Serve static assets (CSS, JS, images, etc.) directly or from a CDN.**
 
 ## Usage
 
 To serve assets, put them in `app/assets` or `app/{package}/assets`.
 
-Then include the `plain.assets.urls` in your `urls.py`:
+Then include the `AssetsRouter` in your own router, typically under the `assets/` path.
 
 ```python
 # app/urls.py
-from plain.urls import include, path
-import plain.assets.urls
+from plain.assets.urls import AssetsRouter
+from plain.urls import include, Router
 
 
-urlpatterns = [
-    path("assets/", include(plain.assets.urls)),
-    # ...
-]
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("assets/", AssetsRouter),
+        # your other routes here...
+    ]
 ```
 
-Now in your template you can use the `asset()` function to get the URL:
+Now in your template you can use the `asset()` function to get the URL, which will output the fully compiled and fingerprinted URL.
 
 ```html
 <link rel="stylesheet" href="{{ asset('css/style.css') }}">
 ```
 
-
 ## Local development
 
 When you're working with `settings.DEBUG = True`, the assets will be served directly from their original location. You don't need to run `plain build` or configure anything else.
 
-
 ## Production deployment
 
 In production, one of your deployment steps should be to compile the assets.
@@ -41,11 +40,10 @@ In production, one of your deployment steps should be to compile the assets.
 plain build
 ```
 
-By default, this generates "fingerprinted" and compressed versions of the assets, which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
+By default, this [generates "fingerprinted" and compressed versions of the assets](fingerprints.py#get_file_fingerprint), which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
 
 The purpose of fingerprinting the assets is to allow the browser to cache them indefinitely. When the content of the file changes, the fingerprint will change, and the browser will use the newer file. This cuts down on the number of requests that your app has to handle related to assets.
 
-
 ## FAQs
 
 ### How do you reference assets in Python code?
@@ -67,10 +65,16 @@ mv .plain/assets/compiled /path/to/your/static
 
 ### 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.
+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).
 
 ```bash
+# Compile the assets
 plain build
+
+# List the newly compiled files
+ls .plain/assets/compiled
+
+# Upload the files to your CDN
 ./example-upload-to-cdn-script
 ```
 
@@ -81,14 +85,10 @@ Use the `ASSETS_BASE_URL` setting to tell the `{{ asset() }}` template function
 ASSETS_BASE_URL = "https://cdn.example.com/"
 ```
 
-
 ### 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).
 
 If you need the originals for any reason, you can use `plain build --keep-original`, though this will typically be combined with `--no-fingerprint` otherwise the fingerprinted files will still get priority in `{{ asset() }}` template calls.
 
-
-### What about source maps or imported css files?
-
-TODO
+Note that by default, the `ASSETS_REDIRECT_ORIGINAL` setting is `True`, which will redirect requests for the original file to the fingerprinted file.

{plain-0.32.1 → plain-0.33.0}/plain/assets/compile.py

@@ -1,14 +1,11 @@
 import gzip
-import hashlib
 import os
 import shutil
 
 from plain.runtime import settings
 
 from .finders import iter_assets
-from .fingerprints import AssetsFingerprintsManifest
-
-FINGERPRINT_LENGTH = 7
+from .fingerprints import AssetsFingerprintsManifest, get_file_fingerprint
 
 SKIP_COMPRESS_EXTENSIONS = (
     # Images
@@ -46,12 +43,17 @@ SKIP_COMPRESS_EXTENSIONS = (
 def get_compiled_path():
     """
     Get the path at runtime to the compiled assets directory.
+
     There's no reason currently for this to be a user-facing setting.
     """
     return settings.PLAIN_TEMP_PATH / "assets" / "compiled"
 
 
 def compile_assets(*, target_dir, keep_original, fingerprint, compress):
+    """
+    Compile all assets to the target directory and save a JSON manifest
+    mapping the original filenames to the compiled filenames.
+    """
     manifest = AssetsFingerprintsManifest()
 
     for asset in iter_assets():
@@ -68,8 +70,7 @@ def compile_assets(*, target_dir, keep_original, fingerprint, compress):
 
         yield url_path, resolved_path, compiled_paths
 
-    if manifest:
-        manifest.save()
+    manifest.save()
 
 
 def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
@@ -98,11 +99,7 @@ def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
         # Fingerprint it with an md5 hash
         # (maybe need a setting with fnmatch patterns for files to NOT fingerprint?
         # that would allow pre-fingerprinted files to be used as-is, and keep source maps etc in tact)
-        with open(asset.absolute_path, "rb") as f:
-            content = f.read()
-            fingerprint_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()[
-                :FINGERPRINT_LENGTH
-            ]
+        fingerprint_hash = get_file_fingerprint(asset.absolute_path)
 
         fingerprinted_basename = f"{base}.{fingerprint_hash}{extension}"
         fingerprinted_path = os.path.join(target_dir, fingerprinted_basename)

{plain-0.32.1 → plain-0.33.0}/plain/assets/finders.py

@@ -9,6 +9,11 @@ SKIP_ASSETS = (".DS_Store", ".gitignore")
 
 
 def iter_assets():
+    """
+    Iterate all valid asset files found in the installed
+    packages and the app itself.
+    """
+
     class Asset:
         def __init__(self, *, url_path, absolute_path):
             self.url_path = url_path
@@ -32,6 +37,10 @@ def iter_assets():
 
 
 def iter_asset_dirs():
+    """
+    Iterate all directories containing assets, from installed
+    packages and from app/assets.
+    """
     # Iterate the installed package assets, in order
     for pkg in packages_registry.get_package_configs():
         asset_dir = os.path.join(pkg.path, "assets")

{plain-0.32.1 → plain-0.33.0}/plain/assets/fingerprints.py

@@ -1,10 +1,17 @@
+import hashlib
 import json
 from functools import cache
 
 from plain.runtime import settings
 
+FINGERPRINT_LENGTH = 7
+
 
 class AssetsFingerprintsManifest(dict):
+    """
+    A manifest of original filenames to fingerprinted filenames.
+    """
+
     def __init__(self):
         self.path = settings.PLAIN_TEMP_PATH / "assets" / "fingerprints.json"
 
@@ -36,3 +43,16 @@ def get_fingerprinted_url_path(url_path):
     manifest = _get_manifest()
     if url_path in manifest:
         return manifest[url_path]
+
+
+def get_file_fingerprint(file_path):
+    """
+    Get the fingerprint hash for a file.
+    """
+    with open(file_path, "rb") as f:
+        content = f.read()
+        fingerprint_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()[
+            :FINGERPRINT_LENGTH
+        ]
+
+    return fingerprint_hash

{plain-0.32.1 → plain-0.33.0}/plain/assets/urls.py

@@ -6,6 +6,12 @@ from .views import AssetView
 
 
 class AssetsRouter(Router):
+    """
+    The router for serving static assets.
+
+    Include this router in your app router if you are serving assets yourself.
+    """
+
     namespace = "assets"
     urls = [
         path("<path:path>", AssetView, name="asset"),
@@ -13,6 +19,9 @@ class AssetsRouter(Router):
 
 
 def get_asset_url(url_path):
+    """
+    Get the full URL to a given asset path.
+    """
     if settings.DEBUG:
         # In debug, we only ever use the original URL path.
         resolved_url_path = url_path

{plain-0.32.1 → plain-0.33.0}/plain/assets/views.py

@@ -16,9 +16,9 @@ from plain.runtime import settings
 from plain.urls import reverse
 from plain.views import View
 
-from .compile import FINGERPRINT_LENGTH, get_compiled_path
+from .compile import get_compiled_path
 from .finders import iter_assets
-from .fingerprints import get_fingerprinted_url_path
+from .fingerprints import FINGERPRINT_LENGTH, get_fingerprinted_url_path
 
 
 class AssetView(View):
@@ -28,8 +28,12 @@ class AssetView(View):
     This class could be subclassed to further tweak the responses or behavior.
     """
 
+    def __init__(self, asset_path=None):
+        # Allow a path to be passed in AssetView.as_view(path="...")
+        self.asset_path = asset_path
+
     def get_url_path(self):
-        return self.url_kwargs["path"]
+        return self.asset_path or self.url_kwargs["path"]
 
     def get(self):
         url_path = self.get_url_path()

plain-0.33.0/plain/cli/README.md

@@ -0,0 +1,84 @@
+# 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 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 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.