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

plain/utils/module_loading.py

@@ -1,9 +1,13 @@
+from __future__ import annotations
+
 import os
 import sys
 from importlib import import_module
+from types import ModuleType
+from typing import Any
 
 
-def cached_import(module_path, class_name):
+def cached_import(module_path: str, class_name: str) -> Any:
     # Check whether module is loaded and fully initialized.
     if not (
         (module := sys.modules.get(module_path))
@@ -14,7 +18,7 @@ def cached_import(module_path, class_name):
     return getattr(module, class_name)
 
 
-def import_string(dotted_path):
+def import_string(dotted_path: str) -> Any:
     """
     Import a dotted module path and return the attribute/class designated by the
     last name in the path. Raise ImportError if the import failed.
@@ -32,7 +36,7 @@ def import_string(dotted_path):
         ) from err
 
 
-def module_dir(module):
+def module_dir(module: ModuleType) -> str:
     """
     Find the name of the directory that contains a module, if possible.
 

plain/utils/regex_helper.py

@@ -6,14 +6,19 @@ This is not, and is not intended to be, a complete reg-exp decompiler. It
 should be good enough for a large class of URLS, however.
 """
 
+from __future__ import annotations
+
 import re
+from collections.abc import Iterator
+from typing import Any
 
+from plain.internal import internalcode
 from plain.utils.functional import SimpleLazyObject
 
 # Mapping of an escape character to a representative of that class. So, e.g.,
 # "\w" is replaced by "x" in a reverse URL. A value of None means to ignore
 # this sequence. Any missing key is mapped to itself.
-ESCAPE_MAPPINGS = {
+_ESCAPE_MAPPINGS = {
     "A": None,
     "b": None,
     "B": None,
@@ -27,19 +32,22 @@ ESCAPE_MAPPINGS = {
 }
 
 
+@internalcode
 class Choice(list):
     """Represent multiple possibilities at this point in a pattern string."""
 
 
+@internalcode
 class Group(list):
     """Represent a capturing group in the pattern string."""
 
 
+@internalcode
 class NonCapture(list):
     """Represent a non-capturing group in the pattern string."""
 
 
-def normalize(pattern):
+def _normalize(pattern: str) -> list[tuple[str, list[str | None]]]:
     r"""
     Given a reg-exp pattern, normalize it to an iterable of forms that
     suffice for reverse matching. This does the following:
@@ -65,7 +73,7 @@ def normalize(pattern):
     result = []
     non_capturing_groups = []
     consume_next = True
-    pattern_iter = next_char(iter(pattern))
+    pattern_iter = _next_char(iter(pattern))
     num_args = 0
 
     # A "while" loop is used here because later on we need to be able to peek
@@ -115,13 +123,13 @@ def normalize(pattern):
                     name = "_%d" % num_args  # noqa: UP031
                     num_args += 1
                     result.append(Group(((f"%({name})s"), name)))
-                    walk_to_end(ch, pattern_iter)
+                    _walk_to_end(ch, pattern_iter)
                 else:
                     ch, escaped = next(pattern_iter)
                     if ch in "!=<":
                         # All of these are ignorable. Walk to the end of the
                         # group.
-                        walk_to_end(ch, pattern_iter)
+                        _walk_to_end(ch, pattern_iter)
                     elif ch == ":":
                         # Non-capturing group
                         non_capturing_groups.append(len(result))
@@ -152,12 +160,12 @@ def normalize(pattern):
                         # parenthesis.
                         if terminal_char != ")":
                             result.append(Group(((f"%({param})s"), param)))
-                            walk_to_end(ch, pattern_iter)
+                            _walk_to_end(ch, pattern_iter)
                         else:
                             result.append(Group(((f"%({param})s"), None)))
             elif ch in "*?+{":
                 # Quantifiers affect the previous item in the result list.
-                count, ch = get_quantifier(ch, pattern_iter)
+                count, ch = _get_quantifier(ch, pattern_iter)
                 if ch:
                     # We had to look ahead, but it wasn't need to compute the
                     # quantifier, so use this character next time around the
@@ -165,7 +173,7 @@ def normalize(pattern):
                     consume_next = False
 
                 if count == 0:
-                    if contains(result[-1], Group):
+                    if _contains(result[-1], Group):
                         # If we are quantifying a capturing group (or
                         # something containing such a group) and the minimum is
                         # zero, we must also handle the case of one occurrence
@@ -190,10 +198,10 @@ def normalize(pattern):
         # A case of using the disjunctive form. No results for you!
         return [("", [])]
 
-    return list(zip(*flatten_result(result)))
+    return list(zip(*_flatten_result(result)))
 
 
-def next_char(input_iter):
+def _next_char(input_iter: Iterator[str]) -> Iterator[tuple[str, bool]]:
     r"""
     An iterator that yields the next character from "pattern_iter", respecting
     escape sequences. An escaped character is replaced by a representative of
@@ -208,13 +216,13 @@ def next_char(input_iter):
             yield ch, False
             continue
         ch = next(input_iter)
-        representative = ESCAPE_MAPPINGS.get(ch, ch)
+        representative = _ESCAPE_MAPPINGS.get(ch, ch)
         if representative is None:
             continue
         yield representative, True
 
 
-def walk_to_end(ch, input_iter):
+def _walk_to_end(ch: str, input_iter: Iterator[tuple[str, bool]]) -> None:
     """
     The iterator is currently inside a capturing group. Walk to the close of
     this group, skipping over any nested groups and handling escaped
@@ -235,7 +243,9 @@ def walk_to_end(ch, input_iter):
             nesting -= 1
 
 
-def get_quantifier(ch, input_iter):
+def _get_quantifier(
+    ch: str, input_iter: Iterator[tuple[str, bool]]
+) -> tuple[int, str | None]:
     """
     Parse a quantifier from the input, where "ch" is the first character in the
     quantifier.
@@ -263,16 +273,18 @@ def get_quantifier(ch, input_iter):
     values = "".join(quant).split(",")
 
     # Consume the trailing '?', if necessary.
+    ch2: str | None
     try:
         ch, escaped = next(input_iter)
+        ch2 = ch
     except StopIteration:
-        ch = None
-    if ch == "?":
-        ch = None
-    return int(values[0]), ch
+        ch2 = None
+    if ch2 == "?":
+        ch2 = None
+    return int(values[0]), ch2
 
 
-def contains(source, inst):
+def _contains(source: Any, inst: type) -> bool:
     """
     Return True if the "source" contains an instance of "inst". False,
     otherwise.
@@ -281,12 +293,12 @@ def contains(source, inst):
         return True
     if isinstance(source, NonCapture):
         for elt in source:
-            if contains(elt, inst):
+            if _contains(elt, inst):
                 return True
     return False
 
 
-def flatten_result(source):
+def _flatten_result(source: Any) -> tuple[list[str], list[list[str | None]]]:
     """
     Turn the given source sequence into a list of reg-exp possibilities and
     their arguments. Return a list of strings and a list of argument lists.
@@ -322,7 +334,7 @@ def flatten_result(source):
                 elt = [elt]
             inner_result, inner_args = [], []
             for item in elt:
-                res, args = flatten_result(item)
+                res, args = _flatten_result(item)
                 inner_result.extend(res)
                 inner_args.extend(args)
             new_result = []
@@ -340,10 +352,12 @@ def flatten_result(source):
     return result, result_args
 
 
-def _lazy_re_compile(regex, flags=0):
+def _lazy_re_compile(
+    regex: str | bytes | re.Pattern[str] | re.Pattern[bytes], flags: int = 0
+) -> SimpleLazyObject:
     """Lazily compile a regex with flags."""
 
-    def _compile():
+    def _compile() -> re.Pattern[str] | re.Pattern[bytes]:
         # Compile the regex if it was not passed pre-compiled.
         if isinstance(regex, str | bytes):
             return re.compile(regex, flags)

plain/utils/safestring.py

@@ -5,15 +5,21 @@ that the producer of the string has already turned characters that should not
 be interpreted by the HTML engine (e.g. '<') into the appropriate entities.
 """
 
+from __future__ import annotations
+
+from collections.abc import Callable
 from functools import wraps
+from typing import Any, TypeVar
 
 from plain.utils.functional import keep_lazy
 
+_T = TypeVar("_T")
+
 
 class SafeData:
     __slots__ = ()
 
-    def __html__(self):
+    def __html__(self) -> SafeData:
         """
         Return the html representation of a string for interoperability.
 
@@ -30,7 +36,7 @@ class SafeString(str, SafeData):
 
     __slots__ = ()
 
-    def __add__(self, rhs):
+    def __add__(self, rhs: str) -> SafeString | str:  # type: ignore[override]
         """
         Concatenating a safe string with another safe bytestring or
         safe string is safe. Otherwise, the result is no longer safe.
@@ -40,20 +46,22 @@ class SafeString(str, SafeData):
             return SafeString(t)
         return t
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self
 
 
-def _safety_decorator(safety_marker, func):
+def _safety_decorator(
+    safety_marker: Callable[[Any], _T], func: Callable[..., Any]
+) -> Callable[..., _T]:
     @wraps(func)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Any, **kwargs: Any) -> _T:
         return safety_marker(func(*args, **kwargs))
 
     return wrapper
 
 
 @keep_lazy(SafeString)
