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

plain/http/request.py

@@ -1,33 +1,40 @@
-import codecs
+from __future__ import annotations
+
 import copy
 import json
+import secrets
 import uuid
+from collections.abc import Iterator
 from functools import cached_property
 from io import BytesIO
 from itertools import chain
+from typing import TYPE_CHECKING, Any, TypeVar, overload
 from urllib.parse import parse_qsl, quote, urlencode, urljoin, urlsplit
 
-from plain.exceptions import (
-    ImproperlyConfigured,
-    RequestDataTooBig,
-    TooManyFieldsSent,
-)
+if TYPE_CHECKING:
+    from plain.urls import ResolverMatch
+
+from plain.exceptions import ImproperlyConfigured
 from plain.http.cookie import unsign_cookie_value
 from plain.http.multipartparser import (
     MultiPartParser,
-    MultiPartParserError,
-    TooManyFilesSent,
 )
-from plain.internal.files import uploadhandler
 from plain.runtime import settings
 from plain.utils.datastructures import (
     CaseInsensitiveMapping,
-    ImmutableList,
     MultiValueDict,
 )
 from plain.utils.encoding import iri_to_uri
 from plain.utils.http import parse_header_parameters
 
+from .exceptions import (
+    BadRequestError400,
+    RequestDataTooBigError400,
+    TooManyFieldsSentError400,
+)
+
+_T = TypeVar("_T")
+
 
 class UnreadablePostError(OSError):
     pass
@@ -43,49 +50,43 @@ class RawPostDataException(Exception):
     pass
 
 
-class HttpRequest:
+class Request:
     """A basic HTTP request."""
 
     # The encoding used in GET/POST dicts. None means use default setting.
-    _encoding = None
-    _upload_handlers = []
+    encoding: str | None = None
 
     non_picklable_attrs = frozenset(["resolver_match", "_stream"])
 
-    def __init__(self):
-        # WARNING: The `WSGIRequest` subclass doesn't call `super`.
-        # Any variable assignment made here should also happen in
-        # `WSGIRequest.__init__()`.
+    method: str | None
+    resolver_match: ResolverMatch | None
+    content_type: str | None
+    content_params: dict[str, str] | None
+    query_params: QueryDict
+    cookies: dict[str, str]
+    environ: dict[str, Any]
+    path: str
+    path_info: str
+    unique_id: str
 
+    def __init__(self):
         # A unique ID we can use to trace this request
         self.unique_id = str(uuid.uuid4())
-
-        self.query_params = QueryDict(mutable=True)
-        self.data = QueryDict(mutable=True)
-        self.cookies = {}
-        self.meta = {}
-        self.files = MultiValueDict()
-
-        self.path = ""
-        self.path_info = ""
-        self.method = None
         self.resolver_match = None
-        self.content_type = None
-        self.content_params = None
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if self.method is None or not self.get_full_path():
             return f"<{self.__class__.__name__}>"
         return f"<{self.__class__.__name__}: {self.method} {self.get_full_path()!r}>"
 
-    def __getstate__(self):
+    def __getstate__(self) -> dict[str, Any]:
         obj_dict = self.__dict__.copy()
         for attr in self.non_picklable_attrs:
             if attr in obj_dict:
                 del obj_dict[attr]
         return obj_dict
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> Request:
         obj = copy.copy(self)
         for attr in self.non_picklable_attrs:
             if hasattr(self, attr):
@@ -94,34 +95,54 @@ class HttpRequest:
         return obj
 
     @cached_property
-    def headers(self):
-        return HttpHeaders(self.meta)
+    def headers(self) -> RequestHeaders:
+        return RequestHeaders(self.environ)
 
     @cached_property
-    def accepted_types(self):
-        """Return a list of MediaType instances."""
-        return parse_accept_header(self.headers.get("Accept", "*/*"))
+    def csp_nonce(self) -> str:
+        """Generate a cryptographically secure nonce for Content Security Policy.
 
-    def accepts(self, media_type):
-        return any(
-            accepted_type.match(media_type) for accepted_type in self.accepted_types
-        )
+        The nonce is generated once per request and cached. It can be used in
+        CSP headers and templates to allow specific inline scripts/styles while
+        blocking others.
+        """
+        return secrets.token_urlsafe(16)
 
