plain 0.66.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/preflight/security.py

@@ -1,89 +1,83 @@
-from plain.exceptions import ImproperlyConfigured
+from __future__ import annotations
+
 from plain.runtime import settings
 
-from .messages import Warning
+from .checks import PreflightCheck
 from .registry import register_check
+from .results import PreflightResult
 
-SECRET_KEY_MIN_LENGTH = 50
-SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
-
-SECRET_KEY_WARNING_MSG = (
-    f"Your %s has less than {SECRET_KEY_MIN_LENGTH} characters or less than "
-    f"{SECRET_KEY_MIN_UNIQUE_CHARACTERS} unique characters. Please generate "
-    f"a long and random value, otherwise many of Plain's security-critical "
-    f"features will be vulnerable to attack."
-)
+_SECRET_KEY_MIN_LENGTH = 50
+_SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
 
-W025 = Warning(SECRET_KEY_WARNING_MSG, id="security.W025")
 
-
-def _check_secret_key(secret_key):
+def _check_secret_key(secret_key: str) -> bool:
     return (
-        len(set(secret_key)) >= SECRET_KEY_MIN_UNIQUE_CHARACTERS
-        and len(secret_key) >= SECRET_KEY_MIN_LENGTH
+        len(set(secret_key)) >= _SECRET_KEY_MIN_UNIQUE_CHARACTERS
+        and len(secret_key) >= _SECRET_KEY_MIN_LENGTH
     )
 
 
-@register_check(deploy=True)
-def check_secret_key(package_configs, **kwargs):
-    try:
-        secret_key = settings.SECRET_KEY
-    except (ImproperlyConfigured, AttributeError):
-        passed_check = False
-    else:
-        passed_check = _check_secret_key(secret_key)
-    return (
-        []
-        if passed_check
-        else [
-            Warning(
-                SECRET_KEY_WARNING_MSG % "SECRET_KEY",
-                id="security.W009",
-            )
-        ]
-    )
+@register_check(name="security.secret_key", deploy=True)
+class CheckSecretKey(PreflightCheck):
+    """Validates that SECRET_KEY is long and random enough for security."""
+
+    def run(self) -> list[PreflightResult]:
+        if not _check_secret_key(settings.SECRET_KEY):
+            return [
+                PreflightResult(
+                    fix=f"SECRET_KEY is too weak (needs {_SECRET_KEY_MIN_LENGTH}+ characters, "
+                    f"{_SECRET_KEY_MIN_UNIQUE_CHARACTERS}+ unique). Generate a new long random value or "
+                    f"Plain's security features will be vulnerable to attack.",
+                    id="security.secret_key_weak",
+                )
+            ]
+        return []
+
 
+@register_check(name="security.secret_key_fallbacks", deploy=True)
+class CheckSecretKeyFallbacks(PreflightCheck):
+    """Validates that SECRET_KEY_FALLBACKS are long and random enough for security."""
 
-@register_check(deploy=True)
-def check_secret_key_fallbacks(package_configs, **kwargs):
-    warnings = []
-    try:
-        fallbacks = settings.SECRET_KEY_FALLBACKS
-    except (ImproperlyConfigured, AttributeError):
-        warnings.append(Warning(W025.msg % "SECRET_KEY_FALLBACKS", id=W025.id))
-    else:
-        for index, key in enumerate(fallbacks):
+    def run(self) -> list[PreflightResult]:
+        errors = []
+        for index, key in enumerate(settings.SECRET_KEY_FALLBACKS):
             if not _check_secret_key(key):