-def mark_safe(s):
+def mark_safe(s: Any) -> SafeString | SafeData | Callable[..., Any]:
     """
     Explicitly mark a string as safe for (HTML) output purposes. The returned
     object can be used everywhere a string is appropriate.

plain/utils/text.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 import re
 import unicodedata
+from typing import Any
 
 from plain.utils.functional import SimpleLazyObject, keep_lazy_text, lazy
 from plain.utils.regex_helper import _lazy_re_compile
 
 # Set up regular expressions
-re_words = _lazy_re_compile(r"<[^>]+?>|([^<>\s]+)", re.S)
-re_chars = _lazy_re_compile(r"<[^>]+?>|(.)", re.S)
-re_tag = _lazy_re_compile(r"<(/)?(\S+?)(?:(\s*/)|\s.*?)?>", re.S)
+_re_words = _lazy_re_compile(r"<[^>]+?>|([^<>\s]+)", re.S)
+_re_chars = _lazy_re_compile(r"<[^>]+?>|(.)", re.S)
+_re_tag = _lazy_re_compile(r"<(/)?(\S+?)(?:(\s*/)|\s.*?)?>", re.S)
 
 
 class Truncator(SimpleLazyObject):
@@ -15,10 +18,12 @@ class Truncator(SimpleLazyObject):
     An object used to truncate text, either by characters or words.
     """
 
