plain 0.1.0__py3-none-any.whl

plain/paginator.py

@@ -0,0 +1,187 @@
+import collections.abc
+import inspect
+import warnings
+from math import ceil
+
+from plain.utils.functional import cached_property
+from plain.utils.inspect import method_has_no_args
+
+
+class UnorderedObjectListWarning(RuntimeWarning):
+    pass
+
+
+class InvalidPage(Exception):
+    pass
+
+
+class PageNotAnInteger(InvalidPage):
+    pass
+
+
+class EmptyPage(InvalidPage):
+    pass
+
+
+class Paginator:
+    # Translators: String used to replace omitted page numbers in elided page
+    # range generated by paginators, e.g. [1, 2, '…', 5, 6, 7, '…', 9, 10].
+    ELLIPSIS = "…"
+
+    def __init__(self, object_list, per_page, orphans=0, allow_empty_first_page=True):
+        self.object_list = object_list
+        self._check_object_list_is_ordered()
+        self.per_page = int(per_page)
+        self.orphans = int(orphans)
+        self.allow_empty_first_page = allow_empty_first_page
+
+    def __iter__(self):
+        for page_number in self.page_range:
+            yield self.page(page_number)
+
+    def validate_number(self, number):
+        """Validate the given 1-based page number."""
+        try:
+            if isinstance(number, float) and not number.is_integer():
+                raise ValueError
+            number = int(number)
+        except (TypeError, ValueError):
+            raise PageNotAnInteger("That page number is not an integer")
+        if number < 1:
+            raise EmptyPage("That page number is less than 1")
+        if number > self.num_pages:
+            raise EmptyPage("That page contains no results")
+        return number
+
+    def get_page(self, number):
+        """
+        Return a valid page, even if the page argument isn't a number or isn't
+        in range.
+        """
+        try:
+            number = self.validate_number(number)
+        except PageNotAnInteger:
+            number = 1
+        except EmptyPage:
+            number = self.num_pages
+        return self.page(number)
+
+    def page(self, number):
+        """Return a Page object for the given 1-based page number."""
+        number = self.validate_number(number)
+        bottom = (number - 1) * self.per_page
+        top = bottom + self.per_page
+        if top + self.orphans >= self.count:
+            top = self.count
+        return self._get_page(self.object_list[bottom:top], number, self)
+
+    def _get_page(self, *args, **kwargs):
+        """
+        Return an instance of a single page.
+
+        This hook can be used by subclasses to use an alternative to the
+        standard :cls:`Page` object.
+        """
+        return Page(*args, **kwargs)
+
+    @cached_property
+    def count(self):
+        """Return the total number of objects, across all pages."""
+        c = getattr(self.object_list, "count", None)
+        if callable(c) and not inspect.isbuiltin(c) and method_has_no_args(c):
+            return c()
+        return len(self.object_list)
+
+    @cached_property
+    def num_pages(self):
+        """Return the total number of pages."""
+        if self.count == 0 and not self.allow_empty_first_page:
+            return 0
+        hits = max(1, self.count - self.orphans)
+        return ceil(hits / self.per_page)
+
+    @property
+    def page_range(self):
+        """
+        Return a 1-based range of pages for iterating through within
+        a template for loop.
+        """
+        return range(1, self.num_pages + 1)
+
+    def _check_object_list_is_ordered(self):
+        """
+        Warn if self.object_list is unordered (typically a QuerySet).
+        """
+        ordered = getattr(self.object_list, "ordered", None)
+        if ordered is not None and not ordered:
+            obj_list_repr = (
+                f"{self.object_list.model} {self.object_list.__class__.__name__}"
+                if hasattr(self.object_list, "model")
+                else f"{self.object_list!r}"
+            )
+            warnings.warn(
+                "Pagination may yield inconsistent results with an unordered "
+                f"object_list: {obj_list_repr}.",
+                UnorderedObjectListWarning,
+                stacklevel=3,
+            )
+
+
+class Page(collections.abc.Sequence):
+    def __init__(self, object_list, number, paginator):
+        self.object_list = object_list
+        self.number = number
+        self.paginator = paginator
+
+    def __repr__(self):
+        return f"<Page {self.number} of {self.paginator.num_pages}>"
+
+    def __len__(self):
+        return len(self.object_list)
+
+    def __getitem__(self, index):
+        if not isinstance(index, int | slice):
+            raise TypeError(
+                "Page indices must be integers or slices, not %s."
+                % type(index).__name__
+            )
+        # The object_list is converted to a list so that if it was a QuerySet
+        # it won't be a database hit per __getitem__.
+        if not isinstance(self.object_list, list):
+            self.object_list = list(self.object_list)
+        return self.object_list[index]
+
+    def has_next(self):
+        return self.number < self.paginator.num_pages
+
+    def has_previous(self):
+        return self.number > 1
+
+    def has_other_pages(self):
+        return self.has_previous() or self.has_next()
+
+    def next_page_number(self):
+        return self.paginator.validate_number(self.number + 1)
+
+    def previous_page_number(self):
+        return self.paginator.validate_number(self.number - 1)
+
+    def start_index(self):
+        """
+        Return the 1-based index of the first object on this page,
+        relative to total objects in the paginator.
+        """
+        # Special case, return zero if no items.
+        if self.paginator.count == 0:
+            return 0
+        return (self.paginator.per_page * (self.number - 1)) + 1
+
+    def end_index(self):
+        """
+        Return the 1-based index of the last object on this page,
+        relative to total objects found (hits).
+        """
+        # Special case for the last page because there can be orphans.
+        if self.number == self.paginator.num_pages:
+            return self.paginator.count
+        return self.number * self.paginator.per_page

