plain 0.4.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

plain/runtime/user_settings.py

@@ -1,13 +1,5 @@
-"""
-Settings and configuration for Plain.
-
-Read values from the module specified by the PLAIN_SETTINGS_MODULE environment
-variable, and then from plain.global_settings; see the global_settings.py
-for a list of all possible variables.
-"""
 import importlib
 import json
-import logging
 import os
 import time
 import types
@@ -16,106 +8,256 @@ from pathlib import Path
 
 from plain.exceptions import ImproperlyConfigured
 from plain.packages import PackageConfig
-from plain.utils.functional import LazyObject, empty
 
 ENVIRONMENT_VARIABLE = "PLAIN_SETTINGS_MODULE"
 ENV_SETTINGS_PREFIX = "PLAIN_"
-
-logger = logging.getLogger("plain.runtime")
+CUSTOM_SETTINGS_PREFIX = "APP_"
 
 
-class SettingsReference(str):
+class Settings:
     """
-    String subclass which references a current settings value. It's treated as
-    the value in memory but serializes to a settings.NAME attribute reference.
+    Settings and configuration for Plain.
+
+    This class handles loading settings from the module specified by the
+    PLAIN_SETTINGS_MODULE environment variable, as well as from default settings,
+    environment variables, and explicit settings in the settings module.
+
+    Lazy initialization is implemented to defer loading until settings are first accessed.
     """
 
-    def __new__(self, value, setting_name):
-        return str.__new__(self, value)
+    def __init__(self, settings_module=None):
+        self._settings_module = settings_module
+        self._settings = {}
+        self._errors = []  # Collect configuration errors
+        self.configured = False
 
-    def __init__(self, value, setting_name):
-        self.setting_name = setting_name
+    def _setup(self):
+        if self.configured:
+            return
+        else:
+            self.configured = True
 
+        self._settings = {}  # Maps setting names to SettingDefinition instances
 
-class LazySettings(LazyObject):
-    """
-    A lazy proxy for either global Plain settings or a custom settings object.
-    The user can manually configure settings prior to using them. Otherwise,
-    Plain uses the settings module pointed to by PLAIN_SETTINGS_MODULE.
-    """
+        # Determine the settings module
+        if self._settings_module is None:
+            self._settings_module = os.environ.get(ENVIRONMENT_VARIABLE, "app.settings")
+
+        # First load the global settings from plain
+        self._load_module_settings(
+            importlib.import_module("plain.runtime.global_settings")
+        )
 
-    def _setup(self, name=None):
-        """
-        Load the settings module pointed to by the environment variable. This
-        is used the first time settings are needed, if the user hasn't
-        configured settings manually.
-        """
-        settings_module = os.environ.get(ENVIRONMENT_VARIABLE, "settings")
-        self._wrapped = Settings(settings_module)
+        # Import the user's settings module
+        try:
+            mod = importlib.import_module(self._settings_module)
+        except ImportError as e:
+            raise ImproperlyConfigured(
+                f"Could not import settings '{self._settings_module}': {e}"
+            )
 
