plain 0.1.0__py3-none-any.whl

plain/logs/README.md

@@ -0,0 +1,24 @@
+# Logging
+
+Default logging settings and key-value logger.
+
+In Python, logging can be a surprisingly complex topic.
+
+So Plain aims for easy-to-use defaults that "just work".
+
+## `app_logger`
+
+The default `app_logger` doesn't do much!
+
+But it is paired with the default [settings](#) to actually show the logs like you would expect,
+without any additional configuration.
+
+```python
+from plain.logs import app_logger
+
+
+def example_function():
+    app_logger.info("Hey!")
+```
+
+## `app_logger.kv`

plain/logs/__init__.py

@@ -0,0 +1,5 @@
+from .configure import configure_logging
+from .loggers import app_logger
+from .utils import log_response
+
+__all__ = ["app_logger", "log_response", "configure_logging"]

plain/logs/configure.py

@@ -0,0 +1,39 @@
+import logging
+import logging.config
+from os import environ
+
+
+def configure_logging(logging_settings):
+    # Load the defaults
+    default_logging = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "simple": {
+                "format": "[%(levelname)s] %(message)s",
+            },
+        },
+        "handlers": {
+            "console": {
+                "level": "INFO",
+                "class": "logging.StreamHandler",
+                "formatter": "simple",
+            },
+        },
+        "loggers": {
+            "plain": {
+                "handlers": ["console"],
+                "level": environ.get("PLAIN_LOG_LEVEL", "INFO"),
+            },
+            "app": {
+                "handlers": ["console"],
+                "level": environ.get("APP_LOG_LEVEL", "INFO"),
+                "propagate": False,
+            },
+        },
+    }
+    logging.config.dictConfig(default_logging)
+
+    # Then customize it from settings
+    if logging_settings:
+        logging.config.dictConfig(logging_settings)

plain/logs/loggers.py

@@ -0,0 +1,74 @@
+import logging
+
+app_logger = logging.getLogger("app")
+
+
+class KVLogger:
+    def __init__(self, logger):
+        self.logger = logger
+        self.context = {}  # A dict that will be output in every log message
+
+    def log(self, level, message, **kwargs):
+        msg_kwargs = {
+            **kwargs,
+            **self.context,  # Put these last so they're at the end of the line
+        }
+        self.logger.log(level, f"{message} {self._format_kwargs(msg_kwargs)}")
+
+    def _format_kwargs(self, kwargs):
+        outputs = []
+
+        for k, v in kwargs.items():
+            self._validate_key(k)
+            formatted_value = self._format_value(v)
+            outputs.append(f"{k}={formatted_value}")
+
+        return " ".join(outputs)
+
+    def _validate_key(self, key):
+        if " " in key:
+            raise ValueError("Keys cannot have spaces")
+
+        if "=" in key:
+            raise ValueError("Keys cannot have equals signs")
+
+        if '"' in key or "'" in key:
+            raise ValueError("Keys cannot have quotes")
+
+    def _format_value(self, value):
+        if isinstance(value, str):
+            s = value
+        else:
+            s = str(value)
+
+        if '"' in s:
+            # Escape quotes and surround it
+            s = s.replace('"', '\\"')
+            s = f'"{s}"'
+        elif s == "":
+            # Quote empty strings instead of printing nothing
+            s = '""'
+        elif any(char in s for char in [" ", "/", "'", ":", "=", "."]):
+            # Surround these with quotes for parsers
+            s = f'"{s}"'
+
+        return s
+
+    def info(self, message, **kwargs):
+        self.log(logging.INFO, message, **kwargs)
+
+    def debug(self, message, **kwargs):
+        self.log(logging.DEBUG, message, **kwargs)
+
+    def warning(self, message, **kwargs):
+        self.log(logging.WARNING, message, **kwargs)
+
+    def error(self, message, **kwargs):
+        self.log(logging.ERROR, message, **kwargs)
+
+    def critical(self, message, **kwargs):
+        self.log(logging.CRITICAL, message, **kwargs)
+
+
+# Make this accessible from the app_logger
+app_logger.kv = KVLogger(app_logger)

