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

plain/utils/tree.py

@@ -3,7 +3,13 @@ A class for storing a tree graph. Primarily used for filter constructs in the
 ORM.
 """
 
+from __future__ import annotations
+
 import copy
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from typing import Self
 
 from plain.utils.hashable import make_hashable
 
@@ -17,16 +23,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,
+    ) -> Self:
         """
         Create a new instance using Node() instead of __init__() as some
         subclasses, e.g. plain.models.query_utils.Q, may implement a custom
@@ -35,40 +51,40 @@ class Node:
         """
         obj = Node(children, connector or cls.default, negated)
         obj.__class__ = cls
-        return obj
+        return obj  # type: ignore[return-value]
 
-    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) -> Self:
         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]) -> Self:
         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 +92,7 @@ class Node:
             and self.children == other.children
         )
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(
             (
                 self.__class__,
@@ -86,7 +102,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 +137,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

plain/validators.py

@@ -1,7 +1,11 @@
+from __future__ import annotations
+
 import ipaddress
 import math
 import re
+from collections.abc import Callable
 from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import urlsplit, urlunsplit
 
 from plain.exceptions import ValidationError
@@ -11,23 +15,40 @@ from plain.utils.ipv6 import is_valid_ipv6_address
 from plain.utils.regex_helper import _lazy_re_compile
 from plain.utils.text import pluralize_lazy
 
+if TYPE_CHECKING:
+    from plain.utils.functional import SimpleLazyObject
+
 # These values, if given to validate(), will trigger the self.required check.
 EMPTY_VALUES = (None, "", [], (), {})
 
 
 @deconstructible
 class RegexValidator:
-    regex = ""
+    regex: str | re.Pattern[str] | SimpleLazyObject = ""
     message = "Enter a valid value."
     code = "invalid"
     inverse_match = False
     flags = 0
 
     def __init__(
-        self, regex=None, message=None, code=None, inverse_match=None, flags=None
-    ):
+        self,
+        regex: str | re.Pattern[str] | None = None,
+        message: str | None = None,
+        code: str | None = None,
+        inverse_match: bool | None = None,
+        flags: int | None = None,
+    ) -> None:
+        # Only compile regex if explicitly provided or if class default needs compilation
         if regex is not None:
-            self.regex = regex
+            regex_to_compile: str | re.Pattern[str] = regex
+        elif isinstance(self.regex, str | re.Pattern):
+            # Class-level regex is a string or pattern that needs compilation
+            regex_to_compile = self.regex
+        else:
+            # Class-level regex is already compiled (e.g., in URL Validator subclass)
+            # Don't recompile it
+            regex_to_compile = None
+
         if message is not None:
             self.message = message
         if code is not None:
@@ -36,28 +57,31 @@ class RegexValidator:
             self.inverse_match = inverse_match
         if flags is not None:
             self.flags = flags
-        if self.flags and not isinstance(self.regex, str):
-            raise TypeError(
-                "If the flags are set, regex must be a regular expression string."
-            )
 
-        self.regex = _lazy_re_compile(self.regex, self.flags)
+        # Only compile if we have a regex to compile
+        if regex_to_compile is not None:
+            if self.flags and not isinstance(regex_to_compile, str):
+                raise TypeError(
+                    "If the flags are set, regex must be a regular expression string."
+                )
+            self.regex = _lazy_re_compile(regex_to_compile, self.flags)
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         """
         Validate that the input contains (or does *not* contain, if
         inverse_match is True) a match for the regular expression.
         """
-        regex_matches = self.regex.search(str(value))
+        # self.regex is always a SimpleLazyObject with search() after __init__
+        regex_matches = cast(re.Pattern[str], self.regex).search(str(value))
         invalid_input = regex_matches if self.inverse_match else not regex_matches
         if invalid_input:
             raise ValidationError(self.message, code=self.code, params={"value": value})
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, RegexValidator)
-            and self.regex.pattern == other.regex.pattern
-            and self.regex.flags == other.regex.flags
+            and self.regex.pattern == other.regex.pattern  # type: ignore[union-attr]
+            and self.regex.flags == other.regex.flags  # type: ignore[union-attr]
             and (self.message == other.message)
             and (self.code == other.code)
             and (self.inverse_match == other.inverse_match)
@@ -104,12 +128,12 @@ class URLValidator(RegexValidator):
     schemes = ["http", "https", "ftp", "ftps"]
     unsafe_chars = frozenset("\t\r\n")
 
-    def __init__(self, schemes=None, **kwargs):
+    def __init__(self, schemes: list[str] | None = None, **kwargs: Any) -> None:
         super().__init__(**kwargs)
         if schemes is not None:
             self.schemes = schemes
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         if not isinstance(value, str):
             raise ValidationError(self.message, code=self.code, params={"value": value})
         if self.unsafe_chars.intersection(value):
@@ -182,7 +206,12 @@ class EmailValidator:
     )
     domain_allowlist = ["localhost"]
 
-    def __init__(self, message=None, code=None, allowlist=None):
+    def __init__(
+        self,
+        message: str | None = None,
+        code: str | None = None,
+        allowlist: list[str] | None = None,
+    ) -> None:
         if message is not None:
             self.message = message
         if code is not None:
@@ -190,7 +219,7 @@ class EmailValidator:
         if allowlist is not None:
             self.domain_allowlist = allowlist
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         if not value or "@" not in value:
             raise ValidationError(self.message, code=self.code, params={"value": value})
 
@@ -209,10 +238,11 @@ class EmailValidator:
                 pass
             else:
                 if self.validate_domain_part(domain_part):
-                    return
+                    return None
             raise ValidationError(self.message, code=self.code, params={"value": value})
+        return None
 
-    def validate_domain_part(self, domain_part):
+    def validate_domain_part(self, domain_part: str) -> bool:
         if self.domain_regex.match(domain_part):
             return True
 
@@ -226,7 +256,7 @@ class EmailValidator:
                 pass
         return False
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, EmailValidator)
             and (self.domain_allowlist == other.domain_allowlist)
@@ -238,7 +268,7 @@ class EmailValidator:
 validate_email = EmailValidator()
 
 
-def validate_ipv4_address(value):
+def validate_ipv4_address(value: str) -> None:
     try:
         ipaddress.IPv4Address(value)
     except ValueError:
@@ -247,14 +277,14 @@ def validate_ipv4_address(value):
         )
 
 
-def validate_ipv6_address(value):
+def validate_ipv6_address(value: str) -> None:
     if not is_valid_ipv6_address(value):
         raise ValidationError(
             "Enter a valid IPv6 address.", code="invalid", params={"value": value}
         )
 
 
-def validate_ipv46_address(value):
+def validate_ipv46_address(value: str) -> None:
     try:
         validate_ipv4_address(value)
     except ValidationError:
@@ -275,7 +305,9 @@ ip_address_validator_map = {
 }
 
 
-def ip_address_validators(protocol, unpack_ipv4):
+def ip_address_validators(
+    protocol: str, unpack_ipv4: bool
+) -> tuple[list[Callable[[str], None]], str]:
     """
     Depending on the given parameters, return the appropriate validators for
     the GenericIPAddressField.