-    def __repr__(self):
-        # Hardcode the class name as otherwise it yields 'Settings'.
-        if self._wrapped is empty:
-            return "<LazySettings [Unevaluated]>"
-        return f'<LazySettings "{self._wrapped.SETTINGS_MODULE}">'
+        # Keep a reference to the settings.py module path
+        self.path = Path(mod.__file__).resolve()
+
+        # Load default settings from installed packages
+        self._load_default_settings(mod)
+        # Load environment settings
+        self._load_env_settings()
+        # Load explicit settings from the settings module
+        self._load_explicit_settings(mod)
+        # Check for any required settings that are missing
+        self._check_required_settings()
+        # Check for any collected errors
+        self._raise_errors_if_any()
+
+    def _load_module_settings(self, module):
+        annotations = getattr(module, "__annotations__", {})
+        settings = dir(module)
+
+        for setting in settings:
+            if setting.isupper():
+                if setting in self._settings:
+                    self._errors.append(f"Duplicate setting '{setting}'.")
+                    continue
+
+                setting_value = getattr(module, setting)
+                self._settings[setting] = SettingDefinition(
+                    name=setting,
+                    default_value=setting_value,
+                    annotation=annotations.get(setting, None),
+                    module=module,
+                )
+
+        # Store any annotations that didn't have a value (these are required settings)
+        for setting, annotation in annotations.items():
+            if setting not in self._settings:
+                self._settings[setting] = SettingDefinition(
+                    name=setting,
+                    default_value=None,
+                    annotation=annotation,
+                    module=module,
+                    required=True,
+                )
+
+    def _load_default_settings(self, settings_module):
+        for entry in getattr(settings_module, "INSTALLED_PACKAGES", []):
+            try:
+                if isinstance(entry, PackageConfig):
+                    app_settings = entry.module.default_settings
+                else:
+                    app_settings = importlib.import_module(f"{entry}.default_settings")
+            except ModuleNotFoundError:
+                continue
+
+            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():
+            if setting in self._settings:
+                setting_def = self._settings[setting]
+                try:
+                    parsed_value = _parse_env_value(value, setting_def.annotation)
+                    setting_def.set_value(parsed_value, "env")
+                except ImproperlyConfigured as e:
+                    self._errors.append(str(e))
+
+    def _load_explicit_settings(self, settings_module):
+        for setting in dir(settings_module):
+            if setting.isupper():
+                setting_value = getattr(settings_module, setting)
+
+                if setting in self._settings:
+                    setting_def = self._settings[setting]
+                    try:
+                        setting_def.set_value(setting_value, "explicit")
+                    except ImproperlyConfigured as e:
+                        self._errors.append(str(e))
+                        continue
+
+                elif setting.startswith(CUSTOM_SETTINGS_PREFIX):
+                    # Accept custom settings prefixed with '{CUSTOM_SETTINGS_PREFIX}'
+                    setting_def = SettingDefinition(
+                        name=setting,
+                        default_value=None,
+                        annotation=None,
+                        required=False,
+                    )
+                    try:
+                        setting_def.set_value(setting_value, "explicit")
+                    except ImproperlyConfigured as e:
+                        self._errors.append(str(e))
+                        continue
+                    self._settings[setting] = setting_def
+                else:
+                    # Collect unrecognized settings individually
+                    self._errors.append(
+                        f"Unknown setting '{setting}'. Custom settings must start with '{CUSTOM_SETTINGS_PREFIX}'."
+                    )
+
+        if hasattr(time, "tzset") and self.TIME_ZONE:
+            zoneinfo_root = Path("/usr/share/zoneinfo")
+            zone_info_file = zoneinfo_root.joinpath(*self.TIME_ZONE.split("/"))
+            if zoneinfo_root.exists() and not zone_info_file.exists():
+                self._errors.append(
+                    f"Invalid TIME_ZONE setting '{self.TIME_ZONE}'. Timezone file not found."
+                )
+            else:
+                os.environ["TZ"] = self.TIME_ZONE
+                time.tzset()
+
+    def _check_required_settings(self):
+        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):
+        if self._errors:
+            errors = ["- " + e for e in self._errors]
+            raise ImproperlyConfigured(
+                "Settings configuration errors:\n" + "\n".join(errors)
+            )
 
     def __getattr__(self, name):
-        """Return the value of a setting and cache it in self.__dict__."""
-        if (_wrapped := self._wrapped) is empty:
-            self._setup(name)
-            _wrapped = self._wrapped
-        val = getattr(_wrapped, name)
+        # Avoid recursion by directly returning internal attributes
+        if not name.isupper():
+            return object.__getattribute__(self, name)
 
-        # Special case some settings which require further modification.
-        # This is done here for performance reasons so the modified value is cached.
-        if name == "SECRET_KEY" and not val:
-            raise ImproperlyConfigured("The SECRET_KEY setting must not be empty.")
+        self._setup()
 
-        self.__dict__[name] = val
-        return val
+        if name in self._settings:
+            return self._settings[name].value
+        else:
+            raise AttributeError(f"'Settings' object has no attribute '{name}'")
 
     def __setattr__(self, name, value):
-        """
-        Set the value of setting. Clear all cached values if _wrapped changes
-        (@override_settings does this) or clear single values when set.
-        """
-        if name == "_wrapped":
-            self.__dict__.clear()
+        # Handle internal attributes without recursion
+        if not name.isupper():
+            object.__setattr__(self, name, value)
         else:
-            self.__dict__.pop(name, None)
-        super().__setattr__(name, value)
-
-    def __delattr__(self, name):
-        """Delete a setting and clear it from cache if needed."""
-        super().__delattr__(name)
-        self.__dict__.pop(name, None)
+            if name in self._settings:
+                self._settings[name].set_value(value, "runtime")
+                self._raise_errors_if_any()
+            else:
+                object.__setattr__(self, name, value)
 
-    @property
-    def configured(self):
-        """Return True if the settings have already been configured."""
-        return self._wrapped is not empty
+    def __repr__(self):
+        if not self.configured:
+            return "<Settings [Unevaluated]>"
+        return f'<Settings "{self._settings_module}">'
+
+
+def _parse_env_value(value, annotation):
+    if not annotation:
+        raise ImproperlyConfigured("Type hint required to set from environment.")
+
+    if annotation is bool:
+        # Special case for bools
+        return value.lower() in ("true", "1", "yes")
+    elif annotation is str:
+        return value
+    else:
+        # Parse other types using JSON
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as e:
+            raise ImproperlyConfigured(
+                f"Invalid JSON value for setting: {e.msg}"
+            ) from e
 
 
 class SettingDefinition:
