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

plain/forms/fields.py

@@ -2,6 +2,8 @@
 Field classes.
 """
 
+from __future__ import annotations
+
 import copy
 import datetime
 import enum
@@ -9,8 +11,10 @@ import json
 import math
 import re
 import uuid
+from collections.abc import Callable
 from decimal import Decimal, DecimalException
 from io import BytesIO
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlsplit, urlunsplit
 
 from plain import validators
@@ -24,6 +28,9 @@ from plain.utils.text import pluralize_lazy
 from .boundfield import BoundField
 from .exceptions import FormFieldMissingError
 
+if TYPE_CHECKING:
+    from .forms import BaseForm
+
 __all__ = (
     "Field",
     "CharField",
@@ -53,7 +60,7 @@ FILE_INPUT_CONTRADICTION = object()
 
 
 class Field:
-    default_validators = []  # Default set of validators
+    default_validators: list[Callable[[Any], None]] = []  # Default set of validators
     # Add an 'invalid' entry to default_error_message if you want a specific
     # field error message not raised by the field validators.
     default_error_messages = {
@@ -64,10 +71,10 @@ class Field:
     def __init__(
         self,
         *,
-        required=True,
-        initial=None,
-        error_messages=None,
-        validators=(),
+        required: bool = True,
+        initial: Any = None,
+        error_messages: dict[str, str] | None = None,
+        validators: tuple[Callable[[Any], None], ...] = (),
     ):
         # required -- Boolean that specifies whether the field is required.
         #             True by default.
@@ -87,19 +94,19 @@ class Field:
 
         self.validators = [*self.default_validators, *validators]
 
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         return value
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Any:
         return value
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         if value in self.empty_values and self.required:
             raise ValidationError(self.error_messages["required"], code="required")
 
-    def run_validators(self, value):
+    def run_validators(self, value: Any) -> None:
         if value in self.empty_values:
-            return
+            return None
         errors = []
         for v in self.validators:
             try:
@@ -111,7 +118,7 @@ class Field:
         if errors:
             raise ValidationError(errors)
 
-    def clean(self, value):
+    def clean(self, value: Any) -> Any:
         """
         Validate the given value and return its "cleaned" value as an
         appropriate Python object. Raise ValidationError for any errors.
@@ -121,7 +128,7 @@ class Field:
         self.run_validators(value)
         return value
 
-    def bound_data(self, data, initial):
+    def bound_data(self, data: Any, initial: Any) -> Any:
         """
         Return the value that should be shown for this field on render of a
         bound form, given the submitted POST data for the field and the initial
@@ -132,7 +139,7 @@ class Field:
         """
         return data
 
-    def has_changed(self, initial, data):
+    def has_changed(self, initial: Any, data: Any) -> bool:
         """Return True if data differs from initial."""
         try:
             data = self.to_python(data)
@@ -147,28 +154,28 @@ class Field:
         data_value = data if data is not None else ""
         return initial_value != data_value
 
-    def get_bound_field(self, form, field_name):
+    def get_bound_field(self, form: BaseForm, field_name: str) -> BoundField:
         """
         Return a BoundField instance that will be used when accessing the form
         field in a template.
         """
         return BoundField(form, self, field_name)
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> Field:
         result = copy.copy(self)
         memo[id(self)] = result
         result.error_messages = self.error_messages.copy()
         result.validators = self.validators[:]
         return result
 
-    def value_from_form_data(self, data, files, html_name):
+    def value_from_form_data(self, data: Any, files: Any, html_name: str) -> Any:
         # By default, all fields are expected to be present in HTML form data.
         try:
             return data[html_name]
         except KeyError as e:
             raise FormFieldMissingError(html_name) from e
 
-    def value_from_json_data(self, data, files, html_name):
+    def value_from_json_data(self, data: Any, files: Any, html_name: str) -> Any:
         if self.required and html_name not in data:
             raise FormFieldMissingError(html_name)
 
@@ -177,7 +184,13 @@ class Field:
 
 class CharField(Field):
     def __init__(
-        self, *, max_length=None, min_length=None, strip=True, empty_value="", **kwargs
+        self,
+        *,
+        max_length: int | None = None,
+        min_length: int | None = None,
+        strip: bool = True,
+        empty_value: str = "",
+        **kwargs: Any,
     ):
         self.max_length = max_length
         self.min_length = min_length
@@ -190,7 +203,7 @@ class CharField(Field):
             self.validators.append(validators.MaxLengthValidator(int(max_length)))
         self.validators.append(validators.ProhibitNullCharactersValidator())
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> str:
         """Return a string."""
         if value not in self.empty_values:
             value = str(value)