-    def _set_content_type_params(self, meta):
-        """Set content_type, content_params, and encoding."""
-        self.content_type, self.content_params = parse_header_parameters(
-            meta.get("CONTENT_TYPE", "")
-        )
-        if "charset" in self.content_params:
-            try:
-                codecs.lookup(self.content_params["charset"])
-            except LookupError:
-                pass
-            else:
-                self.encoding = self.content_params["charset"]
+    @cached_property
+    def accepted_types(self) -> list[MediaType]:
+        """Return accepted media types sorted by quality value (highest first).
+
+        When quality values are equal, the original order from the Accept header
+        is preserved (as per HTTP spec).
+        """
+        header = self.headers.get("Accept", "*/*")
+        types = [MediaType(token) for token in header.split(",") if token.strip()]
+        return sorted(types, key=lambda t: t.quality, reverse=True)
+
+    def get_preferred_type(self, *media_types: str) -> str | None:
+        """Return the most preferred media type from the given options.
+
+        Checks the Accept header in priority order (by quality value) and returns
+        the first matching media type from the provided options.
+
+        Returns None if none of the options are accepted.
+
+        Example:
+            # Accept: text/html;q=1.0, application/json;q=0.5
+            request.get_preferred_type("application/json", "text/html")  # Returns "text/html"
+        """
+        for accepted in self.accepted_types:
+            for option in media_types:
+                if accepted.match(option):
+                    return option
+        return None
+
+    def accepts(self, media_type: str) -> bool:
+        """Check if the given media type is accepted."""
+        return self.get_preferred_type(media_type) is not None
 
     @cached_property
-    def host(self):
+    def host(self) -> str:
         """
         Return the HTTP host using the environment or request headers.
 
@@ -129,28 +150,60 @@ class HttpRequest:
         property can safely return the host without any validation.
         """
         # We try three options, in order of decreasing preference.
-        if settings.USE_X_FORWARDED_HOST and ("HTTP_X_FORWARDED_HOST" in self.meta):
-            host = self.meta["HTTP_X_FORWARDED_HOST"]
-        elif "HTTP_HOST" in self.meta:
-            host = self.meta["HTTP_HOST"]
+        if settings.HTTP_X_FORWARDED_HOST and (
+            xff_host := self.headers.get("X-Forwarded-Host")
+        ):
+            host = xff_host
+        elif http_host := self.headers.get("Host"):
+            host = http_host
         else:
             # Reconstruct the host using the algorithm from PEP 333.
-            host = self.meta["SERVER_NAME"]
+            host = self.environ["SERVER_NAME"]
             server_port = self.port
             if server_port != ("443" if self.is_https() else "80"):
                 host = f"{host}:{server_port}"
         return host
 
     @cached_property
-    def port(self):
+    def port(self) -> str:
         """Return the port number for the request as a string."""
-        if settings.USE_X_FORWARDED_PORT and "HTTP_X_FORWARDED_PORT" in self.meta:
-            port = self.meta["HTTP_X_FORWARDED_PORT"]
+        if settings.HTTP_X_FORWARDED_PORT and (
+            xff_port := self.headers.get("X-Forwarded-Port")
+        ):
+            port = xff_port
         else:
-            port = self.meta["SERVER_PORT"]
+            port = self.environ["SERVER_PORT"]
         return str(port)
 