plain/preflight/README.md

@@ -0,0 +1,3 @@
+# Checks
+
+Static system checks to catch misconfigurations.

plain/preflight/__init__.py

@@ -0,0 +1,38 @@
+from .messages import (
+    CRITICAL,
+    DEBUG,
+    ERROR,
+    INFO,
+    WARNING,
+    CheckMessage,
+    Critical,
+    Debug,
+    Error,
+    Info,
+    Warning,
+)
+from .registry import register, run_checks
+
+# Import these to force registration of checks
+import plain.preflight.compatibility.django_4_0  # NOQA isort:skip
+import plain.preflight.files  # NOQA isort:skip
+import plain.preflight.security.base  # NOQA isort:skip
+import plain.preflight.security.csrf  # NOQA isort:skip
+import plain.preflight.urls  # NOQA isort:skip
+
+
+__all__ = [
+    "CheckMessage",
+    "Debug",
+    "Info",
+    "Warning",
+    "Error",
+    "Critical",
+    "DEBUG",
+    "INFO",
+    "WARNING",
+    "ERROR",
+    "CRITICAL",
+    "register",
+    "run_checks",
+]

plain/preflight/compatibility/django_4_0.py

@@ -0,0 +1,20 @@
+from plain.runtime import settings
+
+from .. import Error, register
+
+
+@register
+def check_csrf_trusted_origins(package_configs, **kwargs):
+    errors = []
+    for origin in settings.CSRF_TRUSTED_ORIGINS:
+        if "://" not in origin:
+            errors.append(
+                Error(
+                    "As of Plain 4.0, the values in the CSRF_TRUSTED_ORIGINS "
+                    "setting must start with a scheme (usually http:// or "
+                    "https://) but found %s. See the release notes for details."
+                    % origin,
+                    id="4_0.E001",
+                )
+            )
+    return errors

plain/preflight/files.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from plain.runtime import settings
+
+from . import Error, register
+
+
+@register
+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 []

plain/preflight/messages.py

