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

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,24 +11,35 @@ 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.
-# "*" matches anything, ".example.com" matches example.com and all subdomains
-# "192.168.1.0/24" matches IP addresses in that CIDR range
-ALLOWED_HOSTS: list[str]
+# - An empty list [] allows all hosts (useful for development).
+# - ".example.com" matches example.com and all subdomains
+# - "192.168.1.0/24" matches IP addresses in that CIDR range
+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",
@@ -46,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
 
@@ -96,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
@@ -112,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
@@ -134,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
 
@@ -151,11 +161,11 @@ ASSETS_BASE_URL: str = ""
 
 # MARK: Preflight Checks
 
-# List of all issues generated by system checks that should be silenced. Light
-# issues like warnings, infos or debugs will not generate a message. Silencing
-# serious issues like errors and criticals does not result in hiding the
-# message, but Plain will not stop you from e.g. running server.
-PREFLIGHT_SILENCED_CHECKS = []
+# Silence checks by name
+PREFLIGHT_SILENCED_CHECKS: list[str] = []
+
+# Silence specific check results by id
+PREFLIGHT_SILENCED_RESULTS: list[str] = []
 
 # MARK: Templates
 

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

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.