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

plain/utils/functional.py

@@ -1,7 +1,13 @@
+from __future__ import annotations
+
 import copy
 import itertools
 import operator
+from collections.abc import Callable
 from functools import total_ordering, wraps
+from typing import Any, TypeVar
+
+T = TypeVar("T")
 
 
 class classproperty:
@@ -10,13 +16,15 @@ class classproperty:
     that can be accessed directly from the class.
     """
 
-    def __init__(self, method=None):
+    def __init__(self, method: Callable[[type], Any] | None = None) -> None:
         self.fget = method
 
-    def __get__(self, instance, cls=None):
+    def __get__(self, instance: Any, cls: type | None = None) -> Any:
+        assert cls is not None, "cls must be provided for classproperty"
+        assert self.fget is not None, "fget must be set before accessing classproperty"
         return self.fget(cls)
 
-    def getter(self, method):
+    def getter(self, method: Callable[[type], Any]) -> classproperty:
         self.fget = method
         return self
 
@@ -30,7 +38,7 @@ class Promise:
     pass
 
 
-def lazy(func, *resultclasses):
+def lazy(func: Callable[..., Any], *resultclasses: type) -> Callable[..., Any]:
     """
     Turn any callable into a lazy evaluated callable. result classes or types
     is required -- at least one is needed so that the automatic forcing of
@@ -48,24 +56,24 @@ def lazy(func, *resultclasses):
 
         __prepared = False
 
-        def __init__(self, args, kw):
+        def __init__(self, args: tuple[Any, ...], kw: dict[str, Any]) -> None:
             self.__args = args
             self.__kw = kw
             if not self.__prepared:
                 self.__prepare_class__()
             self.__class__.__prepared = True
 
-        def __reduce__(self):
+        def __reduce__(self) -> tuple[Callable[..., Any], tuple[Any, ...]]:
             return (
                 _lazy_proxy_unpickle,
                 (func, self.__args, self.__kw) + resultclasses,
             )
 
-        def __repr__(self):
+        def __repr__(self) -> str:
             return repr(self.__cast())
 
         @classmethod
-        def __prepare_class__(cls):
+        def __prepare_class__(cls) -> None:
             for resultclass in resultclasses:
                 for type_ in resultclass.mro():
                     for method_name in type_.__dict__:
@@ -82,14 +90,14 @@ def lazy(func, *resultclasses):
                     "Cannot call lazy() with both bytes and text return types."
                 )
             if cls._delegate_text:
-                cls.__str__ = cls.__text_cast
+                setattr(cls, "__str__", cls.__text_cast)
             elif cls._delegate_bytes:
-                cls.__bytes__ = cls.__bytes_cast
+                setattr(cls, "__bytes__", cls.__bytes_cast)
 
         @classmethod
-        def __promise__(cls, method_name):
+        def __promise__(cls, method_name: str) -> Callable[..., Any]:
             # Builds a wrapper around some magic method
-            def __wrapper__(self, *args, **kw):
+            def __wrapper__(self: Any, *args: Any, **kw: Any) -> Any:
                 # Automatically triggers the evaluation of a lazy value and
                 # applies the given magic method of the result type.
                 res = func(*self.__args, **self.__kw)
@@ -97,16 +105,16 @@ def lazy(func, *resultclasses):
 
             return __wrapper__
 
-        def __text_cast(self):
+        def __text_cast(self) -> str:
             return func(*self.__args, **self.__kw)
 
-        def __bytes_cast(self):
+        def __bytes_cast(self) -> bytes:
             return bytes(func(*self.__args, **self.__kw))
 
-        def __bytes_cast_encoded(self):
+        def __bytes_cast_encoded(self) -> bytes:
             return func(*self.__args, **self.__kw).encode()
 
-        def __cast(self):
+        def __cast(self) -> Any:
             if self._delegate_bytes:
                 return self.__bytes_cast()
             elif self._delegate_text:
@@ -114,36 +122,36 @@ def lazy(func, *resultclasses):
             else:
                 return func(*self.__args, **self.__kw)
 
-        def __str__(self):
+        def __str__(self) -> str:
             # object defines __str__(), so __prepare_class__() won't overload
             # a __str__() method from the proxied class.
             return str(self.__cast())
 
-        def __eq__(self, other):
+        def __eq__(self, other: Any) -> bool:
             if isinstance(other, Promise):
                 other = other.__cast()
             return self.__cast() == other
 
-        def __lt__(self, other):
+        def __lt__(self, other: Any) -> bool:
             if isinstance(other, Promise):
                 other = other.__cast()
             return self.__cast() < other
 
