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

plain/utils/datastructures.py

@@ -1,5 +1,12 @@
+from __future__ import annotations
+
+import builtins
 import copy
-from collections.abc import Mapping
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from typing import Any, TypeVar
+
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
 
 
 class OrderedSet:
@@ -7,37 +14,37 @@ class OrderedSet:
     A set which keeps the ordering of the inserted items.
     """
 
-    def __init__(self, iterable=None):
-        self.dict = dict.fromkeys(iterable or ())
+    def __init__(self, iterable: Iterable[Any] | None = None) -> None:
+        self.dict: dict[Any, None] = dict.fromkeys(iterable or ())
 
-    def add(self, item):
+    def add(self, item: Any) -> None:
         self.dict[item] = None
 
-    def remove(self, item):
+    def remove(self, item: Any) -> None:
         del self.dict[item]
 
-    def discard(self, item):
+    def discard(self, item: Any) -> None:
         try:
             self.remove(item)
         except KeyError:
             pass
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Any]:
         return iter(self.dict)
 
-    def __reversed__(self):
+    def __reversed__(self) -> Iterator[Any]:
         return reversed(self.dict)
 
-    def __contains__(self, item):
+    def __contains__(self, item: Any) -> bool:
         return item in self.dict
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return bool(self.dict)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.dict)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         data = repr(list(self.dict)) if self.dict else ""
         return f"{self.__class__.__qualname__}({data})"
 
@@ -46,7 +53,7 @@ class MultiValueDictKeyError(KeyError):
     pass
 
 
-class MultiValueDict(dict):
+class MultiValueDict(dict[str, list[Any]]):
     """
     A subclass of dictionary customized to handle multiple values for the
     same key.
@@ -69,13 +76,17 @@ class MultiValueDict(dict):
     single name-value pairs.
     """
 
-    def __init__(self, key_to_list_mapping=()):
+    def __init__(
+        self,
+        key_to_list_mapping: Mapping[str, list[Any]]
+        | Iterable[tuple[str, list[Any]]] = (),
+    ) -> None:
         super().__init__(key_to_list_mapping)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {super().__repr__()}>"
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> Any:
         """
         Return the last data value for this key, or [] if it's an empty list;
         raise KeyError if not found.
@@ -89,13 +100,13 @@ class MultiValueDict(dict):
         except IndexError:
             return []
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: Any) -> None:
         super().__setitem__(key, [value])
 
-    def __copy__(self):
+    def __copy__(self) -> MultiValueDict:
         return self.__class__([(k, v[:]) for k, v in self.lists()])
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: builtins.dict[int, Any]) -> MultiValueDict:
         result = self.__class__()
         memo[id(self)] = result
         for key, value in dict.items(self):
@@ -104,16 +115,16 @@ class MultiValueDict(dict):
             )
         return result
 
-    def __getstate__(self):
+    def __getstate__(self) -> builtins.dict[str, Any]:
         return {**self.__dict__, "_data": {k: self._getlist(k) for k in self}}
 
-    def __setstate__(self, obj_dict):
+    def __setstate__(self, obj_dict: builtins.dict[str, Any]) -> None:
         data = obj_dict.pop("_data", {})
         for k, v in data.items():
             self.setlist(k, v)
         self.__dict__.update(obj_dict)
 
-    def get(self, key, default=None):
+    def get(self, key: str, default: Any = None) -> Any:
         """
         Return the last data value for the passed key. If key doesn't exist
         or value is an empty list, return `default`.
@@ -126,7 +137,9 @@ class MultiValueDict(dict):
             return default
         return val
 
-    def _getlist(self, key, default=None, force_list=False):
+    def _getlist(
+        self, key: str, default: list[Any] | None = None, force_list: bool = False
+    ) -> list[Any] | None:
         """
         Return a list of values for the key.
 
@@ -144,37 +157,39 @@ class MultiValueDict(dict):
                 values = list(values) if values is not None else None
             return values
 
-    def getlist(self, key, default=None):
+    def getlist(self, key: str, default: list[Any] | None = None) -> list[Any]:
         """
         Return the list of values for the key. If key doesn't exist, return a
         default value.
         """
-        return self._getlist(key, default, force_list=True)
+        return self._getlist(key, default, force_list=True)  # type: ignore
 
-    def setlist(self, key, list_):
+    def setlist(self, key: str, list_: list[Any]) -> None:
         super().__setitem__(key, list_)
 
-    def setdefault(self, key, default=None):
+    def setdefault(self, key: str, default: Any = None) -> Any:
         if key not in self:
             self[key] = default
             # Do not return default here because __setitem__() may store
             # another value -- QueryDict.__setitem__() does. Look it up.
         return self[key]
 
-    def setlistdefault(self, key, default_list=None):
+    def setlistdefault(
+        self, key: str, default_list: list[Any] | None = None
+    ) -> list[Any]:
         if key not in self:
             if default_list is None:
                 default_list = []
             self.setlist(key, default_list)
             # Do not return default_list here because setlist() may store
             # another value -- QueryDict.setlist() does. Look it up.