@@ -207,7 +220,14 @@ class IntegerField(Field):
     }
     re_decimal = _lazy_re_compile(r"\.0*\s*$")
 
-    def __init__(self, *, max_value=None, min_value=None, step_size=None, **kwargs):
+    def __init__(
+        self,
+        *,
+        max_value: int | None = None,
+        min_value: int | None = None,
+        step_size: int | None = None,
+        **kwargs: Any,
+    ):
         self.max_value, self.min_value, self.step_size = max_value, min_value, step_size
         super().__init__(**kwargs)
 
@@ -218,7 +238,7 @@ class IntegerField(Field):
         if step_size is not None:
             self.validators.append(validators.StepValueValidator(step_size))
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> int | None:
         """
         Validate that int() can be called on the input. Return the result
         of int() or None for empty values.
@@ -239,7 +259,7 @@ class FloatField(IntegerField):
         "invalid": "Enter a number.",
     }
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> float | None:
         """
         Validate that float() can be called on the input. Return the result
         of float() or None for empty values.
@@ -253,10 +273,10 @@ class FloatField(IntegerField):
             raise ValidationError(self.error_messages["invalid"], code="invalid")
         return value
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         super().validate(value)
         if value in self.empty_values:
-            return
+            return None
         if not math.isfinite(value):
             raise ValidationError(self.error_messages["invalid"], code="invalid")
 
@@ -269,17 +289,17 @@ class DecimalField(IntegerField):
     def __init__(
         self,
         *,
-        max_value=None,
-        min_value=None,
-        max_digits=None,
-        decimal_places=None,
-        **kwargs,
+        max_value: int | None = None,
+        min_value: int | None = None,
+        max_digits: int | None = None,
+        decimal_places: int | None = None,
+        **kwargs: Any,
     ):
         self.max_digits, self.decimal_places = max_digits, decimal_places
         super().__init__(max_value=max_value, min_value=min_value, **kwargs)
         self.validators.append(validators.DecimalValidator(max_digits, decimal_places))
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Decimal | None:
         """
         Validate that the input is a decimal number. Return a Decimal
         instance or None for empty values. Ensure that there are no more
@@ -294,10 +314,10 @@ class DecimalField(IntegerField):
             raise ValidationError(self.error_messages["invalid"], code="invalid")
         return value
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         super().validate(value)
         if value in self.empty_values:
-            return
+            return None
         if not value.is_finite():
             raise ValidationError(
                 self.error_messages["invalid"],
@@ -352,12 +372,12 @@ class BaseTemporalField(Field):
         "%m/%d/%y %H:%M",  # '10/25/06 14:30'
     ]
 
-    def __init__(self, *, input_formats=None, **kwargs):
+    def __init__(self, *, input_formats: list[str] | None = None, **kwargs: Any):
         super().__init__(**kwargs)
         if input_formats is not None:
             self.input_formats = input_formats
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Any:
         value = value.strip()
         # Try to strptime against each input format.
         for format in self.input_formats:
@@ -367,7 +387,7 @@ class BaseTemporalField(Field):
                 continue
         raise ValidationError(self.error_messages["invalid"], code="invalid")
 
-    def strptime(self, value, format):
+    def strptime(self, value: str, format: str) -> Any:
         raise NotImplementedError("Subclasses must define this method.")
 
 
@@ -377,7 +397,7 @@ class DateField(BaseTemporalField):
         "invalid": "Enter a valid date.",
     }
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> datetime.date | None:
         """
         Validate that the input can be converted to a date. Return a Python
         datetime.date object.
@@ -390,7 +410,7 @@ class DateField(BaseTemporalField):
             return value
         return super().to_python(value)
 
-    def strptime(self, value, format):
+    def strptime(self, value: str, format: str) -> datetime.date:
         return datetime.datetime.strptime(value, format).date()
 
 
@@ -398,7 +418,7 @@ class TimeField(BaseTemporalField):
     input_formats = BaseTemporalField.TIME_INPUT_FORMATS
     default_error_messages = {"invalid": "Enter a valid time."}
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> datetime.time | None:
         """
         Validate that the input can be converted to a time. Return a Python
         datetime.time object.
@@ -409,12 +429,12 @@ class TimeField(BaseTemporalField):
             return value
         return super().to_python(value)
 
-    def strptime(self, value, format):
+    def strptime(self, value: str, format: str) -> datetime.time:
         return datetime.datetime.strptime(value, format).time()
 
 
 class DateTimeFormatsIterator:
-    def __iter__(self):
+    def __iter__(self) -> Any:
         yield from BaseTemporalField.DATETIME_INPUT_FORMATS
         yield from BaseTemporalField.DATE_INPUT_FORMATS
 
@@ -425,12 +445,12 @@ class DateTimeField(BaseTemporalField):
         "invalid": "Enter a valid date/time.",
     }
 
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         if isinstance(value, datetime.datetime):
             value = to_current_timezone(value)
         return value
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> datetime.datetime | None:
         """
         Validate that the input can be converted to a datetime. Return a
         Python datetime.datetime object.