@@ -292,14 +324,19 @@ def ip_address_validators(protocol, unpack_ipv4):
         )
 
 
-def int_list_validator(sep=",", message=None, code="invalid", allow_negative=False):
+def int_list_validator(
+    sep: str = ",",
+    message: str | None = None,
+    code: str = "invalid",
+    allow_negative: bool = False,
+) -> RegexValidator:
     regexp = _lazy_re_compile(
         r"^{neg}\d+(?:{sep}{neg}\d+)*\Z".format(
             neg="(-)?" if allow_negative else "",
             sep=re.escape(sep),
         )
     )
-    return RegexValidator(regexp, message=message, code=code)
+    return RegexValidator(regexp, message=message, code=code)  # type: ignore[arg-type]
 
 
 validate_comma_separated_integer_list = int_list_validator(
@@ -312,12 +349,12 @@ class BaseValidator:
     message = "Ensure this value is %(limit_value)s (it is %(show_value)s)."
     code = "limit_value"
 
-    def __init__(self, limit_value, message=None):
+    def __init__(self, limit_value: Any, message: str | None = None) -> None:
         self.limit_value = limit_value
         if message:
             self.message = message
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         cleaned = self.clean(value)
         limit_value = (
             self.limit_value() if callable(self.limit_value) else self.limit_value
@@ -326,7 +363,7 @@ class BaseValidator:
         if self.compare(cleaned, limit_value):
             raise ValidationError(self.message, code=self.code, params=params)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, self.__class__):
             return NotImplemented
         return (
@@ -335,10 +372,10 @@ class BaseValidator:
             and self.code == other.code
         )
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return a is not b
 
-    def clean(self, x):
+    def clean(self, x: Any) -> Any:
         return x
 
 
@@ -347,7 +384,7 @@ class MaxValueValidator(BaseValidator):
     message = "Ensure this value is less than or equal to %(limit_value)s."
     code = "max_value"
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return a > b
 
 
@@ -356,7 +393,7 @@ class MinValueValidator(BaseValidator):
     message = "Ensure this value is greater than or equal to %(limit_value)s."
     code = "min_value"
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return a < b
 
 
@@ -365,7 +402,7 @@ class StepValueValidator(BaseValidator):
     message = "Ensure this value is a multiple of step size %(limit_value)s."
     code = "step_size"
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return not math.isclose(math.remainder(a, b), 0, abs_tol=1e-9)
 
 
@@ -380,10 +417,10 @@ class MinLengthValidator(BaseValidator):
     )
     code = "min_length"
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return a < b
 
