plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/urls/resolvers.py

@@ -6,31 +6,39 @@ a string) and returns a ResolverMatch object which provides access to all
 attributes of the resolved URL match.
 """
 
+from __future__ import annotations
+
 import functools
 import re
 from threading import local
+from typing import TYPE_CHECKING, Any
 from urllib.parse import quote
 
 from plain.runtime import settings
 from plain.utils.datastructures import MultiValueDict
 from plain.utils.http import RFC3986_SUBDELIMS, escape_leading_slashes
 from plain.utils.module_loading import import_string
-from plain.utils.regex_helper import normalize
+from plain.utils.regex_helper import _normalize
 
 from .exceptions import NoReverseMatch, Resolver404
-from .patterns import RegexPattern, URLPattern
+from .patterns import RegexPattern, RoutePattern, URLPattern
+
+if TYPE_CHECKING:
+    from plain.preflight import PreflightResult
+
+    from .routers import Router
 
 
 class ResolverMatch:
     def __init__(
         self,
         *,
-        view,
-        args,
-        kwargs,
-        url_name=None,
-        namespaces=None,
-        route=None,
+        view: Any,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        url_name: str | None = None,
+        namespaces: list[str] | None = None,
+        route: str | None = None,
     ):
         self.view = view
         self.args = args
@@ -48,7 +56,7 @@ class ResolverMatch:
         )
 
 
-def get_resolver(router=None):
+def get_resolver(router: str | Router | None = None) -> URLResolver:
     if router is None:
         router = settings.URLS_ROUTER
 
@@ -56,7 +64,7 @@ def get_resolver(router=None):
 
 
 @functools.cache
-def _get_cached_resolver(router):
+def _get_cached_resolver(router: str | Router) -> URLResolver:
     if isinstance(router, str):
         # Do this inside the cached call, primarily for the URLS_ROUTER
         router_class = import_string(router)
@@ -66,7 +74,9 @@ def _get_cached_resolver(router):
 
 
 @functools.cache
-def get_ns_resolver(ns_pattern, resolver, converters):
+def get_ns_resolver(
+    ns_pattern: str, resolver: URLResolver, converters: tuple[tuple[str, Any], ...]
+) -> URLResolver:
     from .routers import Router
 
     # Build a namespaced resolver for the given parent urls_module pattern.
@@ -95,13 +105,13 @@ class URLResolver:
     def __init__(
         self,
         *,
-        pattern,
-        router,
+        pattern: RegexPattern | RoutePattern,
+        router: Router,
     ):
         self.pattern = pattern
         self.router = router
-        self._reverse_dict = {}
-        self._namespace_dict = {}
+        self._reverse_dict: MultiValueDict = MultiValueDict()
+        self._namespace_dict: dict[str, tuple[str, URLResolver]] = {}
         self._populated = False
         self._local = local()
 
@@ -110,17 +120,17 @@ class URLResolver:
         self.namespace = self.router.namespace
         self.url_patterns = self.router.urls
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {repr(self.router)} ({self.namespace}) {self.pattern.describe()}>"
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         messages = []
         messages.extend(self.pattern.preflight())
         for pattern in self.url_patterns:
             messages.extend(pattern.preflight())
         return messages
 
-    def _populate(self):
+    def _populate(self) -> None:
         # Short-circuit if called recursively in this thread to prevent
         # infinite recursion. Concurrent threads may call this at the same
         # time and will need to continue, so set 'populating' on a
@@ -135,7 +145,7 @@ class URLResolver:
                 p_pattern = url_pattern.pattern.regex.pattern
                 p_pattern = p_pattern.removeprefix("^")
                 if isinstance(url_pattern, URLPattern):
-                    bits = normalize(url_pattern.pattern.regex.pattern)
+                    bits = _normalize(url_pattern.pattern.regex.pattern)
                     lookups.appendlist(
                         url_pattern.view,
                         (
@@ -164,7 +174,7 @@ class URLResolver:
                                 pat,
                                 converters,
                             ) in url_pattern.reverse_dict.getlist(name):
-                                new_matches = normalize(p_pattern + pat)
+                                new_matches = _normalize(p_pattern + pat)
                                 lookups.appendlist(
                                     name,
                                     (
@@ -191,26 +201,26 @@ class URLResolver:
             self._local.populating = False
 
     @property
-    def reverse_dict(self):
+    def reverse_dict(self) -> MultiValueDict:
         if not self._reverse_dict:
             self._populate()
         return self._reverse_dict
 
     @property
-    def namespace_dict(self):
+    def namespace_dict(self) -> dict[str, tuple[str, URLResolver]]:
         if not self._namespace_dict:
             self._populate()
         return self._namespace_dict
 
     @staticmethod
-    def _join_route(route1, route2):
+    def _join_route(route1: str, route2: str) -> str:
         """Join two routes, without the starting ^ in the second route."""
         if not route1:
             return route2
         route2 = route2.removeprefix("^")
         return route1 + route2
 
-    def resolve(self, path):
+    def resolve(self, path: str) -> ResolverMatch:
         path = str(path)  # path may be a reverse_lazy object
         match = self.pattern.match(path)
         if match:
@@ -247,7 +257,7 @@ class URLResolver:
             raise Resolver404({"path": new_path})
         raise Resolver404({"path": path})
 
-    def reverse(self, lookup_view, *args, **kwargs):
+    def reverse(self, lookup_view: Any, *args: Any, **kwargs: Any) -> str:
         if args and kwargs:
             raise ValueError("Don't mix *args and **kwargs in call to reverse()!")
 

plain/urls/utils.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.utils.functional import lazy
 
 from .exceptions import NoReverseMatch
 from .resolvers import get_ns_resolver, get_resolver
 
 
-def reverse(url_name: str, *args, **kwargs):
+def reverse(url_name: str, *args: Any, **kwargs: Any) -> str:
     resolver = get_resolver()
 
     *path, view = url_name.split(":")

plain/utils/README.md

@@ -1,9 +1,256 @@
-# Utils
+# plain.utils
 
-**Various utilities for text manipulation, parsing, dates, and more.**
+**Common utilities for working with dates, text, HTML, and more.**
 
 - [Overview](#overview)
+- [Timezone utilities](#timezone-utilities)
+    - [Getting the current time](#getting-the-current-time)
+    - [Converting between aware and naive datetimes](#converting-between-aware-and-naive-datetimes)
+    - [Temporarily changing the timezone](#temporarily-changing-the-timezone)
+- [Time formatting](#time-formatting)
+- [Text utilities](#text-utilities)
+    - [Slugify](#slugify)
+    - [Truncating text](#truncating-text)
+- [HTML utilities](#html-utilities)
+    - [Escaping HTML](#escaping-html)
+    - [Formatting HTML safely](#formatting-html-safely)
+    - [Stripping tags](#stripping-tags)
+    - [Embedding JSON in HTML](#embedding-json-in-html)
+- [Safe strings](#safe-strings)
+- [Random strings](#random-strings)
+- [Date parsing](#date-parsing)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-The utilities aren't going to be documented in detail here. Take a look at the source code for more information.
+The `plain.utils` module provides a collection of utilities that you'll commonly need when building web applications. You can import what you need directly from the submodules:
+
+```python
+from plain.utils.timezone import now, localtime
+from plain.utils.text import slugify
+from plain.utils.html import escape, format_html
+
+# Get the current time as a timezone-aware datetime
+current_time = now()
+
+# Create a URL-safe slug
+slug = slugify("Hello World!")  # "hello-world"
+
+# Safely format HTML with escaped values
+html = format_html("<p>Hello, {}!</p>", user_input)
+```
+
+## Timezone utilities
+
+Plain uses timezone-aware datetimes throughout. The timezone utilities help you work with aware datetimes consistently.
+
+### Getting the current time
+
+```python
+from plain.utils.timezone import now
+
+current_time = now()  # Returns a timezone-aware datetime in UTC
+```
+
+### Converting between aware and naive datetimes
+
+```python
+from plain.utils.timezone import make_aware, make_naive, is_aware, localtime
+from datetime import datetime
+
+# Check if a datetime is aware
+is_aware(some_datetime)
+
+# Make a naive datetime aware (uses current timezone by default)
+aware_dt = make_aware(datetime(2024, 1, 15, 10, 30))
+
+# Convert to local time
+local_dt = localtime(aware_dt)
+
+# Make an aware datetime naive
+naive_dt = make_naive(aware_dt)
+```
+
+### Temporarily changing the timezone
+
+```python
+from plain.utils.timezone import override, get_current_timezone
+
+with override("America/New_York"):
+    # Code here uses the New York timezone
+    tz = get_current_timezone()
+```
+
+For more timezone functions, see [`timezone.py`](./timezone.py#activate).
+
+## Time formatting
+
+Format time differences as human-readable strings.
+
+```python
+from plain.utils.timesince import timesince, timeuntil
+from datetime import datetime, timedelta
+from plain.utils.timezone import now
+
+past = now() - timedelta(days=2, hours=3)
+timesince(past)  # "2 days, 3 hours"
+
+future = now() + timedelta(weeks=1)
+timeuntil(future)  # "1 week"
+```
+
+You can use a short format for compact display:
+
+```python
+timesince(past, format="short")  # "2d 3h"
+```
+
+## Text utilities
+
+### Slugify
+
+Convert text to a URL-safe slug.
+
+```python
+from plain.utils.text import slugify
+
+slugify("Hello World!")  # "hello-world"
+slugify("Cafe au lait")  # "cafe-au-lait"
+slugify("My Article Title")  # "my-article-title"
+
+# Preserve unicode characters
+slugify("Ich liebe Berlin", allow_unicode=True)  # "ich-liebe-berlin"
+```
+
+### Truncating text
+
+Truncate text by characters or words, with HTML support.
+
+```python
+from plain.utils.text import Truncator
+
+text = "This is a long piece of text that needs to be shortened."
+Truncator(text).chars(20)  # "This is a long pie..."
+Truncator(text).words(5)   # "This is a long piece..."
+
+# Truncate HTML while preserving valid structure
+html = "<p>This is <strong>bold</strong> text.</p>"
+Truncator(html).chars(15, html=True)  # "<p>This is <strong>bo</strong>...</p>"
+```
+
+## HTML utilities
+
+### Escaping HTML
+
+```python
+from plain.utils.html import escape
+
+escape("<script>alert('xss')</script>")
+# "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;"
+```
+
+### Formatting HTML safely
+
+Build HTML fragments with automatic escaping of values:
+
+```python
+from plain.utils.html import format_html
+
+# Values are automatically escaped
+format_html("<a href='{}'>{}</a>", url, link_text)
+
+# Safe for untrusted input
+format_html("<p>Welcome, {}!</p>", user_provided_name)
+```
+
+### Stripping tags
+
+Remove HTML tags from text:
+
+```python
+from plain.utils.html import strip_tags
+
+strip_tags("<p>Hello <strong>world</strong>!</p>")  # "Hello world!"
+```
+
+### Embedding JSON in HTML
+
+Safely embed JSON data in a script tag:
+
+```python
+from plain.utils.html import json_script
+
+data = {"user": "john", "count": 42}
+json_script(data, element_id="user-data")
+# '<script id="user-data" type="application/json">{"user": "john", "count": 42}</script>'
+```
+
+## Safe strings
+
+Mark strings as safe to prevent double-escaping.
+
+```python
+from plain.utils.safestring import mark_safe, SafeString
+
+# Mark a string as already escaped/safe
+html = mark_safe("<strong>Already safe HTML</strong>")
+
+# Check if something is a SafeString
+isinstance(html, SafeString)  # True
+```
+
+Use `mark_safe` only when you've manually ensured the content is safe. For building HTML from untrusted input, use `format_html` instead.
+
+## Random strings
+
+Generate cryptographically secure random strings.
+
+```python
+from plain.utils.crypto import get_random_string
+
+# Default: 12 characters, alphanumeric
+token = get_random_string(12)  # e.g., "Kx9mP2nL4qRs"
+
+# Custom character set
+pin = get_random_string(6, allowed_chars="0123456789")  # e.g., "847293"
+```
+
+## Date parsing
+
+Parse date and time strings into Python objects.
+
+```python
+from plain.utils.dateparse import parse_date, parse_datetime, parse_time, parse_duration
+
+parse_date("2024-01-15")  # datetime.date(2024, 1, 15)
+parse_datetime("2024-01-15T10:30:00Z")  # datetime.datetime(2024, 1, 15, 10, 30, tzinfo=UTC)
+parse_time("10:30:00")  # datetime.time(10, 30)
+parse_duration("1 02:30:00")  # datetime.timedelta(days=1, hours=2, minutes=30)
+```
+
+These functions return `None` if the input is not well-formatted, and raise `ValueError` if the input is well-formatted but invalid.
+
+## FAQs
+
+#### What about the other utilities in this module?
+
+The `plain.utils` module contains additional utilities that are primarily used internally by Plain. You can explore the source files directly:
+
+- [`datastructures.py`](./datastructures.py) - `MultiValueDict`, `OrderedSet`, `ImmutableList`
+- [`functional.py`](./functional.py) - `SimpleLazyObject`, `lazy`, `classproperty`
+- [`http.py`](./http.py) - `urlencode`, `http_date`, `base36_to_int`
+- [`encoding.py`](./encoding.py) - `force_str`, `force_bytes`
+
+#### Should I use `datetime.datetime.now()` or `plain.utils.timezone.now()`?
+
+Always use `plain.utils.timezone.now()`. It returns a timezone-aware datetime in UTC, which is what Plain expects throughout the framework.
+
+## Installation
+
+The `plain.utils` module is included with Plain.
+
+```python
+from plain.utils.timezone import now
+from plain.utils.text import slugify
+```

plain/utils/cache.py

@@ -15,16 +15,22 @@ An example: i18n middleware would need to distinguish caches by the
 "Accept-language" header.
 """
 
