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

plain/runtime/user_settings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import importlib
 import json
 import os
@@ -9,10 +11,11 @@ from pathlib import Path
 
 from plain.exceptions import ImproperlyConfigured
 from plain.packages import PackageConfig
+from plain.runtime.secret import Secret
 
-ENVIRONMENT_VARIABLE = "PLAIN_SETTINGS_MODULE"
-ENV_SETTINGS_PREFIX = "PLAIN_"
-CUSTOM_SETTINGS_PREFIX = "APP_"
+_ENVIRONMENT_VARIABLE = "PLAIN_SETTINGS_MODULE"
+_DEFAULT_ENV_SETTINGS_PREFIXES = ["PLAIN_"]
+_CUSTOM_SETTINGS_PREFIX = "APP_"
 
 
 class Settings:
@@ -26,13 +29,14 @@ class Settings:
     Lazy initialization is implemented to defer loading until settings are first accessed.
     """
 
-    def __init__(self, settings_module=None):
+    def __init__(self, settings_module: str | None = None):
         self._settings_module = settings_module
-        self._settings = {}
-        self._errors = []  # Collect configuration errors
+        self._settings: dict[str, SettingDefinition] = {}
+        self._errors: list[str] = []  # Collect configuration errors
+        self._env_prefixes: list[str] = []  # Configured env prefixes
         self.configured = False
 
-    def _setup(self):
+    def _setup(self) -> None:
         if self.configured:
             return
         else:
@@ -42,7 +46,9 @@ class Settings:
 
         # Determine the settings module
         if self._settings_module is None:
-            self._settings_module = os.environ.get(ENVIRONMENT_VARIABLE, "app.settings")
+            self._settings_module = os.environ.get(
+                _ENVIRONMENT_VARIABLE, "app.settings"
+            )
 
         # First load the global settings from plain
         self._load_module_settings(
@@ -58,8 +64,14 @@ class Settings:
             )
 
         # Keep a reference to the settings.py module path
+        assert mod.__file__ is not None
         self.path = Path(mod.__file__).resolve()
 
+        # Get env prefixes from settings module (must be configured in settings.py, not env)
+        self._env_prefixes = getattr(
+            mod, "ENV_SETTINGS_PREFIXES", _DEFAULT_ENV_SETTINGS_PREFIXES
+        )
+
         # Load default settings from installed packages
         self._load_default_settings(mod)
         # Load environment settings
@@ -71,7 +83,7 @@ class Settings:
         # Check for any collected errors
         self._raise_errors_if_any()
 
-    def _load_module_settings(self, module):
+    def _load_module_settings(self, module: types.ModuleType) -> None:
         annotations = getattr(module, "__annotations__", {})
         settings = dir(module)
 
@@ -100,7 +112,7 @@ class Settings:
                     required=True,
                 )
 
-    def _load_default_settings(self, settings_module):
+    def _load_default_settings(self, settings_module: types.ModuleType) -> None:
         for entry in getattr(settings_module, "INSTALLED_PACKAGES", []):
             if isinstance(entry, PackageConfig):
                 app_settings = entry.module.default_settings
@@ -111,13 +123,20 @@ class Settings:
 
             self._load_module_settings(app_settings)
 
-    def _load_env_settings(self):
-        env_settings = {
-            k[len(ENV_SETTINGS_PREFIX) :]: v
-            for k, v in os.environ.items()
-            if k.startswith(ENV_SETTINGS_PREFIX) and k.isupper()
-        }
-        for setting, value in env_settings.items():
+    def _load_env_settings(self) -> None:
+        # Collect env settings from all configured prefixes
+        # First prefix wins if same setting appears with multiple prefixes
+        env_settings: dict[
+            str, tuple[str, str]
+        ] = {}  # setting_name -> (value, env_var)
+        for prefix in self._env_prefixes:
+            for key, value in os.environ.items():
+                if key.startswith(prefix) and key.isupper():
+                    setting_name = key[len(prefix) :]
+                    if setting_name and setting_name not in env_settings:
+                        env_settings[setting_name] = (value, key)
+
+        for setting, (value, env_var) in env_settings.items():
             if setting in self._settings:
                 setting_def = self._settings[setting]
                 try:
@@ -125,10 +144,11 @@ class Settings:
                         value, setting_def.annotation, setting
                     )
                     setting_def.set_value(parsed_value, "env")
+                    setting_def.env_var_name = env_var
                 except ImproperlyConfigured as e:
                     self._errors.append(str(e))
 
-    def _load_explicit_settings(self, settings_module):
+    def _load_explicit_settings(self, settings_module: types.ModuleType) -> None:
         for setting in dir(settings_module):
             if setting.isupper():
                 setting_value = getattr(settings_module, setting)
@@ -141,8 +161,8 @@ class Settings:
                         self._errors.append(str(e))
                         continue
 
-                elif setting.startswith(CUSTOM_SETTINGS_PREFIX):
-                    # Accept custom settings prefixed with '{CUSTOM_SETTINGS_PREFIX}'
+                elif setting.startswith(_CUSTOM_SETTINGS_PREFIX):
+                    # Accept custom settings prefixed with '{_CUSTOM_SETTINGS_PREFIX}'
                     setting_def = SettingDefinition(
                         name=setting,
                         default_value=None,
@@ -158,7 +178,7 @@ class Settings:
                 else:
                     # Collect unrecognized settings individually
                     self._errors.append(
-                        f"Unknown setting '{setting}'. Custom settings must start with '{CUSTOM_SETTINGS_PREFIX}'."
+                        f"Unknown setting '{setting}'. Custom settings must start with '{_CUSTOM_SETTINGS_PREFIX}'."
                     )
 
         if hasattr(time, "tzset") and self.TIME_ZONE:
@@ -172,19 +192,19 @@ class Settings:
                 os.environ["TZ"] = self.TIME_ZONE
                 time.tzset()
 
-    def _check_required_settings(self):
+    def _check_required_settings(self) -> None:
         missing = [k for k, v in self._settings.items() if v.required and not v.is_set]
         if missing:
             self._errors.append(f"Missing required setting(s): {', '.join(missing)}.")
 
-    def _raise_errors_if_any(self):
+    def _raise_errors_if_any(self) -> None:
         if self._errors:
             errors = ["- " + e for e in self._errors]
             raise ImproperlyConfigured(
                 "Settings configuration errors:\n" + "\n".join(errors)
             )
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str) -> typing.Any:
         # Avoid recursion by directly returning internal attributes
         if not name.isupper():
             return object.__getattribute__(self, name)
@@ -196,7 +216,7 @@ class Settings:
         else:
             raise AttributeError(f"'Settings' object has no attribute '{name}'")
 
-    def __setattr__(self, name, value):
+    def __setattr__(self, name: str, value: typing.Any) -> None:
         # Handle internal attributes without recursion
         if not name.isupper():
             object.__setattr__(self, name, value)
@@ -207,18 +227,46 @@ class Settings:
             else:
                 object.__setattr__(self, name, value)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if not self.configured:
             return "<Settings [Unevaluated]>"
         return f'<Settings "{self._settings_module}">'
 
+    def get_settings(
+        self, *, source: str | None = None
+    ) -> list[tuple[str, SettingDefinition]]:
+        """
+        Get settings as a sorted list of (name, definition) tuples.
+
+        Args:
+            source: Filter to settings from a specific source ('default', 'env', 'explicit', 'runtime')
+        """
+        self._setup()
+        result = []
+        for name, defn in sorted(self._settings.items()):
+            if source is not None and defn.source != source:
+                continue
+            result.append((name, defn))
+        return result
+
+    def get_env_settings(self) -> list[tuple[str, SettingDefinition]]:
+        """Get settings that were loaded from environment variables."""
+        return self.get_settings(source="env")
 
-def _parse_env_value(value, annotation, setting_name):
+
+def _parse_env_value(
+    value: str, annotation: type | None, setting_name: str
+) -> typing.Any:
     if not annotation:
         raise ImproperlyConfigured(
             f"{setting_name}: Type hint required to set from environment."
         )
 
+    # Unwrap Secret[T] to get the inner type
+    if typing.get_origin(annotation) is Secret:
+        if args := typing.get_args(annotation):
+            annotation = args[0]
+
     if annotation is bool:
         # Special case for bools
         return value.lower() in ("true", "1", "yes")
@@ -238,7 +286,12 @@ class SettingDefinition:
     """Store detailed information about settings."""
 
     def __init__(
-        self, name, default_value=None, annotation=None, module=None, required=False
+        self,
+        name: str,
+        default_value: typing.Any = None,
+        annotation: type | None = None,
+        module: types.ModuleType | None = None,
+        required: bool = False,
     ):
         self.name = name
         self.default_value = default_value
@@ -248,14 +301,27 @@ class SettingDefinition:
         self.value = default_value
         self.source = "default"  # 'default', 'env', 'explicit', or 'runtime'
         self.is_set = False  # Indicates if the value was set explicitly
+        self.env_var_name: str | None = None  # Env var name if loaded from env
+        self.is_secret = self._check_if_secret(annotation)
+
+    @staticmethod
+    def _check_if_secret(annotation: type | None) -> bool:
+        """Check if annotation is Secret[T]."""
+        return annotation is not None and typing.get_origin(annotation) is Secret
 
-    def set_value(self, value, source):
+    def display_value(self) -> str:
+        """Return value for display, masked if secret."""
+        if self.is_secret:
+            return "********"
+        return repr(self.value)
+
+    def set_value(self, value: typing.Any, source: str) -> None:
         self.check_type(value)
         self.value = value
         self.source = source
         self.is_set = True
 
-    def check_type(self, obj):
+    def check_type(self, obj: typing.Any) -> None:
         if not self.annotation:
             return
 
@@ -265,23 +331,29 @@ class SettingDefinition:
             )
 
     @staticmethod
-    def _is_instance_of_type(value, type_hint) -> bool:
+    def _is_instance_of_type(value: typing.Any, type_hint: typing.Any) -> bool:
         # Simple types
         if isinstance(type_hint, type):
             return isinstance(value, type_hint)
 
+        origin = typing.get_origin(type_hint)
+
+        # Secret[T] - check the inner type (Secret is just a marker)
+        if origin is Secret:
+            args = typing.get_args(type_hint)
+            if args:
+                return SettingDefinition._is_instance_of_type(value, args[0])
+            return True
+
         # Union types
-        if (
-            typing.get_origin(type_hint) is typing.Union
-            or typing.get_origin(type_hint) is types.UnionType
-        ):
+        if origin is typing.Union or origin is types.UnionType:
             return any(
                 SettingDefinition._is_instance_of_type(value, arg)
                 for arg in typing.get_args(type_hint)
             )
 
         # List types
-        if typing.get_origin(type_hint) is list:
+        if origin is list:
             return isinstance(value, list) and all(
                 SettingDefinition._is_instance_of_type(
                     item, typing.get_args(type_hint)[0]
@@ -290,7 +362,7 @@ class SettingDefinition:
             )
 
         # Tuple types
-        if typing.get_origin(type_hint) is tuple:
+        if origin is tuple:
             return isinstance(value, tuple) and all(
                 SettingDefinition._is_instance_of_type(
                     item, typing.get_args(type_hint)[i]
@@ -300,5 +372,5 @@ class SettingDefinition:
 
         raise ValueError(f"Unsupported type hint: {type_hint}")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"SettingDefinition(name={self.name}, value={self.value}, source={self.source})"

plain/runtime/utils.py

@@ -2,7 +2,7 @@ import tomllib
 from pathlib import Path
 
 
-def get_app_info_from_pyproject():
+def get_app_info_from_pyproject() -> tuple[str, str]:
     """Get the project name and version from the nearest pyproject.toml file."""
     current_path = Path.cwd()
 

plain/server/LICENSE

@@ -0,0 +1,35 @@
+Plain HTTP Server - License and Attribution
+============================================
+
+This module is based on gunicorn (https://gunicorn.org), integrated from
+commit 1dc4ce9d59c3458305d701c4c6d63aa6b1d1b309 (gunicorn 23.0.0, October 2024).
+
+The gunicorn code has been integrated into Plain and modified for Plain's
+specific use case. All files should be considered modified from the original.
+
+Original repository: https://github.com/benoitc/gunicorn
+
+--------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2009-2024 Benoît Chesneau <benoitc@gunicorn.org>
+Copyright (c) 2009-2015 Paul J. Davis <paul.joseph.davis@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plain/server/README.md

@@ -0,0 +1,155 @@
+# Server
+
+**A production-ready WSGI HTTP server based on gunicorn.**
+
+- [Overview](#overview)
+- [Worker types](#worker-types)
+- [Configuration options](#configuration-options)
+- [Environment variables](#environment-variables)
+- [Signals](#signals)
+- [Using a different WSGI server](#using-a-different-wsgi-server)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+You can run the built-in HTTP server with the `plain server` command.
+
+```bash
+plain server
+```
+
+By default, the server binds to `127.0.0.1:8000` and uses a single worker process. In production, you will typically want to increase the number of workers and optionally enable threading.
+
+```bash
+# Run with 4 worker processes
+plain server --workers 4
+
+# Auto-detect based on available CPUs
+plain server --workers auto
+
+# Run with 2 workers and 4 threads each
+plain server --workers 2 --threads 4
+```
+
+For local development, you can enable auto-reload to restart workers when code changes.
+
+```bash
+plain server --reload
+```
+
+## Worker types
+
+The server automatically selects the worker type based on your configuration.
+
+**Sync workers** handle one request at a time per worker. These are simple and predictable.
+
+```bash
+# Single-threaded (uses sync worker)
+plain server --workers 4
+```
+
+**Threaded workers** handle multiple concurrent requests per worker using a thread pool. These are useful when your application does blocking I/O.
+
+```bash
+# Multi-threaded (uses threaded worker)
+plain server --workers 2 --threads 8
+```
+
+For advanced worker customization, see the [`SyncWorker`](./workers/sync.py#SyncWorker) and [`ThreadWorker`](./workers/thread.py#ThreadWorker) classes.
+
+## Configuration options
+
+All options are available via the command line. Run `plain server --help` to see the full list.
+
+| Option             | Default          | Description                                           |
+| ------------------ | ---------------- | ----------------------------------------------------- |
+| `--bind` / `-b`    | `127.0.0.1:8000` | Address to bind (can be used multiple times)          |
+| `--workers` / `-w` | `1`              | Number of worker processes (or `auto` for CPU count)  |
+| `--threads`        | `1`              | Number of threads per worker                          |
+| `--timeout` / `-t` | `30`             | Worker timeout in seconds                             |
+| `--reload`         | `False`          | Restart workers when code changes                     |
+| `--certfile`       | -                | Path to SSL certificate file                          |
+| `--keyfile`        | -                | Path to SSL key file                                  |
+| `--log-level`      | `info`           | Logging level (debug, info, warning, error, critical) |
+| `--access-log`     | `-` (stdout)     | Access log file path                                  |
+| `--error-log`      | `-` (stderr)     | Error log file path                                   |
+| `--max-requests`   | `0` (disabled)   | Max requests before worker restart                    |
+| `--pidfile`        | -                | PID file path                                         |
+
+## Environment variables
+
+| Variable              | Description                                                              |
+| --------------------- | ------------------------------------------------------------------------ |
+| `WEB_CONCURRENCY`     | Sets the number of workers (use `auto` to detect CPU cores, or a number) |
+| `SENDFILE`            | Enable sendfile() syscall (`1`, `yes`, `true`, or `y` to enable)         |
+| `FORWARDED_ALLOW_IPS` | Comma-separated list of trusted proxy IPs (default: `127.0.0.1,::1`)     |
+
+## Signals
+
+The server responds to UNIX signals for process management.
+
+| Signal    | Effect                           |
+| --------- | -------------------------------- |
+| `SIGTERM` | Graceful shutdown                |
+| `SIGINT`  | Quick shutdown                   |
+| `SIGQUIT` | Quick shutdown                   |
+| `SIGHUP`  | Reload configuration and workers |
+| `SIGTTIN` | Increase worker count by 1       |
+| `SIGTTOU` | Decrease worker count by 1       |
+| `SIGUSR1` | Reopen log files                 |
+
+## Using a different WSGI server
+
+You can use any WSGI-compatible server instead of the built-in one. Plain provides a standard WSGI application interface at `plain.wsgi:app`.
+
+```bash
+# Using uvicorn
+uvicorn plain.wsgi:app --port 8000
+
+# Using waitress
+waitress-serve --port=8000 plain.wsgi:app
+
+# Using gunicorn directly
+gunicorn plain.wsgi:app --workers 4
+```
+
+## FAQs
+
+#### How do I run with SSL/TLS?
+
+Provide both `--certfile` and `--keyfile` options pointing to your certificate and key files.
+
+```bash
+plain server --certfile cert.pem --keyfile key.pem
+```
+
+#### How do I run behind a reverse proxy?
+
+Configure your proxy to pass the appropriate headers, then set `FORWARDED_ALLOW_IPS` to include your proxy's IP address.
+
+```bash
+FORWARDED_ALLOW_IPS="10.0.0.1,10.0.0.2" plain server --bind 0.0.0.0:8000
+```
+
+The server recognizes `X-Forwarded-Proto`, `X-Forwarded-Protocol`, and `X-Forwarded-SSL` headers from trusted proxies.
+
+#### How do I handle worker timeouts?
+
+If workers are being killed due to timeouts, increase the `--timeout` value. This is common when handling long-running requests.
+
+```bash
+plain server --timeout 120
+```
+
+#### How do I rotate log files?
+
+Send `SIGUSR1` to the master process to reopen log files. This works with tools like `logrotate`.
+
+```bash
+kill -USR1 $(cat /path/to/pidfile)
+```
+
+## Installation
+
+The server module is included with Plain. No additional installation is required.

plain/server/__init__.py

@@ -0,0 +1,9 @@
+#
+# This file is part of gunicorn released under the MIT license.
+# See the LICENSE for more information.
+#
+# Vendored and modified for Plain.
+
+from .app import ServerApplication
+
+__all__ = ["ServerApplication"]

plain/server/app.py

@@ -0,0 +1,52 @@
+#
+#
+# This file is part of gunicorn released under the MIT license.
+# See the LICENSE for more information.
+#
+# Vendored and modified for Plain.
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+from .arbiter import Arbiter
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class ServerApplication:
+    """
+    Plain's server application.
+
+    This class provides the interface for running the WSGI server.
+    """
+
+    def __init__(self, cfg: Config) -> None:
+        self.cfg: Config = cfg
+        self.callable: Any = None
+
+    def load(self) -> Any:
+        """Load the WSGI application."""
+        # Import locally to avoid circular dependencies and allow
+        # the WSGI module to handle Plain runtime setup
+        from plain.wsgi import app
+
+        return app
+
+    def wsgi(self) -> Any:
+        """Get the WSGI application."""
+        if self.callable is None:
+            self.callable = self.load()
+        return self.callable
+
+    def run(self) -> None:
+        """Run the server."""
+
+        try:
+            Arbiter(self).run()
+        except RuntimeError as e:
+            print(f"\nError: {e}\n", file=sys.stderr)
+            sys.stderr.flush()
+            sys.exit(1)