-    def get_full_path(self, force_append_slash=False):
+    @cached_property
+    def client_ip(self) -> str:
+        """Return the client's IP address.
+
+        If HTTP_X_FORWARDED_FOR is True, checks the X-Forwarded-For header first
+        (using the first/leftmost IP). Otherwise returns REMOTE_ADDR directly.
+
+        Only enable HTTP_X_FORWARDED_FOR when behind a trusted proxy that
+        overwrites the X-Forwarded-For header.
+        """
+        if settings.HTTP_X_FORWARDED_FOR:
+            if xff := self.headers.get("X-Forwarded-For"):
+                return xff.split(",")[0].strip()
+        return self.environ["REMOTE_ADDR"]
+
+    @property
+    def query_string(self) -> str:
+        """Return the raw query string from the request URL."""
+        return self.environ.get("QUERY_STRING", "")
+
+    @property
+    def content_length(self) -> int:
+        """Return the Content-Length header value, or 0 if not provided."""
+        try:
+            return int(self.environ.get("CONTENT_LENGTH") or 0)
+        except (ValueError, TypeError):
+            return 0
+
+    def get_full_path(self, force_append_slash: bool = False) -> str:
         """
         Return the full path for the request, including query string.
 
@@ -160,7 +213,7 @@ class HttpRequest:
         # RFC 3986 requires query string arguments to be in the ASCII range.
         # Rather than crash if this doesn't happen, we encode defensively.
 
-        def escape_uri_path(path):
+        def escape_uri_path(path: str) -> str:
             """
             Escape the unsafe characters from the path portion of a Uniform Resource
             Identifier (URI).
@@ -179,12 +232,10 @@ class HttpRequest:
         return "{}{}{}".format(
             escape_uri_path(self.path),
             "/" if force_append_slash and not self.path.endswith("/") else "",
-            ("?" + iri_to_uri(self.meta.get("QUERY_STRING", "")))
-            if self.meta.get("QUERY_STRING", "")
-            else "",
+            ("?" + (iri_to_uri(self.query_string) or "")) if self.query_string else "",
         )
 
-    def build_absolute_uri(self, location=None):
+    def build_absolute_uri(self, location: str | None = None) -> str:
         """
         Build an absolute URI from the location and the variables available in
         this request. If no ``location`` is specified, build the absolute URI
@@ -224,9 +275,9 @@ class HttpRequest:
                 # base path.
                 location = urljoin(current_scheme_host + self.path, location)
 
-        return iri_to_uri(location)
+        return iri_to_uri(location) or ""
 
-    def _get_scheme(self):
+    def _get_scheme(self) -> str:
         """
         Hook for subclasses like WSGIRequest to implement. Return 'http' by
         default.
@@ -234,76 +285,27 @@ class HttpRequest:
         return "http"
 
     @property
-    def scheme(self):
+    def scheme(self) -> str:
         if settings.HTTPS_PROXY_HEADER:
-            try:
-                header, secure_value = settings.HTTPS_PROXY_HEADER
-            except ValueError:
+            if ":" not in settings.HTTPS_PROXY_HEADER:
                 raise ImproperlyConfigured(
-                    "The HTTPS_PROXY_HEADER setting must be a tuple containing "
-                    "two values."
+                    "The HTTPS_PROXY_HEADER setting must be a string in the format "
+                    "'Header-Name: value' (e.g., 'X-Forwarded-Proto: https')."
                 )
-            header_value = self.meta.get(header)
+            header, secure_value = settings.HTTPS_PROXY_HEADER.split(":", 1)
+            header = header.strip()
+            secure_value = secure_value.strip()
+            header_value = self.headers.get(header)
             if header_value is not None:
                 header_value, *_ = header_value.split(",", 1)
                 return "https" if header_value.strip() == secure_value else "http"
         return self._get_scheme()
 
-    def is_https(self):
+    def is_https(self) -> bool:
         return self.scheme == "https"
 
     @property
