plain 0.1.0__py3-none-any.whl

plain/signals/dispatch/license.txt

@@ -0,0 +1,35 @@
+plain.signals.dispatch was originally forked from PyDispatcher.
+
+PyDispatcher License:
+
+    Copyright (c) 2001-2003, Patrick K. O'Brien and Contributors
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+        Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+
+        Redistributions in binary form must reproduce the above
+        copyright notice, this list of conditions and the following
+        disclaimer in the documentation and/or other materials
+        provided with the distribution.
+
+        The name of Patrick K. O'Brien, or the name of any Contributor,
+        may not be used to endorse or promote products derived from this
+        software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+    OF THE POSSIBILITY OF SUCH DAMAGE.

plain/signing.py

@@ -0,0 +1,299 @@
+"""
+Functions for creating and restoring url-safe signed JSON objects.
+
+The format used looks like this:
+
+>>> signing.dumps("hello")
+'ImhlbGxvIg:1QaUZC:YIye-ze3TTx7gtSv422nZA4sgmk'
+
+There are two components here, separated by a ':'. The first component is a
+URLsafe base64 encoded JSON of the object passed to dumps(). The second
+component is a base64 encoded hmac/SHA-256 hash of "$first_component:$secret"
+
+signing.loads(s) checks the signature and returns the deserialized object.
+If the signature fails, a BadSignature exception is raised.
+
+>>> signing.loads("ImhlbGxvIg:1QaUZC:YIye-ze3TTx7gtSv422nZA4sgmk")
+'hello'
+>>> signing.loads("ImhlbGxvIg:1QaUZC:YIye-ze3TTx7gtSv42-modified")
+...
+BadSignature: Signature "ImhlbGxvIg:1QaUZC:YIye-ze3TTx7gtSv42-modified" does not match
+
+You can optionally compress the JSON prior to base64 encoding it to save
+space, using the compress=True argument. This checks if compression actually
+helps and only applies compression if the result is a shorter string:
+
+>>> signing.dumps(list(range(1, 20)), compress=True)
+'.eJwFwcERACAIwLCF-rCiILN47r-GyZVJsNgkxaFxoDgxcOHGxMKD_T7vhAml:1QaUaL:BA0thEZrp4FQVXIXuOvYJtLJSrQ'
+
+The fact that the string is compressed is signalled by the prefixed '.' at the
+start of the base64 JSON.
+
+There are 65 url-safe characters: the 64 used by url-safe base64 and the ':'.
+These functions make use of all of them.
+"""
+
+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
+
+_SEP_UNSAFE = _lazy_re_compile(r"^[A-z0-9-_=]*$")
+BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+
+class BadSignature(Exception):
+    """Signature does not match."""
+
+    pass
+
+
+class SignatureExpired(BadSignature):
+    """Signature timestamp is older than required max_age."""
+
+    pass
+
+
+def b62_encode(s):
+    if s == 0:
+        return "0"
+    sign = "-" if s < 0 else ""
+    s = abs(s)
+    encoded = ""
+    while s > 0:
+        s, remainder = divmod(s, 62)
+        encoded = BASE62_ALPHABET[remainder] + encoded
+    return sign + encoded
+
+
+def b62_decode(s):
+    if s == "0":
+        return 0
+    sign = 1
+    if s[0] == "-":
+        s = s[1:]
+        sign = -1
+    decoded = 0
+    for digit in s:
+        decoded = decoded * 62 + BASE62_ALPHABET.index(digit)
+    return sign * decoded
+
+
+def b64_encode(s):
+    return base64.urlsafe_b64encode(s).strip(b"=")
+
+
+def b64_decode(s):
+    pad = b"=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def base64_hmac(salt, value, key, algorithm="sha1"):
+    return b64_encode(
+        salted_hmac(salt, value, key, algorithm=algorithm).digest()
+    ).decode()
+
+
+def _cookie_signer_key(key):
+    # SECRET_KEYS items may be str or bytes.
+    return b"plain.http.cookies" + force_bytes(key)
+
+
+def get_cookie_signer(salt="plain.signing.get_cookie_signer"):
+    Signer = import_string(settings.SIGNING_BACKEND)
+    return Signer(
+        key=_cookie_signer_key(settings.SECRET_KEY),
+        fallback_keys=map(_cookie_signer_key, settings.SECRET_KEY_FALLBACKS),
+        salt=salt,
+    )
+
+
+class JSONSerializer:
+    """
+    Simple wrapper around json to be used in signing.dumps and
+    signing.loads.
+    """
+
+    def dumps(self, obj):
+        return json.dumps(obj, separators=(",", ":")).encode("latin-1")
+
+    def loads(self, data):
+        return json.loads(data.decode("latin-1"))
+
+
+def dumps(
+    obj, key=None, salt="plain.signing", serializer=JSONSerializer, compress=False
+):
+    """
+    Return URL-safe, hmac signed base64 compressed JSON string. If key is
+    None, use settings.SECRET_KEY instead. The hmac algorithm is the default
+    Signer algorithm.
+
+    If compress is True (not the default), check if compressing using zlib can
+    save some space. Prepend a '.' to signify compression. This is included
+    in the signature, to protect against zip bombs.
+
+    Salt can be used to namespace the hash, so that a signed string is
+    only valid for a given namespace. Leaving this at the default
+    value or re-using a salt value across different parts of your
+    application without good cause is a security risk.
+
+    The serializer is expected to return a bytestring.
+    """
+    return TimestampSigner(key=key, salt=salt).sign_object(
+        obj, serializer=serializer, compress=compress
+    )
+
+
+def loads(
+    s,
+    key=None,
+    salt="plain.signing",
+    serializer=JSONSerializer,
+    max_age=None,
+    fallback_keys=None,
+):
+    """
+    Reverse of dumps(), raise BadSignature if signature fails.
+
+    The serializer is expected to accept a bytestring.
+    """
+    return TimestampSigner(
+        key=key, salt=salt, fallback_keys=fallback_keys
+    ).unsign_object(
+        s,
+        serializer=serializer,
+        max_age=max_age,
+    )
+
+
+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,
+        fallback_keys=None,
+    ):
+        self.key = key or settings.SECRET_KEY
+        self.fallback_keys = (
+            fallback_keys
+            if fallback_keys is not None
+            else settings.SECRET_KEY_FALLBACKS
+        )
+        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)
+        if _SEP_UNSAFE.match(self.sep):
+            raise ValueError(
+                "Unsafe Signer separator: %r (cannot be empty or consist of "
+                "only A-z0-9-_=)" % sep,
+            )
+
+    def signature(self, value, key=None):
+        key = key or self.key
+        return base64_hmac(self.salt + "signer", value, key, algorithm=self.algorithm)
+
+    def sign(self, value):
+        return f"{value}{self.sep}{self.signature(value)}"
+
+    def unsign(self, signed_value):
+        if self.sep not in signed_value:
+            raise BadSignature('No "%s" found in value' % self.sep)
+        value, sig = signed_value.rsplit(self.sep, 1)
+        for key in [self.key, *self.fallback_keys]:
+            if constant_time_compare(sig, self.signature(value, key)):
+                return value
+        raise BadSignature('Signature "%s" does not match' % sig)
+
+    def sign_object(self, obj, serializer=JSONSerializer, compress=False):
+        """
+        Return URL-safe, hmac signed base64 compressed JSON string.
+
+        If compress is True (not the default), check if compressing using zlib
+        can save some space. Prepend a '.' to signify compression. This is
+        included in the signature, to protect against zip bombs.
+
+        The serializer is expected to return a bytestring.
+        """
+        data = serializer().dumps(obj)
+        # Flag for if it's been compressed or not.
+        is_compressed = False
+
+        if compress:
+            # Avoid zlib dependency unless compress is being used.
+            compressed = zlib.compress(data)
+            if len(compressed) < (len(data) - 1):
+                data = compressed
+                is_compressed = True
+        base64d = b64_encode(data).decode()
+        if is_compressed:
+            base64d = "." + base64d
+        return self.sign(base64d)
+
+    def unsign_object(self, signed_obj, serializer=JSONSerializer, **kwargs):
+        # Signer.unsign() returns str but base64 and zlib compression operate
+        # on bytes.
+        base64d = self.unsign(signed_obj, **kwargs).encode()
+        decompress = base64d[:1] == b"."
+        if decompress:
+            # It's compressed; uncompress it first.
+            base64d = base64d[1:]
+        data = b64_decode(base64d)
+        if decompress:
+            data = zlib.decompress(data)
+        return serializer().loads(data)
+
+
+class TimestampSigner(Signer):
+    def timestamp(self):
+        return b62_encode(int(time.time()))
+
+    def sign(self, value):
+        value = f"{value}{self.sep}{self.timestamp()}"
+        return super().sign(value)
+
+    def unsign(self, value, max_age=None):
+        """
+        Retrieve original value and check it wasn't signed more
+        than max_age seconds ago.
+        """
+        result = super().unsign(value)
+        value, timestamp = result.rsplit(self.sep, 1)
+        timestamp = b62_decode(timestamp)
+        if max_age is not None:
+            if isinstance(max_age, datetime.timedelta):
+                max_age = max_age.total_seconds()
+            # Check timestamp is not older than max_age
+            age = time.time() - timestamp
+            if age > max_age:
+                raise SignatureExpired(f"Signature age {age} > {max_age} seconds")
+        return value