-    """Store some basic info about default settings and where they came from"""
+    """Store detailed information about settings."""
 
-    def __init__(self, name, value, annotation, module, required=False):
+    def __init__(
+        self, name, default_value=None, annotation=None, module=None, required=False
+    ):
         self.name = name
-        self.value = value
+        self.default_value = default_value
         self.annotation = annotation
         self.module = module
         self.required = required
+        self.value = default_value
+        self.source = "default"  # 'default', 'env', 'explicit', or 'runtime'
+        self.is_set = False  # Indicates if the value was set explicitly
 
-    def __str__(self):
-        return self.name
+    def set_value(self, value, source):
+        self.check_type(value)
+        self.value = value
+        self.source = source
+        self.is_set = True
 
     def check_type(self, obj):
         if not self.annotation:
             return
 
         if not SettingDefinition._is_instance_of_type(obj, self.annotation):
-            raise ValueError(
-                f"The {self.name} setting must be of type {self.annotation}"
+            raise ImproperlyConfigured(
+                f"'{self.name}': Expected type {self.annotation}, but got {type(obj)}."
             )
 
     @staticmethod
@@ -152,153 +294,20 @@ class SettingDefinition:
                 for i, item in enumerate(value)
             )
 
-        raise ValueError("Unsupported type hint: %s" % type_hint)
-
-
-class Settings:
-    def __init__(self, settings_module):
-        self._default_settings = {}
-        self._explicit_settings = set()
-
-        # First load the global settings from plain
-        self._load_module_settings(
-            importlib.import_module("plain.runtime.global_settings")
-        )
-
-        # store the settings module in case someone later cares
-        self.SETTINGS_MODULE = settings_module
-
-        mod = importlib.import_module(self.SETTINGS_MODULE)
-
-        # Keep a reference to the settings.py module path
-        # so we can find files next to it (assume it's at the app root)
-        self.path = Path(mod.__file__).resolve()
-
-        # First, get all the default_settings from the INSTALLED_PACKAGES and set those values
-        self._load_default_settings(mod)
-        # Second, look at the environment variables and overwrite with those
-        self._load_env_settings()
-        # Finally, load the explicit settings from the settings module
-        self._load_explicit_settings(mod)
-        # Check for any required settings that are missing
-        self._check_required_settings()
-
-    def _load_default_settings(self, settings_module):
-        # Get INSTALLED_PACKAGES from mod,
-        # then (without populating packages) do a check for default_settings in each
-        # app and load those now too.
-        for entry in getattr(settings_module, "INSTALLED_PACKAGES", []):
-            try:
-                if isinstance(entry, PackageConfig):
-                    app_settings = entry.module.default_settings
-                else:
-                    app_settings = importlib.import_module(f"{entry}.default_settings")
-            except ModuleNotFoundError:
-                continue
-
-            self._load_module_settings(app_settings)
-
-    def _load_module_settings(self, module):
-        annotations = getattr(module, "__annotations__", {})
-        settings = dir(module)
-
-        for setting in settings:
-            if setting.isupper():
-                if hasattr(self, setting):
-                    raise ImproperlyConfigured("The %s setting is duplicated" % setting)
+        raise ValueError(f"Unsupported type hint: {type_hint}")
 
-                setting_value = getattr(module, setting)
-
-                # Set a simple attr on the settings object
-                setattr(self, setting, setting_value)
-
-                # Store a more complex setting reference for more detail
-                self._default_settings[setting] = SettingDefinition(
-                    name=setting,
-                    value=setting_value,
-                    annotation=annotations.get(setting, ""),
-                    module=module,
-                )
-
-        # Store any annotations that didn't have a value (these are required settings)
-        for setting, annotation in annotations.items():
-            if setting not in self._default_settings:
-                self._default_settings[setting] = SettingDefinition(
-                    name=setting,
-                    value=None,
-                    annotation=annotation,
-                    module=module,
-                    required=True,
-                )
-
-    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)
-        }
-        logger.debug("Loading environment settings: %s", env_settings)
-        for setting, value in env_settings.items():
-            if setting not in self._default_settings:
-                # Ignore anything not defined in the default settings
-                continue
-
-            default_setting = self._default_settings[setting]
-            if not default_setting.annotation:
-                raise ValueError(
-                    f"Setting {setting} needs a type hint to be set from the environment"
-                )
-
-            if default_setting.annotation is bool:
-                # Special case for bools
-                parsed_value = value.lower() in ("true", "1", "yes")
-            elif default_setting.annotation is str:
-                parsed_value = value
-            else:
-                # Anything besides a string will be parsed as JSON
-                # (works for ints, lists, etc.)
-                parsed_value = json.loads(value)
-
-            default_setting.check_type(parsed_value)
-
-            setattr(self, setting, parsed_value)
-            self._explicit_settings.add(setting)
-
-    def _load_explicit_settings(self, settings_module):
-        for setting in dir(settings_module):
-            if setting.isupper():
-                setting_value = getattr(settings_module, setting)
-
-                if setting in self._default_settings:
-                    self._default_settings[setting].check_type(setting_value)
-
-                setattr(self, setting, setting_value)
-                self._explicit_settings.add(setting)
+    def __str__(self):
+        return f"SettingDefinition(name={self.name}, value={self.value}, source={self.source})"
 
