plain 0.69.0__py3-none-any.whl → 0.71.0__py3-none-any.whl

plain/forms/forms.py

@@ -2,21 +2,34 @@
 Form classes
 """
 
+from __future__ import annotations
+
 import copy
 from functools import cached_property
+from typing import TYPE_CHECKING, Any
 
 from plain.exceptions import NON_FIELD_ERRORS
 
 from .exceptions import ValidationError
 from .fields import Field, FileField
 
+if TYPE_CHECKING:
+    from plain.http import Request
+
+    from .boundfield import BoundField
+
 __all__ = ("BaseForm", "Form")
 
 
 class DeclarativeFieldsMetaclass(type):
     """Collect Fields declared on the base classes."""
 
-    def __new__(mcs, name, bases, attrs):
+    def __new__(
+        mcs: type[DeclarativeFieldsMetaclass],
+        name: str,
+        bases: tuple[type, ...],
+        attrs: dict[str, Any],
+    ) -> type:
         # Collect fields from current class and remove them from attrs.
         attrs["declared_fields"] = {
             key: attrs.pop(key)
@@ -24,7 +37,7 @@ class DeclarativeFieldsMetaclass(type):
             if isinstance(value, Field)
         }
 
-        new_class = super().__new__(mcs, name, bases, attrs)
+        new_class = super().__new__(mcs, name, bases, attrs)  # type: ignore[misc]
 
         # Walk through the MRO.
         declared_fields = {}
@@ -52,15 +65,15 @@ class BaseForm:
     class.
     """
 
-    prefix = None
+    prefix: str | None = None
 
     def __init__(
         self,
         *,
-        request,
-        auto_id="id_%s",
-        prefix=None,
-        initial=None,
+        request: Request,
+        auto_id: str | bool = "id_%s",
+        prefix: str | None = None,
+        initial: dict[str, Any] | None = None,
     ):
         self.data = request.data
         self.files = request.files
@@ -75,17 +88,19 @@ class BaseForm:
         if prefix is not None:
             self.prefix = prefix
         self.initial = initial or {}
-        self._errors = None  # Stores the errors after clean() has been called.
+        self._errors: dict[str, list[str]] | None = (
+            None  # Stores the errors after clean() has been called.
+        )
 
         # The base_fields class attribute is the *class-wide* definition of
         # fields. Because a particular *instance* of the class might want to
         # alter self.fields, we create self.fields here by copying base_fields.
         # Instances should always modify self.fields; they should not modify
         # self.base_fields.
-        self.fields = copy.deepcopy(self.base_fields)
-        self._bound_fields_cache = {}
+        self.fields: dict[str, Field] = copy.deepcopy(self.base_fields)
+        self._bound_fields_cache: dict[str, BoundField] = {}
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if self._errors is None:
             is_valid = "Unknown"
         else:
@@ -97,17 +112,17 @@ class BaseForm:
             fields=";".join(self.fields),
         )
 
-    def _bound_items(self):
+    def _bound_items(self) -> Any:
         """Yield (name, bf) pairs, where bf is a BoundField object."""
         for name in self.fields:
             yield name, self[name]
 
-    def __iter__(self):
+    def __iter__(self) -> Any:
         """Yield the form's fields as BoundField objects."""
         for name in self.fields:
             yield self[name]
 
-    def __getitem__(self, name):
+    def __getitem__(self, name: str) -> BoundField:
         """Return a BoundField with the given name."""
         try:
             field = self.fields[name]
@@ -124,17 +139,17 @@ class BaseForm:
         return self._bound_fields_cache[name]
 
     @property
-    def errors(self):
+    def errors(self) -> dict[str, list[str]] | None:
         """Return an error dict for the data provided for the form."""
         if self._errors is None:
             self.full_clean()
         return self._errors
 
-    def is_valid(self):
+    def is_valid(self) -> bool:
         """Return True if the form has no errors, or False otherwise."""
         return self.is_bound and not self.errors
 