+from __future__ import annotations
+
 import time
 from collections import defaultdict
+from typing import TYPE_CHECKING, Any
 
 from .http import http_date
 from .regex_helper import _lazy_re_compile
 
-cc_delim_re = _lazy_re_compile(r"\s*,\s*")
+if TYPE_CHECKING:
+    from plain.http import ResponseBase
+
+_cc_delim_re = _lazy_re_compile(r"\s*,\s*")
 
 
-def patch_response_headers(response, cache_timeout):
+def patch_response_headers(response: ResponseBase, cache_timeout: int | float) -> None:
     """
     Add HTTP caching headers to the given HttpResponse: Expires and
     Cache-Control.
@@ -38,7 +44,7 @@ def patch_response_headers(response, cache_timeout):
     patch_cache_control(response, max_age=cache_timeout)
 
 
-def add_never_cache_headers(response):
+def add_never_cache_headers(response: ResponseBase) -> None:
     """
     Add headers to a response to indicate that a page should never be cached.
     """
@@ -48,7 +54,7 @@ def add_never_cache_headers(response):
     )
 
 
-def patch_cache_control(response, **kwargs):
+def patch_cache_control(response: ResponseBase, **kwargs: Any) -> None:
     """
     Patch the Cache-Control header by adding all keyword arguments to it.
     The transformation is as follows:
@@ -61,22 +67,22 @@ def patch_cache_control(response, **kwargs):
       str() to it.
     """
 
-    def dictitem(s):
+    def dictitem(s: str) -> tuple[str, str | bool]:
         t = s.split("=", 1)
         if len(t) > 1:
             return (t[0].lower(), t[1])
         else:
             return (t[0].lower(), True)
 
-    def dictvalue(*t):
+    def dictvalue(*t: str | bool) -> str:
         if t[1] is True:
-            return t[0]
+            return str(t[0])
         else:
             return f"{t[0]}={t[1]}"
 
     cc = defaultdict(set)
     if response.headers.get("Cache-Control"):
-        for field in cc_delim_re.split(response.headers["Cache-Control"]):
+        for field in _cc_delim_re.split(response.headers["Cache-Control"]):
             directive, value = dictitem(field)
             if directive == "no-cache":
                 # no-cache supports multiple field names.
@@ -117,7 +123,7 @@ def patch_cache_control(response, **kwargs):
     response.headers["Cache-Control"] = cc
 
 
-def patch_vary_headers(response, newheaders):
+def patch_vary_headers(response: ResponseBase, newheaders: list[str]) -> None:
     """
     Add (or update) the "Vary" header in the given Response object.
     newheaders is a list of header names that should be in "Vary". If headers