@@ -0,0 +1,88 @@
+# Levels
+DEBUG = 10
+INFO = 20
+WARNING = 30
+ERROR = 40
+CRITICAL = 50
+
+
+class CheckMessage:
+    def __init__(self, level, msg, hint=None, obj=None, id=None):
+        if not isinstance(level, int):
+            raise TypeError("The first argument should be level.")
+        self.level = level
+        self.msg = msg
+        self.hint = hint
+        self.obj = obj
+        self.id = id
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and all(
+            getattr(self, attr) == getattr(other, attr)
+            for attr in ["level", "msg", "hint", "obj", "id"]
+        )
+
+    def __str__(self):
+        try:
+            from plain import models
+
+            ModelBase = models.base.ModelBase
+            using_db = True
+        except ImportError:
+            using_db = False
+            ModelBase = object
+
+        if self.obj is None:
+            obj = "?"
+        elif using_db and isinstance(self.obj, ModelBase):
+            # We need to hardcode ModelBase and Field cases because its __str__
+            # method doesn't return "applabel.modellabel" and cannot be changed.
+            obj = self.obj._meta.label
+        else:
+            obj = str(self.obj)
+        id = "(%s) " % self.id if self.id else ""
+        hint = "\n\tHINT: %s" % self.hint if self.hint else ""
+        return f"{obj}: {id}{self.msg}{hint}"
+
+    def __repr__(self):
+        return "<{}: level={!r}, msg={!r}, hint={!r}, obj={!r}, id={!r}>".format(
+            self.__class__.__name__,
+            self.level,
+            self.msg,
+            self.hint,
+            self.obj,
+            self.id,
+        )
+
+    def is_serious(self, level=ERROR):
+        return self.level >= level
+
+    def is_silenced(self):
+        from plain.runtime import settings
+
+        return self.id in settings.SILENCED_PREFLIGHT_CHECKS
+
+
+class Debug(CheckMessage):
+    def __init__(self, *args, **kwargs):
+        super().__init__(DEBUG, *args, **kwargs)
+
+
+class Info(CheckMessage):
+    def __init__(self, *args, **kwargs):
+        super().__init__(INFO, *args, **kwargs)
+
+
+class Warning(CheckMessage):
+    def __init__(self, *args, **kwargs):
+        super().__init__(WARNING, *args, **kwargs)
+
+
+class Error(CheckMessage):
+    def __init__(self, *args, **kwargs):
+        super().__init__(ERROR, *args, **kwargs)
+
+
+class Critical(CheckMessage):
+    def __init__(self, *args, **kwargs):
+        super().__init__(CRITICAL, *args, **kwargs)

plain/preflight/registry.py