-        if hasattr(time, "tzset") and self.TIME_ZONE:
-            # When we can, attempt to validate the timezone. If we can't find
-            # this file, no check happens and it's harmless.
-            zoneinfo_root = Path("/usr/share/zoneinfo")
-            zone_info_file = zoneinfo_root.joinpath(*self.TIME_ZONE.split("/"))
-            if zoneinfo_root.exists() and not zone_info_file.exists():
-                raise ValueError("Incorrect timezone setting: %s" % self.TIME_ZONE)
-            # Move the time zone info into os.environ. See ticket #2315 for why
-            # we don't do this unconditionally (breaks Windows).
-            os.environ["TZ"] = self.TIME_ZONE
-            time.tzset()
 
-    def _check_required_settings(self):
-        # Required settings have to be explicitly defined (there is no default)
-        # so we can check whether they have been set by the user
-        required_settings = {k for k, v in self._default_settings.items() if v.required}
-        if missing := required_settings - self._explicit_settings:
-            raise ImproperlyConfigured(
-                "The following settings are required: %s" % ", ".join(missing)
-            )
+class SettingsReference(str):
+    """
+    String subclass which references a current settings value. It's treated as
+    the value in memory but serializes to a settings.NAME attribute reference.
+    """
 
-    # Seems like this could almost be removed
-    def is_overridden(self, setting):
-        return setting in self._explicit_settings
+    def __new__(self, value, setting_name):
+        return str.__new__(self, value)
 
-    def __repr__(self):
-        return f'<{self.__class__.__name__} "{self.SETTINGS_MODULE}">'
+    def __init__(self, value, setting_name):
+        self.setting_name = setting_name

plain/signing.py

@@ -37,12 +37,10 @@ import base64
 import datetime
 import json
 import time
-import warnings
 import zlib
 
 from plain.runtime import settings
 from plain.utils.crypto import constant_time_compare, salted_hmac
-from plain.utils.deprecation import RemovedInDjango51Warning
 from plain.utils.encoding import force_bytes
 from plain.utils.module_loading import import_string
 from plain.utils.regex_helper import _lazy_re_compile
@@ -109,7 +107,7 @@ def _cookie_signer_key(key):
 
 
 def get_cookie_signer(salt="plain.signing.get_cookie_signer"):
-    Signer = import_string(settings.SIGNING_BACKEND)
+    Signer = import_string(settings.COOKIE_SIGNING_BACKEND)
     return Signer(
         key=_cookie_signer_key(settings.SECRET_KEY),
         fallback_keys=map(_cookie_signer_key, settings.SECRET_KEY_FALLBACKS),
@@ -177,17 +175,13 @@ def loads(
 
 
 class Signer:
-    # RemovedInDjango51Warning: When the deprecation ends, replace with:
-    # def __init__(
-    #   self, *, key=None, sep=":", salt=None, algorithm=None, fallback_keys=None
-    # ):
     def __init__(
         self,
-        *args,
+        *,
         key=None,
         sep=":",
         salt=None,
-        algorithm=None,
+        algorithm="sha256",
         fallback_keys=None,
     ):
         self.key = key or settings.SECRET_KEY
@@ -198,20 +192,8 @@ class Signer:
         )
         self.sep = sep
         self.salt = salt or f"{self.__class__.__module__}.{self.__class__.__name__}"
-        self.algorithm = algorithm or "sha256"
-        # RemovedInDjango51Warning.
-        if args:
-            warnings.warn(
-                f"Passing positional arguments to {self.__class__.__name__} is "
-                f"deprecated.",
-                RemovedInDjango51Warning,
-                stacklevel=2,
-            )
-            for arg, attr in zip(
-                args, ["key", "sep", "salt", "algorithm", "fallback_keys"]
-            ):
-                if arg or attr == "sep":
-                    setattr(self, attr, arg)
+        self.algorithm = algorithm
+
         if _SEP_UNSAFE.match(self.sep):
             raise ValueError(
                 "Unsafe Signer separator: %r (cannot be empty or consist of "