plain 0.66.0__py3-none-any.whl → 0.101.2__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
+$ 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:
 
-If you use [`plain.dev`](/plain-dev/README.md) for local development, the Plain preflight command is run automatically when you run `plain dev`.
+```bash
+plain preflight
+```
+
+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` 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 --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.
 
-@register_check
-def custom_check(package_configs, **kwargs):
-    return Error("This is a custom error message.", id="custom.C001")
+### Deployment-only checks
+
+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.
+
+## Silencing checks
 
-The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.W020`).
+### Silencing entire checks
+
+To skip a check entirely, add its name to `PREFLIGHT_SILENCED_CHECKS`:
 
 ```python
 # app/settings.py
 PREFLIGHT_SILENCED_CHECKS = [
-    "security.W020",
+    "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

@@ -1,36 +1,17 @@
-from .messages import (
-    CRITICAL,
-    DEBUG,
-    ERROR,
-    INFO,
-    WARNING,
-    CheckMessage,
-    Critical,
-    Debug,
-    Error,
-    Info,
-    Warning,
-)
+from .checks import PreflightCheck
 from .registry import register_check, run_checks
+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
 
 
 __all__ = [
-    "CheckMessage",
-    "Debug",
-    "Info",
-    "Warning",
-    "Error",
-    "Critical",
-    "DEBUG",
-    "INFO",
-    "WARNING",
-    "ERROR",
-    "CRITICAL",
+    "PreflightCheck",
+    "PreflightResult",
     "register_check",
     "run_checks",
 ]

plain/preflight/checks.py

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

plain/preflight/files.py

@@ -1,19 +1,25 @@
+from __future__ import annotations
+
 from pathlib import Path
 
 from plain.runtime import settings
 
-from . import Error, register_check
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
+
 
+@register_check("files.upload_temp_dir")
+class CheckSettingFileUploadTempDir(PreflightCheck):
+    """Validates that the FILE_UPLOAD_TEMP_DIR setting points to an existing directory."""
 
-@register_check
-def check_setting_file_upload_temp_dir(package_configs, **kwargs):
-    setting = getattr(settings, "FILE_UPLOAD_TEMP_DIR", None)
-    if setting and not Path(setting).is_dir():
-        return [
-            Error(
-                f"The FILE_UPLOAD_TEMP_DIR setting refers to the nonexistent "
-                f"directory '{setting}'.",
-                id="files.E001",
-            ),
-        ]
-    return []
+    def run(self) -> list[PreflightResult]:
+        setting = settings.FILE_UPLOAD_TEMP_DIR
+        if setting and not Path(setting).is_dir():
+            return [
+                PreflightResult(
+                    fix=f"FILE_UPLOAD_TEMP_DIR points to nonexistent directory '{setting}'. Create the directory or update the setting.",
+                    id="files.upload_temp_dir_nonexistent",
+                )
+            ]
+        return []

plain/preflight/registry.py

@@ -1,72 +1,94 @@
-from plain.utils.inspect import func_accepts_kwargs
-from plain.utils.itercompat import is_iterable
+from __future__ import annotations
 
+from collections.abc import Callable, Generator
+from typing import Any, TypeVar
 
-class CheckRegistry:
-    def __init__(self):
-        self.registered_checks = set()
-        self.deployment_checks = set()
+from plain.runtime import settings
 
-    def register(self, check=None, deploy=False):
-        """
-        Can be used as a function or a decorator. Register given function
-        `f`. The function should receive **kwargs
-        and return list of Errors and Warnings.
-
-        Example::
-
-            registry = CheckRegistry()
-            @registry.register('mytag', 'anothertag')
-            def my_check(package_configs, **kwargs):
-                # ... perform checks and collect `errors` ...
-                return errors
-            # or
-            registry.register(my_check, 'mytag', 'anothertag')
-        """
+from .results import PreflightResult
 
-        def inner(check):
-            if not func_accepts_kwargs(check):
-                raise TypeError(
-                    "Check functions must accept keyword arguments (**kwargs)."
-                )
-            checks = self.deployment_checks if deploy else self.registered_checks
-            checks.add(check)
-            return check
+T = TypeVar("T")
 
-        if callable(check):
-            return inner(check)
-        else:
-            return inner
+
+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")
+        self.checks[name] = (check_class, deploy)
 
     def run_checks(
         self,
-        package_configs=None,
-        include_deployment_checks=False,
-        database=False,
-    ):
+        include_deploy_checks: bool = False,
+    ) -> Generator[tuple[type[Any], str, list[PreflightResult]]]:
         """
-        Run all registered checks and return list of Errors and Warnings.
+        Run all registered checks and yield (check_class, name, results) tuples.
         """
-        errors = []
-        checks = self.get_checks(include_deployment_checks)
-
-        for check in checks:
-            new_errors = check(package_configs=package_configs, database=database)
-            if not is_iterable(new_errors):
-                raise TypeError(
-                    f"The function {check!r} did not return a list. All functions "
-                    "registered with the checks registry must return a list.",
-                )
-            errors.extend(new_errors)
-        return errors
-
-    def get_checks(self, include_deployment_checks=False):
-        checks = list(self.registered_checks)
-        if include_deployment_checks:
-            checks.extend(self.deployment_checks)
-        return checks
+        # Validate silenced check names
+        silenced_checks = settings.PREFLIGHT_SILENCED_CHECKS
+        unknown_silenced = set(silenced_checks) - set(self.checks.keys())
+        if unknown_silenced:
+            unknown_names = ", ".join(sorted(unknown_silenced))
+            raise ValueError(
+                f"Unknown check names in PREFLIGHT_SILENCED_CHECKS: {unknown_names}. "
+                "Check for typos or remove outdated check names."
+            )
+
+        for name, (check_class, deploy) in sorted(self.checks.items()):
+            # Skip silenced checks
+            if name in silenced_checks:
+                continue
+
+            # Skip deployment checks if not requested
+            if deploy and not include_deploy_checks:
+                continue
+
+            # Instantiate and run check
+            check = check_class()
+            results = check.run()
+            yield check_class, name, results
+
+    def get_checks(
+        self, include_deploy_checks: bool = False
+    ) -> list[tuple[type[Any], str]]:
+        """Get list of (check_class, name) tuples."""
+        result: list[tuple[type[Any], str]] = []
+        for name, (check_class, deploy) in self.checks.items():
+            if deploy and not include_deploy_checks:
+                continue
+            result.append((check_class, name))
+        return result
 
 
 checks_registry = CheckRegistry()
-register_check = checks_registry.register
+
+
+def register_check(name: str, *, deploy: bool = False) -> Callable[[type[T]], type[T]]:
+    """
+    Decorator to register a check class.
+
+    Usage:
+        @register_check("security.secret_key", deploy=True)
+        class CheckSecretKey(PreflightCheck):
+            pass
+
+        @register_check("files.upload_temp_dir")
+        class CheckUploadTempDir(PreflightCheck):
+            pass
+    """
+
+    def wrapper(cls: type[T]) -> type[T]:
+        checks_registry.register_check(cls, name=name, deploy=deploy)
+        return cls
+
+    return wrapper
+
+
 run_checks = checks_registry.run_checks

plain/preflight/results.py

@@ -0,0 +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: Any = None, warning: bool = False
+    ) -> None:
+        self.fix = fix
+        self.obj = obj
+        self.id = id
+        self.warning = warning
+
+    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) -> str:
+        if self.obj is None:
+            obj = ""
+        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.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) -> bool:
+        return bool(self.id and self.id in settings.PREFLIGHT_SILENCED_RESULTS)