-        return self._getlist(key)
+        return self._getlist(key)  # type: ignore[return-value]
 
-    def appendlist(self, key, value):
+    def appendlist(self, key: str, value: Any) -> None:
         """Append an item to the internal list associated with key."""
         self.setlistdefault(key).append(value)
 
-    def items(self):
+    def items(self) -> Iterator[tuple[str, Any]]:  # type: ignore[override]
         """
         Yield (key, value) pairs, where value is the last item in the list
         associated with the key.
@@ -182,23 +197,23 @@ class MultiValueDict(dict):
         for key in self:
             yield key, self[key]
 
-    def lists(self):
+    def lists(self) -> Iterator[tuple[str, list[Any]]]:
         """Yield (key, list) pairs."""
         return iter(super().items())
 
-    def values(self):
+    def values(self) -> Iterator[Any]:  # type: ignore[override]
         """Yield the last value on every key list."""
         for key in self:
             yield self[key]
 
-    def copy(self):
+    def copy(self) -> MultiValueDict:
         """Return a shallow copy of this object."""
         return copy.copy(self)
 
-    def update(self, *args, **kwargs):
+    def update(self, *args: Any, **kwargs: Any) -> None:
         """Extend rather than replace existing key lists."""
         if len(args) > 1:
-            raise TypeError("update expected at most 1 argument, got %d" % len(args))  # noqa: UP031
+            raise TypeError(f"update expected at most 1 argument, got {len(args)}")
         if args:
             arg = args[0]
             if isinstance(arg, MultiValueDict):
@@ -212,7 +227,7 @@ class MultiValueDict(dict):
         for key, value in kwargs.items():
             self.setlistdefault(key).append(value)
 
-    def dict(self):
+    def dict(self) -> builtins.dict[str, Any]:
         """Return current object as a dict with singular values."""
         return {key: self[key] for key in self}
 
@@ -230,12 +245,19 @@ class ImmutableList(tuple):
         AttributeError: You cannot mutate this.
     """
 
-    def __new__(cls, *args, warning="ImmutableList object is immutable.", **kwargs):
+    warning: str  # Set in __new__
+
+    def __new__(
+        cls,
+        *args: Any,
+        warning: str = "ImmutableList object is immutable.",
+        **kwargs: Any,
+    ) -> ImmutableList:
         self = tuple.__new__(cls, *args, **kwargs)
         self.warning = warning
         return self
 
-    def complain(self, *args, **kwargs):
+    def complain(self, *args: Any, **kwargs: Any) -> None:
         raise AttributeError(self.warning)
 
     # All list mutation functions complain.
@@ -254,7 +276,7 @@ class ImmutableList(tuple):
     reverse = complain
 
 
-class DictWrapper(dict):
+class DictWrapper(dict[str, Any]):
     """
     Wrap accesses to a dictionary so that certain values (those starting with
     the specified prefix) are passed through a function before being returned.
@@ -264,12 +286,14 @@ class DictWrapper(dict):
     quoted before being used.
     """
 
-    def __init__(self, data, func, prefix):
+    def __init__(
+        self, data: dict[str, Any], func: Callable[[Any], Any], prefix: str
+    ) -> None:
         super().__init__(data)
         self.func = func
         self.prefix = prefix
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> Any:
         """
         Retrieve the real value after stripping the prefix string (if
         present). If the prefix is present, pass the value through self.func
@@ -283,7 +307,7 @@ class DictWrapper(dict):
         return value
 
 
-class CaseInsensitiveMapping(Mapping):
+class CaseInsensitiveMapping(Mapping[str, Any]):
     """
     Mapping allowing case-insensitive key lookups. Original case of keys is
     preserved for iteration and string representation.
