plain 0.68.1__py3-none-any.whl → 0.70.0__py3-none-any.whl

plain/utils/regex_helper.py

@@ -6,7 +6,11 @@ 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, cast
 
 from plain.utils.functional import SimpleLazyObject
 
@@ -39,7 +43,7 @@ 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:
@@ -193,7 +197,7 @@ def normalize(pattern):
     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
@@ -214,7 +218,7 @@ def next_char(input_iter):
         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 +239,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 +269,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.
@@ -286,7 +294,7 @@ def contains(source, inst):
     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.
@@ -340,15 +348,17 @@ 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)
         else:
             assert not flags, "flags must be empty if regex is passed pre-compiled"
-            return regex
+            return cast(re.Pattern[str] | re.Pattern[bytes], regex)
 
     return SimpleLazyObject(_compile)

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:
         """
         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,5 +1,8 @@
+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
@@ -15,10 +18,10 @@ class Truncator(SimpleLazyObject):
     An object used to truncate text, either by characters or words.
     """
 
-    def __init__(self, text):
+    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 +34,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 +57,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 +78,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 +90,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 +102,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.
@@ -178,7 +190,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 +210,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 +233,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 +246,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 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,7 +183,7 @@ 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) -> bool:
     """
     Determine if a given datetime.datetime is aware.
 
@@ -185,7 +196,7 @@ def is_aware(value):
     return value.utcoffset() is not None
 
 
-def is_naive(value):
+def is_naive(value: datetime) -> bool:
     """
     Determine if a given datetime.datetime is naive.
 
@@ -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)

plain/utils/tree.py

@@ -3,7 +3,10 @@ A class for storing a tree graph. Primarily used for filter constructs in the
 ORM.
 """
 
+from __future__ import annotations
+
 import copy
+from typing import Any
 
 from plain.utils.hashable import make_hashable
 
@@ -17,16 +20,26 @@ class Node:
 
     # Standard connector type. Clients usually won't use this at all and
     # subclasses will usually override the value.
-    default = "DEFAULT"
-
-    def __init__(self, children=None, connector=None, negated=False):
+    default: str = "DEFAULT"
+
+    def __init__(
+        self,
+        children: list[Any] | None = None,
+        connector: str | None = None,
+        negated: bool = False,
+    ) -> None:
         """Construct a new Node. If no connector is given, use the default."""
-        self.children = children[:] if children else []
-        self.connector = connector or self.default
-        self.negated = negated
+        self.children: list[Any] = children[:] if children else []
+        self.connector: str = connector or self.default
+        self.negated: bool = negated
 
     @classmethod
-    def create(cls, children=None, connector=None, negated=False):
+    def create(
+        cls,
+        children: list[Any] | None = None,
+        connector: str | None = None,
+        negated: bool = False,
+    ) -> Node:
         """
         Create a new instance using Node() instead of __init__() as some
         subclasses, e.g. plain.models.query_utils.Q, may implement a custom
@@ -37,38 +50,38 @@ class Node:
         obj.__class__ = cls
         return obj
 
-    def __str__(self):
+    def __str__(self) -> str:
         template = "(NOT (%s: %s))" if self.negated else "(%s: %s)"
         return template % (self.connector, ", ".join(str(c) for c in self.children))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {self}>"
 
-    def __copy__(self):
+    def __copy__(self) -> Node:
         obj = self.create(connector=self.connector, negated=self.negated)
         obj.children = self.children  # Don't [:] as .__init__() via .create() does.
         return obj
 
     copy = __copy__
 
-    def __deepcopy__(self, memodict):
+    def __deepcopy__(self, memodict: dict[int, Any]) -> Node:
         obj = self.create(connector=self.connector, negated=self.negated)
         obj.children = copy.deepcopy(self.children, memodict)
         return obj
 
-    def __len__(self):
+    def __len__(self) -> int:
         """Return the number of children this node has."""
         return len(self.children)
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         """Return whether or not this node has children."""
         return bool(self.children)
 
-    def __contains__(self, other):
+    def __contains__(self, other: Any) -> bool:
         """Return True if 'other' is a direct child of this instance."""
         return other in self.children
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return (
             self.__class__ == other.__class__
             and self.connector == other.connector
@@ -76,7 +89,7 @@ class Node:
             and self.children == other.children
         )
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(
             (
                 self.__class__,
@@ -86,7 +99,7 @@ class Node:
             )
         )
 
-    def add(self, data, conn_type):
+    def add(self, data: Any, conn_type: str) -> Any:
         """
         Combine this tree and the data represented by data using the
         connector conn_type. The combine is done by squashing the node other
@@ -121,6 +134,6 @@ class Node:
             self.children.append(data)
             return data
 
-    def negate(self):
+    def negate(self) -> None:
         """Negate the sense of the root connector."""
         self.negated = not self.negated