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

plain/preflight/README.md

@@ -1,61 +1,246 @@
-# Preflight
+# plain.preflight
 
-**System checks for Plain applications.**
+**System checks that validate your settings and environment before running your application.**
 
 - [Overview](#overview)
-- [Development](#development)
-- [Deployment](#deployment)
+- [Running preflight checks](#running-preflight-checks)
+    - [Development](#development)
+    - [Deployment](#deployment)
+    - [JSON output](#json-output)
+- [Built-in checks](#built-in-checks)
 - [Custom preflight checks](#custom-preflight-checks)
-- [Silencing preflight checks](#silencing-preflight-checks)
+    - [Basic checks](#basic-checks)
+    - [Deployment-only checks](#deployment-only-checks)
+    - [Warnings vs errors](#warnings-vs-errors)
+- [Silencing checks](#silencing-checks)
+    - [Silencing entire checks](#silencing-entire-checks)
+    - [Silencing specific results](#silencing-specific-results)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Preflight checks help identify issues with your settings or environment before running your application.
+Preflight checks help you catch configuration problems early. You can run checks to verify that settings are valid, directories exist, URL patterns are correct, and security requirements are met before your application starts.
+
+```python
+from plain.preflight import PreflightCheck, PreflightResult, register_check
+
+
+@register_check("custom.database_connection")
+class CheckDatabaseConnection(PreflightCheck):
+    """Verify database is reachable."""
+
+    def run(self) -> list[PreflightResult]:
+        from plain.models import connection
+
+        try:
+            connection.ensure_connection()
+        except Exception as e:
+            return [
+                PreflightResult(
+                    fix=f"Database connection failed: {e}. Check your DATABASE_URL.",
+                    id="custom.database_unreachable",
+                )
+            ]
+        return []
+```
+
+When you run `plain preflight`, your check runs alongside the built-in checks:
 
 ```bash
-plain preflight check
+$ plain preflight
+Running preflight checks...
+Check: custom.database_connection ✔
+Check: files.upload_temp_dir ✔
+Check: settings.unused_env_vars ✔
+Check: urls.config ✔
+
+4 passed
 ```
 
-## Development
+## Running preflight checks
+
+### Development
+
+Run preflight checks at any time:
+
+```bash
+plain preflight
+```
 
-If you use [`plain.dev`](/plain-dev/README.md) for local development, the Plain preflight command is run automatically when you run `plain dev`.
+If you use [`plain.dev`](/plain-dev/README.md) for local development, preflight checks run automatically when you start `plain dev`.
 
-## Deployment
+### Deployment
 
-The `plain preflight check` command should often be part of your deployment process. Make sure to add the `--deploy` flag to the command to run checks that are only relevant in a production environment.
+Add `--deploy` to include deployment-specific checks like `SECRET_KEY` strength, `DEBUG` mode, and `ALLOWED_HOSTS`:
 
 ```bash
-plain preflight check --deploy
+plain preflight --deploy
 ```
 
+This should be part of your deployment process. If any check fails (returns errors, not warnings), the command exits with code 1.
+
+### JSON output
+
+For CI/CD pipelines or programmatic access, use JSON output:
+
+```bash
+plain preflight --format json
+```
+
+```json
+{
+  "passed": true,
+  "checks": [
+    {
+      "name": "files.upload_temp_dir",
+      "passed": true,
+      "issues": []
+    }
+  ]
+}
+```
+
+Use `--quiet` to suppress progress output and only show errors.
+
+## Built-in checks
+
+Plain includes these checks out of the box:
+
+| Check                           | Description                                              | Deploy only |
+| ------------------------------- | -------------------------------------------------------- | ----------- |
+| `files.upload_temp_dir`         | Validates `FILE_UPLOAD_TEMP_DIR` exists                  | No          |
+| `settings.unused_env_vars`      | Detects env vars that look like settings but aren't used | No          |
+| `urls.config`                   | Validates URL patterns for common issues                 | No          |
+| `security.secret_key`           | Validates `SECRET_KEY` strength                          | Yes         |
+| `security.secret_key_fallbacks` | Validates `SECRET_KEY_FALLBACKS` strength                | Yes         |
+| `security.debug`                | Ensures `DEBUG` is False                                 | Yes         |
+| `security.allowed_hosts`        | Ensures `ALLOWED_HOSTS` is not empty                     | Yes         |
+
 ## Custom preflight checks
 
-Use the `@register_check` decorator to add your own preflight check to the system. Just make sure that particular Python module is somehow imported so the check registration runs.
+### Basic checks
+
+Create a check by subclassing [`PreflightCheck`](./checks.py#PreflightCheck) and using the [`@register_check`](./registry.py#register_check) decorator:
 
 ```python
-from plain.preflight import register_check, Error
+from plain.preflight import PreflightCheck, PreflightResult, register_check
+
+
+@register_check("custom.redis_connection")
+class CheckRedisConnection(PreflightCheck):
+    """Verify Redis cache is reachable."""
+
+    def run(self) -> list[PreflightResult]:
+        from plain.cache import cache
+
+        try:
+            cache.set("preflight_test", "ok", timeout=1)
+        except Exception as e:
+            return [
+                PreflightResult(
+                    fix=f"Redis connection failed: {e}",
+                    id="custom.redis_unreachable",
+                )
+            ]
+        return []
+```
+
+Place this in a `preflight.py` file in your app directory. Plain autodiscovers `preflight.py` modules when running checks.
 
+### Deployment-only checks
 
-@register_check
-def custom_check(package_configs, **kwargs):
-    return Error("This is a custom error message.", id="custom.C001")
+For checks that only matter in production, add `deploy=True`:
+
+```python
+@register_check("custom.ssl_certificate", deploy=True)
+class CheckSSLCertificate(PreflightCheck):
+    """Verify SSL certificate is valid and not expiring soon."""
+
+    def run(self) -> list[PreflightResult]:
+        # Check certificate expiration...
+        if days_until_expiry < 30:
+            return [
+                PreflightResult(
+                    fix=f"SSL certificate expires in {days_until_expiry} days.",
+                    id="custom.ssl_expiring_soon",
+                )
+            ]
+        return []
 ```
 
-For deployment-specific checks, add the `deploy` argument to the decorator.
+### Warnings vs errors
+
+By default, [`PreflightResult`](./results.py#PreflightResult) represents an error that fails the preflight. For non-critical issues, use `warning=True`:
 
 ```python
-@register_check(deploy=True)
-def custom_deploy_check(package_configs, **kwargs):
-    return Error("This is a custom error message for deployment.", id="custom.D001")
+PreflightResult(
+    fix="Consider enabling gzip compression for better performance.",
+    id="custom.gzip_disabled",
+    warning=True,  # Won't cause preflight to fail
+)
 ```
 
-## Silencing preflight checks
+Warnings display with a yellow indicator but don't cause the command to exit with an error code.
 
-The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.E020`).
+## Silencing checks
+
+### Silencing entire checks
+
+To skip a check entirely, add its name to `PREFLIGHT_SILENCED_CHECKS`:
 
 ```python
 # app/settings.py
 PREFLIGHT_SILENCED_CHECKS = [
-    "security.E020",  # Allow empty ALLOWED_HOSTS in deployment
+    "security.debug",  # We intentionally run with DEBUG=True in staging
+]
+```
+
+### Silencing specific results
+
+To silence individual result IDs (not the whole check), use `PREFLIGHT_SILENCED_RESULTS`:
+
+```python
+# app/settings.py
+PREFLIGHT_SILENCED_RESULTS = [
+    "security.secret_key_weak",  # Using a known weak key in testing
 ]
 ```
+
+## FAQs
+
+#### What's the difference between a check name and a result ID?
+
+The check name (like `security.secret_key`) identifies the check class. The result ID (like `security.secret_key_weak`) identifies a specific issue that check can report. A single check can return multiple different result IDs.
+
+#### Where should I put custom preflight checks?
+
+Create a `preflight.py` file in your app directory. Plain autodiscovers these modules when running `plain preflight`.
+
+#### How do I run checks programmatically?
+
+Use the [`run_checks`](./registry.py#run_checks) function:
+
+```python
+from plain.preflight import run_checks
+
+for check_class, name, results in run_checks(include_deploy_checks=True):
+    for result in results:
+        print(f"{name}: {result.fix}")
+```
+
+#### Can I attach additional context to a result?
+
+Use the `obj` parameter to attach a related object:
+
+```python
+PreflightResult(
+    fix="Invalid URL pattern",
+    id="urls.invalid_pattern",
+    obj=some_url_pattern,  # Will be included in output
+)
+```
+
+## Installation
+
+`plain.preflight` is included with the `plain` package. No additional installation is required.

plain/preflight/__init__.py

@@ -5,6 +5,7 @@ from .results import PreflightResult
 # Import these to force registration of checks
 import plain.preflight.files  # NOQA isort:skip
 import plain.preflight.security  # NOQA isort:skip
+import plain.preflight.settings  # NOQA isort:skip
 import plain.preflight.urls  # NOQA isort:skip
 
 

plain/preflight/checks.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 
 
@@ -5,6 +7,6 @@ class PreflightCheck(ABC):
     """Base class for all preflight checks."""
 
     @abstractmethod
-    def run(self):
+    def run(self) -> list:
         """Must return a list of Warning/Error results."""
         raise NotImplementedError

plain/preflight/files.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pathlib import Path
 
 from plain.runtime import settings
@@ -11,7 +13,7 @@ from .results import PreflightResult
 class CheckSettingFileUploadTempDir(PreflightCheck):
     """Validates that the FILE_UPLOAD_TEMP_DIR setting points to an existing directory."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         setting = settings.FILE_UPLOAD_TEMP_DIR
         if setting and not Path(setting).is_dir():
             return [

plain/preflight/registry.py

@@ -1,11 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, TypeVar
+
 from plain.runtime import settings
 
+from .results import PreflightResult
 
-class CheckRegistry:
-    def __init__(self):
-        self.checks = {}  # name -> (check_class, deploy)
+T = TypeVar("T")
 
-    def register_check(self, check_class, name, deploy=False):
+
+class CheckRegistry:
+    def __init__(self) -> None:
+        self.checks: dict[
+            str, tuple[type[Any], bool]
+        ] = {}  # name -> (check_class, deploy)
+
+    def register_check(
+        self, check_class: type[Any], name: str, deploy: bool = False
+    ) -> None:
         """Register a check class with a unique name."""
         if name in self.checks:
             raise ValueError(f"Check {name} already registered")
@@ -13,8 +26,8 @@ class CheckRegistry:
 
     def run_checks(
         self,
-        include_deploy_checks=False,
-    ):
+        include_deploy_checks: bool = False,
+    ) -> Generator[tuple[type[Any], str, list[PreflightResult]]]:
         """
         Run all registered checks and yield (check_class, name, results) tuples.
         """
@@ -28,7 +41,7 @@ class CheckRegistry:
                 "Check for typos or remove outdated check names."
             )
 
-        for name, (check_class, deploy) in self.checks.items():
+        for name, (check_class, deploy) in sorted(self.checks.items()):
             # Skip silenced checks
             if name in silenced_checks:
                 continue
@@ -42,9 +55,11 @@ class CheckRegistry:
             results = check.run()
             yield check_class, name, results
 
-    def get_checks(self, include_deploy_checks=False):
+    def get_checks(
+        self, include_deploy_checks: bool = False
+    ) -> list[tuple[type[Any], str]]:
         """Get list of (check_class, name) tuples."""
-        result = []
+        result: list[tuple[type[Any], str]] = []
         for name, (check_class, deploy) in self.checks.items():
             if deploy and not include_deploy_checks:
                 continue
@@ -55,7 +70,7 @@ class CheckRegistry:
 checks_registry = CheckRegistry()
 
 
-def register_check(name: str, *, deploy: bool = False):
+def register_check(name: str, *, deploy: bool = False) -> Callable[[type[T]], type[T]]:
     """
     Decorator to register a check class.
 
@@ -69,7 +84,7 @@ def register_check(name: str, *, deploy: bool = False):
             pass
     """
 
-    def wrapper(cls):
+    def wrapper(cls: type[T]) -> type[T]:
         checks_registry.register_check(cls, name=name, deploy=deploy)
         return cls
 

plain/preflight/results.py

@@ -1,29 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.runtime import settings
 
 
 class PreflightResult:
-    def __init__(self, *, fix: str, id: str, obj=None, warning: bool = False):
+    def __init__(
+        self, *, fix: str, id: str, obj: Any = None, warning: bool = False
+    ) -> None:
         self.fix = fix
         self.obj = obj
         self.id = id
         self.warning = warning
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, self.__class__) and all(
             getattr(self, attr) == getattr(other, attr)
             for attr in ["fix", "obj", "id", "warning"]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.obj is None:
             obj = ""
-        elif hasattr(self.obj, "_meta") and hasattr(self.obj._meta, "label"):
+        elif hasattr(self.obj, "model_options") and hasattr(
+            self.obj.model_options, "label"
+        ):
             # Duck type for model objects - use their meta label
-            obj = self.obj._meta.label
+            obj = self.obj.model_options.label
         else:
             obj = str(self.obj)
         id_part = f"({self.id}) " if self.id else ""
         return f"{obj}: {id_part}{self.fix}"
 
-    def is_silenced(self):
-        return self.id and self.id in settings.PREFLIGHT_SILENCED_RESULTS
+    def is_silenced(self) -> bool:
+        return bool(self.id and self.id in settings.PREFLIGHT_SILENCED_RESULTS)

plain/preflight/security.py

@@ -1,17 +1,19 @@
+from __future__ import annotations
+
 from plain.runtime import settings
 
 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_MIN_LENGTH = 50
+_SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
 
 
-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
     )
 
 
@@ -19,12 +21,12 @@ def _check_secret_key(secret_key):
 class CheckSecretKey(PreflightCheck):
     """Validates that SECRET_KEY is long and random enough for security."""
 
-    def run(self):
+    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 "
+                    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",
                 )
@@ -36,14 +38,14 @@ class CheckSecretKey(PreflightCheck):
 class CheckSecretKeyFallbacks(PreflightCheck):
     """Validates that SECRET_KEY_FALLBACKS are long and random enough for security."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         errors = []
         for index, key in enumerate(settings.SECRET_KEY_FALLBACKS):
             if not _check_secret_key(key):
                 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 "
+                        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",
                     )
@@ -55,7 +57,7 @@ class CheckSecretKeyFallbacks(PreflightCheck):
 class CheckDebug(PreflightCheck):
     """Ensures DEBUG is False in production deployment."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         if settings.DEBUG:
             return [
                 PreflightResult(
@@ -70,7 +72,7 @@ class CheckDebug(PreflightCheck):
 class CheckAllowedHosts(PreflightCheck):
     """Ensures ALLOWED_HOSTS is not empty in production deployment."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         if not settings.ALLOWED_HOSTS:
             return [
                 PreflightResult(

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,12 +1,15 @@
+from __future__ import annotations
+
 from .checks import PreflightCheck
 from .registry import register_check
+from .results import PreflightResult
 
 
 @register_check("urls.config")
 class CheckUrlConfig(PreflightCheck):
     """Validates the URL configuration for common issues."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         from plain.urls import get_resolver
 
         resolver = get_resolver()