-    def clean(self, x):
+    def clean(self, x: Any) -> int:
         return len(x)
 
 
@@ -398,10 +435,10 @@ class MaxLengthValidator(BaseValidator):
     )
     code = "max_length"
 
-    def compare(self, a, b):
+    def compare(self, a: Any, b: Any) -> bool:
         return a > b
 
-    def clean(self, x):
+    def clean(self, x: Any) -> int:
         return len(x)
 
 
@@ -433,11 +470,11 @@ class DecimalValidator:
         ),
     }
 
-    def __init__(self, max_digits, decimal_places):
+    def __init__(self, max_digits: int | None, decimal_places: int | None) -> None:
         self.max_digits = max_digits
         self.decimal_places = decimal_places
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         digit_tuple, exponent = value.as_tuple()[1:]
         if exponent in {"F", "n", "N"}:
             raise ValidationError(
@@ -485,7 +522,7 @@ class DecimalValidator:
                 params={"max": (self.max_digits - self.decimal_places), "value": value},
             )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, self.__class__)
             and self.max_digits == other.max_digits
@@ -495,10 +532,15 @@ class DecimalValidator:
 
 @deconstructible
 class FileExtensionValidator:
-    message = "File extension “%(extension)s” is not allowed. Allowed extensions are: %(allowed_extensions)s."
+    message = 'File extension "%(extension)s" is not allowed. Allowed extensions are: %(allowed_extensions)s.'
     code = "invalid_extension"
 
-    def __init__(self, allowed_extensions=None, message=None, code=None):
+    def __init__(
+        self,
+        allowed_extensions: list[str] | None = None,
+        message: str | None = None,
+        code: str | None = None,
+    ) -> None:
         if allowed_extensions is not None:
             allowed_extensions = [
                 allowed_extension.lower() for allowed_extension in allowed_extensions
@@ -509,7 +551,7 @@ class FileExtensionValidator:
         if code is not None:
             self.code = code
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         extension = Path(value.name).suffix[1:].lower()
         if (
             self.allowed_extensions is not None
@@ -525,7 +567,7 @@ class FileExtensionValidator:
                 },
             )
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, self.__class__)
             and self.allowed_extensions == other.allowed_extensions
@@ -534,9 +576,9 @@ class FileExtensionValidator:
         )
 
 
-def get_available_image_extensions():
+def get_available_image_extensions() -> list[str]:
     try:
-        from PIL import Image
+        from PIL import Image  # type: ignore[import-not-found]
     except ImportError:
         return []
     else:
@@ -544,7 +586,7 @@ def get_available_image_extensions():
         return [ext.lower()[1:] for ext in Image.EXTENSION]
 
 
-def validate_image_file_extension(value):
+def validate_image_file_extension(value: Any) -> None:
     return FileExtensionValidator(allowed_extensions=get_available_image_extensions())(
         value
     )
@@ -557,17 +599,17 @@ class ProhibitNullCharactersValidator:
     message = "Null characters are not allowed."
     code = "null_characters_not_allowed"
 
-    def __init__(self, message=None, code=None):
+    def __init__(self, message: str | None = None, code: str | None = None) -> None:
         if message is not None:
             self.message = message
         if code is not None:
             self.code = code
 
-    def __call__(self, value):
+    def __call__(self, value: Any) -> None:
         if "\x00" in str(value):
             raise ValidationError(self.message, code=self.code, params={"value": value})
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, self.__class__)
             and self.message == other.message