plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/runtime/README.md

@@ -1,20 +1,28 @@
 # Runtime
 
-**Access app and package settings at runtime.**
+**Access and configure settings for your Plain application.**
 
 - [Overview](#overview)
 - [Environment variables](#environment-variables)
     - [.env files](#env-files)
+    - [Custom prefixes](#custom-prefixes)
 - [Package settings](#package-settings)
-- [Custom app-wide settings](#custom-app-wide-settings)
-- [Using Plain in other environments](#using-plain-in-other-environments)
+- [Custom app settings](#custom-app-settings)
+- [Secret values](#secret-values)
+- [Using Plain outside of an app](#using-plain-outside-of-an-app)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## 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.
+You configure Plain through settings, which are Python variables defined in your `app/settings.py` file.
 
 ```python
 # app/settings.py
+from plain.runtime import Secret
+
+SECRET_KEY: Secret[str]
+
 URLS_ROUTER = "app.urls.AppRouter"
 
 TIME_ZONE = "America/Chicago"
@@ -23,11 +31,9 @@ INSTALLED_PACKAGES = [
     "plain.models",
     "plain.tailwind",
     "plain.auth",
-    "plain.passwords",
     "plain.sessions",
     "plain.htmx",
     "plain.admin",
-    "plain.elements",
     # Local packages
     "app.users",
 ]
@@ -37,107 +43,99 @@ AUTH_LOGIN_URL = "login"
 
 MIDDLEWARE = [
     "plain.sessions.middleware.SessionMiddleware",
-    "plain.auth.middleware.AuthenticationMiddleware",
     "plain.admin.AdminMiddleware",
 ]
 ```
 
-While working inside a Plain application or package, you can access settings at runtime via `plain.runtime.settings`.
+You can access settings anywhere in your application via `plain.runtime.settings`.
 
 ```python
 from plain.runtime import settings
 
-print(settings.AN_EXAMPLE_SETTING)
+print(settings.TIME_ZONE)
+print(settings.DEBUG)
 ```
 
-The Plain core settings are defined in [`plain/runtime/global_settings.py`](global_settings.py) and you should look at that for reference. Each installed package can also define its own settings in a `default_settings.py` file.
+Plain's built-in settings are defined in [`global_settings.py`](./global_settings.py). Each installed package can also define its own settings in a `default_settings.py` file.
 
 ## Environment variables
 
-It's common in both development and production to use environment variables to manage settings. To handle this, any type-annotated setting can be loaded from the env with a `PLAIN_` prefix.
+Type-annotated settings can be loaded from environment variables using a `PLAIN_` prefix.
 
-For example, to set the `SECRET_KEY` setting is defined with a type annotation.
+For example, if you define a setting with a type annotation:
 
 ```python
 SECRET_KEY: str
 ```
 
-And can be set by an environment variable.
+You can set it via an environment variable:
 
 ```bash
 PLAIN_SECRET_KEY=supersecret
 ```
 
-For more complex types like lists or dictionaries, just use the `list` or `dict` type annotation and JSON-compatible types.
+For lists, dicts, and other complex types, use JSON-encoded values:
 
 ```python
-LIST_EXAMPLE: list[str]
+ALLOWED_HOSTS: list[str]
 ```
 
-And set the environment variable with a JSON-encoded string.
+```bash
+PLAIN_ALLOWED_HOSTS='["example.com", "www.example.com"]'
+```
+
+Boolean settings accept `true`, `1`, `yes` (case-insensitive) as truthy values:
 
 ```bash
-PLAIN_LIST_EXAMPLE='["one", "two", "three"]'
+PLAIN_DEBUG=true
 ```
 
-Custom behavior can always be supported by checking the environment directly.
+### .env files
 
-```python
-# plain/models/default_settings.py
-from os import environ
+Plain does not load `.env` files automatically. If you use [`plain.dev`](/plain-dev/README.md), it loads `.env` files for you during development. For production, you need to load them yourself or rely on your deployment platform to inject environment variables.
 
-from . import database_url
+### Custom prefixes
 
-# Make DATABASE a required setting
-DATABASE: dict
+You can configure additional environment variable prefixes using `ENV_SETTINGS_PREFIXES`:
 
-# Automatically configure DATABASE if a DATABASE_URL was given in the environment
-if "DATABASE_URL" in environ:
-    DATABASE = database_url.parse_database_url(
-        environ["DATABASE_URL"],
-        # Enable persistent connections by default
-        conn_max_age=int(environ.get("DATABASE_CONN_MAX_AGE", 600)),
-        conn_health_checks=environ.get("DATABASE_CONN_HEALTH_CHECKS", "true").lower()
-        in [
-            "true",
-            "1",
-        ],
-    )
+```python
+# app/settings.py
+ENV_SETTINGS_PREFIXES = ["PLAIN_", "MYAPP_"]
 ```
 
-### .env files
-
-Plain itself does not load `.env` files automatically, except in development if you use [`plain.dev`](/plain-dev/README.md). If you use `.env` files in production then you will need to load them yourself.
+Now both `PLAIN_DEBUG=true` and `MYAPP_DEBUG=true` would set the `DEBUG` setting. The first matching prefix wins if the same setting appears with multiple prefixes.
 
 ## Package settings
 
-An installed package can provide a `default_settings.py` file. It is strongly recommended to prefix any defined settings with the package name to avoid conflicts.
+Installed packages can provide default settings via a `default_settings.py` file. It's best practice to prefix package settings with the package name to avoid conflicts.
 
 ```python
 # app/users/default_settings.py
 USERS_DEFAULT_ROLE = "user"
 ```
 
-The way you define these settings can impact the runtime behavior. For example, a required setting should be defined with a type annotation but no default value.
+To make a setting required (no default value), define it with only a type annotation:
 
 ```python
 # app/users/default_settings.py
 USERS_DEFAULT_ROLE: str
 ```
 
-Type annotations are only required for settings that don't provide a default value (to enable the environment variable loading). But generally type annotations are recommended as they also provide basic validation at runtime — if a setting is defined as a `str` but the user sets it to an `int`, an error will be raised.
+Type annotations provide basic runtime validation. If a setting is defined as `str` but someone sets it to an `int`, Plain raises an error.
 
 ```python
 # app/users/default_settings.py
-USERS_DEFAULT_ROLE: str = "user"
+USERS_DEFAULT_ROLE: str = "user"  # Optional with a default
 ```
 
-## Custom app-wide settings
+## Custom app settings
 
-At times it can be useful to create your own settings that are used across your application. When you define these in `app/settings.py`, you simply prefix them with `APP_` which marks them as a custom setting.
+You can create your own app-wide settings by prefixing them with `APP_`:
 
 ```python
 # app/settings.py
+import os
+
 # A required env setting
 APP_STRIPE_SECRET_KEY = os.environ["STRIPE_SECRET_KEY"]
 
@@ -149,12 +147,82 @@ with open("app/secret_key.txt") as f:
     APP_EXAMPLE_KEY = f.read().strip()
 ```
 
-## Using Plain in other environments
+Settings without the `APP_` prefix that aren't recognized by Plain or installed packages will raise an error.
+
+## Secret values
+
+You can mark sensitive settings using the [`Secret`](./secret.py#Secret) type. Secret values are masked when displayed in logs or debugging output.
+
+```python
+from plain.runtime import Secret
+
+SECRET_KEY: Secret[str]
+DATABASE_PASSWORD: Secret[str]
+```
+
+At runtime, the value is still a plain string. The `Secret` type is purely a marker that tells Plain to mask the value when displaying settings.
+
+## Using Plain outside of an app
 
-There may be some situations where you want to manually invoke Plain, like in a Python script. To get everything set up, you can call the `plain.runtime.setup()` function.
+If you need to use Plain in a standalone script, call `plain.runtime.setup()` first:
 
 ```python
 import plain.runtime
 
 plain.runtime.setup()
+
+# Now you can use Plain normally
+from plain.runtime import settings
+print(settings.DEBUG)
+```
+
+The `setup()` function configures settings, logging, and populates the package registry. You can only call it once.
+
+## FAQs
+
+#### Where are the default settings defined?
+
+Plain's core settings are in [`global_settings.py`](./global_settings.py). Each installed package can also have a `default_settings.py` file with package-specific defaults.
+
+#### How do I see what settings are available?
+
+Check [`global_settings.py`](./global_settings.py) for core settings. For package-specific settings, look at the `default_settings.py` file in each package.
+
+#### What's the difference between required and optional settings?
+
+A setting with only a type annotation (no value) is required:
+
+```python
+SECRET_KEY: str  # Required - must be set
+```
+
+A setting with a value is optional (has a default):
+
+```python
+DEBUG: bool = False  # Optional - defaults to False
+```
+
+#### Can I modify settings at runtime?
+
+Yes, you can assign new values to settings after setup:
+
+```python
+from plain.runtime import settings
+
+settings.DEBUG = True
 ```
+
+#### What paths are available without setup?
+
+`APP_PATH` and `PLAIN_TEMP_PATH` are available immediately without calling `setup()`:
+
+```python
+from plain.runtime import APP_PATH, PLAIN_TEMP_PATH
+
+print(APP_PATH)  # /path/to/project/app
+print(PLAIN_TEMP_PATH)  # /path/to/project/.plain
+```
+
+## Installation
+
+The runtime module is included with Plain by default. No additional installation is required.

plain/runtime/__init__.py

@@ -2,10 +2,12 @@ import importlib.metadata
 import sys
 from importlib.metadata import entry_points
 from pathlib import Path
+from typing import Self
 
 from plain.logs.configure import configure_logging
 from plain.packages import packages_registry
 
+from .secret import Secret
 from .user_settings import Settings
 
 try:
@@ -32,7 +34,7 @@ class SetupError(RuntimeError):
     pass
 
 
-def setup():
+def setup() -> None:
     """
     Configure the settings (this happens as a side effect of accessing the
     first setting), configure logging and populate the app registry.
@@ -63,9 +65,10 @@ def setup():
         sys.path.insert(0, APP_PATH.parent.as_posix())
 
     configure_logging(
-        plain_log_level=settings.PLAIN_LOG_LEVEL,
-        app_log_level=settings.APP_LOG_LEVEL,
-        app_log_format=settings.APP_LOG_FORMAT,
+        plain_log_level=settings.FRAMEWORK_LOG_LEVEL,
+        app_log_level=settings.LOG_LEVEL,
+        app_log_format=settings.LOG_FORMAT,
+        log_stream=settings.LOG_STREAM,
     )
 
     packages_registry.populate(settings.INSTALLED_PACKAGES)
@@ -77,17 +80,18 @@ class SettingsReference(str):
     the value in memory but serializes to a settings.NAME attribute reference.
     """
 
-    def __new__(self, setting_name):
+    def __new__(self, setting_name: str) -> Self:
         value = getattr(settings, setting_name)
         return str.__new__(self, value)
 
-    def __init__(self, setting_name):
+    def __init__(self, setting_name: str):
         self.setting_name = setting_name
 
 
 __all__ = [
     "setup",
     "settings",
+    "Secret",
     "SettingsReference",
     "APP_PATH",
     "__version__",

plain/runtime/global_settings.py

@@ -3,8 +3,7 @@ Default Plain settings. Override these with settings in the module pointed to
 by the PLAIN_SETTINGS_MODULE environment variable.
 """
 
-from os import environ
-
+from .secret import Secret
 from .utils import get_app_info_from_pyproject
 
 # MARK: Core Settings
@@ -12,14 +11,20 @@ from .utils import get_app_info_from_pyproject
 DEBUG: bool = False
 
 name, version = get_app_info_from_pyproject()
-APP_NAME: str = name
-APP_VERSION: str = version
+NAME: str = name
+VERSION: str = version
 
 # List of strings representing installed packages.
 INSTALLED_PACKAGES: list[str] = []
 
 URLS_ROUTER: str
 
+# List of environment variable prefixes to check for settings.
+# Settings can be configured via environment variables using these prefixes.
+# Example: ENV_SETTINGS_PREFIXES = ["PLAIN_", "MYAPP_"]
+# Then both PLAIN_DEBUG and MYAPP_DEBUG would set the DEBUG setting.
+ENV_SETTINGS_PREFIXES: list[str] = ["PLAIN_"]
+
 # MARK: HTTP and Security
 
 # Hosts/domain names that are valid for this site.
@@ -29,8 +34,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",
@@ -47,25 +56,28 @@ HTTPS_REDIRECT_ENABLED = True
 # If your Plain app is behind a proxy that sets a header to specify secure
 # connections, AND that proxy ensures that user-submitted headers with the
 # same name are ignored (so that people can't spoof it), set this value to
-# a tuple of (header_name, header_value). For any requests that come in with
-# that header/value, request.is_https() will return True.
+# a string in the format "Header-Name: value". For any requests that come in
+# with that header/value, request.is_https() will return True.
 # WARNING! Only set this if you fully understand what you're doing. Otherwise,
 # you may be opening yourself up to a security risk.
-HTTPS_PROXY_HEADER = None
+# Example: HTTPS_PROXY_HEADER = "X-Forwarded-Proto: https"
+HTTPS_PROXY_HEADER: str = ""
 
-# Whether to use the X-Forwarded-Host and X-Forwarded-Port headers
-# when determining the host and port for the request.
-USE_X_FORWARDED_HOST = False
-USE_X_FORWARDED_PORT = False
+# Whether to use the X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-For
+# headers when determining the host, port, and client IP for the request.
+# Only enable these when behind a trusted proxy that overwrites these headers.
+HTTP_X_FORWARDED_HOST: bool = False
+HTTP_X_FORWARDED_PORT: bool = False
+HTTP_X_FORWARDED_FOR: bool = False
 
 # A secret key for this particular Plain installation. Used in secret-key
 # hashing algorithms. Set this in your settings, or Plain will complain
 # loudly.
-SECRET_KEY: str
+SECRET_KEY: Secret[str]
 
 # List of secret keys used to verify the validity of signatures. This allows
 # secret key rotation.
-SECRET_KEY_FALLBACKS: list[str] = []
+SECRET_KEY_FALLBACKS: Secret[list[str]] = []  # type: ignore[assignment]
 
 # MARK: Internationalization
 
@@ -97,15 +109,15 @@ FILE_UPLOAD_HANDLERS = [
 FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440  # i.e. 2.5 MB
 
 # Maximum size in bytes of request data (excluding file uploads) that will be
-# read before a SuspiciousOperation (RequestDataTooBig) is raised.
+# read before a SuspiciousOperationError400 (RequestDataTooBigError400) is raised.
 DATA_UPLOAD_MAX_MEMORY_SIZE = 2621440  # i.e. 2.5 MB
 
 # Maximum number of GET/POST parameters that will be read before a
-# SuspiciousOperation (TooManyFieldsSent) is raised.
+# SuspiciousOperationError400 (TooManyFieldsSentError400) is raised.
 DATA_UPLOAD_MAX_NUMBER_FIELDS = 1000
 
 # Maximum number of files encoded in a multipart upload that will be read
-# before a SuspiciousOperation (TooManyFilesSent) is raised.
+# before a SuspiciousOperationError400 (TooManyFilesSentError400) is raised.
 DATA_UPLOAD_MAX_NUMBER_FILES = 100
 
 # Directory in which upload streamed files will be temporarily saved. A value of
@@ -113,9 +125,6 @@ DATA_UPLOAD_MAX_NUMBER_FILES = 100
 # (i.e. "/tmp" on *nix systems).
 FILE_UPLOAD_TEMP_DIR = None
 
-# User-defined overrides for error views by status code
-HTTP_ERROR_VIEWS: dict[int] = {}
-
 # MARK: Middleware
 
 # List of middleware to use. Order is important; in the request phase, these
@@ -135,11 +144,11 @@ CSRF_TRUSTED_ORIGINS: list[str] = []
 CSRF_EXEMPT_PATHS: list[str] = []
 
 # MARK: Logging
-# (Uses some custom env names in addition to PLAIN_ prefixed )
 
-PLAIN_LOG_LEVEL: str = environ.get("PLAIN_LOG_LEVEL", "INFO")
-APP_LOG_LEVEL: str = environ.get("APP_LOG_LEVEL", "INFO")
-APP_LOG_FORMAT: str = environ.get("APP_LOG_FORMAT", "keyvalue")
+FRAMEWORK_LOG_LEVEL: str = "INFO"
+LOG_LEVEL: str = "INFO"
+LOG_FORMAT: str = "keyvalue"
+LOG_STREAM: str = "split"  # "split", "stdout", or "stderr"
 
 # MARK: Assets
 

plain/runtime/secret.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Secret(Generic[T]):
+    """
+    Marker type for sensitive settings. Values are masked in output/logs.
+
+    Usage:
+        SECRET_KEY: Secret[str]
+        DATABASE_PASSWORD: Secret[str]
+
+    At runtime, the value is still a plain str - this is purely for
+    indicating that the setting should be masked when displayed.
+    """
+
+    pass