-    def encoding(self):
-        return self._encoding
-
-    @encoding.setter
-    def encoding(self, val):
-        """
-        Set the encoding used for query_params/data accesses. If the query_params or data
-        dictionary has already been created, remove and recreate it on the
-        next access (so that it is decoded correctly).
-        """
-        self._encoding = val
-        if hasattr(self, "query_params"):
-            del self.query_params
-        if hasattr(self, "_data"):
-            del self._data
-
-    def _initialize_handlers(self):
-        self._upload_handlers = [
-            uploadhandler.load_handler(handler, self)
-            for handler in settings.FILE_UPLOAD_HANDLERS
-        ]
-
-    @property
-    def upload_handlers(self):
-        if not self._upload_handlers:
-            # If there are no upload handlers defined, initialize them from settings.
-            self._initialize_handlers()
-        return self._upload_handlers
-
-    @upload_handlers.setter
-    def upload_handlers(self, upload_handlers):
-        if hasattr(self, "_files"):
-            raise AttributeError(
-                "You cannot set the upload handlers after the upload has been "
-                "processed."
-            )
-        self._upload_handlers = upload_handlers
-
-    def parse_file_upload(self, meta, post_data):
-        """Return a tuple of (data QueryDict, files MultiValueDict)."""
-        self.upload_handlers = ImmutableList(
-            self.upload_handlers,
-            warning=(
-                "You cannot alter upload handlers after the upload has been processed."
-            ),
-        )
-        parser = MultiPartParser(meta, post_data, self.upload_handlers, self.encoding)
-        return parser.parse()
-
-    @property
-    def body(self):
+    def body(self) -> bytes:
         if not hasattr(self, "_body"):
             if self._read_started:
                 raise RawPostDataException(
@@ -313,10 +315,9 @@ class HttpRequest:
             # Limit the maximum request data size that will be handled in-memory.
             if (
                 settings.DATA_UPLOAD_MAX_MEMORY_SIZE is not None
-                and int(self.meta.get("CONTENT_LENGTH") or 0)
-                > settings.DATA_UPLOAD_MAX_MEMORY_SIZE
+                and self.content_length > settings.DATA_UPLOAD_MAX_MEMORY_SIZE
             ):
-                raise RequestDataTooBig(
+                raise RequestDataTooBigError400(
                     "Request body exceeded settings.DATA_UPLOAD_MAX_MEMORY_SIZE."
                 )
 
@@ -329,84 +330,123 @@ class HttpRequest:
             self._stream = BytesIO(self._body)
         return self._body
 
-    def _mark_post_parse_error(self):
-        self._data = QueryDict()
-        self._files = MultiValueDict()
+    @cached_property
+    def _multipart_data(self) -> tuple[QueryDict, MultiValueDict]:
+        """Parse multipart/form-data. Used internally by form_data and files properties.
 
-    def _load_data_and_files(self):
-        """Populate self._data and self._files"""
+        Raises MultiPartParserError or TooManyFilesSentError400 for malformed uploads,
+        which are handled by response_for_exception() as 400 errors.
+        """
+        return MultiPartParser(self).parse()
 
-        if self._read_started and not hasattr(self, "_body"):
-            self._mark_post_parse_error()
-            return
+    @cached_property
+    def json_data(self) -> dict[str, Any]:
+        """
+        Parsed JSON object from request body.
 
-        if self.content_type.startswith("application/json"):
-            try:
-                self._data = json.loads(self.body)
-                self._files = MultiValueDict()
-            except json.JSONDecodeError:
-                self._mark_post_parse_error()
-                raise
-        elif self.content_type == "multipart/form-data":
-            if hasattr(self, "_body"):
-                # Use already read data
-                data = BytesIO(self._body)
-            else:
-                data = self
-            try:
-                self._data, self._files = self.parse_file_upload(self.meta, data)
-            except (MultiPartParserError, TooManyFilesSent):
-                # An error occurred while parsing POST data. Since when
-                # formatting the error the request handler might access
-                # self.POST, set self._post and self._file to prevent
-                # attempts to parse POST data again.
-                self._mark_post_parse_error()
-                raise
-        elif self.content_type == "application/x-www-form-urlencoded":
-            self._data, self._files = (
-                QueryDict(self.body, encoding=self._encoding),
-                MultiValueDict(),
+        Returns dict for JSON objects.
+        Raises BadRequestError400 if JSON is invalid or not an object.
+        Raises ValueError if request content-type is not JSON.
+
+        Use this when you expect JSON object data and want type-safe dict access.
+        """
+        if not self.content_type or not self.content_type.startswith(
+            "application/json"
+        ):
+            raise ValueError(
+                f"Request content-type is not JSON (got: {self.content_type})"
+            )
+        try:
+            parsed = json.loads(self.body)
+        except json.JSONDecodeError as e:
+            raise BadRequestError400(f"Invalid JSON in request body: {e}") from e
+
+        if not isinstance(parsed, dict):
+            raise BadRequestError400(
+                f"Expected JSON object, got {type(parsed).__name__}"
             )
+        return parsed
+
+    @cached_property
+    def form_data(self) -> QueryDict:
+        """
+        Form data from POST body.
+
+        Returns QueryDict for application/x-www-form-urlencoded or
+        multipart/form-data content types.
+        Returns empty QueryDict if Content-Type is missing (e.g., GET requests).
+        Raises ValueError if request has a different content-type with a body.
+
+        Use this when you expect form data and want type-safe QueryDict access.
+        """
+        if self.content_type == "application/x-www-form-urlencoded":
+            return QueryDict(self.body, encoding=self.encoding)
+        elif self.content_type == "multipart/form-data":
+            return self._multipart_data[0]
+        elif not self.content_type:
+            # No Content-Type (e.g., GET requests) - return empty QueryDict
+            return QueryDict(b"", encoding=self.encoding)
         else:
-            self._data, self._files = (
-                QueryDict(encoding=self._encoding),
-                MultiValueDict(),
+            raise ValueError(
+                f"Request content-type is not form data (got: {self.content_type})"
             )
 
-    def close(self):
-        if hasattr(self, "_files"):
-            for f in chain.from_iterable(list_[1] for list_ in self._files.lists()):
+    @cached_property
+    def files(self) -> MultiValueDict:
+        """
+        File uploads from multipart/form-data requests.
+
+        Returns MultiValueDict of uploaded files for multipart requests,
+        or empty MultiValueDict for other content types.
+        """
+        if self.content_type == "multipart/form-data":
+            return self._multipart_data[1]
+        return MultiValueDict()
+
+    def close(self) -> None:
+        # Close any uploaded files if they were accessed
+        if self.content_type == "multipart/form-data" and hasattr(
+            self, "_multipart_data"
+        ):
+            _, files = self._multipart_data
+            for f in chain.from_iterable(list_[1] for list_ in files.lists()):
                 f.close()
 
     # File-like and iterator interface.
     #
     # Expects self._stream to be set to an appropriate source of bytes by
     # a corresponding request subclass (e.g. WSGIRequest).
-    # Also when request data has already been read by request.data or
-    # request.body, self._stream points to a BytesIO instance
-    # containing that data.
+    # Also when request data has already been read by request.json_data,
+    # request.form_data, or request.body, self._stream points to a BytesIO
+    # instance containing that data.
 
-    def read(self, *args, **kwargs):
+    def read(self, *args: Any, **kwargs: Any) -> bytes:
         self._read_started = True
         try:
             return self._stream.read(*args, **kwargs)
         except OSError as e:
             raise UnreadablePostError(*e.args) from e
 
-    def readline(self, *args, **kwargs):
+    def readline(self, *args: Any, **kwargs: Any) -> bytes:
         self._read_started = True
         try:
             return self._stream.readline(*args, **kwargs)
         except OSError as e:
             raise UnreadablePostError(*e.args) from e
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[bytes]:
         return iter(self.readline, b"")
 
-    def readlines(self):
+    def readlines(self) -> list[bytes]:
         return list(self)
 
-    def get_signed_cookie(self, key, default=None, salt="", max_age=None):
+    def get_signed_cookie(
+        self,
+        key: str,
+        default: str | None = None,
+        salt: str = "",
+        max_age: int | None = None,
+    ) -> str | None:
         """
         Retrieve a cookie value signed with the SECRET_KEY.
 
@@ -421,12 +461,12 @@ class HttpRequest:
         return unsign_cookie_value(key, cookie_value, salt, max_age, default)
 
 
-class HttpHeaders(CaseInsensitiveMapping):
+class RequestHeaders(CaseInsensitiveMapping):
     HTTP_PREFIX = "HTTP_"
     # PEP 333 gives two headers which aren't prepended with HTTP_.
     UNPREFIXED_HEADERS = {"CONTENT_TYPE", "CONTENT_LENGTH"}
 
-    def __init__(self, environ):
+    def __init__(self, environ: dict[str, Any]):
         headers = {}
         for header, value in environ.items():
             name = self.parse_header_name(header)
@@ -434,12 +474,12 @@ class HttpHeaders(CaseInsensitiveMapping):
                 headers[name] = value
         super().__init__(headers)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> str:
         """Allow header lookup using underscores in place of hyphens."""
         return super().__getitem__(key.replace("_", "-"))
 
     @classmethod
-    def parse_header_name(cls, header):
+    def parse_header_name(cls, header: str) -> str | None:
         if header.startswith(cls.HTTP_PREFIX):
             header = header.removeprefix(cls.HTTP_PREFIX)
         elif header not in cls.UNPREFIXED_HEADERS:
@@ -447,14 +487,14 @@ class HttpHeaders(CaseInsensitiveMapping):
         return header.replace("_", "-").title()
 
     @classmethod
-    def to_wsgi_name(cls, header):
+    def to_wsgi_name(cls, header: str) -> str:
         header = header.replace("-", "_").upper()
         if header in cls.UNPREFIXED_HEADERS:
             return header
         return f"{cls.HTTP_PREFIX}{header}"
 
     @classmethod
-    def to_wsgi_names(cls, headers):
+    def to_wsgi_names(cls, headers: dict[str, Any]) -> dict[str, Any]:
         return {
             cls.to_wsgi_name(header_name): value
             for header_name, value in headers.items()
@@ -481,22 +521,28 @@ class QueryDict(MultiValueDict):
     _mutable = True
     _encoding = None
 
-    def __init__(self, query_string=None, mutable=False, encoding=None):
+    def __init__(
+        self,
+        query_string: str | bytes | None = None,
+        mutable: bool = False,
+        encoding: str | None = None,
+    ):
         super().__init__()
         self.encoding = encoding or settings.DEFAULT_CHARSET
         query_string = query_string or ""
-        parse_qsl_kwargs = {
+        parse_qsl_kwargs: dict[str, Any] = {
             "keep_blank_values": True,
             "encoding": self.encoding,
             "max_num_fields": settings.DATA_UPLOAD_MAX_NUMBER_FIELDS,
         }
         if isinstance(query_string, bytes):
             # query_string normally contains URL-encoded data, a subset of ASCII.
+            query_bytes = query_string
             try:
-                query_string = query_string.decode(self.encoding)
+                query_string = query_bytes.decode(self.encoding)
             except UnicodeDecodeError:
                 # ... but some user agents are misbehaving :-(
-                query_string = query_string.decode("iso-8859-1")
+                query_string = query_bytes.decode("iso-8859-1")
         try:
             for key, value in parse_qsl(query_string, **parse_qsl_kwargs):
                 self.appendlist(key, value)
@@ -505,14 +551,20 @@ class QueryDict(MultiValueDict):
             # parse_qsl() is True. As that is not used by Plain, assume that
             # the exception was raised by exceeding the value of max_num_fields
             # instead of fragile checks of exception message strings.
-            raise TooManyFieldsSent(
+            raise TooManyFieldsSentError400(
                 "The number of GET/POST parameters exceeded "
                 "settings.DATA_UPLOAD_MAX_NUMBER_FIELDS."
             ) from e
         self._mutable = mutable
 
     @classmethod
-    def fromkeys(cls, iterable, value="", mutable=False, encoding=None):
+    def fromkeys(  # type: ignore[override]
+        cls,
+        iterable: Any,
+        value: str = "",
+        mutable: bool = False,
+        encoding: str | None = None,
+    ) -> QueryDict:
         """
         Return a new QueryDict with keys (may be repeated) from an iterable and
         values from value.
@@ -525,81 +577,141 @@ class QueryDict(MultiValueDict):
         return q
 
     @property
-    def encoding(self):
+    def encoding(self) -> str:
         if self._encoding is None:
             self._encoding = settings.DEFAULT_CHARSET
         return self._encoding
 
     @encoding.setter
-    def encoding(self, value):
+    def encoding(self, value: str) -> None:
         self._encoding = value
 
-    def _assert_mutable(self):
+    def _assert_mutable(self) -> None:
         if not self._mutable:
             raise AttributeError("This QueryDict instance is immutable")
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: Any) -> None:
         self._assert_mutable()
-        key = bytes_to_text(key, self.encoding)
-        value = bytes_to_text(value, self.encoding)
+        key = self.bytes_to_text(key, self.encoding)
+        value = self.bytes_to_text(value, self.encoding)
         super().__setitem__(key, value)
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: str) -> None:
         self._assert_mutable()
         super().__delitem__(key)
 
-    def __copy__(self):
+    def __getitem__(self, key: str) -> str:  # type: ignore[override]
+        """
+        Return the last data value for this key as a string.
+        QueryDict values are always strings.
+        """
+        return super().__getitem__(key)
+
+    def __copy__(self) -> QueryDict:
         result = self.__class__("", mutable=True, encoding=self.encoding)
         for key, value in self.lists():
             result.setlist(key, value)
         return result
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: dict[int, Any]) -> QueryDict:
         result = self.__class__("", mutable=True, encoding=self.encoding)
         memo[id(self)] = result
         for key, value in self.lists():
             result.setlist(copy.deepcopy(key, memo), copy.deepcopy(value, memo))
         return result
 
