plain 0.1.0__py3-none-any.whl

plain/runtime/user_settings.py

@@ -0,0 +1,353 @@
+"""
+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
+import typing
+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")
+
+
+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.
+    """
+
+    def __new__(self, value, setting_name):
+        return str.__new__(self, value)
+
+    def __init__(self, value, setting_name):
+        self.setting_name = setting_name
+
+
+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.
+    """
+
+    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)
+
+    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}">'
+
+    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)
+
+        # 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.__dict__[name] = val
+        return val
+
+    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()
+        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)
+
+    @property
+    def configured(self):
+        """Return True if the settings have already been configured."""
+        return self._wrapped is not empty
+
+
+class SettingDefinition:
+    """Store some basic info about default settings and where they came from"""
+
+    def __init__(self, name, value, annotation, module, required=False):
+        self.name = name
+        self.value = value
+        self.annotation = annotation
+        self.module = module
+        self.required = required
+
+    def __str__(self):
+        return self.name
+
+    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}"
+            )
+
+    @staticmethod
+    def _is_instance_of_type(value, type_hint) -> bool:
+        # Simple types
+        if isinstance(type_hint, type):
+            return isinstance(value, type_hint)
+
+        # Union types
+        if (
+            typing.get_origin(type_hint) is typing.Union
+            or typing.get_origin(type_hint) 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:
+            return isinstance(value, list) and all(
+                SettingDefinition._is_instance_of_type(
+                    item, typing.get_args(type_hint)[0]
+                )
+                for item in value
+            )
+
+        # Tuple types
+        if typing.get_origin(type_hint) is tuple:
+            return isinstance(value, tuple) and all(
+                SettingDefinition._is_instance_of_type(
+                    item, typing.get_args(type_hint)[i]
+                )
+                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)
+
+                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)
+
+        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)
+            )
+
+    # Seems like this could almost be removed
+    def is_overridden(self, setting):
+        return setting in self._explicit_settings
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__} "{self.SETTINGS_MODULE}">'
+
+
+# Currently used for test settings override... nothing else
+class UserSettingsHolder:
+    """Holder for user configured settings."""
+
+    # SETTINGS_MODULE doesn't make much sense in the manually configured
+    # (standalone) case.
+    SETTINGS_MODULE = None
+
+    def __init__(self, default_settings):
+        """
+        Requests for configuration variables not in this class are satisfied
+        from the module specified in default_settings (if possible).
+        """
+        self.__dict__["_deleted"] = set()
+        self.default_settings = default_settings
+
+    def __getattr__(self, name):
+        if not name.isupper() or name in self._deleted:
+            raise AttributeError
+        return getattr(self.default_settings, name)
+
+    def __setattr__(self, name, value):
+        self._deleted.discard(name)
+        super().__setattr__(name, value)
+
+    def __delattr__(self, name):
+        self._deleted.add(name)
+        if hasattr(self, name):
+            super().__delattr__(name)
+
+    def __dir__(self):
+        return sorted(
+            s
+            for s in [*self.__dict__, *dir(self.default_settings)]
+            if s not in self._deleted
+        )
+
+    def is_overridden(self, setting):
+        deleted = setting in self._deleted
+        set_locally = setting in self.__dict__
+        set_on_default = getattr(
+            self.default_settings, "is_overridden", lambda s: False
+        )(setting)
+        return deleted or set_locally or set_on_default
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}>"

plain/signals/README.md

@@ -0,0 +1,14 @@
+# Signals
+
+Run code when certain events happen.
+
+```python
+from plain.signals import request_finished
+
+
+def on_request_finished(sender, **kwargs):
+    print("Request finished!")
+
+
+request_finished.connect(on_request_finished)
+```

plain/signals/__init__.py

@@ -0,0 +1,5 @@
+from plain.signals.dispatch import Signal
+
+request_started = Signal()
+request_finished = Signal()
+got_request_exception = Signal()

plain/signals/dispatch/__init__.py

@@ -0,0 +1,9 @@
+"""Multi-consumer multi-producer dispatching mechanism
+
+Originally based on pydispatch (BSD) https://pypi.org/project/PyDispatcher/2.0.1/
+See license.txt for original license.
+
+Heavily modified for Plain's purposes.
+"""
+
+from plain.signals.dispatch.dispatcher import Signal, receiver  # NOQA

plain/signals/dispatch/dispatcher.py

@@ -0,0 +1,320 @@
+import logging
+import threading
+import weakref
+
+from plain.utils.inspect import func_accepts_kwargs
+
+logger = logging.getLogger("plain.signals.dispatch")
+
+
+def _make_id(target):
+    if hasattr(target, "__func__"):
+        return (id(target.__self__), id(target.__func__))
+    return id(target)
+
+
+NONE_ID = _make_id(None)
+
+# A marker for caching
+NO_RECEIVERS = object()
+
+
+class Signal:
+    """
+    Base class for all signals
+
+    Internal attributes:
+
+        receivers
+            { receiverkey (id) : weakref(receiver) }
+    """
+
+    def __init__(self, use_caching=False):
+        """
+        Create a new signal.
+        """
+        self.receivers = []
+        self.lock = threading.Lock()
+        self.use_caching = use_caching
+        # For convenience we create empty caches even if they are not used.
+        # A note about caching: if use_caching is defined, then for each
+        # distinct sender we cache the receivers that sender has in
+        # 'sender_receivers_cache'. The cache is cleaned when .connect() or
+        # .disconnect() is called and populated on send().
+        self.sender_receivers_cache = weakref.WeakKeyDictionary() if use_caching else {}
+        self._dead_receivers = False
+
+    def connect(self, receiver, sender=None, weak=True, dispatch_uid=None):
+        """
+        Connect receiver to sender for signal.
+
+        Arguments:
+
+            receiver
+                A function or an instance method which is to receive signals.
+                Receivers must be hashable objects. Receivers can be
+                asynchronous.
+
+                If weak is True, then receiver must be weak referenceable.
+
+                Receivers must be able to accept keyword arguments.
+
+                If a receiver is connected with a dispatch_uid argument, it
+                will not be added if another receiver was already connected
+                with that dispatch_uid.
+
+            sender
+                The sender to which the receiver should respond. Must either be
+                a Python object, or None to receive events from any sender.
+
+            weak
+                Whether to use weak references to the receiver. By default, the
+                module will attempt to use weak references to the receiver
+                objects. If this parameter is false, then strong references will
+                be used.
+
+            dispatch_uid
+                An identifier used to uniquely identify a particular instance of
+                a receiver. This will usually be a string, though it may be
+                anything hashable.
+        """
+        from plain.runtime import settings
+
+        # If DEBUG is on, check that we got a good receiver
+        if settings.configured and settings.DEBUG:
+            if not callable(receiver):
+                raise TypeError("Signal receivers must be callable.")
+            # Check for **kwargs
+            if not func_accepts_kwargs(receiver):
+                raise ValueError(
+                    "Signal receivers must accept keyword arguments (**kwargs)."
+                )
+
+        if dispatch_uid:
+            lookup_key = (dispatch_uid, _make_id(sender))
+        else:
+            lookup_key = (_make_id(receiver), _make_id(sender))
+
+        if weak:
+            ref = weakref.ref
+            receiver_object = receiver
+            # Check for bound methods
+            if hasattr(receiver, "__self__") and hasattr(receiver, "__func__"):
+                ref = weakref.WeakMethod
+                receiver_object = receiver.__self__
+            receiver = ref(receiver)
+            weakref.finalize(receiver_object, self._remove_receiver)
+
+        with self.lock:
+            self._clear_dead_receivers()
+            if not any(r_key == lookup_key for r_key, _ in self.receivers):
+                self.receivers.append((lookup_key, receiver))
+            self.sender_receivers_cache.clear()
+
+    def disconnect(self, receiver=None, sender=None, dispatch_uid=None):
+        """
+        Disconnect receiver from sender for signal.
+
+        If weak references are used, disconnect need not be called. The receiver
+        will be removed from dispatch automatically.
+
+        Arguments:
+
+            receiver
+                The registered receiver to disconnect. May be none if
+                dispatch_uid is specified.
+
+            sender
+                The registered sender to disconnect
+
+            dispatch_uid
+                the unique identifier of the receiver to disconnect
+        """
+        if dispatch_uid:
+            lookup_key = (dispatch_uid, _make_id(sender))
+        else:
+            lookup_key = (_make_id(receiver), _make_id(sender))
+
+        disconnected = False
+        with self.lock:
+            self._clear_dead_receivers()
+            for index in range(len(self.receivers)):
+                r_key, *_ = self.receivers[index]
+                if r_key == lookup_key:
+                    disconnected = True
+                    del self.receivers[index]
+                    break
+            self.sender_receivers_cache.clear()
+        return disconnected
+
+    def has_listeners(self, sender=None):
+        sync_receivers = self._live_receivers(sender)
+        return bool(sync_receivers)
+
+    def send(self, sender, **named):
+        """
+        Send signal from sender to all connected receivers.
+
+        If any receiver raises an error, the error propagates back through send,
+        terminating the dispatch loop. So it's possible that all receivers
+        won't be called if an error is raised.
+
+        If any receivers are asynchronous, they are called after all the
+        synchronous receivers via a single call to async_to_sync(). They are
+        also executed concurrently with asyncio.gather().
+
+        Arguments:
+
+            sender
+                The sender of the signal. Either a specific object or None.
+
+            named
+                Named arguments which will be passed to receivers.
+
+        Return a list of tuple pairs [(receiver, response), ... ].
+        """
+        if (
+            not self.receivers
+            or self.sender_receivers_cache.get(sender) is NO_RECEIVERS
+        ):
+            return []
+        responses = []
+        sync_receivers = self._live_receivers(sender)
+        for receiver in sync_receivers:
+            response = receiver(signal=self, sender=sender, **named)
+            responses.append((receiver, response))
+        return responses
+
+    def _log_robust_failure(self, receiver, err):
+        logger.error(
+            "Error calling %s in Signal.send_robust() (%s)",
+            receiver.__qualname__,
+            err,
+            exc_info=err,
+        )
+
+    def send_robust(self, sender, **named):
+        """
+        Send signal from sender to all connected receivers catching errors.
+
+        If any receivers are asynchronous, they are called after all the
+        synchronous receivers via a single call to async_to_sync(). They are
+        also executed concurrently with asyncio.gather().
+
+        Arguments:
+
+            sender
+                The sender of the signal. Can be any Python object (normally one
+                registered with a connect if you actually want something to
+                occur).
+
+            named
+                Named arguments which will be passed to receivers.
+
+        Return a list of tuple pairs [(receiver, response), ... ].
+
+        If any receiver raises an error (specifically any subclass of
+        Exception), return the error instance as the result for that receiver.
+        """
+        if (
+            not self.receivers
+            or self.sender_receivers_cache.get(sender) is NO_RECEIVERS
+        ):
+            return []
+
+        # Call each receiver with whatever arguments it can accept.
+        # Return a list of tuple pairs [(receiver, response), ... ].
+        responses = []
+        sync_receivers = self._live_receivers(sender)
+        for receiver in sync_receivers:
+            try:
+                response = receiver(signal=self, sender=sender, **named)
+            except Exception as err:
+                self._log_robust_failure(receiver, err)
+                responses.append((receiver, err))
+            else:
+                responses.append((receiver, response))
+        return responses
+
+    def _clear_dead_receivers(self):
+        # Note: caller is assumed to hold self.lock.
+        if self._dead_receivers:
+            self._dead_receivers = False
+            self.receivers = [
+                r
+                for r in self.receivers
+                if not (isinstance(r[1], weakref.ReferenceType) and r[1]() is None)
+            ]
+
+    def _live_receivers(self, sender):
+        """
+        Filter sequence of receivers to get resolved, live receivers.
+
+        This checks for weak references and resolves them, then returning only
+        live receivers.
+        """
+        receivers = None
+        if self.use_caching and not self._dead_receivers:
+            receivers = self.sender_receivers_cache.get(sender)
+            # We could end up here with NO_RECEIVERS even if we do check this case in
+            # .send() prior to calling _live_receivers() due to concurrent .send() call.
+            if receivers is NO_RECEIVERS:
+                return []
+        if receivers is None:
+            with self.lock:
+                self._clear_dead_receivers()
+                senderkey = _make_id(sender)
+                receivers = []
+                for (_receiverkey, r_senderkey), receiver in self.receivers:
+                    if r_senderkey == NONE_ID or r_senderkey == senderkey:
+                        receivers.append(receiver)
+                if self.use_caching:
+                    if not receivers:
+                        self.sender_receivers_cache[sender] = NO_RECEIVERS
+                    else:
+                        # Note, we must cache the weakref versions.
+                        self.sender_receivers_cache[sender] = receivers
+        non_weak_sync_receivers = []
+        for receiver in receivers:
+            if isinstance(receiver, weakref.ReferenceType):
+                # Dereference the weak reference.
+                receiver = receiver()
+                if receiver is not None:
+                    non_weak_sync_receivers.append(receiver)
+            else:
+                non_weak_sync_receivers.append(receiver)
+        return non_weak_sync_receivers
+
+    def _remove_receiver(self, receiver=None):
+        # Mark that the self.receivers list has dead weakrefs. If so, we will
+        # clean those up in connect, disconnect and _live_receivers while
+        # holding self.lock. Note that doing the cleanup here isn't a good
+        # idea, _remove_receiver() will be called as side effect of garbage
+        # collection, and so the call can happen while we are already holding
+        # self.lock.
+        self._dead_receivers = True
+
+
+def receiver(signal, **kwargs):
+    """
+    A decorator for connecting receivers to signals. Used by passing in the
+    signal (or list of signals) and keyword arguments to connect::
+
+        @receiver(post_save, sender=MyModel)
+        def signal_receiver(sender, **kwargs):
+            ...
+
+        @receiver([post_save, post_delete], sender=MyModel)
+        def signals_receiver(sender, **kwargs):
+            ...
+    """
+
+    def _decorator(func):
+        if isinstance(signal, list | tuple):
+            for s in signal:
+                s.connect(func, **kwargs)
+        else:
+            signal.connect(func, **kwargs)
+        return func
+
+    return _decorator