-        def __hash__(self):
+        def __hash__(self) -> int:
             return hash(self.__cast())
 
-        def __mod__(self, rhs):
+        def __mod__(self, rhs: Any) -> Any:
             if self._delegate_text:
                 return str(self) % rhs
             return self.__cast() % rhs
 
-        def __add__(self, other):
+        def __add__(self, other: Any) -> Any:
             return self.__cast() + other
 
-        def __radd__(self, other):
+        def __radd__(self, other: Any) -> Any:
             return other + self.__cast()
 
-        def __deepcopy__(self, memo):
+        def __deepcopy__(self, memo: dict[int, Any]) -> __proxy__:
             # Instances of this class are effectively immutable. It's just a
             # collection of functions. So we don't need to do anything
             # complicated for copying.
@@ -151,18 +159,25 @@ def lazy(func, *resultclasses):
             return self
 
     @wraps(func)
-    def __wrapper__(*args, **kw):
+    def __wrapper__(*args: Any, **kw: Any) -> __proxy__:
         # Creates the proxy object, instead of the actual value.
         return __proxy__(args, kw)
 
     return __wrapper__
 
 
-def _lazy_proxy_unpickle(func, args, kwargs, *resultclasses):
+def _lazy_proxy_unpickle(
+    func: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *resultclasses: type,
+) -> Any:
     return lazy(func, *resultclasses)(*args, **kwargs)
 
 