@@ -450,7 +470,7 @@ class DateTimeField(BaseTemporalField):
             result = super().to_python(value)
         return from_current_timezone(result)
 
-    def strptime(self, value, format):
+    def strptime(self, value: str, format: str) -> datetime.datetime:
         return datetime.datetime.strptime(value, format)
 
 
@@ -460,12 +480,12 @@ class DurationField(Field):
         "overflow": "The number of days must be between {min_days} and {max_days}.",
     }
 
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         if isinstance(value, datetime.timedelta):
             return duration_string(value)
         return value
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> datetime.timedelta | None:
         if value in self.empty_values:
             return None
         if isinstance(value, datetime.timedelta):
@@ -486,7 +506,7 @@ class DurationField(Field):
 
 
 class RegexField(CharField):
-    def __init__(self, regex, **kwargs):
+    def __init__(self, regex: str | re.Pattern[str], **kwargs: Any) -> None:
         """
         regex can be either a string or a compiled regular expression object.
         """
@@ -494,10 +514,10 @@ class RegexField(CharField):
         super().__init__(**kwargs)
         self._set_regex(regex)
 
-    def _get_regex(self):
+    def _get_regex(self) -> re.Pattern[str]:
         return self._regex
 
-    def _set_regex(self, regex):
+    def _set_regex(self, regex: str | re.Pattern[str]) -> None:
         if isinstance(regex, str):
             regex = re.compile(regex)
         self._regex = regex
@@ -515,7 +535,7 @@ class RegexField(CharField):
 class EmailField(CharField):
     default_validators = [validators.validate_email]
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(strip=True, **kwargs)
 
 
@@ -532,12 +552,18 @@ class FileField(Field):
         "contradiction": "Please either submit a file or check the clear checkbox, not both.",
     }
 
-    def __init__(self, *, max_length=None, allow_empty_file=False, **kwargs):
+    def __init__(
+        self,
+        *,
+        max_length: int | None = None,
+        allow_empty_file: bool = False,
+        **kwargs: Any,
+    ) -> None:
         self.max_length = max_length
         self.allow_empty_file = allow_empty_file
         super().__init__(**kwargs)
 
-    def to_python(self, data):
+    def to_python(self, data: Any) -> Any:
         if data in self.empty_values:
             return None
 
@@ -560,7 +586,7 @@ class FileField(Field):
 
         return data
 
-    def clean(self, data, initial=None):
+    def clean(self, data: Any, initial: Any = None) -> Any:
         # If the widget got contradictory inputs, we raise a validation error
         if data is FILE_INPUT_CONTRADICTION:
             raise ValidationError(
@@ -581,16 +607,16 @@ class FileField(Field):
             return initial
         return super().clean(data)
 
-    def bound_data(self, _, initial):
+    def bound_data(self, _: Any, initial: Any) -> Any:
         return initial
 
-    def has_changed(self, initial, data):
+    def has_changed(self, initial: Any, data: Any) -> bool:
         return data is not None
 
-    def value_from_form_data(self, data, files, html_name):
+    def value_from_form_data(self, data: Any, files: Any, html_name: str) -> Any:
         return files.get(html_name)
 
-    def value_from_json_data(self, data, files, html_name):
+    def value_from_json_data(self, data: Any, files: Any, html_name: str) -> Any:
         return files.get(html_name)
 
 
@@ -600,7 +626,7 @@ class ImageField(FileField):
         "invalid_image": "Upload a valid image. The file you uploaded was either not an image or a corrupted image.",
     }
 
-    def to_python(self, data):
+    def to_python(self, data: Any) -> Any:
         """
         Check that the file-upload field data contains a valid image (GIF, JPG,
         PNG, etc. -- whatever Pillow supports).
@@ -609,7 +635,7 @@ class ImageField(FileField):
         if f is None:
             return None
 
-        from PIL import Image
+        from PIL import Image  # type: ignore[import-not-found]
 
         # We need to get a file object for Pillow. We might have a path or we might
         # have to read the data into memory.
@@ -650,11 +676,11 @@ class URLField(CharField):
     }
     default_validators = [validators.URLValidator()]
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(strip=True, **kwargs)
 
-    def to_python(self, value):
-        def split_url(url):
+    def to_python(self, value: Any) -> str:
+        def split_url(url: str | bytes) -> list[str]:
             """
             Return a list of url parts via urlparse.urlsplit(), or raise
             ValidationError for some malformed URLs.