@@ -0,0 +1,72 @@
+from plain.utils.inspect import func_accepts_kwargs
+from plain.utils.itercompat import is_iterable
+
+
+class CheckRegistry:
+    def __init__(self):
+        self.registered_checks = set()
+        self.deployment_checks = set()
+
+    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')
+        """
+
+        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
+
+        if callable(check):
+            return inner(check)
+        else:
+            return inner
+
+    def run_checks(
+        self,
+        package_configs=None,
+        include_deployment_checks=False,
+        databases=None,
+    ):
+        """
+        Run all registered checks and return list of Errors and Warnings.
+        """
+        errors = []
+        checks = self.get_checks(include_deployment_checks)
+
+        for check in checks:
+            new_errors = check(package_configs=package_configs, databases=databases)
+            if not is_iterable(new_errors):
+                raise TypeError(
+                    "The function %r did not return a list. All functions "
+                    "registered with the checks registry must return a list." % check,
+                )
+            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
+
+
+registry = CheckRegistry()
+register = registry.register
+run_checks = registry.run_checks

plain/preflight/security/base.py

@@ -0,0 +1,268 @@
+from plain.exceptions import ImproperlyConfigured
+from plain.runtime import settings
+
+from .. import Error, Warning, register
+
+CROSS_ORIGIN_OPENER_POLICY_VALUES = {
+    "same-origin",
+    "same-origin-allow-popups",
+    "unsafe-none",
+}
+REFERRER_POLICY_VALUES = {
+    "no-referrer",
+    "no-referrer-when-downgrade",
+    "origin",
+    "origin-when-cross-origin",
+    "same-origin",
+    "strict-origin",
+    "strict-origin-when-cross-origin",
+    "unsafe-url",
+}
+
+SECRET_KEY_INSECURE_PREFIX = "plain-insecure-"
+SECRET_KEY_MIN_LENGTH = 50
+SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
+
+SECRET_KEY_WARNING_MSG = (
+    f"Your %s has less than {SECRET_KEY_MIN_LENGTH} characters, less than "
+    f"{SECRET_KEY_MIN_UNIQUE_CHARACTERS} unique characters, or it's prefixed "
+    f"with '{SECRET_KEY_INSECURE_PREFIX}' indicating that it was generated "
+    f"automatically by Plain. Please generate a long and random value, "
+    f"otherwise many of Plain's security-critical features will be "
+    f"vulnerable to attack."
+)
+
+W001 = Warning(
+    "You do not have 'plain.middleware.security.SecurityMiddleware' "
+    "in your MIDDLEWARE so the SECURE_HSTS_SECONDS, "
+    "SECURE_CONTENT_TYPE_NOSNIFF, SECURE_REFERRER_POLICY, "
+    "SECURE_CROSS_ORIGIN_OPENER_POLICY, and SECURE_SSL_REDIRECT settings will "
+    "have no effect.",
+    id="security.W001",
+)
+
+W002 = Warning(
+    "You do not have "
+    "'plain.middleware.clickjacking.XFrameOptionsMiddleware' in your "
+    "MIDDLEWARE, so your pages will not be served with an "
+    "'x-frame-options' header. Unless there is a good reason for your "
+    "site to be served in a frame, you should consider enabling this "
+    "header to help prevent clickjacking attacks.",
+    id="security.W002",
+)
+
+W004 = Warning(
+    "You have not set a value for the SECURE_HSTS_SECONDS setting. "
+    "If your entire site is served only over SSL, you may want to consider "
+    "setting a value and enabling HTTP Strict Transport Security. "
+    "Be sure to read the documentation first; enabling HSTS carelessly "
+    "can cause serious, irreversible problems.",
+    id="security.W004",
+)
+
+W005 = Warning(
+    "You have not set the SECURE_HSTS_INCLUDE_SUBDOMAINS setting to True. "
+    "Without this, your site is potentially vulnerable to attack "
+    "via an insecure connection to a subdomain. Only set this to True if "
+    "you are certain that all subdomains of your domain should be served "
+    "exclusively via SSL.",
+    id="security.W005",
+)
+
+W006 = Warning(
+    "Your SECURE_CONTENT_TYPE_NOSNIFF setting is not set to True, "
+    "so your pages will not be served with an "
+    "'X-Content-Type-Options: nosniff' header. "
+    "You should consider enabling this header to prevent the "
+    "browser from identifying content types incorrectly.",
+    id="security.W006",
+)
+
+W008 = Warning(
+    "Your SECURE_SSL_REDIRECT setting is not set to True. "
+    "Unless your site should be available over both SSL and non-SSL "
+    "connections, you may want to either set this setting True "
+    "or configure a load balancer or reverse-proxy server "
+    "to redirect all connections to HTTPS.",
+    id="security.W008",
+)
+
+W009 = Warning(
+    SECRET_KEY_WARNING_MSG % "SECRET_KEY",
+    id="security.W009",
+)
+
+W018 = Warning(
+    "You should not have DEBUG set to True in deployment.",
+    id="security.W018",
+)
+
+W020 = Warning(
+    "ALLOWED_HOSTS must not be empty in deployment.",
+    id="security.W020",
+)
+
+W021 = Warning(
+    "You have not set the SECURE_HSTS_PRELOAD setting to True. Without this, "
+    "your site cannot be submitted to the browser preload list.",
+    id="security.W021",
+)
+
+W022 = Warning(
+    "You have not set the SECURE_REFERRER_POLICY setting. Without this, your "
+    "site will not send a Referrer-Policy header. You should consider "
+    "enabling this header to protect user privacy.",
+    id="security.W022",
+)
+
+E023 = Error(
+    "You have set the SECURE_REFERRER_POLICY setting to an invalid value.",
+    hint="Valid values are: {}.".format(", ".join(sorted(REFERRER_POLICY_VALUES))),
+    id="security.E023",
+)
+
+E024 = Error(
+    "You have set the SECURE_CROSS_ORIGIN_OPENER_POLICY setting to an invalid "
+    "value.",
+    hint="Valid values are: {}.".format(
+        ", ".join(sorted(CROSS_ORIGIN_OPENER_POLICY_VALUES)),
+    ),
+    id="security.E024",
+)
+
+W025 = Warning(SECRET_KEY_WARNING_MSG, id="security.W025")
+
+
+def _security_middleware():
+    return "plain.middleware.security.SecurityMiddleware" in settings.MIDDLEWARE
+
+
+def _xframe_middleware():
+    return (
+        "plain.middleware.clickjacking.XFrameOptionsMiddleware" in settings.MIDDLEWARE
+    )
+
+
+@register(deploy=True)
+def check_security_middleware(package_configs, **kwargs):
+    passed_check = _security_middleware()
+    return [] if passed_check else [W001]
+
+
+@register(deploy=True)
+def check_xframe_options_middleware(package_configs, **kwargs):
+    passed_check = _xframe_middleware()
+    return [] if passed_check else [W002]
+
+
+@register(deploy=True)
+def check_sts(package_configs, **kwargs):
+    passed_check = not _security_middleware() or settings.SECURE_HSTS_SECONDS
+    return [] if passed_check else [W004]
+
+
+@register(deploy=True)
+def check_sts_include_subdomains(package_configs, **kwargs):
+    passed_check = (
+        not _security_middleware()
+        or not settings.SECURE_HSTS_SECONDS
+        or settings.SECURE_HSTS_INCLUDE_SUBDOMAINS is True
+    )
+    return [] if passed_check else [W005]
+
+
+@register(deploy=True)
+def check_sts_preload(package_configs, **kwargs):
+    passed_check = (
+        not _security_middleware()
+        or not settings.SECURE_HSTS_SECONDS
+        or settings.SECURE_HSTS_PRELOAD is True
+    )
+    return [] if passed_check else [W021]
+
+
+@register(deploy=True)
+def check_content_type_nosniff(package_configs, **kwargs):
+    passed_check = (
+        not _security_middleware() or settings.SECURE_CONTENT_TYPE_NOSNIFF is True
+    )
+    return [] if passed_check else [W006]
+
+
+@register(deploy=True)
+def check_ssl_redirect(package_configs, **kwargs):
+    passed_check = not _security_middleware() or settings.SECURE_SSL_REDIRECT is True
+    return [] if passed_check else [W008]
+
+
+def _check_secret_key(secret_key):
+    return (
+        len(set(secret_key)) >= SECRET_KEY_MIN_UNIQUE_CHARACTERS
+        and len(secret_key) >= SECRET_KEY_MIN_LENGTH
+        and not secret_key.startswith(SECRET_KEY_INSECURE_PREFIX)
+    )
+
+
+@register(deploy=True)
+def check_secret_key(package_configs, **kwargs):
+    try:
+        secret_key = settings.SECRET_KEY
+    except (ImproperlyConfigured, AttributeError):
+        passed_check = False
+    else:
+        passed_check = _check_secret_key(secret_key)
+    return [] if passed_check else [W009]
+
+
+@register(deploy=True)
+def check_secret_key_fallbacks(package_configs, **kwargs):
+    warnings = []
+    try:
+        fallbacks = settings.SECRET_KEY_FALLBACKS
+    except (ImproperlyConfigured, AttributeError):
+        warnings.append(Warning(W025.msg % "SECRET_KEY_FALLBACKS", id=W025.id))
+    else:
+        for index, key in enumerate(fallbacks):
+            if not _check_secret_key(key):
+                warnings.append(
+                    Warning(W025.msg % f"SECRET_KEY_FALLBACKS[{index}]", id=W025.id)
+                )
+    return warnings
+
+
+@register(deploy=True)
+def check_debug(package_configs, **kwargs):
+    passed_check = not settings.DEBUG
+    return [] if passed_check else [W018]
+
+
+@register(deploy=True)
+def check_allowed_hosts(package_configs, **kwargs):
+    return [] if settings.ALLOWED_HOSTS else [W020]
+
+
+@register(deploy=True)
+def check_referrer_policy(package_configs, **kwargs):
+    if _security_middleware():
+        if settings.SECURE_REFERRER_POLICY is None:
+            return [W022]
+        # Support a comma-separated string or iterable of values to allow fallback.
+        if isinstance(settings.SECURE_REFERRER_POLICY, str):
+            values = {v.strip() for v in settings.SECURE_REFERRER_POLICY.split(",")}
+        else:
+            values = set(settings.SECURE_REFERRER_POLICY)
+        if not values <= REFERRER_POLICY_VALUES:
+            return [E023]
+    return []
+
+
+@register(deploy=True)
+def check_cross_origin_opener_policy(package_configs, **kwargs):
+    if (
+        _security_middleware()
+        and settings.SECURE_CROSS_ORIGIN_OPENER_POLICY is not None
+        and settings.SECURE_CROSS_ORIGIN_OPENER_POLICY
+        not in CROSS_ORIGIN_OPENER_POLICY_VALUES
+    ):
+        return [E024]
+    return []