plain 0.66.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/urls/patterns.py

@@ -1,18 +1,25 @@
+from __future__ import annotations
+
 import re
 import string
+from typing import Any
 
 from plain.exceptions import ImproperlyConfigured
 from plain.internal import internalcode
-from plain.preflight import Warning
+from plain.preflight import PreflightResult
 from plain.runtime import settings
 from plain.utils.regex_helper import _lazy_re_compile
 
-from .converters import get_converter
+from .converters import _get_converter
 
 
 @internalcode
 class CheckURLMixin:
-    def describe(self):
+    # Expected to be set by subclasses
+    regex: re.Pattern[str]
+    name: str | None
+
+    def describe(self) -> str:
         """
         Format the URL pattern for display in warning messages.
         """
@@ -21,7 +28,7 @@ class CheckURLMixin:
             description += f" [name='{self.name}']"
         return description
 
-    def _check_pattern_startswith_slash(self):
+    def _check_pattern_startswith_slash(self) -> list[PreflightResult]:
         """
         Check that the pattern does not begin with a forward slash.
         """
@@ -33,11 +40,10 @@ class CheckURLMixin:
         if regex_pattern.startswith(("/", "^/", "^\\/")) and not regex_pattern.endswith(
             "/"
         ):
-            warning = Warning(
-                f"Your URL pattern {self.describe()} has a route beginning with a '/'. Remove this "
-                "slash as it is unnecessary. If this pattern is targeted in an "
-                "include(), ensure the include() pattern has a trailing '/'.",
-                id="urls.W002",
+            warning = PreflightResult(
+                fix=f"URL pattern {self.describe()} starts with unnecessary '/'. Remove the leading slash.",
+                warning=True,
+                id="urls.pattern_starts_with_slash",
             )
             return [warning]
         else:
@@ -45,14 +51,14 @@ class CheckURLMixin:
 
 
 class RegexPattern(CheckURLMixin):
-    def __init__(self, regex, name=None, is_endpoint=False):
+    def __init__(self, regex: str, name: str | None = None, is_endpoint: bool = False):
         self._regex = regex
         self._is_endpoint = is_endpoint
         self.name = name
-        self.converters = {}
+        self.converters: dict[str, Any] = {}
         self.regex = self._compile(str(regex))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[Any, ...], dict[str, Any]] | None:
         match = (
             self.regex.fullmatch(path)
             if self._is_endpoint and self.regex.pattern.endswith("$")
@@ -68,28 +74,27 @@ class RegexPattern(CheckURLMixin):
             return path[match.end() :], args, kwargs
         return None
 
-    def check(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = []
         warnings.extend(self._check_pattern_startswith_slash())
         if not self._is_endpoint:
             warnings.extend(self._check_include_trailing_dollar())
         return warnings
 
-    def _check_include_trailing_dollar(self):
+    def _check_include_trailing_dollar(self) -> list[PreflightResult]:
         regex_pattern = self.regex.pattern
         if regex_pattern.endswith("$") and not regex_pattern.endswith(r"\$"):
             return [
-                Warning(
-                    f"Your URL pattern {self.describe()} uses include with a route ending with a '$'. "
-                    "Remove the dollar from the route to avoid problems including "
-                    "URLs.",
-                    id="urls.W001",
+                PreflightResult(
+                    fix=f"Include pattern {self.describe()} ends with '$' which prevents URL inclusion. Remove the dollar sign.",
+                    warning=True,
+                    id="urls.include_pattern_ends_with_dollar",
                 )
             ]
         else:
             return []
 
-    def _compile(self, regex):
+    def _compile(self, regex: str) -> re.Pattern[str]:
         """Compile and return the given regular expression."""
         try:
             return re.compile(regex)
@@ -98,7 +103,7 @@ class RegexPattern(CheckURLMixin):
                 f'"{regex}" is not a valid regular expression: {e}'
             ) from e
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._regex)
 
 
@@ -107,7 +112,9 @@ _PATH_PARAMETER_COMPONENT_RE = _lazy_re_compile(
 )
 
 
-def _route_to_regex(route, is_endpoint=False):
+def _route_to_regex(
+    route: str, is_endpoint: bool = False
+) -> tuple[str, dict[str, Any]]:
     """
     Convert a path pattern into a regular expression. Return the regular
     expression and a dictionary mapping the capture names to the converters.
@@ -140,7 +147,7 @@ def _route_to_regex(route, is_endpoint=False):
             # If a converter isn't specified, the default is `str`.
             raw_converter = "str"
         try:
-            converter = get_converter(raw_converter)
+            converter = _get_converter(raw_converter)
         except KeyError as e:
             raise ImproperlyConfigured(
                 f"URL route {original_route!r} uses invalid converter {raw_converter!r}."
@@ -153,14 +160,14 @@ def _route_to_regex(route, is_endpoint=False):
 
 
 class RoutePattern(CheckURLMixin):
-    def __init__(self, route, name=None, is_endpoint=False):
+    def __init__(self, route: str, name: str | None = None, is_endpoint: bool = False):
         self._route = route
         self._is_endpoint = is_endpoint
         self.name = name
         self.converters = _route_to_regex(str(route), is_endpoint)[1]
         self.regex = self._compile(str(route))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[()], dict[str, Any]] | None:
         match = self.regex.search(path)
         if match:
             # RoutePattern doesn't allow non-named groups so args are ignored.
@@ -174,56 +181,64 @@ class RoutePattern(CheckURLMixin):
             return path[match.end() :], (), kwargs
         return None
 
-    def check(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_startswith_slash()
         route = self._route
         if "(?P<" in route or route.startswith("^") or route.endswith("$"):
             warnings.append(
-                Warning(
-                    f"Your URL pattern {self.describe()} has a route that contains '(?P<', begins "
+                PreflightResult(
+                    fix=f"Your URL pattern {self.describe()} has a route that contains '(?P<', begins "
                     "with a '^', or ends with a '$'. This was likely an oversight "
                     "when migrating to plain.urls.path().",
-                    id="2_0.W001",
+                    warning=True,
+                    id="urls.path_migration_warning",
                 )
             )
         return warnings
 
-    def _compile(self, route):
+    def _compile(self, route: str) -> re.Pattern[str]:
         return re.compile(_route_to_regex(route, self._is_endpoint)[0])
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._route)
 
 
 class URLPattern:
-    def __init__(self, *, pattern, view, name=None):
+    def __init__(
+        self,
+        *,
+        pattern: RegexPattern | RoutePattern,
+        view: Any,
+        name: str | None = None,
+    ):
         self.pattern = pattern
         self.view = view
         self.name = name
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {self.pattern.describe()}>"
 
-    def check(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_name()
-        warnings.extend(self.pattern.check())
+        warnings.extend(self.pattern.preflight())
         return warnings
 
-    def _check_pattern_name(self):
+    def _check_pattern_name(self) -> list[PreflightResult]:
         """
         Check that the pattern name does not contain a colon.
         """
         if self.pattern.name is not None and ":" in self.pattern.name:
-            warning = Warning(
-                f"Your URL pattern {self.pattern.describe()} has a name including a ':'. Remove the colon, to "
+            warning = PreflightResult(
+                fix=f"Your URL pattern {self.pattern.describe()} has a name including a ':'. Remove the colon, to "
                 "avoid ambiguous namespace references.",
-                id="urls.W003",
+                warning=True,
+                id="urls.pattern_name_contains_colon",
             )
             return [warning]
         else:
             return []
 
-    def resolve(self, path):
+    def resolve(self, path: str) -> Any:
         match = self.pattern.match(path)
         if match:
             new_path, args, captured_kwargs = match
@@ -236,3 +251,4 @@ class URLPattern:
                 url_name=self.pattern.name,
                 route=str(self.pattern),
             )
+        return None

plain/urls/resolvers.py

@@ -6,32 +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.preflight.urls import check_resolver
 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
@@ -49,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
 
@@ -57,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)
@@ -67,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.
@@ -96,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()
 
@@ -111,16 +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 check(self):
+    def preflight(self) -> list[PreflightResult]:
         messages = []
+        messages.extend(self.pattern.preflight())
         for pattern in self.url_patterns:
-            messages.extend(check_resolver(pattern))
-        return messages or self.pattern.check()
+            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
+```