@@ -679,13 +705,16 @@ class URLField(CharField):
                 url_fields[2] = ""
                 # Rebuild the url_fields list, since the domain segment may now
                 # contain the path too.
-                url_fields = split_url(urlunsplit(url_fields))
-            value = urlunsplit(url_fields)
+                url_result = urlunsplit(url_fields)
+                url_fields = split_url(
+                    str(url_result) if isinstance(url_result, bytes) else url_result
+                )
+            value = str(urlunsplit(url_fields))
         return value
 
 
 class BooleanField(Field):
-    def to_python(self, value):
+    def to_python(self, value: Any) -> bool:
         """Return a Python boolean object."""
         # Explicitly check for the string 'False', which is what a hidden field
         # will submit for False. Also check for '0', since this is what
@@ -697,16 +726,18 @@ class BooleanField(Field):
             value = bool(value)
         return super().to_python(value)
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         if not value and self.required:
             raise ValidationError(self.error_messages["required"], code="required")
 
-    def has_changed(self, initial, data):
+    def has_changed(self, initial: Any, data: Any) -> bool:
         # Sometimes data or initial may be a string equivalent of a boolean
         # so we should run it through to_python first to get a boolean value
         return self.to_python(initial) != self.to_python(data)
 
-    def value_from_form_data(self, data, files, html_name):
+    def value_from_form_data(
+        self, data: Any, files: Any, html_name: str
+    ) -> bool | None:
         if html_name not in data:
             # Unselected checkboxes aren't in HTML form data, so return False
             return False
@@ -723,7 +754,7 @@ class BooleanField(Field):
             "on": True,
         }.get(value)
 
-    def value_from_json_data(self, data, files, html_name):
+    def value_from_json_data(self, data: Any, files: Any, html_name: str) -> Any:
         # Boolean fields must be present in the JSON data
         try:
             return data[html_name]
@@ -737,7 +768,7 @@ class NullBooleanField(BooleanField):
     to None.
     """
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> bool | None:
         """
         Explicitly check for the string 'True' and 'False', which is what a
         hidden field will submit for True and False, for 'true' and 'false',
@@ -753,15 +784,15 @@ class NullBooleanField(BooleanField):
         else:
             return None
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         pass
 
 
 class CallableChoiceIterator:
-    def __init__(self, choices_func):
+    def __init__(self, choices_func: Callable[[], Any]) -> None:
         self.choices_func = choices_func
 
-    def __iter__(self):
+    def __iter__(self) -> Any:
         yield from self.choices_func()
 
 
@@ -770,7 +801,7 @@ class ChoiceField(Field):
         "invalid_choice": "Select a valid choice. %(value)s is not one of the available choices.",
     }
 
-    def __init__(self, *, choices=(), **kwargs):
+    def __init__(self, *, choices: Any = (), **kwargs: Any) -> None:
         super().__init__(**kwargs)
         if hasattr(choices, "choices"):
             choices = choices.choices
@@ -778,15 +809,15 @@ class ChoiceField(Field):
             choices = [(member.value, member.name) for member in choices]
         self.choices = choices
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> ChoiceField:
         result = super().__deepcopy__(memo)
         result._choices = copy.deepcopy(self._choices, memo)
         return result
 
-    def _get_choices(self):
+    def _get_choices(self) -> Any:
         return self._choices
 
-    def _set_choices(self, value):
+    def _set_choices(self, value: Any) -> None:
         # Setting choices also sets the choices on the widget.
         # choices can be any iterable, but we call list() on it because
         # it will be consumed more than once.
@@ -799,13 +830,13 @@ class ChoiceField(Field):
 
     choices = property(_get_choices, _set_choices)
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> str:
         """Return a string."""
         if value in self.empty_values:
             return ""
         return str(value)
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         """Validate that the input is in self.choices."""
         super().validate(value)
         if value and not self.valid_value(value):
@@ -815,7 +846,7 @@ class ChoiceField(Field):
                 params={"value": value},
             )
 
-    def valid_value(self, value):
+    def valid_value(self, value: Any) -> bool:
         """Check to see if the provided value is a valid choice."""
         text_value = str(value)
         for k, v in self.choices:
@@ -831,12 +862,18 @@ class ChoiceField(Field):
 
 
 class TypedChoiceField(ChoiceField):