@@ -301,35 +325,44 @@ class CaseInsensitiveMapping(Mapping):
         {'name': 'Jane'}
     """
 
-    def __init__(self, data):
-        self._store = {k.lower(): (k, v) for k, v in self._unpack_items(data)}
+    def __init__(self, data: Mapping[str, Any] | Iterable[tuple[str, Any]]) -> None:
+        self._store: dict[str, tuple[str, Any]] = {
+            k.lower(): (k, v) for k, v in self._unpack_items(data)
+        }
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> Any:
         return self._store[key.lower()][1]
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._store)
 
-    def __eq__(self, other):
-        return isinstance(other, Mapping) and {
-            k.lower(): v for k, v in self.items()
-        } == {k.lower(): v for k, v in other.items()}
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Mapping):
+            return False
+        return {k.lower(): v for k, v in self.items()} == {
+            k.lower(): v for k, v in other.items() if isinstance(k, str)
+        }
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
         return (original_key for original_key, value in self._store.values())
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return repr(dict(self._store.values()))
 
-    def copy(self):
+    def copy(self) -> CaseInsensitiveMapping:
         return self
 
     @staticmethod
-    def _unpack_items(data):
+    def _unpack_items(
+        data: Mapping[str, Any] | Iterable[tuple[str, Any]],
+    ) -> Iterator[tuple[str, Any]]:
         # Explicitly test for dict first as the common case for performance,
         # avoiding abc's __instancecheck__ and _abc_instancecheck for the
         # general Mapping case.
-        if isinstance(data, dict | Mapping):
+        if isinstance(data, dict):
+            yield from data.items()
+            return
+        if isinstance(data, Mapping):
             yield from data.items()
             return
         for i, elem in enumerate(data):

plain/utils/dateparse.py

@@ -1,10 +1,11 @@
 """Functions to parse datetime objects."""
 
+from __future__ import annotations
+
 # We're using regular expressions rather than time.strptime because:
 # - They provide both validation and parsing.
 # - They're more flexible for datetimes.
 # - The date/datetime/time constructors produce friendlier error messages.
-
 import datetime
 
 from plain.utils.regex_helper import _lazy_re_compile
@@ -64,7 +65,7 @@ postgres_interval_re = _lazy_re_compile(
 )
 
 
-def parse_date(value):
+def parse_date(value: str) -> datetime.date | None:
     """Parse a string and return a datetime.date.
 
     Raise ValueError if the input is well formatted but not a valid date.
@@ -76,9 +77,10 @@ def parse_date(value):
         if match := date_re.match(value):
             kw = {k: int(v) for k, v in match.groupdict().items()}
             return datetime.date(**kw)
+    return None
 
 
-def parse_time(value):
+def parse_time(value: str) -> datetime.time | None:
     """Parse a string and return a datetime.time.
 
     This function doesn't support time zone offsets.
@@ -98,10 +100,10 @@ def parse_time(value):
             kw = match.groupdict()
             kw["microsecond"] = kw["microsecond"] and kw["microsecond"].ljust(6, "0")
             kw = {k: int(v) for k, v in kw.items() if v is not None}
-            return datetime.time(**kw)
+            return datetime.time(**kw)  # type: ignore[arg-type]
 
 
-def parse_datetime(value):
+def parse_datetime(value: str) -> datetime.datetime | None:
     """Parse a string and return a datetime.datetime.
 
     This function supports time zone offsets. When the input contains one,
@@ -127,9 +129,10 @@ def parse_datetime(value):
                 tzinfo = get_fixed_timezone(offset)
             kw = {k: int(v) for k, v in kw.items() if v is not None}
             return datetime.datetime(**kw, tzinfo=tzinfo)
+    return None
 
 
-def parse_duration(value):
+def parse_duration(value: str) -> datetime.timedelta | None:
     """Parse a duration string and return a datetime.timedelta.
 
     The preferred format for durations in Plain is '%d %H:%M:%S.%f'.

plain/utils/deconstruct.py

@@ -1,7 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Callable
 from importlib import import_module
+from typing import Any, TypeVar
+
+T = TypeVar("T")
 
 
-def deconstructible(*args, path=None):
+def deconstructible(
+    *args: type[T], path: str | None = None
+) -> Callable[[type[T]], type[T]] | type[T]:
     """
     Class decorator that allows the decorated class to be serialized
     by the migrations subsystem.
@@ -9,14 +17,14 @@ def deconstructible(*args, path=None):
     The `path` kwarg specifies the import path.
     """
 
-    def decorator(klass):
-        def __new__(cls, *args, **kwargs):
+    def decorator(klass: type[T]) -> type[T]:
+        def __new__(cls: type[T], *args: Any, **kwargs: Any) -> T:
             # We capture the arguments to make returning them trivial
-            obj = super(klass, cls).__new__(cls)
+            obj = super(klass, cls).__new__(cls)  # type: ignore[misc]
             obj._constructor_args = (args, kwargs)
             return obj
 
-        def deconstruct(obj):
+        def deconstruct(obj: Any) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
             """
             Return a 3-tuple of class import path, positional arguments,
             and keyword arguments.
@@ -44,8 +52,8 @@ def deconstructible(*args, path=None):
                 obj._constructor_args[1],
             )
 
-        klass.__new__ = staticmethod(__new__)
-        klass.deconstruct = deconstruct
+        setattr(klass, "__new__", staticmethod(__new__))
+        setattr(klass, "deconstruct", deconstruct)
 
         return klass
 

plain/utils/decorators.py

@@ -1,8 +1,12 @@
 "Functions that help with dynamically creating decorators for views."
 
+from __future__ import annotations
+
+from typing import Any
+
 
 class classonlymethod(classmethod):
-    def __get__(self, instance, cls=None):
+    def __get__(self, instance: object | None, cls: type | None = None) -> Any:
         if instance is not None:
             raise AttributeError(
                 "This method is available only on the class, not on instances."