plain/templates/README.md

@@ -0,0 +1,20 @@
+# Templates
+
+Render HTML templates using Jinja.
+
+Templates are typically rendered in `TemplateViews`,
+but you can also render them directly to strings for emails or other use cases.
+
+```python
+from plain.templates import Template
+
+
+Template("comment.md").render({
+    "message": "Hello, world!",
+})
+```
+
+Template files can be located in either a root `app/templates`,
+or the `templates` directory in any installed packages.
+
+[Customizing Jinja](./jinja/README.md)

plain/templates/__init__.py

@@ -0,0 +1,6 @@
+from .core import Template, TemplateFileMissing
+
+__all__ = [
+    "Template",
+    "TemplateFileMissing",
+]

plain/templates/core.py

@@ -0,0 +1,24 @@
+import jinja2
+
+from .jinja import environment
+
+
+class TemplateFileMissing(Exception):
+    def __str__(self) -> str:
+        if self.args:
+            return f"Template file {self.args[0]} not found"
+        else:
+            return "Template file not found"
+
+
+class Template:
+    def __init__(self, filename: str) -> None:
+        self.filename = filename
+
+        try:
+            self._jinja_template = environment.get_template(filename)
+        except jinja2.TemplateNotFound:
+            raise TemplateFileMissing(filename)
+
+    def render(self, context: dict) -> str:
+        return self._jinja_template.render(context)