-    def setlist(self, key, list_):
+    def setlist(self, key: str, list_: list[Any]) -> None:
         self._assert_mutable()
-        key = bytes_to_text(key, self.encoding)
-        list_ = [bytes_to_text(elt, self.encoding) for elt in list_]
+        key = self.bytes_to_text(key, self.encoding)
+        list_ = [self.bytes_to_text(elt, self.encoding) for elt in list_]
         super().setlist(key, list_)
 
-    def setlistdefault(self, key, default_list=None):
+    def setlistdefault(
+        self, key: str, default_list: list[Any] | None = None
+    ) -> list[Any]:
         self._assert_mutable()
         return super().setlistdefault(key, default_list)
 
-    def appendlist(self, key, value):
+    def appendlist(self, key: str, value: Any) -> None:
         self._assert_mutable()
-        key = bytes_to_text(key, self.encoding)
-        value = bytes_to_text(value, self.encoding)
+        key = self.bytes_to_text(key, self.encoding)
+        value = self.bytes_to_text(value, self.encoding)
         super().appendlist(key, value)
 
-    def pop(self, key, *args):
+    def getlist(self, key: str, default: list[str] | None = None) -> list[str]:
+        """
+        Return the list of values for the key as strings.
+        QueryDict values are always strings.
+        """
+        return super().getlist(key, default)
+
+    @overload
+    def get(self, key: str) -> str | None: ...
+
+    @overload
+    def get(self, key: str, default: str) -> str: ...
+
+    @overload
+    def get(self, key: str, default: _T) -> str | _T: ...
+
+    def get(self, key: str, default: Any = None) -> str | Any:  # type: ignore[override]
+        """
+        Return the last data value for the passed key. If key doesn't exist
+        or value is an empty list, return `default`.
+
+        QueryDict values are always strings (from URL parsing), but the
+        return type preserves the type of the default parameter for type safety.
+
+        Examples:
+            get("page")         -> str | None
+            get("page", "1")    -> str
+            get("page", 1)      -> str | int
+        """
+        return super().get(key, default)
+
+    @overload
+    def pop(self, key: str) -> str: ...
+
+    @overload
+    def pop(self, key: str, default: str) -> str: ...
+
+    @overload
+    def pop(self, key: str, default: _T) -> str | _T: ...
+
+    def pop(self, key: str, *args: Any) -> str | Any:  # type: ignore[override]
+        """
+        Remove and return a value for the key.
+
+        QueryDict values are always strings, but the return type preserves
+        the type of the default parameter for type safety.
+
+        Examples:
+            pop("page")         -> str (or raises KeyError)
+            pop("page", "1")    -> str
+            pop("page", 1)      -> str | int
+        """
         self._assert_mutable()
         return super().pop(key, *args)
 