@@ -128,7 +134,7 @@ def patch_vary_headers(response, newheaders):
     # implementations may rely on the order of the Vary contents in, say,
     # computing an MD5 hash.
     if "Vary" in response.headers:
-        vary_headers = cc_delim_re.split(response.headers["Vary"])
+        vary_headers = _cc_delim_re.split(response.headers["Vary"])
     else:
         vary_headers = []
     # Use .lower() here so we treat headers as case-insensitive.
@@ -145,7 +151,7 @@ def patch_vary_headers(response, newheaders):
         response.headers["Vary"] = ", ".join(vary_headers)
 
 
-def _to_tuple(s):
+def _to_tuple(s: str) -> tuple[str, str | bool]:
     t = s.split("=", 1)
     if len(t) == 2:
         return t[0].lower(), t[1]

plain/utils/crypto.py

@@ -2,9 +2,13 @@
 Plain's standard crypto functions and utilities.
 """
 
+from __future__ import annotations
+
 import hashlib
 import hmac
 import secrets
+from collections.abc import Callable
+from typing import Any
 
 from plain.runtime import settings
 from plain.utils.encoding import force_bytes
@@ -16,7 +20,13 @@ class InvalidAlgorithm(ValueError):
     pass
 
 
-def salted_hmac(key_salt, value, secret=None, *, algorithm="sha1"):
+def salted_hmac(
+    key_salt: str | bytes,
+    value: str | bytes,
+    secret: str | bytes | None = None,
+    *,
+    algorithm: str = "sha1",
+) -> hmac.HMAC:
     """
     Return the HMAC of 'value', using a key generated from key_salt and a
     secret (which defaults to settings.SECRET_KEY). Default algorithm is SHA1,