-    def __init__(self, *, coerce=lambda val: val, empty_value="", **kwargs):
+    def __init__(
+        self,
+        *,
+        coerce: Callable[[Any], Any] = lambda val: val,
+        empty_value: Any = "",
+        **kwargs: Any,
+    ) -> None:
         self.coerce = coerce
         self.empty_value = empty_value
         super().__init__(**kwargs)
 
-    def _coerce(self, value):
+    def _coerce(self, value: Any) -> Any:
         """
         Validate that the value can be coerced to the right type (if not empty).
         """
@@ -852,7 +889,7 @@ class TypedChoiceField(ChoiceField):
             )
         return value
 
-    def clean(self, value):
+    def clean(self, value: Any) -> Any:
         value = super().clean(value)
         return self._coerce(value)
 
@@ -863,7 +900,7 @@ class MultipleChoiceField(ChoiceField):
         "invalid_list": "Enter a list of values.",
     }
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> list[str]:
         if not value:
             return []
         elif not isinstance(value, list | tuple):
@@ -872,7 +909,7 @@ class MultipleChoiceField(ChoiceField):
             )
         return [str(val) for val in value]
 
-    def validate(self, value):
+    def validate(self, value: Any) -> None:
         """Validate that the input is a list or tuple."""
         if self.required and not value:
             raise ValidationError(self.error_messages["required"], code="required")
@@ -885,7 +922,7 @@ class MultipleChoiceField(ChoiceField):
                     params={"value": val},
                 )
 
-    def has_changed(self, initial, data):
+    def has_changed(self, initial: Any, data: Any) -> bool:
         if initial is None:
             initial = []
         if data is None:
@@ -896,7 +933,7 @@ class MultipleChoiceField(ChoiceField):
         data_set = {str(value) for value in data}
         return data_set != initial_set
 
-    def value_from_form_data(self, data, files, html_name):
+    def value_from_form_data(self, data: Any, files: Any, html_name: str) -> Any:
         return data.getlist(html_name)
 
 
@@ -905,12 +942,12 @@ class UUIDField(CharField):
         "invalid": "Enter a valid UUID.",
     }
 
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         if isinstance(value, uuid.UUID):
             return str(value)
         return value
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> uuid.UUID | None:
         value = super().to_python(value)
         if value in self.empty_values:
             return None
@@ -936,15 +973,20 @@ class JSONField(CharField):
     }
 
     def __init__(
-        self, encoder=None, decoder=None, indent=None, sort_keys=False, **kwargs
-    ):
+        self,
+        encoder: Any = None,
+        decoder: Any = None,
+        indent: int | None = None,
+        sort_keys: bool = False,
+        **kwargs: Any,
+    ) -> None:
         self.encoder = encoder
         self.decoder = decoder
         self.indent = indent
         self.sort_keys = sort_keys
         super().__init__(**kwargs)
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Any:
         if value in self.empty_values:
             return None
         elif isinstance(value, list | dict | int | float | JSONString):
@@ -962,7 +1004,7 @@ class JSONField(CharField):
         else:
             return converted
 
-    def bound_data(self, data, initial):
+    def bound_data(self, data: Any, initial: Any) -> Any:
         if data is None:
             return None
         try:
@@ -970,7 +1012,7 @@ class JSONField(CharField):
         except json.JSONDecodeError:
             return InvalidJSONInput(data)
 
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         if isinstance(value, InvalidJSONInput):
             return value
         return json.dumps(
@@ -981,7 +1023,7 @@ class JSONField(CharField):
             cls=self.encoder,
         )
 
-    def has_changed(self, initial, data):
+    def has_changed(self, initial: Any, data: Any) -> bool:
         if super().has_changed(initial, data):
             return True
         # For purposes of seeing whether something has changed, True isn't the
@@ -991,7 +1033,7 @@ class JSONField(CharField):
         )
 
 
-def from_current_timezone(value):
+def from_current_timezone(value: datetime.datetime | None) -> datetime.datetime | None:
     """
     When time zone support is enabled, convert naive datetimes
     entered in the current time zone to aware datetimes.
@@ -1005,7 +1047,7 @@ def from_current_timezone(value):
         except Exception as exc:
             raise ValidationError(
                 (
-                    "%(datetime)s couldn’t be interpreted "
+                    "%(datetime)s couldn't be interpreted "
                     "in time zone %(current_timezone)s; it "
                     "may be ambiguous or it may not exist."
                 ),
@@ -1015,7 +1057,7 @@ def from_current_timezone(value):
     return value
 
 
-def to_current_timezone(value):
+def to_current_timezone(value: datetime.datetime | None) -> datetime.datetime | None:
     """
     When time zone support is enabled, convert aware datetimes
     to naive datetimes in the current time zone for display.