-    def __init__(self, text):
+    _wrapped: str  # Override parent type since we always store str
+
+    def __init__(self, text: Any):
         super().__init__(lambda: str(text))
 
-    def add_truncation_text(self, text, truncate=None):
+    def add_truncation_text(self, text: str, truncate: str | None = None) -> str:
         if truncate is None:
             truncate = "%(truncated_text)s…"
         if "%(truncated_text)s" in truncate:
@@ -31,7 +36,7 @@ class Truncator(SimpleLazyObject):
             return text
         return f"{text}{truncate}"
 
-    def chars(self, num, truncate=None, html=False):
+    def chars(self, num: int, truncate: str | None = None, html: bool = False) -> str:
         """
         Return the text truncated to be no longer than the specified number
         of characters.
@@ -54,7 +59,9 @@ class Truncator(SimpleLazyObject):
             return self._truncate_html(length, truncate, text, truncate_len, False)
         return self._text_chars(length, truncate, text, truncate_len)
 
-    def _text_chars(self, length, truncate, text, truncate_len):
+    def _text_chars(
+        self, length: int, truncate: str | None, text: str, truncate_len: int
+    ) -> str:
         """Truncate a string after a certain number of chars."""
         s_len = 0
         end_index = None
@@ -73,7 +80,7 @@ class Truncator(SimpleLazyObject):
         # Return the original string since no truncation was necessary
         return text
 
-    def words(self, num, truncate=None, html=False):
+    def words(self, num: int, truncate: str | None = None, html: bool = False) -> str:
         """
         Truncate a string after a certain number of words. `truncate` specifies
         what should be used to notify that the string has been truncated,
@@ -85,7 +92,7 @@ class Truncator(SimpleLazyObject):
             return self._truncate_html(length, truncate, self._wrapped, length, True)
         return self._text_words(length, truncate)
 
-    def _text_words(self, length, truncate):
+    def _text_words(self, length: int, truncate: str | None) -> str:
         """
         Truncate a string after a certain number of words.
 
@@ -97,7 +104,14 @@ class Truncator(SimpleLazyObject):
             return self.add_truncation_text(" ".join(words), truncate)
         return " ".join(words)
 
-    def _truncate_html(self, length, truncate, text, truncate_len, words):
+    def _truncate_html(
+        self,
+        length: int,
+        truncate: str | None,
+        text: str,
+        truncate_len: int,
+        words: bool,
+    ) -> str:
         """
         Truncate HTML to a certain number of chars (not counting tags and
         comments), or, if words is True, then to a certain number of words.
@@ -126,7 +140,7 @@ class Truncator(SimpleLazyObject):
         current_len = 0
         open_tags = []
 
-        regex = re_words if words else re_chars
+        regex = _re_words if words else _re_chars
 
         while current_len <= length:
             m = regex.search(text, pos)