-    def popitem(self):
+    def popitem(self) -> tuple[str, Any]:
         self._assert_mutable()
         return super().popitem()
 
-    def clear(self):
+    def clear(self) -> None:
         self._assert_mutable()
         super().clear()
 
-    def setdefault(self, key, default=None):
+    def setdefault(self, key: str, default: Any = None) -> Any:
         self._assert_mutable()
-        key = bytes_to_text(key, self.encoding)
-        default = bytes_to_text(default, self.encoding)
+        key = self.bytes_to_text(key, self.encoding)
+        default = self.bytes_to_text(default, self.encoding)
         return super().setdefault(key, default)
 
-    def copy(self):
+    def copy(self) -> QueryDict:
         """Return a mutable copy of this object."""
         return self.__deepcopy__({})
 
-    def urlencode(self, safe=None):
+    def urlencode(self, safe: str | None = None) -> str:
         """
         Return an encoded string of all query string arguments.
 
@@ -614,14 +726,14 @@ class QueryDict(MultiValueDict):
         """
         output = []
         if safe:
-            safe = safe.encode(self.encoding)
+            safe_bytes: bytes = safe.encode(self.encoding)
 
-            def encode(k, v):
-                return f"{quote(k, safe)}={quote(v, safe)}"
+            def encode(k: bytes, v: bytes) -> str:
+                return f"{quote(k, safe_bytes)}={quote(v, safe_bytes)}"
 
         else:
 