-    def add_prefix(self, field_name):
+    def add_prefix(self, field_name: str) -> str:
         """
         Return the field name with a prefix appended, if this Form has a
         prefix set.
@@ -144,7 +159,7 @@ class BaseForm:
         return f"{self.prefix}-{field_name}" if self.prefix else field_name
 
     @property
-    def non_field_errors(self):
+    def non_field_errors(self) -> list[str]:
         """
         Return a list of errors that aren't associated with a particular
         field -- i.e., from Form.clean(). Return an empty list if there
@@ -155,7 +170,7 @@ class BaseForm:
             [],
         )
 
-    def add_error(self, field, error):
+    def add_error(self, field: str | None, error: ValidationError) -> None:
         """
         Update the content of `self._errors`.
 
@@ -179,6 +194,7 @@ class BaseForm:
                 f"`ValidationError`, not `{type(error).__name__}`."
             )
 
+        error_dict: dict[str, Any]
         if hasattr(error, "error_dict"):
             if field is not None:
                 raise TypeError(
@@ -186,45 +202,45 @@ class BaseForm:
                     "argument contains errors for multiple fields."
                 )
             else:
-                error = error.error_dict
+                error_dict = error.error_dict
         else:
-            error = {field or NON_FIELD_ERRORS: error.error_list}
+            error_dict = {field or NON_FIELD_ERRORS: error.error_list}
 
         class ValidationErrors(list):
-            def __iter__(self):
+            def __iter__(self) -> Any:
                 for err in super().__iter__():
                     # TODO make sure this works...
                     yield next(iter(err))
 
-        for field, error_list in error.items():
-            if field not in self.errors:
-                if field != NON_FIELD_ERRORS and field not in self.fields:
+        for field_key, error_list in error_dict.items():
+            if field_key not in self.errors:
+                if field_key != NON_FIELD_ERRORS and field_key not in self.fields:
                     raise ValueError(
-                        f"'{self.__class__.__name__}' has no field named '{field}'."
+                        f"'{self.__class__.__name__}' has no field named '{field_key}'."
                     )
-                self._errors[field] = ValidationErrors()
+                self._errors[field_key] = ValidationErrors()
 
-            self._errors[field].extend(error_list)
+            self._errors[field_key].extend(error_list)
 
             # The field had an error, so removed it from the final data
             # (we use getattr here so errors can be added to uncleaned forms)
-            if field in getattr(self, "cleaned_data", {}):
-                del self.cleaned_data[field]
+            if field_key in getattr(self, "cleaned_data", {}):
+                del self.cleaned_data[field_key]
 
-    def full_clean(self):
+    def full_clean(self) -> None:
         """
         Clean all of self.data and populate self._errors and self.cleaned_data.
         """
         self._errors = {}
         if not self.is_bound:  # Stop further processing.
-            return
+            return None
         self.cleaned_data = {}
 
         self._clean_fields()
         self._clean_form()
         self._post_clean()
 
-    def _field_data_value(self, field, html_name):
+    def _field_data_value(self, field: Field, html_name: str) -> Any:
         if hasattr(self, f"parse_{html_name}"):
             # Allow custom parsing from form data/files at the form level
             return getattr(self, f"parse_{html_name}")()
@@ -234,7 +250,7 @@ class BaseForm:
         else:
             return field.value_from_form_data(self.data, self.files, html_name)
 
-    def _clean_fields(self):
+    def _clean_fields(self) -> None:
         for name, bf in self._bound_items():
             field = bf.field
 
@@ -252,7 +268,7 @@ class BaseForm:
             except ValidationError as e:
                 self.add_error(name, e)
 
-    def _clean_form(self):
+    def _clean_form(self) -> None:
         try:
             cleaned_data = self.clean()
         except ValidationError as e:
@@ -261,14 +277,14 @@ class BaseForm:
             if cleaned_data is not None:
                 self.cleaned_data = cleaned_data
 
-    def _post_clean(self):
+    def _post_clean(self) -> None:
         """
         An internal hook for performing additional cleaning after form cleaning
         is complete. Used for model validation in model forms.
         """
         pass
 
-    def clean(self):
+    def clean(self) -> dict[str, Any]:
         """
         Hook for doing any extra form-wide cleaning after Field.clean() has been
         called on every field. Any ValidationError raised by this method will