@@ -141,7 +155,7 @@ class Truncator(SimpleLazyObject):
                     end_text_pos = pos
                 continue
             # Check for tag
-            tag = re_tag.match(m[0])
+            tag = _re_tag.match(m[0])
             if not tag or current_len >= truncate_len:
                 # Don't worry about non tags or tags after our truncate point
                 continue
@@ -178,7 +192,7 @@ class Truncator(SimpleLazyObject):
 
 
 @keep_lazy_text
-def slugify(value, allow_unicode=False):
+def slugify(value: Any, allow_unicode: bool = False) -> str:
     """
     Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
     dashes to single dashes. Remove characters that aren't alphanumerics,
@@ -198,18 +212,22 @@ def slugify(value, allow_unicode=False):
     return re.sub(r"[-\s]+", "-", value).strip("-_")
 
 
-def pluralize(singular, plural, number):
+def pluralize(singular: str, plural: str, number: int) -> str:
     if number == 1:
         return singular
     else:
         return plural
 
 
-def pluralize_lazy(singular, plural, number):
-    def _lazy_number_unpickle(func, resultclass, number, kwargs):
+def pluralize_lazy(singular: str, plural: str, number: int | str) -> Any:
+    def _lazy_number_unpickle(
+        func: Any, resultclass: Any, number: Any, kwargs: dict[str, Any]
+    ) -> Any:
         return lazy_number(func, resultclass, number=number, **kwargs)
 
-    def lazy_number(func, resultclass, number=None, **kwargs):
+    def lazy_number(
+        func: Any, resultclass: Any, number: int | str | None = None, **kwargs: Any
+    ) -> Any:
         if isinstance(number, int):
             kwargs["number"] = number
             proxy = lazy(func, resultclass)(**kwargs)
@@ -217,12 +235,12 @@ def pluralize_lazy(singular, plural, number):
             original_kwargs = kwargs.copy()
 
             class NumberAwareString(resultclass):
-                def __bool__(self):
+                def __bool__(self) -> bool:
                     return bool(kwargs["singular"])
 
-                def _get_number_value(self, values):
+                def _get_number_value(self, values: dict[str, Any]) -> Any:
                     try:
-                        return values[number]
+                        return values[number]  # type: ignore[index]
                     except KeyError:
                         raise KeyError(
                             f"Your dictionary lacks key '{number}'. Please provide "
@@ -230,17 +248,17 @@ def pluralize_lazy(singular, plural, number):
                             "string is singular or plural."
                         )
 
-                def _translate(self, number_value):
+                def _translate(self, number_value: int) -> str:
                     kwargs["number"] = number_value
                     return func(**kwargs)
 
-                def format(self, *args, **kwargs):
+                def format(self, *args: Any, **kwargs: Any) -> str:
                     number_value = (
                         self._get_number_value(kwargs) if kwargs and number else args[0]
                     )
                     return self._translate(number_value).format(*args, **kwargs)
 
-                def __mod__(self, rhs):
+                def __mod__(self, rhs: Any) -> str:
                     if isinstance(rhs, dict) and number:
                         number_value = self._get_number_value(rhs)
                     else:

plain/utils/timezone.py

@@ -2,11 +2,14 @@
 Timezone-related classes and functions.
 """
 
+from __future__ import annotations
+
 import functools
 import zoneinfo
 from contextlib import ContextDecorator
-from datetime import UTC, datetime, timedelta, timezone, tzinfo
+from datetime import UTC, datetime, time, timedelta, timezone, tzinfo
 from threading import local
+from types import TracebackType
 
 from plain.runtime import settings
 
@@ -28,10 +31,10 @@ __all__ = [
 ]
 
 
-def get_fixed_timezone(offset):
+def get_fixed_timezone(offset: int | timedelta) -> timezone:
     """Return a tzinfo instance with a fixed offset from UTC."""
     if isinstance(offset, timedelta):