-                warnings.append(
-                    Warning(W025.msg % f"SECRET_KEY_FALLBACKS[{index}]", id=W025.id)
+                errors.append(
+                    PreflightResult(
+                        fix=f"SECRET_KEY_FALLBACKS[{index}] is too weak (needs {_SECRET_KEY_MIN_LENGTH}+ characters, "
+                        f"{_SECRET_KEY_MIN_UNIQUE_CHARACTERS}+ unique). Generate a new long random value or "
+                        f"Plain's security features will be vulnerable to attack.",
+                        id="security.secret_key_fallback_weak",
+                    )
                 )
-    return warnings
+        return errors
 
 
-@register_check(deploy=True)
-def check_debug(package_configs, **kwargs):
-    passed_check = not settings.DEBUG
-    return (
-        []
-        if passed_check
-        else [
-            Warning(
-                "You should not have DEBUG set to True in deployment.",
-                id="security.W018",
-            )
-        ]
-    )
+@register_check(name="security.debug", deploy=True)
+class CheckDebug(PreflightCheck):
+    """Ensures DEBUG is False in production deployment."""
 
+    def run(self) -> list[PreflightResult]:
+        if settings.DEBUG:
+            return [
+                PreflightResult(
+                    fix="DEBUG is True in deployment. Set DEBUG=False to prevent exposing sensitive information.",
+                    id="security.debug_enabled_in_production",
+                )
+            ]
+        return []
 
-@register_check(deploy=True)
-def check_allowed_hosts(package_configs, **kwargs):
-    return (
-        []
-        if settings.ALLOWED_HOSTS
-        else [
-            Warning(
-                "ALLOWED_HOSTS must not be empty in deployment.",
-                id="security.W020",
-            )
-        ]
-    )
+
+@register_check(name="security.allowed_hosts", deploy=True)
+class CheckAllowedHosts(PreflightCheck):
+    """Ensures ALLOWED_HOSTS is not empty in production deployment."""
+
+    def run(self) -> list[PreflightResult]:
+        if not settings.ALLOWED_HOSTS:
+            return [
+                PreflightResult(
+                    fix="ALLOWED_HOSTS is empty in deployment. Add your domain(s) to prevent host header attacks.",
+                    id="security.allowed_hosts_empty",
+                )
+            ]
+        return []

plain/preflight/settings.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+
+from plain.runtime import settings
+
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
+
+
+@register_check(name="settings.unused_env_vars")
+class CheckUnusedEnvVars(PreflightCheck):
+    """Detect environment variables that look like settings but aren't used."""
+
+    def run(self) -> list[PreflightResult]:
+        results: list[PreflightResult] = []
+
+        # Get all env vars matching any configured prefix
+        for prefix in settings._env_prefixes:
+            for key in os.environ:
+                if key.startswith(prefix) and key.isupper():
+                    setting_name = key[len(prefix) :]
+                    # Skip empty setting names (just the prefix itself)
+                    if setting_name and setting_name not in settings._settings:
+                        results.append(
+                            PreflightResult(
+                                fix=f"Environment variable '{key}' looks like a setting but "
+                                f"'{setting_name}' is not a recognized setting.",
+                                id="settings.unused_env_var",
+                                warning=True,
+                            )
+                        )
+
+        # Warn if PLAIN_ env vars exist but PLAIN_ not in prefixes
+        if "PLAIN_" not in settings._env_prefixes:
+            plain_vars = [
+                k
+                for k in os.environ
+                if k.startswith("PLAIN_")
+                and k.isupper()
+                and k != "PLAIN_SETTINGS_MODULE"  # This one is always valid
+            ]
+            if plain_vars:
+                results.append(
+                    PreflightResult(
+                        fix=f"Found PLAIN_ environment variables but 'PLAIN_' is not in "
+                        f"ENV_SETTINGS_PREFIXES: {', '.join(sorted(plain_vars))}",
+                        id="settings.plain_prefix_disabled",
+                        warning=True,
+                    )
+                )
+
+        return results

plain/preflight/urls.py

@@ -1,54 +1,16 @@
-from plain.runtime import settings
+from __future__ import annotations
 
-from . import Error, register_check
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
 
 
-@register_check
-def check_url_config(package_configs, **kwargs):
-    if getattr(settings, "URLS_ROUTER", None):
+@register_check("urls.config")
+class CheckUrlConfig(PreflightCheck):
+    """Validates the URL configuration for common issues."""
+
+    def run(self) -> list[PreflightResult]:
         from plain.urls import get_resolver
 
         resolver = get_resolver()
-        return check_resolver(resolver)
-
-    return []
-
-
-def check_resolver(resolver):
-    """
-    Recursively check the resolver.
-    """
-    check_method = getattr(resolver, "check", None)
-    if check_method is not None:
-        return check_method()
-    elif not hasattr(resolver, "resolve"):
-        return get_warning_for_invalid_pattern(resolver)
-    else:
-        return []
-
-
-def get_warning_for_invalid_pattern(pattern):
-    """
-    Return a list containing a warning that the pattern is invalid.
-
-    describe_pattern() cannot be used here, because we cannot rely on the
-    urlpattern having regex or name attributes.
-    """
-    if isinstance(pattern, str):
-        hint = (
-            f"Try removing the string '{pattern}'. The list of urlpatterns should not "
-            "have a prefix string as the first element."
-        )
-    elif isinstance(pattern, tuple):
-        hint = "Try using path() instead of a tuple."
-    else:
-        hint = None
-
-    return [
-        Error(
-            f"Your URL pattern {pattern!r} is invalid. Ensure that urlpatterns is a list "
-            "of path() and/or re_path() instances.",
-            hint=hint,
-            id="urls.E004",
-        )
-    ]
+        return resolver.preflight()

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__",