-            def encode(k, v):
+            def encode(k: bytes, v: bytes) -> str:
                 return urlencode({k: v})
 
         for k, list_ in self.lists():
@@ -631,15 +743,31 @@ class QueryDict(MultiValueDict):
             )
         return "&".join(output)
 
+    # It's neither necessary nor appropriate to use
+    # plain.utils.encoding.force_str() for parsing URLs and form inputs. Thus,
+    # this slightly more restricted function, used by QueryDict.
+    @staticmethod
+    def bytes_to_text(s: Any, encoding: str) -> str:
+        """
+        Convert bytes objects to strings, using the given encoding. Illegally
+        encoded input characters are replaced with Unicode "unknown" codepoint
+        (\ufffd).
+
+        Return any non-bytes objects without change.
+        """
+        if isinstance(s, bytes):
+            return str(s, encoding, "replace")
+        else:
+            return s
+
 
 class MediaType:
-    def __init__(self, media_type_raw_line):
-        full_type, self.params = parse_header_parameters(
-            media_type_raw_line if media_type_raw_line else ""
-        )
+    def __init__(self, media_type_raw_line: str | MediaType):
+        line = str(media_type_raw_line) if media_type_raw_line else ""
+        full_type, self.params = parse_header_parameters(line)
         self.main_type, _, self.sub_type = full_type.partition("/")
 