@@ -278,10 +294,10 @@ class BaseForm:
         return self.cleaned_data
 
     @cached_property
-    def changed_data(self):
+    def changed_data(self) -> list[str]:
         return [name for name, bf in self._bound_items() if bf._has_changed()]
 
-    def get_initial_for_field(self, field, field_name):
+    def get_initial_for_field(self, field: Field, field_name: str) -> Any:
         """
         Return initial data for field on form. Use initial data from the form
         or the field, in that order. Evaluate callable values.

plain/http/README.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-Typically you will interact with [request](request.py#HttpRequest) and [response](response.py#ResponseBase) objects in your views and middleware.
+Typically you will interact with [Request](request.py#Request) and [Response](response.py#ResponseBase) objects in your views and middleware.
 
 ```python
 from plain.views import View

plain/http/__init__.py

@@ -1,9 +1,9 @@
 from plain.http.cookie import parse_cookie
 from plain.http.request import (
-    HttpHeaders,
-    HttpRequest,
     QueryDict,
     RawPostDataException,
+    Request,
+    RequestHeaders,
     UnreadablePostError,
 )
 from plain.http.response import (
@@ -26,8 +26,8 @@ from plain.http.response import (
 
 __all__ = [
     "parse_cookie",
-    "HttpHeaders",
-    "HttpRequest",
+    "Request",
+    "RequestHeaders",
     "QueryDict",
     "RawPostDataException",
     "UnreadablePostError",

plain/http/cookie.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from http import cookies
 
 from plain.runtime import settings
@@ -5,7 +7,7 @@ from plain.signing import BadSignature, TimestampSigner
 from plain.utils.encoding import force_bytes
 
 
-def parse_cookie(cookie):
+def parse_cookie(cookie: str) -> dict[str, str]:
     """
     Return a dictionary parsed from a `Cookie:` header string.
     """
@@ -24,7 +26,7 @@ def parse_cookie(cookie):
     return cookiedict
 
 
-def _cookie_key(key):
+def _cookie_key(key: str) -> bytes:
     """
     Generate a key for cookie signing that matches the pattern used by
     set_signed_cookie and get_signed_cookie.
@@ -32,19 +34,19 @@ def _cookie_key(key):
     return b"plain.http.cookies" + force_bytes(key)
 
 
-def get_signed_cookie_signer(key, salt=""):
+def get_signed_cookie_signer(key: str, salt: str = "") -> TimestampSigner:
     """
     Create a TimestampSigner for signed cookies with the same configuration
     used by both set_signed_cookie and get_signed_cookie.
     """
     return TimestampSigner(
-        key=_cookie_key(settings.SECRET_KEY),
-        fallback_keys=map(_cookie_key, settings.SECRET_KEY_FALLBACKS),
+        key=_cookie_key(settings.SECRET_KEY).decode(),
+        fallback_keys=[_cookie_key(k).decode() for k in settings.SECRET_KEY_FALLBACKS],
         salt=key + salt,
     )
 
 
-def sign_cookie_value(key, value, salt=""):
+def sign_cookie_value(key: str, value: str, salt: str = "") -> str:
     """
     Sign a cookie value using the standard Plain cookie signing approach.
     """
@@ -52,7 +54,13 @@ def sign_cookie_value(key, value, salt=""):
     return signer.sign(value)
 
 
-def unsign_cookie_value(key, signed_value, salt="", max_age=None, default=None):
+def unsign_cookie_value(
+    key: str,
+    signed_value: str,
+    salt: str = "",
+    max_age: int | None = None,
+    default: str | None = None,
+) -> str | None:
     """
     Unsign a cookie value using the standard Plain cookie signing approach.
     Returns the default value if the signature is invalid or the cookie has expired.

plain/http/multipartparser.py

@@ -5,10 +5,14 @@ Exposes one class, ``MultiPartParser``, which feeds chunks of uploaded data to
 file upload handlers for processing.
 """
 