@@ -48,7 +58,7 @@ def salted_hmac(key_salt, value, secret=None, *, algorithm="sha1"):
 RANDOM_STRING_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
 
-def get_random_string(length, allowed_chars=RANDOM_STRING_CHARS):
+def get_random_string(length: int, allowed_chars: str = RANDOM_STRING_CHARS) -> str:
     """
     Return a securely generated random string.
 
@@ -62,11 +72,17 @@ def get_random_string(length, allowed_chars=RANDOM_STRING_CHARS):
     return "".join(secrets.choice(allowed_chars) for i in range(length))
 
 
-def pbkdf2(password, salt, iterations, dklen=0, digest=None):
+def pbkdf2(
+    password: str | bytes,
+    salt: str | bytes,
+    iterations: int,
+    dklen: int = 0,
+    digest: Callable[[], Any] | None = None,
+) -> bytes:
     """Return the hash of password using pbkdf2."""
     if digest is None:
         digest = hashlib.sha256
-    dklen = dklen or None
+    dklen_value: int | None = dklen if dklen else None
     password = force_bytes(password)
     salt = force_bytes(salt)
-    return hashlib.pbkdf2_hmac(digest().name, password, salt, iterations, dklen)
+    return hashlib.pbkdf2_hmac(digest().name, password, salt, iterations, dklen_value)