plain/logs/utils.py

@@ -0,0 +1,46 @@
+import logging
+
+request_logger = logging.getLogger("plain.request")
+
+
+def log_response(
+    message,
+    *args,
+    response=None,
+    request=None,
+    logger=request_logger,
+    level=None,
+    exception=None,
+):
+    """
+    Log errors based on Response status.
+
+    Log 5xx responses as errors and 4xx responses as warnings (unless a level
+    is given as a keyword argument). The Response status_code and the
+    request are passed to the logger's extra parameter.
+    """
+    # Check if the response has already been logged. Multiple requests to log
+    # the same response can be received in some cases, e.g., when the
+    # response is the result of an exception and is logged when the exception
+    # is caught, to record the exception.
+    if getattr(response, "_has_been_logged", False):
+        return
+
+    if level is None:
+        if response.status_code >= 500:
+            level = "error"
+        elif response.status_code >= 400:
+            level = "warning"
+        else:
+            level = "info"
+
+    getattr(logger, level)(
+        message,
+        *args,
+        extra={
+            "status_code": response.status_code,
+            "request": request,
+        },
+        exc_info=exception,
+    )
+    response._has_been_logged = True

plain/middleware/README.md

@@ -0,0 +1,3 @@
+# Middleware
+
+Hook into the request/response cycle.

plain/middleware/clickjacking.py