-def keep_lazy(*resultclasses):
+def keep_lazy(
+    *resultclasses: type,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """
     A decorator that allows a function to be called with one or more lazy
     arguments. If none of the args are lazy, the function is evaluated
@@ -172,11 +187,11 @@ def keep_lazy(*resultclasses):
     if not resultclasses:
         raise TypeError("You must pass at least one argument to keep_lazy().")
 
-    def decorator(func):
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         lazy_func = lazy(func, *resultclasses)
 
         @wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
             if any(
                 isinstance(arg, Promise)
                 for arg in itertools.chain(args, kwargs.values())
@@ -189,7 +204,7 @@ def keep_lazy(*resultclasses):
     return decorator
 
 
-def keep_lazy_text(func):
+def keep_lazy_text(func: Callable[..., Any]) -> Callable[..., Any]:
     """
     A decorator for functions that accept lazy arguments and return text.
     """
@@ -199,14 +214,14 @@ def keep_lazy_text(func):
 empty = object()
 
 
-def new_method_proxy(func):
-    def inner(self, *args):
+def new_method_proxy(func: Callable[..., Any]) -> Callable[..., Any]:
+    def inner(self: Any, *args: Any) -> Any:
         if (_wrapped := self._wrapped) is empty:
             self._setup()
             _wrapped = self._wrapped
         return func(_wrapped, *args)
 
-    inner._mask_wrapped = False
+    inner._mask_wrapped = False  # type: ignore[attr-defined]
     return inner
 
 
@@ -227,7 +242,7 @@ class LazyObject:
         # override __copy__() and __deepcopy__() as well.
         self._wrapped = empty
 
-    def __getattribute__(self, name):
+    def __getattribute__(self, name: str) -> Any:
         if name == "_wrapped":
             # Avoid recursion when getting wrapped object.
             return super().__getattribute__(name)
@@ -240,7 +255,7 @@ class LazyObject:
 
     __getattr__ = new_method_proxy(getattr)
 
-    def __setattr__(self, name, value):
+    def __setattr__(self, name: str, value: Any) -> None:
         if name == "_wrapped":
             # Assign to __dict__ to avoid infinite __setattr__ loops.
             self.__dict__["_wrapped"] = value
@@ -249,14 +264,14 @@ class LazyObject:
                 self._setup()
             setattr(self._wrapped, name, value)
 
-    def __delattr__(self, name):
+    def __delattr__(self, name: str) -> None:
         if name == "_wrapped":
             raise TypeError("can't delete _wrapped.")
         if self._wrapped is empty:
             self._setup()
         delattr(self._wrapped, name)
 
-    def _setup(self):
+    def _setup(self) -> None:
         """
         Must be implemented by subclasses to initialize the wrapped object.
         """
@@ -278,12 +293,12 @@ class LazyObject:
     # pickle the wrapped object as the unpickler's argument, so that pickle
     # will pickle it normally, and then the unpickler simply returns its
     # argument.
-    def __reduce__(self):
+    def __reduce__(self) -> tuple[Callable[[Any], Any], tuple[Any, ...]]:
         if self._wrapped is empty:
             self._setup()
         return (unpickle_lazyobject, (self._wrapped,))
 
-    def __copy__(self):
+    def __copy__(self) -> LazyObject | Any:
         if self._wrapped is empty:
             # If uninitialized, copy the wrapper. Use type(self), not
             # self.__class__, because the latter is proxied.
@@ -292,7 +307,7 @@ class LazyObject:
             # If initialized, return a copy of the wrapped object.
             return copy.copy(self._wrapped)
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> LazyObject | Any:
         if self._wrapped is empty:
             # We have to use type(self), not self.__class__, because the
             # latter is proxied.
@@ -326,7 +341,7 @@ class LazyObject:
     __contains__ = new_method_proxy(operator.contains)
 
 
-def unpickle_lazyobject(wrapped):
+def unpickle_lazyobject(wrapped: Any) -> Any:
     """
     Used to unpickle lazy objects. Just return its argument, which will be the
     wrapped object.
@@ -342,7 +357,7 @@ class SimpleLazyObject(LazyObject):
     known type, use plain.utils.functional.lazy.
     """
 
-    def __init__(self, func):
+    def __init__(self, func: Callable[[], Any]) -> None:
         """
         Pass in a callable that returns the object to be wrapped.
 
@@ -354,19 +369,19 @@ class SimpleLazyObject(LazyObject):
         self.__dict__["_setupfunc"] = func
         super().__init__()
 
-    def _setup(self):
+    def _setup(self) -> None:
         self._wrapped = self._setupfunc()
 
     # Return a meaningful representation of the lazy object for debugging
     # without evaluating the wrapped object.
-    def __repr__(self):
+    def __repr__(self) -> str:
         if self._wrapped is empty:
             repr_attr = self._setupfunc
         else:
             repr_attr = self._wrapped
         return f"<{type(self).__name__}: {repr_attr!r}>"
 
-    def __copy__(self):
+    def __copy__(self) -> SimpleLazyObject | Any:
         if self._wrapped is empty:
             # If uninitialized, copy the wrapper. Use SimpleLazyObject, not
             # self.__class__, because the latter is proxied.
@@ -375,7 +390,7 @@ class SimpleLazyObject(LazyObject):
             # If initialized, return a copy of the wrapped object.
             return copy.copy(self._wrapped)
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> SimpleLazyObject | Any:
         if self._wrapped is empty:
             # We have to use SimpleLazyObject, not self.__class__, because the
             # latter is proxied.
@@ -387,11 +402,13 @@ class SimpleLazyObject(LazyObject):
     __add__ = new_method_proxy(operator.add)
 
     @new_method_proxy
-    def __radd__(self, other):
+    def __radd__(self: Any, other: Any) -> Any:
         return other + self
 
 
-def partition(predicate, values):
+def partition(
+    predicate: Callable[[Any], bool], values: Any
+) -> tuple[list[Any], list[Any]]:
     """
     Split the values into two sets, based on the return value of the function
     (True/False). e.g.:
@@ -399,7 +416,7 @@ def partition(predicate, values):
         >>> partition(lambda x: x > 3, range(5))
         [0, 1, 2, 3], [4]
     """
-    results = ([], [])
+    results: tuple[list[Any], list[Any]] = ([], [])
     for item in values:
         results[predicate(item)].append(item)
     return results

plain/utils/hashable.py

@@ -1,7 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.utils.itercompat import is_iterable
 
 
-def make_hashable(value):
+def make_hashable(value: Any) -> Any:
     """
     Attempt to make value hashable or raise a TypeError if it fails.
 

plain/utils/html.py

@@ -1,15 +1,19 @@
 """HTML utilities suitable for global use."""
 
+from __future__ import annotations
+
 import html
 import json
 from html.parser import HTMLParser
+from typing import Any
 
+from plain.internal import internalcode
 from plain.utils.functional import Promise, keep_lazy, keep_lazy_text
 from plain.utils.safestring import SafeString, mark_safe
 
 
 @keep_lazy(SafeString)
-def escape(text):
+def escape(text: Any) -> SafeString:
     """
     Return the given text with ampersands, quotes and angle brackets encoded
     for use in HTML.
@@ -28,27 +32,36 @@ _json_script_escapes = {
 }
 
 
-def json_script(value, element_id=None, encoder=None):
+def json_script(
+    value: Any,
+    element_id: str | None = None,
+    nonce: str = "",
+    encoder: type[json.JSONEncoder] | None = None,
+) -> SafeString:
     """
     Escape all the HTML/XML special characters with their unicode escapes, so
     value is safe to be output anywhere except for inside a tag attribute. Wrap
     the escaped JSON in a script tag.
+
+    Args:
+        value: The data to encode as JSON
+        element_id: Optional ID attribute for the script tag
+        nonce: Optional CSP nonce for inline script tags
+        encoder: Optional custom JSON encoder class
     """
     from plain.json import PlainJSONEncoder
 
     json_str = json.dumps(value, cls=encoder or PlainJSONEncoder).translate(
         _json_script_escapes
     )
-    if element_id:
-        template = '<script id="{}" type="application/json">{}</script>'
-        args = (element_id, mark_safe(json_str))
-    else:
-        template = '<script type="application/json">{}</script>'
-        args = (mark_safe(json_str),)
-    return format_html(template, *args)
+    id_attr = f' id="{element_id}"' if element_id else ""
+    nonce_attr = f' nonce="{nonce}"' if nonce else ""
+    return mark_safe(
+        f'<script{id_attr}{nonce_attr} type="application/json">{json_str}</script>'
+    )
 
 
-def conditional_escape(text):
+def conditional_escape(text: Any) -> SafeString | str:
     """
     Similar to escape(), except that it doesn't operate on pre-escaped strings.
 
@@ -58,12 +71,12 @@ def conditional_escape(text):
     if isinstance(text, Promise):
         text = str(text)
     if hasattr(text, "__html__"):
-        return text.__html__()
+        return text.__html__()  # type: ignore[union-attr]
     else:
         return escape(text)
 
 
-def format_html(format_string, *args, **kwargs):
+def format_html(format_string: str, *args: Any, **kwargs: Any) -> SafeString:
     """
     Similar to str.format, but pass all arguments through conditional_escape(),
     and call mark_safe() on the result. This function should be used instead
@@ -74,26 +87,27 @@ def format_html(format_string, *args, **kwargs):
     return mark_safe(format_string.format(*args_safe, **kwargs_safe))
 
 
+@internalcode
 class MLStripper(HTMLParser):
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__(convert_charrefs=False)
         self.reset()
-        self.fed = []
+        self.fed: list[str] = []
 
-    def handle_data(self, d):
-        self.fed.append(d)
+    def handle_data(self, data: str) -> None:
+        self.fed.append(data)
 
-    def handle_entityref(self, name):
+    def handle_entityref(self, name: str) -> None:
         self.fed.append(f"&{name};")
 
-    def handle_charref(self, name):
+    def handle_charref(self, name: str) -> None:
         self.fed.append(f"&#{name};")
 
-    def get_data(self):
+    def get_data(self) -> str:
         return "".join(self.fed)
 
 
-def _strip_once(value):
+def _strip_once(value: str) -> str:
     """
     Internal tag stripping utility used by strip_tags.
     """
@@ -104,7 +118,7 @@ def _strip_once(value):
 
 
 @keep_lazy_text
-def strip_tags(value):
+def strip_tags(value: Any) -> str:
     """Return the given HTML with all tags stripped."""
     # Note: in typical case this loop executes _strip_once once. Loop condition
     # is redundant, but helps to reduce number of executions of _strip_once.
@@ -118,7 +132,7 @@ def strip_tags(value):
     return value
 
 
-def avoid_wrapping(value):
+def avoid_wrapping(value: str) -> str:
     """
     Avoid text wrapping in the middle of a phrase by adding non-breaking
     spaces where there previously were normal spaces.

plain/utils/http.py

@@ -1,4 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import Generator, Iterable
 from email.utils import formatdate
+from typing import Any
 from urllib.parse import quote, unquote
 from urllib.parse import urlencode as original_urlencode
 
@@ -7,7 +11,10 @@ from plain.utils.datastructures import MultiValueDict
 RFC3986_SUBDELIMS = "!$&'()*+,;="
 
 
-def urlencode(query, doseq=False):
+def urlencode(
+    query: MultiValueDict | dict[str, Any] | Iterable[tuple[str, Any]],
+    doseq: bool = False,
+) -> str:
     """
     A version of Python's urllib.parse.urlencode() function that can operate on
     MultiValueDict and non-string values.
@@ -15,7 +22,7 @@ def urlencode(query, doseq=False):
     if isinstance(query, MultiValueDict):
         query = query.lists()
     elif hasattr(query, "items"):
-        query = query.items()
+        query = query.items()  # type: ignore[union-attr]
     query_params = []
     for key, value in query:
         if value is None:
@@ -48,7 +55,7 @@ def urlencode(query, doseq=False):
     return original_urlencode(query_params, doseq)
 
 
-def http_date(epoch_seconds=None):
+def http_date(epoch_seconds: float | None = None) -> str:
     """
     Format the time to match the RFC 5322 date format as specified by RFC 9110
     Section 5.6.7.
@@ -65,7 +72,7 @@ def http_date(epoch_seconds=None):
 # Base 36 functions: useful for generating compact URLs
 
 
-def base36_to_int(s):
+def base36_to_int(s: str) -> int:
     """
     Convert a base 36 string to an int. Raise ValueError if the input won't fit
     into an int.
@@ -78,7 +85,7 @@ def base36_to_int(s):
     return int(s, 36)
 
 
-def int_to_base36(i):
+def int_to_base36(i: int) -> str:
     """Convert an integer to a base36 string."""
     char_set = "0123456789abcdefghijklmnopqrstuvwxyz"
     if i < 0:
@@ -92,7 +99,7 @@ def int_to_base36(i):
     return b36
 
 
-def escape_leading_slashes(url):
+def escape_leading_slashes(url: str) -> str:
     """
     If redirecting to an absolute path (two leading slashes), a slash must be
     escaped to prevent browsers from handling the path as schemaless and
@@ -103,7 +110,7 @@ def escape_leading_slashes(url):
     return url
 
 
-def _parseparam(s):
+def _parseparam(s: str) -> Generator[str, None, None]:
     while s[:1] == ";":
         s = s[1:]
         end = s.find(";")
@@ -116,7 +123,7 @@ def _parseparam(s):
         s = s[end:]
 
 
-def parse_header_parameters(line):
+def parse_header_parameters(line: str) -> tuple[str, dict[str, str]]:
     """
     Parse a Content-type like header.
     Return the main content-type and a dictionary of options.
@@ -146,7 +153,7 @@ def parse_header_parameters(line):
     return key, pdict
 
 
-def content_disposition_header(as_attachment, filename):
+def content_disposition_header(as_attachment: bool, filename: str) -> str | None:
     """
     Construct a Content-Disposition HTTP header value from the given filename
     as specified by RFC 6266.

plain/utils/inspect.py

@@ -1,22 +1,30 @@
+from __future__ import annotations
+
 import functools
 import inspect
+from collections.abc import Callable
+from typing import Any
 
 
 @functools.lru_cache(maxsize=512)
-def _get_func_parameters(func, remove_first):
+def _get_func_parameters(
+    func: Callable[..., Any], remove_first: bool
+) -> tuple[inspect.Parameter, ...]:
     parameters = tuple(inspect.signature(func).parameters.values())
     if remove_first:
         parameters = parameters[1:]
     return parameters
 
 
-def _get_callable_parameters(meth_or_func):
+def _get_callable_parameters(
+    meth_or_func: Callable[..., Any],
+) -> tuple[inspect.Parameter, ...]:
     is_method = inspect.ismethod(meth_or_func)
-    func = meth_or_func.__func__ if is_method else meth_or_func
+    func = meth_or_func.__func__ if is_method else meth_or_func  # type: ignore[union-attr]
     return _get_func_parameters(func, remove_first=is_method)
 
 
-def get_func_args(func):
+def get_func_args(func: Callable[..., Any]) -> list[str]:
     params = _get_callable_parameters(func)
     return [
         param.name
@@ -25,12 +33,12 @@ def get_func_args(func):
     ]
 
 
-def func_accepts_kwargs(func):
+def func_accepts_kwargs(func: Callable[..., Any]) -> bool:
     """Return True if function 'func' accepts keyword arguments **kwargs."""
     return any(p for p in _get_callable_parameters(func) if p.kind == p.VAR_KEYWORD)
 
 
-def method_has_no_args(meth):
+def method_has_no_args(meth: Callable[..., Any]) -> bool:
     """Return True if a method only accepts 'self'."""
     count = len(
         [p for p in _get_callable_parameters(meth) if p.kind == p.POSITIONAL_OR_KEYWORD]

plain/utils/ipv6.py

@@ -1,11 +1,15 @@
+from __future__ import annotations
+
 import ipaddress
 
 from plain.exceptions import ValidationError
 
 
 def clean_ipv6_address(
-    ip_str, unpack_ipv4=False, error_message="This is not a valid IPv6 address."
-):
+    ip_str: str,
+    unpack_ipv4: bool = False,
+    error_message: str = "This is not a valid IPv6 address.",
+) -> str:
     """
     Clean an IPv6 address string.
 
@@ -35,7 +39,7 @@ def clean_ipv6_address(
     return str(addr)
 
 
-def is_valid_ipv6_address(ip_str):
+def is_valid_ipv6_address(ip_str: str) -> bool:
     """
     Return whether or not the `ip_str` string is a valid IPv6 address.
     """

plain/utils/itercompat.py

@@ -1,4 +1,9 @@
-def is_iterable(x):
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_iterable(x: Any) -> bool:
     "An implementation independent way of checking for iterables"
     try:
         iter(x)