+from __future__ import annotations
+
 import base64
 import binascii
 import collections
 import html
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
 
 from plain.exceptions import (
     RequestDataTooBig,
@@ -23,6 +27,9 @@ from plain.utils.encoding import force_str
 from plain.utils.http import parse_header_parameters
 from plain.utils.regex_helper import _lazy_re_compile
 
+if TYPE_CHECKING:
+    from plain.internal.files.uploadhandler import FileUploadHandler
+
 __all__ = ("MultiPartParser", "MultiPartParserError", "InputStreamExhausted")
 
 
@@ -54,7 +61,13 @@ class MultiPartParser:
 
     boundary_re = _lazy_re_compile(r"[ -~]{0,200}[!-~]")
 
-    def __init__(self, meta, input_data, upload_handlers, encoding=None):
+    def __init__(
+        self,
+        meta: dict[str, Any],
+        input_data: Any,
+        upload_handlers: list[FileUploadHandler],
+        encoding: str | None = None,
+    ):
         """
         Initialize the MultiPartParser object.
 
@@ -112,7 +125,7 @@ class MultiPartParser:
         self._content_length = content_length
         self._upload_handlers = upload_handlers
 
-    def parse(self):
+    def parse(self) -> tuple[Any, MultiValueDict]:
         # Call the actual parse routine and close all open files in case of
         # errors. This is needed because if exceptions are thrown the
         # MultiPartParser will not be garbage collected immediately and
@@ -128,7 +141,7 @@ class MultiPartParser:
                         fileobj.close()
             raise
 
-    def _parse(self):
+    def _parse(self) -> tuple[Any, MultiValueDict]:
         """
         Parse the POST data and break it into a FILES MultiValueDict and a POST
         MultiValueDict.
@@ -276,7 +289,12 @@ class MultiPartParser:
                     charset = content_type_extra.get("charset")
 
                     try:
-                        content_length = int(meta_data.get("content-length")[0])
+                        content_length_value = meta_data.get("content-length")
+                        content_length = (
+                            int(content_length_value[0])
+                            if content_length_value
+                            else None
+                        )
                     except (IndexError, TypeError, ValueError):
                         content_length = None
 
@@ -362,7 +380,7 @@ class MultiPartParser:
         self._post._mutable = False
         return self._post, self._files
 
-    def handle_file_complete(self, old_field_name, counters):
+    def handle_file_complete(self, old_field_name: str, counters: list[int]) -> None:
         """
         Handle all the signaling that takes place when a file is complete.
         """
@@ -376,7 +394,7 @@ class MultiPartParser:
                 )
                 break
 
-    def sanitize_file_name(self, file_name):
+    def sanitize_file_name(self, file_name: str) -> str | None:
         """
         Sanitize the filename of an upload.
 
@@ -399,7 +417,7 @@ class MultiPartParser:
             return None
         return file_name
 
-    def _close_files(self):
+    def _close_files(self) -> None:
         # Free up all file handles.
         # FIXME: this currently assumes that upload handlers store the file as 'file'
         # We should document that...
@@ -418,7 +436,7 @@ class LazyStream:
     variable in case you need to "unget" some bytes.
     """
 
-    def __init__(self, producer, length=None):
+    def __init__(self, producer: Iterator[bytes], length: int | None = None):
         """
         Every LazyStream must have a producer when instantiated.
 
@@ -433,11 +451,11 @@ class LazyStream:
         self._remaining = length
         self._unget_history = []
 
-    def tell(self):
+    def tell(self) -> int:
         return self.position
 
-    def read(self, size=None):
-        def parts():
+    def read(self, size: int | None = None) -> bytes:
+        def parts() -> Iterator[bytes]:
             remaining = self._remaining if size is None else size
             # do the whole thing in one shot if no limit was provided.
             if remaining is None:
@@ -462,7 +480,7 @@ class LazyStream:
 
         return b"".join(parts())
 
-    def __next__(self):
+    def __next__(self) -> bytes:
         """
         Used when the exact number of bytes to read is unimportant.
 
@@ -478,7 +496,7 @@ class LazyStream:
         self.position += len(output)
         return output
 
-    def close(self):
+    def close(self) -> None:
         """
         Used to invalidate/disable this lazy stream.
 
@@ -487,10 +505,10 @@ class LazyStream:
         """
         self._producer = []
 