plain/templates/jinja/README.md

@@ -0,0 +1,227 @@
+# Jinja
+
+Templates can be stored inside `INSTALLED_PACKAGES` (ex. `app/<pkg>/templates`) or in the `templates` directory at the root of your project (ex. `app/templates`).
+
+### App templates
+
+You `app/templates` will typically have things like `base.html`,
+which the whole app depends on.
+
+### Package templates
+
+Since all template directories are effectively "merged" together,
+packages will typically namespace their own templates such as `app/users/templates/users/delete.html`.
+
+## Jinja
+
+There is a default set of globals, filters, and extensions.
+
+## Default globals
+
+- `static` - a function that returns the URL for a static file
+- `url` - a function that returns the URL for a view
+- `Paginator` - the Plain Paginator class
+
+## Default filters
+
+- `strftime` - `datetime.datetime.strftime`
+- `strptime` - `datetime.datetime.strptime`
+- `localtime` - convert a datetime to the activated time zone (or a given time zone)
+- `timeuntil` - human readable time until a date
+- `timesince` - human readable time since a date
+- `json_script` - serialize a value as JSON and wrap it in a `<script>` tag
+- `islice` - `itertools.islice` which is a slice for `dict.items()`
+
+## Default extensions
+
+- `jinja2.ext.debug`
+- `jinja2.ext.loopcontrols`
+
+## Default request context
+
+Each request is rendered with a `context`.
+This will include the [default globals](#default-globals),
+any app or project globals,
+as well as the `get_template_context()` from your view.
+
+When a view is rendered,
+the default context includes the `request` itself,
+as well as a `csrf_input` (and `csrf_token`) to be used in forms.
+
+## Extending with a root `jinja.py`
+
+You can customize the Jinja environment by adding a `jinja.py` module to your app root.
+This works just like [extending with packages](#extending-with-packages),
+where you can define `filters`, `globals`, and `extensions`.
+
+## Extending with Packages
+
+Any of your `INSTALLED_PACKAGES` can customize Jinja by adding a `jinja.py` module.
+
+To put it simply, the three things you can "export" from this module are:
+- `filters` - functions that can be used in templates
+- `globals` - variables that can be used in templates
+- `extensions` - a list of custom Jinja extensions to install
+
+All you need to do is define a variable with the correct name:
+
+```python
+# <appname>/jinja.py
+from jinja2 import Extension
+
+
+def add_exclamation(obj):
+    return obj + "!"
+
+
+class MyExtension(Extension):
+    # ...
+    pass
+
+# Filters are used on a variable with a pipe,
+# like {{ variable|add_exclamation }}.
+# You can use these to add new features to all variables.
+filters = {
+    "add_exclamation": add_exclamation,
+}
+
+# Globals are essentially variables that are available in all templates.
+# But you can also include functions here, which can be called in the template like {{ a_callable_global() }}.
+globals = {
+    "my_global": "my global value",
+}
+
+# Extensions are classes that can add new features to the Jinja environment.
+extensions = [
+    MyExtension,
+]
+```
+
+TODO - when to use a global function vs a filter
+
+## Time zone aware output
+
+TODO - example middleware, `|localtime` filter
+
+## Settings
+
+Most Jinja customization happens in `jinja.py` at the root of your app or in `INSTALLED_PACKAGES`.
+But if you need to further customize the environment,
+you can define your own callable which will be used to create the Jinja environment.
+
+```python
+# app/settings.py
+JINJA_ENVIRONMENT = "myjinja.create_environment"
+```
+
+```python
+# app/myjinja.py
+from jinja2 import Environment
+
+
+def create_environment():
+    return Environment(
+        # ...
+    )
+```
+
+## HTML Components
+
+- `{% include %}` shorthand
+- strictly html, no python classes to back them
+- react-inspired syntax
+- react components in the future? live-wire style? script tags?
+
+## Background
+
+Django has two options for template languages: the [Django template language (DTL)](https://docs.djangoproject.com/en/4.2/topics/templates/) and [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/).
+
+I'm not an expert on the history here,
+but my understanding is that the DTL inspired Jinja,
+and my guess is that Jinja then became so popular that they added support for it back to Django.
+And now there are two options.
+
+The two are pretty similar,
+but one of the biggest differences that I care about is the fact that in Django templates,
+you don't use `()` to call functions.
+Which means that you can't call any functions that take arguments.
+
+Sometimes, this can lead you to create better, simpler templates.
+But other times,
+it just forces you to find silly workarounds like creating custom template tags/filters or additional model methods,
+just because you can't pass an argument in your template.
+
+```python
+class MyModel(models.Model):
+    def foo(self, bar=None):
+        return f"foo {bar}"
+```
+
+```html
+<!-- django-template.html -->
+{{ my_model.foo }}
+```
+
+This is not a problem in Jinja.
+
+```html
+<!-- jinja-template.html -->
+{{ my_model.foo(bar) }}
+```
+
+It's also weird to explain to new users of Django/Python that you "use the same `foo()` method, but leave off the `()`, which would not do what you want in a Python shell or anywhere else..."
+
+And even as someone who has understood how this works for a long time,
+it's still really annoying when you want to search across your entire project for usage of a specific method,
+but you can't simply search for `.foo(` because it won't pick it up in the template code.
+
+Plain simply removes the Django Template Language (DTL) and only supports Jinja templates.
+Nobody uses Django templates outside of Django, but people encounter Jinja in lots of other tools.
+I think focusing on Jinja is a better move as an independent templating ecosystem.
+This is also a change that I doubt Django would ever be able to make,
+even if they wanted to.
+
+https://github.com/mitsuhiko/minijinja
+
+- request.user, not user
+- jinja error if you try to render a callable?
+- manager method example?
+
+### `request.user` vs `user`
+
+Django auth does this neat thing where it automatically [puts a `"user"` in your template context](https://github.com/django/django/blob/42b4f81e6efd5c4587e1207a2ae3dd0facb1436f/django/contrib/auth/context_processors.py#L65),
+in addition to `request.user`.
+
+I've seen this cause confusion/conflicts for templates that are trying to render a specific user...
+Plain doesn't do this -- if you want the current logged in user, use `request.user`.
+
+```html
+{% if request.user.is_authenticated %}
+
+{% endif %}
+```
+
+### StrictUndefined
+
+Another feature of Django templates is that,
+by default,
+you don't get any kind of error if you try to render a variable that doesn't exist.
+
+This can be handy for simple kinds of template logic,
+but it can also be the source of some pretty big rendering bugs.
+
+Plain runs Jinja with `strict_undefined=True` by default,
+so you get a big, loud error if you try to render a variable that doesn't exist.
+
+You can use the `|default()` filter to provide a default value if you want to allow a variable to be undefined,
+or check `{% if variable is defined %}` if you want to conditionally render something.
+
+```html
+{{ variable|default('default value') }}
+```
+
+```html
+{% if variable is defined %}
+    {{ variable }}
+{% endif %}
+```

plain/templates/jinja/__init__.py

@@ -0,0 +1,22 @@
+from plain.runtime import settings
+from plain.utils.functional import LazyObject
+from plain.utils.module_loading import import_string
+
+from .defaults import create_default_environment, get_template_dirs
+
+
+class JinjaEnvironment(LazyObject):
+    def _setup(self):
+        environment_setting = settings.JINJA_ENVIRONMENT
+
+        if isinstance(environment_setting, str):
+            environment = import_string(environment_setting)()
+        else:
+            environment = environment_setting()
+
+        self._wrapped = environment
+
+
+environment = JinjaEnvironment()
+
+__all__ = ["environment", "create_default_environment", "get_template_dirs"]