-    def __str__(self):
+    def __str__(self) -> str:
         params_str = "".join(f"; {k}={v}" for k, v in self.params.items())
         return "{}{}{}".format(
             self.main_type,
@@ -647,38 +775,22 @@ class MediaType:
             params_str,
         )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__qualname__}: {self}>"
 
     @property
-    def is_all_types(self):
+    def is_all_types(self) -> bool:
         return self.main_type == "*" and self.sub_type == "*"
 
-    def match(self, other):
+    @property
+    def quality(self) -> float:
+        """Return the quality value from the Accept header (default 1.0)."""
+        return float(self.params.get("q", 1.0))
+
+    def match(self, other: str | MediaType) -> bool:
         if self.is_all_types:
             return True
         other = MediaType(other)
         if self.main_type == other.main_type and self.sub_type in {"*", other.sub_type}:
             return True
         return False
-
-
-# It's neither necessary nor appropriate to use
-# plain.utils.encoding.force_str() for parsing URLs and form inputs. Thus,
-# this slightly more restricted function, used by QueryDict.
-def bytes_to_text(s, encoding):
-    """
-    Convert bytes objects to strings, using the given encoding. Illegally
-    encoded input characters are replaced with Unicode "unknown" codepoint
-    (\ufffd).
-
-    Return any non-bytes objects without change.
-    """
-    if isinstance(s, bytes):
-        return str(s, encoding, "replace")
-    else:
-        return s
-
-
-def parse_accept_header(header):
-    return [MediaType(token) for token in header.split(",") if token.strip()]