-        offset = offset.total_seconds() // 60
+        offset = int(offset.total_seconds() // 60)
     sign = "-" if offset < 0 else "+"
     hhmm = "%02d%02d" % divmod(abs(offset), 60)  # noqa: UP031
     name = sign + hhmm
@@ -41,7 +44,7 @@ def get_fixed_timezone(offset):
 # In order to avoid accessing settings at compile time,
 # wrap the logic in a function and cache the result.
 @functools.lru_cache
-def get_default_timezone():
+def get_default_timezone() -> zoneinfo.ZoneInfo:
     """
     Return the default time zone as a tzinfo instance.
 
@@ -51,7 +54,7 @@ def get_default_timezone():
 
 
 # This function exists for consistency with get_current_timezone_name
-def get_default_timezone_name():
+def get_default_timezone_name() -> str:
     """Return the name of the default time zone."""
     return _get_timezone_name(get_default_timezone())
 
@@ -59,17 +62,17 @@ def get_default_timezone_name():
 _active = local()
 
 
-def get_current_timezone():
+def get_current_timezone() -> tzinfo:
     """Return the currently active time zone as a tzinfo instance."""
     return getattr(_active, "value", get_default_timezone())
 
 
-def get_current_timezone_name():
+def get_current_timezone_name() -> str:
     """Return the name of the currently active time zone."""
     return _get_timezone_name(get_current_timezone())
 
 
-def _get_timezone_name(timezone):
+def _get_timezone_name(timezone: tzinfo) -> str:
     """
     Return the offset for fixed offset timezones, or the name of timezone if
     not set.
@@ -83,7 +86,7 @@ def _get_timezone_name(timezone):
 # because it isn't thread safe.
 
 
-def activate(timezone):
+def activate(timezone: tzinfo | str) -> None:
     """
     Set the time zone for the current thread.
 
@@ -98,7 +101,7 @@ def activate(timezone):
         raise ValueError(f"Invalid timezone: {timezone!r}")
 
 
-def deactivate():
+def deactivate() -> None:
     """
     Unset the time zone for the current thread.
 
@@ -121,17 +124,23 @@ class override(ContextDecorator):
     time zone.
     """
 
-    def __init__(self, timezone):
+    def __init__(self, timezone: tzinfo | str | None) -> None:
         self.timezone = timezone
+        self.old_timezone: tzinfo | None = None
 
-    def __enter__(self):
+    def __enter__(self) -> None:
         self.old_timezone = getattr(_active, "value", None)
         if self.timezone is None:
             deactivate()
         else:
             activate(self.timezone)
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         if self.old_timezone is None:
             deactivate()
         else:
@@ -141,7 +150,9 @@ class override(ContextDecorator):
 # Utilities
 
 
-def localtime(value=None, timezone=None):
+def localtime(
+    value: datetime | None = None, timezone: tzinfo | None = None
+) -> datetime:
     """
     Convert an aware datetime.datetime to local time.
 
@@ -161,7 +172,7 @@ def localtime(value=None, timezone=None):
     return value.astimezone(timezone)
 
 
-def now():
+def now() -> datetime:
     """
     Return a timezone aware datetime.
     """
@@ -172,9 +183,9 @@ def now():
 # The caller should ensure that they don't receive an invalid value like None.
 
 
-def is_aware(value):
+def is_aware(value: datetime | time) -> bool:
     """
-    Determine if a given datetime.datetime is aware.
+    Determine if a given datetime.datetime or datetime.time is aware.
 
     The concept is defined in Python's docs:
     https://docs.python.org/library/datetime.html#datetime.tzinfo
@@ -185,9 +196,9 @@ def is_aware(value):
     return value.utcoffset() is not None
 
 
-def is_naive(value):
+def is_naive(value: datetime | time) -> bool:
     """
-    Determine if a given datetime.datetime is naive.
+    Determine if a given datetime.datetime or datetime.time is naive.
 
     The concept is defined in Python's docs:
     https://docs.python.org/library/datetime.html#datetime.tzinfo
@@ -198,7 +209,7 @@ def is_naive(value):
     return value.utcoffset() is None
 
 
-def make_aware(value, timezone=None):
+def make_aware(value: datetime, timezone: tzinfo | None = None) -> datetime:
     """Make a naive datetime.datetime in a given time zone aware."""
     if timezone is None:
         timezone = get_current_timezone()
@@ -209,7 +220,7 @@ def make_aware(value, timezone=None):
     return value.replace(tzinfo=timezone)
 
 
-def make_naive(value, timezone=None):
+def make_naive(value: datetime, timezone: tzinfo | None = None) -> datetime:
     """Make an aware datetime.datetime naive in a given time zone."""
     if timezone is None:
         timezone = get_current_timezone()
@@ -219,5 +230,5 @@ def make_naive(value, timezone=None):
     return value.astimezone(timezone).replace(tzinfo=None)
 
 
-def _datetime_ambiguous_or_imaginary(dt, tz):
+def _datetime_ambiguous_or_imaginary(dt: datetime, tz: tzinfo) -> bool:
     return tz.utcoffset(dt.replace(fold=not dt.fold)) != tz.utcoffset(dt)