@@ -0,0 +1,52 @@
+"""
+Clickjacking Protection Middleware.
+
+This module provides a middleware that implements protection against a
+malicious site loading resources from your site in a hidden frame.
+"""
+
+from plain.runtime import settings
+
+
+class XFrameOptionsMiddleware:
+    """
+    Set the X-Frame-Options HTTP header in HTTP responses.
+
+    Do not set the header if it's already set or if the response contains
+    a xframe_options_exempt value set to True.
+
+    By default, set the X-Frame-Options header to 'DENY', meaning the response
+    cannot be displayed in a frame, regardless of the site attempting to do so.
+    To enable the response to be loaded on a frame within the same site, set
+    X_FRAME_OPTIONS in your project's Plain settings to 'SAMEORIGIN'.
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+
+        # Don't set it if it's already in the response
+        if response.get("X-Frame-Options") is not None:
+            return response
+
+        # Don't set it if they used @xframe_options_exempt
+        if getattr(response, "xframe_options_exempt", False):
+            return response
+
+        response.headers["X-Frame-Options"] = self.get_xframe_options_value(
+            request,
+            response,
+        )
+        return response
+
+    def get_xframe_options_value(self, request, response):
+        """
+        Get the value to set for the X_FRAME_OPTIONS header. Use the value from
+        the X_FRAME_OPTIONS setting, or 'DENY' if not set.
+
+        This method can be overridden if needed, allowing it to vary based on
+        the request or response.
+        """
+        return getattr(settings, "X_FRAME_OPTIONS", "DENY").upper()

plain/middleware/common.py

@@ -0,0 +1,87 @@
+from plain.http import ResponsePermanentRedirect
+from plain.runtime import settings
+from plain.urls import is_valid_path
+from plain.utils.http import escape_leading_slashes
+
+
+class CommonMiddleware:
+    """
+    "Common" middleware for taking care of some basic operations:
+
+        - URL rewriting: Based on the APPEND_SLASH setting,
+          append missing slashes.
+
+            - If APPEND_SLASH is set and the initial URL doesn't end with a
+              slash, and it is not found in urlpatterns, form a new URL by
+              appending a slash at the end. If this new URL is found in
+              urlpatterns, return an HTTP redirect to this new URL; otherwise
+              process the initial URL as usual.
+
+          This behavior can be customized by subclassing CommonMiddleware and
+          overriding the response_redirect_class attribute.
+    """
+
+    response_redirect_class = ResponsePermanentRedirect
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        """
+        Rewrite the URL based on settings.APPEND_SLASH
+        """
+
+        response = self.get_response(request)
+
+        """
+        When the status code of the response is 404, it may redirect to a path
+        with an appended slash if should_redirect_with_slash() returns True.
+        """
+        # If the given URL is "Not Found", then check if we should redirect to
+        # a path with a slash appended.
+        if response.status_code == 404 and self.should_redirect_with_slash(request):
+            return self.response_redirect_class(self.get_full_path_with_slash(request))
+
+        # Add the Content-Length header to non-streaming responses if not
+        # already set.
+        if not response.streaming and not response.has_header("Content-Length"):
+            response.headers["Content-Length"] = str(len(response.content))
+
+        return response
+
+    def should_redirect_with_slash(self, request):
+        """
+        Return True if settings.APPEND_SLASH is True and appending a slash to
+        the request path turns an invalid path into a valid one.
+        """
+        if settings.APPEND_SLASH and not request.path_info.endswith("/"):
+            urlconf = getattr(request, "urlconf", None)
+            if not is_valid_path(request.path_info, urlconf):
+                match = is_valid_path("%s/" % request.path_info, urlconf)
+                if match:
+                    view = match.func
+                    return getattr(view, "should_append_slash", True)
+        return False
+
+    def get_full_path_with_slash(self, request):
+        """
+        Return the full path of the request with a trailing slash appended.
+
+        Raise a RuntimeError if settings.DEBUG is True and request.method is
+        POST, PUT, or PATCH.
+        """
+        new_path = request.get_full_path(force_append_slash=True)
+        # Prevent construction of scheme relative urls.
+        new_path = escape_leading_slashes(new_path)
+        if settings.DEBUG and request.method in ("POST", "PUT", "PATCH"):
+            raise RuntimeError(
+                "You called this URL via {method}, but the URL doesn't end "
+                "in a slash and you have APPEND_SLASH set. Plain can't "
+                "redirect to the slash URL while maintaining {method} data. "
+                "Change your form to point to {url} (note the trailing "
+                "slash), or set APPEND_SLASH=False in your Plain settings.".format(
+                    method=request.method,
+                    url=request.get_host() + new_path,
+                )
+            )
+        return new_path

plain/middleware/gzip.py

@@ -0,0 +1,64 @@
+from plain.utils.cache import patch_vary_headers
+from plain.utils.regex_helper import _lazy_re_compile
+from plain.utils.text import compress_sequence, compress_string
+
+re_accepts_gzip = _lazy_re_compile(r"\bgzip\b")
+
+
+class GZipMiddleware:
+    """
+    Compress content if the browser allows gzip compression.
+    Set the Vary header accordingly, so that caches will base their storage
+    on the Accept-Encoding header.
+    """
+
+    max_random_bytes = 100
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+
+        # It's not worth attempting to compress really short responses.
+        if not response.streaming and len(response.content) < 200:
+            return response
+
+        # Avoid gzipping if we've already got a content-encoding.
+        if response.has_header("Content-Encoding"):
+            return response
+
+        patch_vary_headers(response, ("Accept-Encoding",))
+
+        ae = request.META.get("HTTP_ACCEPT_ENCODING", "")
+        if not re_accepts_gzip.search(ae):
+            return response
+
+        if response.streaming:
+            response.streaming_content = compress_sequence(
+                response.streaming_content,
+                max_random_bytes=self.max_random_bytes,
+            )
+            # Delete the `Content-Length` header for streaming content, because
+            # we won't know the compressed size until we stream it.
+            del response.headers["Content-Length"]
+        else:
+            # Return the compressed content only if it's actually shorter.
+            compressed_content = compress_string(
+                response.content,
+                max_random_bytes=self.max_random_bytes,
+            )
+            if len(compressed_content) >= len(response.content):
+                return response
+            response.content = compressed_content
+            response.headers["Content-Length"] = str(len(response.content))
+
+        # If there is a strong ETag, make it weak to fulfill the requirements
+        # of RFC 9110 Section 8.8.1 while also allowing conditional request
+        # matches on ETags.
+        etag = response.get("ETag")
+        if etag and etag.startswith('"'):
+            response.headers["ETag"] = "W/" + etag
+        response.headers["Content-Encoding"] = "gzip"
+
+        return response

plain/middleware/security.py

@@ -0,0 +1,64 @@
+import re
+
+from plain.http import ResponsePermanentRedirect
+from plain.runtime import settings
+
+
+class SecurityMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.sts_seconds = settings.SECURE_HSTS_SECONDS
+        self.sts_include_subdomains = settings.SECURE_HSTS_INCLUDE_SUBDOMAINS
+        self.sts_preload = settings.SECURE_HSTS_PRELOAD
+        self.content_type_nosniff = settings.SECURE_CONTENT_TYPE_NOSNIFF
+        self.redirect = settings.SECURE_SSL_REDIRECT
+        self.redirect_host = settings.SECURE_SSL_HOST
+        self.redirect_exempt = [re.compile(r) for r in settings.SECURE_REDIRECT_EXEMPT]
+        self.referrer_policy = settings.SECURE_REFERRER_POLICY
+        self.cross_origin_opener_policy = settings.SECURE_CROSS_ORIGIN_OPENER_POLICY
+
+    def __call__(self, request):
+        path = request.path.lstrip("/")
+        if (
+            self.redirect
+            and not request.is_secure()
+            and not any(pattern.search(path) for pattern in self.redirect_exempt)
+        ):
+            host = self.redirect_host or request.get_host()
+            return ResponsePermanentRedirect(f"https://{host}{request.get_full_path()}")
+
+        response = self.get_response(request)
+
+        if (
+            self.sts_seconds
+            and request.is_secure()
+            and "Strict-Transport-Security" not in response
+        ):
+            sts_header = "max-age=%s" % self.sts_seconds
+            if self.sts_include_subdomains:
+                sts_header += "; includeSubDomains"
+            if self.sts_preload:
+                sts_header += "; preload"
+            response.headers["Strict-Transport-Security"] = sts_header
+
+        if self.content_type_nosniff:
+            response.headers.setdefault("X-Content-Type-Options", "nosniff")
+
+        if self.referrer_policy:
+            # Support a comma-separated string or iterable of values to allow
+            # fallback.
+            response.headers.setdefault(
+                "Referrer-Policy",
+                ",".join(
+                    [v.strip() for v in self.referrer_policy.split(",")]
+                    if isinstance(self.referrer_policy, str)
+                    else self.referrer_policy
+                ),
+            )
+
+        if self.cross_origin_opener_policy:
+            response.setdefault(
+                "Cross-Origin-Opener-Policy",
+                self.cross_origin_opener_policy,
+            )
+        return response

plain/packages/README.md

@@ -0,0 +1,41 @@
+# Packages
+
+Create app-packages and install third-party packages from PyPI.
+
+Like Django, Plain is heavily dependent on the concept of "packages".
+
+In your `settings.py`, you define which packages are enabled with the `INSTALLED_PACKAGES` setting.
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+
+]
+```
+
+These can refer to third-party packages from PyPI (after you've installed them with `pip`),
+or they can refer to packages that you've written yourself.
+
+- some packages don't need to be installed as packages, but most do (and should specify)
+
+
+## Your own packages
+
+- naming examples
+- startapp
+
+
+## App settings
+
+```python
+# <app>/default_settings.py
+EXAMPLE_SETTING: str = "example"
+```
+
+```python
+# <app>/models.py
+from plain.runtime import settings
+
+
+print(settings.EXAMPLE_SETTING)
+```

plain/packages/__init__.py

@@ -0,0 +1,4 @@
+from .config import PackageConfig
+from .registry import packages
+
+__all__ = ["PackageConfig", "packages"]