-    def __iter__(self):
+    def __iter__(self) -> LazyStream:
         return self
 
-    def unget(self, bytes):
+    def unget(self, bytes: bytes) -> None:
         """
         Place bytes back onto the front of the lazy stream.
 
@@ -503,7 +521,7 @@ class LazyStream:
         self.position -= len(bytes)
         self._leftover = bytes + self._leftover
 
-    def _update_unget_history(self, num_bytes):
+    def _update_unget_history(self, num_bytes: int) -> None:
         """
         Update the unget history as a sanity check to see if we've pushed
         back the same number of bytes in one chunk. If we keep ungetting the
@@ -534,11 +552,11 @@ class ChunkIter:
     constructor, yield chunks of read operations from that object.
     """
 
-    def __init__(self, flo, chunk_size=64 * 1024):
+    def __init__(self, flo: Any, chunk_size: int = 64 * 1024):
         self.flo = flo
         self.chunk_size = chunk_size
 
-    def __next__(self):
+    def __next__(self) -> bytes:
         try:
             data = self.flo.read(self.chunk_size)
         except InputStreamExhausted:
@@ -548,7 +566,7 @@ class ChunkIter:
         else:
             raise StopIteration()
 
-    def __iter__(self):
+    def __iter__(self) -> ChunkIter:
         return self
 
 
@@ -557,14 +575,14 @@ class InterBoundaryIter:
     A Producer that will iterate over boundaries.
     """
 
-    def __init__(self, stream, boundary):
+    def __init__(self, stream: LazyStream, boundary: bytes):
         self._stream = stream
         self._boundary = boundary
 
-    def __iter__(self):
+    def __iter__(self) -> InterBoundaryIter:
         return self
 
-    def __next__(self):
+    def __next__(self) -> LazyStream:
         try:
             return LazyStream(BoundaryIter(self._stream, self._boundary))
         except InputStreamExhausted:
@@ -583,7 +601,7 @@ class BoundaryIter:
     StopIteration exception.
     """
 
-    def __init__(self, stream, boundary):
+    def __init__(self, stream: LazyStream, boundary: bytes):
         self._stream = stream
         self._boundary = boundary
         self._done = False
@@ -598,10 +616,10 @@ class BoundaryIter:
             raise InputStreamExhausted()
         self._stream.unget(unused_char)
 
-    def __iter__(self):
+    def __iter__(self) -> BoundaryIter:
         return self
 
-    def __next__(self):
+    def __next__(self) -> bytes:
         if self._done:
             raise StopIteration()
 
@@ -642,7 +660,7 @@ class BoundaryIter:
                 stream.unget(chunk[-rollback:])
                 return chunk[:-rollback]
 
-    def _find_boundary(self, data):
+    def _find_boundary(self, data: bytes) -> tuple[int, int] | None:
         """
         Find a multipart boundary in data.
 
@@ -667,7 +685,7 @@ class BoundaryIter:
             return end, next
 
 
-def exhaust(stream_or_iterable):
+def exhaust(stream_or_iterable: Any) -> None:
     """Exhaust an iterator or stream."""
     try:
         iterator = iter(stream_or_iterable)
@@ -676,7 +694,9 @@ def exhaust(stream_or_iterable):
     collections.deque(iterator, maxlen=0)  # consume iterator quickly.
 
 
-def parse_boundary_stream(stream, max_header_size):
+def parse_boundary_stream(
+    stream: LazyStream, max_header_size: int
+) -> tuple[str, dict[str, Any], LazyStream]:
     """
     Parse one and exactly one stream that encapsulates a boundary.
     """
@@ -730,11 +750,11 @@ def parse_boundary_stream(stream, max_header_size):
 
 
 class Parser:
-    def __init__(self, stream, boundary):
+    def __init__(self, stream: LazyStream, boundary: bytes):
         self._stream = stream
         self._separator = b"--" + boundary
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[tuple[str, dict[str, Any], LazyStream]]:
         boundarystream = InterBoundaryIter(self._stream, self._separator)
         for sub_stream in boundarystream:
             # Iterate over each part