From 0294d88b9c10fe079ecfe9e02129d52b1e95de54 Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Mon, 28 Oct 2024 09:29:57 -0700
Subject: [PATCH 1/5] inline annotations for datastructures

---
 CHANGES.rst                                   |   2 +
 src/werkzeug/datastructures/accept.py         |  98 +--
 src/werkzeug/datastructures/accept.pyi        |  54 --
 src/werkzeug/datastructures/auth.py           |   3 +-
 src/werkzeug/datastructures/cache_control.py  |  72 ++-
 src/werkzeug/datastructures/cache_control.pyi | 130 ----
 src/werkzeug/datastructures/csp.py            |  82 +--
 src/werkzeug/datastructures/csp.pyi           | 169 -----
 src/werkzeug/datastructures/etag.py           |  49 +-
 src/werkzeug/datastructures/etag.pyi          |  30 -
 src/werkzeug/datastructures/file_storage.py   |  85 +--
 src/werkzeug/datastructures/file_storage.pyi  |  49 --
 src/werkzeug/datastructures/headers.py        | 392 +++++++-----
 src/werkzeug/datastructures/headers.pyi       | 109 ----
 src/werkzeug/datastructures/mixins.py         | 274 +++++----
 src/werkzeug/datastructures/mixins.pyi        |  97 ---
 src/werkzeug/datastructures/range.py          | 122 ++--
 src/werkzeug/datastructures/range.pyi         |  57 --
 src/werkzeug/datastructures/structures.py     | 579 +++++++++++-------
 src/werkzeug/datastructures/structures.pyi    | 206 -------
 src/werkzeug/exceptions.py                    |   2 +-
 src/werkzeug/http.py                          |   4 +
 src/werkzeug/sansio/http.py                   |   1 -
 src/werkzeug/test.py                          |   4 +-
 src/werkzeug/utils.py                         |   2 +-
 25 files changed, 1095 insertions(+), 1577 deletions(-)
 delete mode 100644 src/werkzeug/datastructures/accept.pyi
 delete mode 100644 src/werkzeug/datastructures/cache_control.pyi
 delete mode 100644 src/werkzeug/datastructures/csp.pyi
 delete mode 100644 src/werkzeug/datastructures/etag.pyi
 delete mode 100644 src/werkzeug/datastructures/file_storage.pyi
 delete mode 100644 src/werkzeug/datastructures/headers.pyi
 delete mode 100644 src/werkzeug/datastructures/mixins.pyi
 delete mode 100644 src/werkzeug/datastructures/range.pyi
 delete mode 100644 src/werkzeug/datastructures/structures.pyi

diff --git a/CHANGES.rst b/CHANGES.rst
index 8280c91ba..2976f889a 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -18,6 +18,8 @@ Unreleased
     ``ResponseCacheControl``. :issue:`2948`
 -   Add 421 ``MisdirectedRequest`` HTTP exception. :issue:`2850`
 -   Increase default work factor for PBKDF2 to 1,000,000 iterations. :issue:`2969`
+-   Inline annotations for ``datastructures``, removing stub files.
+    :issue:`2970`
 
 
 
diff --git a/src/werkzeug/datastructures/accept.py b/src/werkzeug/datastructures/accept.py
index d80f0bbb8..44179a93f 100644
--- a/src/werkzeug/datastructures/accept.py
+++ b/src/werkzeug/datastructures/accept.py
@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import codecs
+import collections.abc as cabc
 import re
+import typing as t
 
 from .structures import ImmutableList
 
 
-class Accept(ImmutableList):
+class Accept(ImmutableList[tuple[str, float]]):
     """An :class:`Accept` object is just a list subclass for lists of
     ``(value, quality)`` tuples.  It is automatically sorted by specificity
     and quality.
@@ -42,29 +44,39 @@ class Accept(ImmutableList):
 
     """
 
-    def __init__(self, values=()):
+    def __init__(
+        self, values: Accept | cabc.Iterable[tuple[str, float]] | None = ()
+    ) -> None:
         if values is None:
-            list.__init__(self)
+            super().__init__()
             self.provided = False
         elif isinstance(values, Accept):
             self.provided = values.provided
-            list.__init__(self, values)
+            super().__init__(values)
         else:
             self.provided = True
             values = sorted(
                 values, key=lambda x: (self._specificity(x[0]), x[1]), reverse=True
             )
-            list.__init__(self, values)
+            super().__init__(values)
 
-    def _specificity(self, value):
+    def _specificity(self, value: str) -> tuple[bool, ...]:
         """Returns a tuple describing the value's specificity."""
         return (value != "*",)
 
-    def _value_matches(self, value, item):
+    def _value_matches(self, value: str, item: str) -> bool:
         """Check if a value matches a given accept item."""
         return item == "*" or item.lower() == value.lower()
 
-    def __getitem__(self, key):
+    @t.overload
+    def __getitem__(self, key: str) -> float: ...
+    @t.overload
+    def __getitem__(self, key: t.SupportsIndex) -> tuple[str, float]: ...
+    @t.overload
+    def __getitem__(self, key: slice) -> list[tuple[str, float]]: ...
+    def __getitem__(
+        self, key: str | t.SupportsIndex | slice
+    ) -> float | tuple[str, float] | list[tuple[str, float]]:
         """Besides index lookup (getting item n) you can also pass it a string
         to get the quality for the item.  If the item is not in the list, the
         returned quality is ``0``.
@@ -73,7 +85,7 @@ def __getitem__(self, key):
             return self.quality(key)
         return list.__getitem__(self, key)
 
-    def quality(self, key):
+    def quality(self, key: str) -> float:
         """Returns the quality of the key.
 
         .. versionadded:: 0.6
@@ -85,17 +97,17 @@ def quality(self, key):
                 return quality
         return 0
 
-    def __contains__(self, value):
+    def __contains__(self, value: str) -> bool:  # type: ignore[override]
         for item, _quality in self:
             if self._value_matches(value, item):
                 return True
         return False
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         pairs_str = ", ".join(f"({x!r}, {y})" for x, y in self)
         return f"{type(self).__name__}([{pairs_str}])"
 
-    def index(self, key):
+    def index(self, key: str | tuple[str, float]) -> int:  # type: ignore[override]
         """Get the position of an entry or raise :exc:`ValueError`.
 
         :param key: The key to be looked up.
@@ -111,7 +123,7 @@ def index(self, key):
             raise ValueError(key)
         return list.index(self, key)
 
-    def find(self, key):
+    def find(self, key: str | tuple[str, float]) -> int:
         """Get the position of an entry or return -1.
 
         :param key: The key to be looked up.
@@ -121,12 +133,12 @@ def find(self, key):
         except ValueError:
             return -1
 
-    def values(self):
+    def values(self) -> cabc.Iterator[str]:
         """Iterate over all values."""
         for item in self:
             yield item[0]
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Convert the header set into an HTTP header string."""
         result = []
         for value, quality in self:
@@ -135,17 +147,23 @@ def to_header(self):
             result.append(value)
         return ",".join(result)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def _best_single_match(self, match):
+    def _best_single_match(self, match: str) -> tuple[str, float] | None:
         for client_item, quality in self:
             if self._value_matches(match, client_item):
                 # self is sorted by specificity descending, we can exit
                 return client_item, quality
         return None
 
-    def best_match(self, matches, default=None):
+    @t.overload
+    def best_match(self, matches: cabc.Iterable[str]) -> str | None: ...
+    @t.overload
+    def best_match(self, matches: cabc.Iterable[str], default: str = ...) -> str: ...
+    def best_match(
+        self, matches: cabc.Iterable[str], default: str | None = None
+    ) -> str | None:
         """Returns the best match from a list of possible matches based
         on the specificity and quality of the client. If two items have the
         same quality and specificity, the one is returned that comes first.
@@ -154,8 +172,8 @@ def best_match(self, matches, default=None):
         :param default: the value that is returned if none match
         """
         result = default
-        best_quality = -1
-        best_specificity = (-1,)
+        best_quality: float = -1
+        best_specificity: tuple[float, ...] = (-1,)
         for server_item in matches:
             match = self._best_single_match(server_item)
             if not match:
@@ -172,16 +190,18 @@ def best_match(self, matches, default=None):
         return result
 
     @property
-    def best(self):
+    def best(self) -> str | None:
         """The best match as value."""
         if self:
             return self[0][0]
 
+        return None
+
 
 _mime_split_re = re.compile(r"/|(?:\s*;\s*)")
 
 
-def _normalize_mime(value):
+def _normalize_mime(value: str) -> list[str]:
     return _mime_split_re.split(value.lower())
 
 
@@ -190,10 +210,10 @@ class MIMEAccept(Accept):
     mimetypes.
     """
 
-    def _specificity(self, value):
+    def _specificity(self, value: str) -> tuple[bool, ...]:
         return tuple(x != "*" for x in _mime_split_re.split(value))
 
-    def _value_matches(self, value, item):
+    def _value_matches(self, value: str, item: str) -> bool:
         # item comes from the client, can't match if it's invalid.
         if "/" not in item:
             return False
@@ -234,27 +254,25 @@ def _value_matches(self, value, item):
         )
 
     @property
-    def accept_html(self):
+    def accept_html(self) -> bool:
         """True if this object accepts HTML."""
-        return (
-            "text/html" in self or "application/xhtml+xml" in self or self.accept_xhtml
-        )
+        return "text/html" in self or self.accept_xhtml  # type: ignore[comparison-overlap]
 
     @property
-    def accept_xhtml(self):
+    def accept_xhtml(self) -> bool:
         """True if this object accepts XHTML."""
-        return "application/xhtml+xml" in self or "application/xml" in self
+        return "application/xhtml+xml" in self or "application/xml" in self  # type: ignore[comparison-overlap]
 
     @property
-    def accept_json(self):
+    def accept_json(self) -> bool:
         """True if this object accepts JSON."""
-        return "application/json" in self
+        return "application/json" in self  # type: ignore[comparison-overlap]
 
 
 _locale_delim_re = re.compile(r"[_-]")
 
 
-def _normalize_lang(value):
+def _normalize_lang(value: str) -> list[str]:
     """Process a language tag for matching."""
     return _locale_delim_re.split(value.lower())
 
@@ -262,10 +280,16 @@ def _normalize_lang(value):
 class LanguageAccept(Accept):
     """Like :class:`Accept` but with normalization for language tags."""
 
-    def _value_matches(self, value, item):
+    def _value_matches(self, value: str, item: str) -> bool:
         return item == "*" or _normalize_lang(value) == _normalize_lang(item)
 
-    def best_match(self, matches, default=None):
+    @t.overload
+    def best_match(self, matches: cabc.Iterable[str]) -> str | None: ...
+    @t.overload
+    def best_match(self, matches: cabc.Iterable[str], default: str = ...) -> str: ...
+    def best_match(
+        self, matches: cabc.Iterable[str], default: str | None = None
+    ) -> str | None:
         """Given a list of supported values, finds the best match from
         the list of accepted values.
 
@@ -316,8 +340,8 @@ def best_match(self, matches, default=None):
 class CharsetAccept(Accept):
     """Like :class:`Accept` but with normalization for charsets."""
 
-    def _value_matches(self, value, item):
-        def _normalize(name):
+    def _value_matches(self, value: str, item: str) -> bool:
+        def _normalize(name: str) -> str:
             try:
                 return codecs.lookup(name).name
             except LookupError:
diff --git a/src/werkzeug/datastructures/accept.pyi b/src/werkzeug/datastructures/accept.pyi
deleted file mode 100644
index 4b74dd950..000000000
--- a/src/werkzeug/datastructures/accept.pyi
+++ /dev/null
@@ -1,54 +0,0 @@
-from collections.abc import Iterable
-from collections.abc import Iterator
-from typing import overload
-
-from .structures import ImmutableList
-
-class Accept(ImmutableList[tuple[str, int]]):
-    provided: bool
-    def __init__(
-        self, values: Accept | Iterable[tuple[str, float]] | None = None
-    ) -> None: ...
-    def _specificity(self, value: str) -> tuple[bool, ...]: ...
-    def _value_matches(self, value: str, item: str) -> bool: ...
-    @overload  # type: ignore
-    def __getitem__(self, key: str) -> int: ...
-    @overload
-    def __getitem__(self, key: int) -> tuple[str, int]: ...
-    @overload
-    def __getitem__(self, key: slice) -> Iterable[tuple[str, int]]: ...
-    def quality(self, key: str) -> int: ...
-    def __contains__(self, value: str) -> bool: ...  # type: ignore
-    def index(self, key: str) -> int: ...  # type: ignore
-    def find(self, key: str) -> int: ...
-    def values(self) -> Iterator[str]: ...
-    def to_header(self) -> str: ...
-    def _best_single_match(self, match: str) -> tuple[str, int] | None: ...
-    @overload
-    def best_match(self, matches: Iterable[str], default: str) -> str: ...
-    @overload
-    def best_match(
-        self, matches: Iterable[str], default: str | None = None
-    ) -> str | None: ...
-    @property
-    def best(self) -> str: ...
-
-def _normalize_mime(value: str) -> list[str]: ...
-
-class MIMEAccept(Accept):
-    def _specificity(self, value: str) -> tuple[bool, ...]: ...
-    def _value_matches(self, value: str, item: str) -> bool: ...
-    @property
-    def accept_html(self) -> bool: ...
-    @property
-    def accept_xhtml(self) -> bool: ...
-    @property
-    def accept_json(self) -> bool: ...
-
-def _normalize_lang(value: str) -> list[str]: ...
-
-class LanguageAccept(Accept):
-    def _value_matches(self, value: str, item: str) -> bool: ...
-
-class CharsetAccept(Accept):
-    def _value_matches(self, value: str, item: str) -> bool: ...
diff --git a/src/werkzeug/datastructures/auth.py b/src/werkzeug/datastructures/auth.py
index a3ca0de46..42f7aa468 100644
--- a/src/werkzeug/datastructures/auth.py
+++ b/src/werkzeug/datastructures/auth.py
@@ -2,6 +2,7 @@
 
 import base64
 import binascii
+import collections.abc as cabc
 import typing as t
 
 from ..http import dump_header
@@ -176,7 +177,7 @@ def __init__(
             values, lambda _: self._trigger_on_update()
         )
         self._token = token
-        self._on_update: t.Callable[[WWWAuthenticate], None] | None = None
+        self._on_update: cabc.Callable[[WWWAuthenticate], None] | None = None
 
     def _trigger_on_update(self) -> None:
         if self._on_update is not None:
diff --git a/src/werkzeug/datastructures/cache_control.py b/src/werkzeug/datastructures/cache_control.py
index fa7ed0a71..e185944b3 100644
--- a/src/werkzeug/datastructures/cache_control.py
+++ b/src/werkzeug/datastructures/cache_control.py
@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+import collections.abc as cabc
+import typing as t
+
 from .mixins import ImmutableDictMixin
-from .mixins import UpdateDictMixin
+from .structures import CallbackDict
 
 
-def cache_control_property(key, empty, type):
+def cache_control_property(key: str, empty: t.Any, type: type[t.Any] | None) -> t.Any:
     """Return a new property object for a cache header. Useful if you
     want to add support for a cache extension in a subclass.
 
@@ -19,7 +22,7 @@ def cache_control_property(key, empty, type):
     )
 
 
-class _CacheControl(UpdateDictMixin, dict):
+class _CacheControl(CallbackDict[str, t.Any]):
     """Subclass of a dict that stores values for a Cache-Control header.  It
     has accessors for all the cache-control directives specified in RFC 2616.
     The class does not differentiate between request and response directives.
@@ -59,17 +62,22 @@ class _CacheControl(UpdateDictMixin, dict):
        no longer existing `CacheControl` class.
     """
 
-    no_cache = cache_control_property("no-cache", "*", None)
-    no_store = cache_control_property("no-store", None, bool)
-    max_age = cache_control_property("max-age", -1, int)
-    no_transform = cache_control_property("no-transform", None, bool)
-
-    def __init__(self, values=(), on_update=None):
-        dict.__init__(self, values or ())
-        self.on_update = on_update
+    no_cache: str | bool | None = cache_control_property("no-cache", "*", None)
+    no_store: bool = cache_control_property("no-store", None, bool)
+    max_age: int | None = cache_control_property("max-age", -1, int)
+    no_transform: bool = cache_control_property("no-transform", None, bool)
+
+    def __init__(
+        self,
+        values: cabc.Mapping[str, t.Any] | cabc.Iterable[tuple[str, t.Any]] | None = (),
+        on_update: cabc.Callable[[_CacheControl], None] | None = None,
+    ):
+        super().__init__(values, on_update)
         self.provided = values is not None
 
-    def _get_cache_value(self, key, empty, type):
+    def _get_cache_value(
+        self, key: str, empty: t.Any, type: type[t.Any] | None
+    ) -> t.Any:
         """Used internally by the accessor properties."""
         if type is bool:
             return key in self
@@ -85,7 +93,9 @@ def _get_cache_value(self, key, empty, type):
             return value
         return None
 
-    def _set_cache_value(self, key, value, type):
+    def _set_cache_value(
+        self, key: str, value: t.Any, type: type[t.Any] | None
+    ) -> None:
         """Used internally by the accessor properties."""
         if type is bool:
             if value:
@@ -103,26 +113,26 @@ def _set_cache_value(self, key, value, type):
                 else:
                     self[key] = value
 
-    def _del_cache_value(self, key):
+    def _del_cache_value(self, key: str) -> None:
         """Used internally by the accessor properties."""
         if key in self:
             del self[key]
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Convert the stored values into a cache control header."""
         return http.dump_header(self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         kv_str = " ".join(f"{k}={v!r}" for k, v in sorted(self.items()))
         return f"<{type(self).__name__} {kv_str}>"
 
     cache_property = staticmethod(cache_control_property)
 
 
-class RequestCacheControl(ImmutableDictMixin, _CacheControl):
+class RequestCacheControl(ImmutableDictMixin[str, t.Any], _CacheControl):  # type: ignore[misc]
     """A cache control for requests.  This is immutable and gives access
     to all the request-relevant cache control headers.
 
@@ -146,9 +156,9 @@ class RequestCacheControl(ImmutableDictMixin, _CacheControl):
        both for request and response.
     """
 
-    max_stale = cache_control_property("max-stale", "*", int)
-    min_fresh = cache_control_property("min-fresh", None, int)
-    only_if_cached = cache_control_property("only-if-cached", None, bool)
+    max_stale: str | int | None = cache_control_property("max-stale", "*", int)
+    min_fresh: int | None = cache_control_property("min-fresh", None, int)
+    only_if_cached: bool = cache_control_property("only-if-cached", None, bool)
 
 
 class ResponseCacheControl(_CacheControl):
@@ -180,15 +190,17 @@ class ResponseCacheControl(_CacheControl):
        both for request and response.
     """
 
-    public = cache_control_property("public", None, bool)
-    private = cache_control_property("private", "*", None)
-    must_revalidate = cache_control_property("must-revalidate", None, bool)
-    proxy_revalidate = cache_control_property("proxy-revalidate", None, bool)
-    s_maxage = cache_control_property("s-maxage", None, int)
-    immutable = cache_control_property("immutable", None, bool)
-    must_understand = cache_control_property("must-understand", None, bool)
-    stale_while_revalidate = cache_control_property("stale-while-revalidate", None, int)
-    stale_if_error = cache_control_property("stale-if-error", None, int)
+    public: bool = cache_control_property("public", None, bool)
+    private: str | None = cache_control_property("private", "*", None)
+    must_revalidate: bool = cache_control_property("must-revalidate", None, bool)
+    proxy_revalidate: bool = cache_control_property("proxy-revalidate", None, bool)
+    s_maxage: int | None = cache_control_property("s-maxage", None, int)
+    immutable: bool = cache_control_property("immutable", None, bool)
+    must_understand: bool = cache_control_property("must-understand", None, bool)
+    stale_while_revalidate: int | None = cache_control_property(
+        "stale-while-revalidate", None, int
+    )
+    stale_if_error: int | None = cache_control_property("stale-if-error", None, int)
 
 
 # circular dependencies
diff --git a/src/werkzeug/datastructures/cache_control.pyi b/src/werkzeug/datastructures/cache_control.pyi
deleted file mode 100644
index 93c595db8..000000000
--- a/src/werkzeug/datastructures/cache_control.pyi
+++ /dev/null
@@ -1,130 +0,0 @@
-from collections.abc import Callable
-from collections.abc import Iterable
-from collections.abc import Mapping
-from typing import Literal
-from typing import TypeVar
-
-from .mixins import ImmutableDictMixin
-from .mixins import UpdateDictMixin
-
-T = TypeVar("T")
-_CPT = TypeVar("_CPT", str, int, bool)
-
-def cache_control_property(
-    key: str, empty: _CPT | None, type: type[_CPT]
-) -> property: ...
-
-class _CacheControl(
-    UpdateDictMixin[str, str | int | bool | None], dict[str, str | int | bool | None]
-):
-    provided: bool
-    def __init__(
-        self,
-        values: Mapping[str, str | int | bool | None]
-        | Iterable[tuple[str, str | int | bool | None]] = (),
-        on_update: Callable[[_CacheControl], None] | None = None,
-    ) -> None: ...
-    @property
-    def no_cache(self) -> str | None: ...
-    @no_cache.setter
-    def no_cache(self, value: Literal[True] | str | None) -> None: ...
-    @no_cache.deleter
-    def no_cache(self) -> None: ...
-    @property
-    def no_store(self) -> bool: ...
-    @no_store.setter
-    def no_store(self, value: bool | None) -> None: ...
-    @no_store.deleter
-    def no_store(self) -> None: ...
-    @property
-    def max_age(self) -> int | None: ...
-    @max_age.setter
-    def max_age(self, value: int | None) -> None: ...
-    @max_age.deleter
-    def max_age(self) -> None: ...
-    @property
-    def no_transform(self) -> bool: ...
-    @no_transform.setter
-    def no_transform(self, value: bool | None) -> None: ...
-    @no_transform.deleter
-    def no_transform(self) -> None: ...
-    def _get_cache_value(self, key: str, empty: T | None, type: type[T]) -> T: ...
-    def _set_cache_value(self, key: str, value: T | None, type: type[T]) -> None: ...
-    def _del_cache_value(self, key: str) -> None: ...
-    def to_header(self) -> str: ...
-    @staticmethod
-    def cache_property(key: str, empty: _CPT | None, type: type[_CPT]) -> property: ...
-
-class RequestCacheControl(  # type: ignore[misc]
-    ImmutableDictMixin[str, str | int | bool | None], _CacheControl
-):
-    @property  # type: ignore
-    def no_cache(self) -> str | None: ...
-    @property  # type: ignore
-    def no_store(self) -> bool: ...
-    @property  # type: ignore
-    def max_age(self) -> int | None: ...
-    @property  # type: ignore
-    def no_transform(self) -> bool: ...
-    @property
-    def max_stale(self) -> int | Literal["*"] | None: ...
-    @property
-    def min_fresh(self) -> int | None: ...
-    @property
-    def only_if_cached(self) -> bool | None: ...
-
-class ResponseCacheControl(_CacheControl):
-    @property
-    def public(self) -> bool: ...
-    @public.setter
-    def public(self, value: bool | None) -> None: ...
-    @public.deleter
-    def public(self) -> None: ...
-    @property
-    def private(self) -> str | None: ...
-    @private.setter
-    def private(self, value: Literal[True] | str | None) -> None: ...
-    @private.deleter
-    def private(self) -> None: ...
-    @property
-    def must_revalidate(self) -> bool: ...
-    @must_revalidate.setter
-    def must_revalidate(self, value: bool | None) -> None: ...
-    @must_revalidate.deleter
-    def must_revalidate(self) -> None: ...
-    @property
-    def proxy_revalidate(self) -> bool: ...
-    @proxy_revalidate.setter
-    def proxy_revalidate(self, value: bool | None) -> None: ...
-    @proxy_revalidate.deleter
-    def proxy_revalidate(self) -> None: ...
-    @property
-    def s_maxage(self) -> int | None: ...
-    @s_maxage.setter
-    def s_maxage(self, value: int | None) -> None: ...
-    @s_maxage.deleter
-    def s_maxage(self) -> None: ...
-    @property
-    def immutable(self) -> bool: ...
-    @immutable.setter
-    def immutable(self, value: bool | None) -> None: ...
-    @immutable.deleter
-    def immutable(self) -> None: ...
-    @property
-    def must_understand(self) -> bool: ...
-    @must_understand.setter
-    def must_understand(self, value: bool | None) -> None: ...
-    @must_understand.deleter
-    def must_understand(self) -> None: ...
-    @property
-    def stale_while_revalidate(self) -> int | None: ...
-    @stale_while_revalidate.setter
-    def stale_while_revalidate(self, value: int | None) -> None: ...
-    @stale_while_revalidate.deleter
-    def stale_while_revalidate(self) -> None: ...
-    @property
-    def stale_if_error(self) -> int | None: ...
-    @stale_if_error.setter
-    def stale_if_error(self, value: int | None) -> None: ...
-    @stale_if_error.deleter
-    def stale_if_error(self) -> None: ...
diff --git a/src/werkzeug/datastructures/csp.py b/src/werkzeug/datastructures/csp.py
index dde941495..0353eebea 100644
--- a/src/werkzeug/datastructures/csp.py
+++ b/src/werkzeug/datastructures/csp.py
@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from .mixins import UpdateDictMixin
+import collections.abc as cabc
+import typing as t
 
+from .structures import CallbackDict
 
-def csp_property(key):
+
+def csp_property(key: str) -> t.Any:
     """Return a new property object for a content security policy header.
     Useful if you want to add support for a csp extension in a
     subclass.
@@ -16,7 +19,7 @@ def csp_property(key):
     )
 
 
-class ContentSecurityPolicy(UpdateDictMixin, dict):
+class ContentSecurityPolicy(CallbackDict[str, str]):
     """Subclass of a dict that stores values for a Content Security Policy
     header. It has accessors for all the level 3 policies.
 
@@ -33,62 +36,65 @@ class ContentSecurityPolicy(UpdateDictMixin, dict):
 
     """
 
-    base_uri = csp_property("base-uri")
-    child_src = csp_property("child-src")
-    connect_src = csp_property("connect-src")
-    default_src = csp_property("default-src")
-    font_src = csp_property("font-src")
-    form_action = csp_property("form-action")
-    frame_ancestors = csp_property("frame-ancestors")
-    frame_src = csp_property("frame-src")
-    img_src = csp_property("img-src")
-    manifest_src = csp_property("manifest-src")
-    media_src = csp_property("media-src")
-    navigate_to = csp_property("navigate-to")
-    object_src = csp_property("object-src")
-    prefetch_src = csp_property("prefetch-src")
-    plugin_types = csp_property("plugin-types")
-    report_to = csp_property("report-to")
-    report_uri = csp_property("report-uri")
-    sandbox = csp_property("sandbox")
-    script_src = csp_property("script-src")
-    script_src_attr = csp_property("script-src-attr")
-    script_src_elem = csp_property("script-src-elem")
-    style_src = csp_property("style-src")
-    style_src_attr = csp_property("style-src-attr")
-    style_src_elem = csp_property("style-src-elem")
-    worker_src = csp_property("worker-src")
-
-    def __init__(self, values=(), on_update=None):
-        dict.__init__(self, values or ())
-        self.on_update = on_update
+    base_uri: str | None = csp_property("base-uri")
+    child_src: str | None = csp_property("child-src")
+    connect_src: str | None = csp_property("connect-src")
+    default_src: str | None = csp_property("default-src")
+    font_src: str | None = csp_property("font-src")
+    form_action: str | None = csp_property("form-action")
+    frame_ancestors: str | None = csp_property("frame-ancestors")
+    frame_src: str | None = csp_property("frame-src")
+    img_src: str | None = csp_property("img-src")
+    manifest_src: str | None = csp_property("manifest-src")
+    media_src: str | None = csp_property("media-src")
+    navigate_to: str | None = csp_property("navigate-to")
+    object_src: str | None = csp_property("object-src")
+    prefetch_src: str | None = csp_property("prefetch-src")
+    plugin_types: str | None = csp_property("plugin-types")
+    report_to: str | None = csp_property("report-to")
+    report_uri: str | None = csp_property("report-uri")
+    sandbox: str | None = csp_property("sandbox")
+    script_src: str | None = csp_property("script-src")
+    script_src_attr: str | None = csp_property("script-src-attr")
+    script_src_elem: str | None = csp_property("script-src-elem")
+    style_src: str | None = csp_property("style-src")
+    style_src_attr: str | None = csp_property("style-src-attr")
+    style_src_elem: str | None = csp_property("style-src-elem")
+    worker_src: str | None = csp_property("worker-src")
+
+    def __init__(
+        self,
+        values: cabc.Mapping[str, str] | cabc.Iterable[tuple[str, str]] | None = (),
+        on_update: cabc.Callable[[ContentSecurityPolicy], None] | None = None,
+    ) -> None:
+        super().__init__(values, on_update)
         self.provided = values is not None
 
-    def _get_value(self, key):
+    def _get_value(self, key: str) -> str | None:
         """Used internally by the accessor properties."""
         return self.get(key)
 
-    def _set_value(self, key, value):
+    def _set_value(self, key: str, value: str | None) -> None:
         """Used internally by the accessor properties."""
         if value is None:
             self.pop(key, None)
         else:
             self[key] = value
 
-    def _del_value(self, key):
+    def _del_value(self, key: str) -> None:
         """Used internally by the accessor properties."""
         if key in self:
             del self[key]
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Convert the stored values into a cache control header."""
         from ..http import dump_csp_header
 
         return dump_csp_header(self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         kv_str = " ".join(f"{k}={v!r}" for k, v in sorted(self.items()))
         return f"<{type(self).__name__} {kv_str}>"
diff --git a/src/werkzeug/datastructures/csp.pyi b/src/werkzeug/datastructures/csp.pyi
deleted file mode 100644
index f9e2ac0f4..000000000
--- a/src/werkzeug/datastructures/csp.pyi
+++ /dev/null
@@ -1,169 +0,0 @@
-from collections.abc import Callable
-from collections.abc import Iterable
-from collections.abc import Mapping
-
-from .mixins import UpdateDictMixin
-
-def csp_property(key: str) -> property: ...
-
-class ContentSecurityPolicy(UpdateDictMixin[str, str], dict[str, str]):
-    @property
-    def base_uri(self) -> str | None: ...
-    @base_uri.setter
-    def base_uri(self, value: str | None) -> None: ...
-    @base_uri.deleter
-    def base_uri(self) -> None: ...
-    @property
-    def child_src(self) -> str | None: ...
-    @child_src.setter
-    def child_src(self, value: str | None) -> None: ...
-    @child_src.deleter
-    def child_src(self) -> None: ...
-    @property
-    def connect_src(self) -> str | None: ...
-    @connect_src.setter
-    def connect_src(self, value: str | None) -> None: ...
-    @connect_src.deleter
-    def connect_src(self) -> None: ...
-    @property
-    def default_src(self) -> str | None: ...
-    @default_src.setter
-    def default_src(self, value: str | None) -> None: ...
-    @default_src.deleter
-    def default_src(self) -> None: ...
-    @property
-    def font_src(self) -> str | None: ...
-    @font_src.setter
-    def font_src(self, value: str | None) -> None: ...
-    @font_src.deleter
-    def font_src(self) -> None: ...
-    @property
-    def form_action(self) -> str | None: ...
-    @form_action.setter
-    def form_action(self, value: str | None) -> None: ...
-    @form_action.deleter
-    def form_action(self) -> None: ...
-    @property
-    def frame_ancestors(self) -> str | None: ...
-    @frame_ancestors.setter
-    def frame_ancestors(self, value: str | None) -> None: ...
-    @frame_ancestors.deleter
-    def frame_ancestors(self) -> None: ...
-    @property
-    def frame_src(self) -> str | None: ...
-    @frame_src.setter
-    def frame_src(self, value: str | None) -> None: ...
-    @frame_src.deleter
-    def frame_src(self) -> None: ...
-    @property
-    def img_src(self) -> str | None: ...
-    @img_src.setter
-    def img_src(self, value: str | None) -> None: ...
-    @img_src.deleter
-    def img_src(self) -> None: ...
-    @property
-    def manifest_src(self) -> str | None: ...
-    @manifest_src.setter
-    def manifest_src(self, value: str | None) -> None: ...
-    @manifest_src.deleter
-    def manifest_src(self) -> None: ...
-    @property
-    def media_src(self) -> str | None: ...
-    @media_src.setter
-    def media_src(self, value: str | None) -> None: ...
-    @media_src.deleter
-    def media_src(self) -> None: ...
-    @property
-    def navigate_to(self) -> str | None: ...
-    @navigate_to.setter
-    def navigate_to(self, value: str | None) -> None: ...
-    @navigate_to.deleter
-    def navigate_to(self) -> None: ...
-    @property
-    def object_src(self) -> str | None: ...
-    @object_src.setter
-    def object_src(self, value: str | None) -> None: ...
-    @object_src.deleter
-    def object_src(self) -> None: ...
-    @property
-    def prefetch_src(self) -> str | None: ...
-    @prefetch_src.setter
-    def prefetch_src(self, value: str | None) -> None: ...
-    @prefetch_src.deleter
-    def prefetch_src(self) -> None: ...
-    @property
-    def plugin_types(self) -> str | None: ...
-    @plugin_types.setter
-    def plugin_types(self, value: str | None) -> None: ...
-    @plugin_types.deleter
-    def plugin_types(self) -> None: ...
-    @property
-    def report_to(self) -> str | None: ...
-    @report_to.setter
-    def report_to(self, value: str | None) -> None: ...
-    @report_to.deleter
-    def report_to(self) -> None: ...
-    @property
-    def report_uri(self) -> str | None: ...
-    @report_uri.setter
-    def report_uri(self, value: str | None) -> None: ...
-    @report_uri.deleter
-    def report_uri(self) -> None: ...
-    @property
-    def sandbox(self) -> str | None: ...
-    @sandbox.setter
-    def sandbox(self, value: str | None) -> None: ...
-    @sandbox.deleter
-    def sandbox(self) -> None: ...
-    @property
-    def script_src(self) -> str | None: ...
-    @script_src.setter
-    def script_src(self, value: str | None) -> None: ...
-    @script_src.deleter
-    def script_src(self) -> None: ...
-    @property
-    def script_src_attr(self) -> str | None: ...
-    @script_src_attr.setter
-    def script_src_attr(self, value: str | None) -> None: ...
-    @script_src_attr.deleter
-    def script_src_attr(self) -> None: ...
-    @property
-    def script_src_elem(self) -> str | None: ...
-    @script_src_elem.setter
-    def script_src_elem(self, value: str | None) -> None: ...
-    @script_src_elem.deleter
-    def script_src_elem(self) -> None: ...
-    @property
-    def style_src(self) -> str | None: ...
-    @style_src.setter
-    def style_src(self, value: str | None) -> None: ...
-    @style_src.deleter
-    def style_src(self) -> None: ...
-    @property
-    def style_src_attr(self) -> str | None: ...
-    @style_src_attr.setter
-    def style_src_attr(self, value: str | None) -> None: ...
-    @style_src_attr.deleter
-    def style_src_attr(self) -> None: ...
-    @property
-    def style_src_elem(self) -> str | None: ...
-    @style_src_elem.setter
-    def style_src_elem(self, value: str | None) -> None: ...
-    @style_src_elem.deleter
-    def style_src_elem(self) -> None: ...
-    @property
-    def worker_src(self) -> str | None: ...
-    @worker_src.setter
-    def worker_src(self, value: str | None) -> None: ...
-    @worker_src.deleter
-    def worker_src(self) -> None: ...
-    provided: bool
-    def __init__(
-        self,
-        values: Mapping[str, str] | Iterable[tuple[str, str]] = (),
-        on_update: Callable[[ContentSecurityPolicy], None] | None = None,
-    ) -> None: ...
-    def _get_value(self, key: str) -> str | None: ...
-    def _set_value(self, key: str, value: str) -> None: ...
-    def _del_value(self, key: str) -> None: ...
-    def to_header(self) -> str: ...
diff --git a/src/werkzeug/datastructures/etag.py b/src/werkzeug/datastructures/etag.py
index 747d9966d..a4ef34245 100644
--- a/src/werkzeug/datastructures/etag.py
+++ b/src/werkzeug/datastructures/etag.py
@@ -1,14 +1,19 @@
 from __future__ import annotations
 
-from collections.abc import Collection
+import collections.abc as cabc
 
 
-class ETags(Collection):
+class ETags(cabc.Collection[str]):
     """A set that can be used to check if one etag is present in a collection
     of etags.
     """
 
-    def __init__(self, strong_etags=None, weak_etags=None, star_tag=False):
+    def __init__(
+        self,
+        strong_etags: cabc.Iterable[str] | None = None,
+        weak_etags: cabc.Iterable[str] | None = None,
+        star_tag: bool = False,
+    ):
         if not star_tag and strong_etags:
             self._strong = frozenset(strong_etags)
         else:
@@ -17,7 +22,7 @@ def __init__(self, strong_etags=None, weak_etags=None, star_tag=False):
         self._weak = frozenset(weak_etags or ())
         self.star_tag = star_tag
 
-    def as_set(self, include_weak=False):
+    def as_set(self, include_weak: bool = False) -> set[str]:
         """Convert the `ETags` object into a python set.  Per default all the
         weak etags are not part of this set."""
         rv = set(self._strong)
@@ -25,19 +30,19 @@ def as_set(self, include_weak=False):
             rv.update(self._weak)
         return rv
 
-    def is_weak(self, etag):
+    def is_weak(self, etag: str) -> bool:
         """Check if an etag is weak."""
         return etag in self._weak
 
-    def is_strong(self, etag):
+    def is_strong(self, etag: str) -> bool:
         """Check if an etag is strong."""
         return etag in self._strong
 
-    def contains_weak(self, etag):
+    def contains_weak(self, etag: str) -> bool:
         """Check if an etag is part of the set including weak and strong tags."""
         return self.is_weak(etag) or self.contains(etag)
 
-    def contains(self, etag):
+    def contains(self, etag: str) -> bool:
         """Check if an etag is part of the set ignoring weak tags.
         It is also possible to use the ``in`` operator.
         """
@@ -45,7 +50,7 @@ def contains(self, etag):
             return True
         return self.is_strong(etag)
 
-    def contains_raw(self, etag):
+    def contains_raw(self, etag: str) -> bool:
         """When passed a quoted tag it will check if this tag is part of the
         set.  If the tag is weak it is checked against weak and strong tags,
         otherwise strong only."""
@@ -56,7 +61,7 @@ def contains_raw(self, etag):
             return self.contains_weak(etag)
         return self.contains(etag)
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Convert the etags set into a HTTP header string."""
         if self.star_tag:
             return "*"
@@ -64,10 +69,16 @@ def to_header(self):
             [f'"{x}"' for x in self._strong] + [f'W/"{x}"' for x in self._weak]
         )
 
-    def __call__(self, etag=None, data=None, include_weak=False):
-        if [etag, data].count(None) != 1:
-            raise TypeError("either tag or data required, but at least one")
+    def __call__(
+        self,
+        etag: str | None = None,
+        data: bytes | None = None,
+        include_weak: bool = False,
+    ) -> bool:
         if etag is None:
+            if data is None:
+                raise TypeError("'data' is required when 'etag' is not given.")
+
             from ..http import generate_etag
 
             etag = generate_etag(data)
@@ -76,20 +87,20 @@ def __call__(self, etag=None, data=None, include_weak=False):
                 return True
         return etag in self._strong
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return bool(self.star_tag or self._strong or self._weak)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._strong)
 
-    def __iter__(self):
+    def __iter__(self) -> cabc.Iterator[str]:
         return iter(self._strong)
 
-    def __contains__(self, etag):
+    def __contains__(self, etag: str) -> bool:  # type: ignore[override]
         return self.contains(etag)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{type(self).__name__} {str(self)!r}>"
diff --git a/src/werkzeug/datastructures/etag.pyi b/src/werkzeug/datastructures/etag.pyi
deleted file mode 100644
index 88e54f154..000000000
--- a/src/werkzeug/datastructures/etag.pyi
+++ /dev/null
@@ -1,30 +0,0 @@
-from collections.abc import Collection
-from collections.abc import Iterable
-from collections.abc import Iterator
-
-class ETags(Collection[str]):
-    _strong: frozenset[str]
-    _weak: frozenset[str]
-    star_tag: bool
-    def __init__(
-        self,
-        strong_etags: Iterable[str] | None = None,
-        weak_etags: Iterable[str] | None = None,
-        star_tag: bool = False,
-    ) -> None: ...
-    def as_set(self, include_weak: bool = False) -> set[str]: ...
-    def is_weak(self, etag: str) -> bool: ...
-    def is_strong(self, etag: str) -> bool: ...
-    def contains_weak(self, etag: str) -> bool: ...
-    def contains(self, etag: str) -> bool: ...
-    def contains_raw(self, etag: str) -> bool: ...
-    def to_header(self) -> str: ...
-    def __call__(
-        self,
-        etag: str | None = None,
-        data: bytes | None = None,
-        include_weak: bool = False,
-    ) -> bool: ...
-    def __len__(self) -> int: ...
-    def __iter__(self) -> Iterator[str]: ...
-    def __contains__(self, item: str) -> bool: ...  # type: ignore
diff --git a/src/werkzeug/datastructures/file_storage.py b/src/werkzeug/datastructures/file_storage.py
index e878a56d4..123424477 100644
--- a/src/werkzeug/datastructures/file_storage.py
+++ b/src/werkzeug/datastructures/file_storage.py
@@ -1,11 +1,15 @@
 from __future__ import annotations
 
+import collections.abc as cabc
 import mimetypes
+import os
+import typing as t
 from io import BytesIO
 from os import fsdecode
 from os import fspath
 
 from .._internal import _plain_int
+from .headers import Headers
 from .structures import MultiDict
 
 
@@ -19,12 +23,12 @@ class FileStorage:
 
     def __init__(
         self,
-        stream=None,
-        filename=None,
-        name=None,
-        content_type=None,
-        content_length=None,
-        headers=None,
+        stream: t.IO[bytes] | None = None,
+        filename: str | None = None,
+        name: str | None = None,
+        content_type: str | None = None,
+        content_length: int | None = None,
+        headers: Headers | None = None,
     ):
         self.name = name
         self.stream = stream or BytesIO()
@@ -46,8 +50,6 @@ def __init__(
         self.filename = filename
 
         if headers is None:
-            from .headers import Headers
-
             headers = Headers()
         self.headers = headers
         if content_type is not None:
@@ -55,17 +57,17 @@ def __init__(
         if content_length is not None:
             headers["Content-Length"] = str(content_length)
 
-    def _parse_content_type(self):
+    def _parse_content_type(self) -> None:
         if not hasattr(self, "_parsed_content_type"):
             self._parsed_content_type = http.parse_options_header(self.content_type)
 
     @property
-    def content_type(self):
+    def content_type(self) -> str | None:
         """The content-type sent in the header.  Usually not available"""
         return self.headers.get("content-type")
 
     @property
-    def content_length(self):
+    def content_length(self) -> int:
         """The content-length sent in the header.  Usually not available"""
         if "content-length" in self.headers:
             try:
@@ -76,7 +78,7 @@ def content_length(self):
         return 0
 
     @property
-    def mimetype(self):
+    def mimetype(self) -> str:
         """Like :attr:`content_type`, but without parameters (eg, without
         charset, type etc.) and always lowercase.  For example if the content
         type is ``text/HTML; charset=utf-8`` the mimetype would be
@@ -88,7 +90,7 @@ def mimetype(self):
         return self._parsed_content_type[0].lower()
 
     @property
-    def mimetype_params(self):
+    def mimetype_params(self) -> dict[str, str]:
         """The mimetype parameters as dict.  For example if the content
         type is ``text/html; charset=utf-8`` the params would be
         ``{'charset': 'utf-8'}``.
@@ -98,7 +100,9 @@ def mimetype_params(self):
         self._parse_content_type()
         return self._parsed_content_type[1]
 
-    def save(self, dst, buffer_size=16384):
+    def save(
+        self, dst: str | os.PathLike[str] | t.IO[bytes], buffer_size: int = 16384
+    ) -> None:
         """Save the file to a destination path or file object.  If the
         destination is a file object you have to close it yourself after the
         call.  The buffer size is the number of bytes held in memory during
@@ -131,35 +135,34 @@ def save(self, dst, buffer_size=16384):
             if close_dst:
                 dst.close()
 
-    def close(self):
+    def close(self) -> None:
         """Close the underlying file if possible."""
         try:
             self.stream.close()
         except Exception:
             pass
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return bool(self.filename)
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str) -> t.Any:
         try:
             return getattr(self.stream, name)
         except AttributeError:
-            # SpooledTemporaryFile doesn't implement IOBase, get the
-            # attribute from its backing file instead.
-            # https://github.com/python/cpython/pull/3249
+            # SpooledTemporaryFile on Python < 3.11 doesn't implement IOBase,
+            # get the attribute from its backing file instead.
             if hasattr(self.stream, "_file"):
                 return getattr(self.stream._file, name)
             raise
 
-    def __iter__(self):
+    def __iter__(self) -> cabc.Iterator[bytes]:
         return iter(self.stream)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{type(self).__name__}: {self.filename!r} ({self.content_type!r})>"
 
 
-class FileMultiDict(MultiDict):
+class FileMultiDict(MultiDict[str, FileStorage]):
     """A special :class:`MultiDict` that has convenience methods to add
     files to it.  This is used for :class:`EnvironBuilder` and generally
     useful for unittesting.
@@ -167,7 +170,13 @@ class FileMultiDict(MultiDict):
     .. versionadded:: 0.5
     """
 
-    def add_file(self, name, file, filename=None, content_type=None):
+    def add_file(
+        self,
+        name: str,
+        file: str | os.PathLike[str] | t.IO[bytes] | FileStorage,
+        filename: str | None = None,
+        content_type: str | None = None,
+    ) -> None:
         """Adds a new file to the dict.  `file` can be a file name or
         a :class:`file`-like or a :class:`FileStorage` object.
 
@@ -177,19 +186,23 @@ def add_file(self, name, file, filename=None, content_type=None):
         :param content_type: an optional content type
         """
         if isinstance(file, FileStorage):
-            value = file
+            self.add(name, file)
+            return
+
+        if isinstance(file, (str, os.PathLike)):
+            if filename is None:
+                filename = os.fspath(file)
+
+            file_obj: t.IO[bytes] = open(file, "rb")
         else:
-            if isinstance(file, str):
-                if filename is None:
-                    filename = file
-                file = open(file, "rb")
-            if filename and content_type is None:
-                content_type = (
-                    mimetypes.guess_type(filename)[0] or "application/octet-stream"
-                )
-            value = FileStorage(file, filename, name, content_type)
-
-        self.add(name, value)
+            file_obj = file  # type: ignore[assignment]
+
+        if filename and content_type is None:
+            content_type = (
+                mimetypes.guess_type(filename)[0] or "application/octet-stream"
+            )
+
+        self.add(name, FileStorage(file_obj, filename, name, content_type))
 
 
 # circular dependencies
diff --git a/src/werkzeug/datastructures/file_storage.pyi b/src/werkzeug/datastructures/file_storage.pyi
deleted file mode 100644
index 36a7ed9f2..000000000
--- a/src/werkzeug/datastructures/file_storage.pyi
+++ /dev/null
@@ -1,49 +0,0 @@
-from collections.abc import Iterator
-from os import PathLike
-from typing import Any
-from typing import IO
-
-from .headers import Headers
-from .structures import MultiDict
-
-class FileStorage:
-    name: str | None
-    stream: IO[bytes]
-    filename: str | None
-    headers: Headers
-    _parsed_content_type: tuple[str, dict[str, str]]
-    def __init__(
-        self,
-        stream: IO[bytes] | None = None,
-        filename: str | PathLike[str] | None = None,
-        name: str | None = None,
-        content_type: str | None = None,
-        content_length: int | None = None,
-        headers: Headers | None = None,
-    ) -> None: ...
-    def _parse_content_type(self) -> None: ...
-    @property
-    def content_type(self) -> str: ...
-    @property
-    def content_length(self) -> int: ...
-    @property
-    def mimetype(self) -> str: ...
-    @property
-    def mimetype_params(self) -> dict[str, str]: ...
-    def save(
-        self, dst: str | PathLike[str] | IO[bytes], buffer_size: int = ...
-    ) -> None: ...
-    def close(self) -> None: ...
-    def __bool__(self) -> bool: ...
-    def __getattr__(self, name: str) -> Any: ...
-    def __iter__(self) -> Iterator[bytes]: ...
-    def __repr__(self) -> str: ...
-
-class FileMultiDict(MultiDict[str, FileStorage]):
-    def add_file(
-        self,
-        name: str,
-        file: FileStorage | str | IO[bytes],
-        filename: str | None = None,
-        content_type: str | None = None,
-    ) -> None: ...
diff --git a/src/werkzeug/datastructures/headers.py b/src/werkzeug/datastructures/headers.py
index d9dd655c2..a23a0e0b1 100644
--- a/src/werkzeug/datastructures/headers.py
+++ b/src/werkzeug/datastructures/headers.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import collections.abc as cabc
 import re
 import typing as t
 
@@ -9,8 +10,14 @@
 from .structures import iter_multi_items
 from .structures import MultiDict
 
+if t.TYPE_CHECKING:
+    import typing_extensions as te
+    from _typeshed.wsgi import WSGIEnvironment
 
-class Headers:
+T = t.TypeVar("T")
+
+
+class Headers(cabc.MutableMapping[str, str]):
     """An object that stores some headers. It has a dict-like interface,
     but is ordered, can store the same key multiple times, and iterating
     yields ``(key, value)`` pairs instead of only keys.
@@ -47,41 +54,69 @@ class Headers:
        was an API that does not support the changes to the encoding model.
     """
 
-    def __init__(self, defaults=None):
-        self._list = []
+    def __init__(
+        self,
+        defaults: (
+            Headers
+            | MultiDict[str, t.Any]
+            | cabc.Mapping[str, t.Any | cabc.Collection[t.Any]]
+            | cabc.Iterable[tuple[str, t.Any]]
+            | None
+        ) = None,
+    ) -> None:
+        self._list: list[tuple[str, str]] = []
+
         if defaults is not None:
             self.extend(defaults)
 
-    def __getitem__(self, key, _get_mode=False):
-        if not _get_mode:
-            if isinstance(key, int):
-                return self._list[key]
-            elif isinstance(key, slice):
-                return self.__class__(self._list[key])
-        if not isinstance(key, str):
-            raise BadRequestKeyError(key)
+    @t.overload
+    def __getitem__(self, key: str) -> str: ...
+    @t.overload
+    def __getitem__(self, key: int) -> tuple[str, str]: ...
+    @t.overload
+    def __getitem__(self, key: slice) -> te.Self: ...
+    def __getitem__(self, key: str | int | slice) -> str | tuple[str, str] | te.Self:
+        if isinstance(key, str):
+            return self._get_key(key)
+
+        if isinstance(key, int):
+            return self._list[key]
+
+        return self.__class__(self._list[key])
+
+    def _get_key(self, key: str) -> str:
         ikey = key.lower()
+
         for k, v in self._list:
             if k.lower() == ikey:
                 return v
-        # micro optimization: if we are in get mode we will catch that
-        # exception one stack level down so we can raise a standard
-        # key error instead of our special one.
-        if _get_mode:
-            raise KeyError()
-        raise BadRequestKeyError(key)
-
-    def __eq__(self, other):
-        def lowered(item):
-            return (item[0].lower(),) + item[1:]
-
-        return other.__class__ is self.__class__ and set(
-            map(lowered, other._list)
-        ) == set(map(lowered, self._list))
 
-    __hash__ = None
+        raise BadRequestKeyError(key)
 
-    def get(self, key, default=None, type=None):
+    def __eq__(self, other: object) -> bool:
+        if other.__class__ is not self.__class__:
+            return NotImplemented
+
+        def lowered(item: tuple[str, ...]) -> tuple[str, ...]:
+            return item[0].lower(), *item[1:]
+
+        return set(map(lowered, other._list)) == set(map(lowered, self._list))  # type: ignore[attr-defined]
+
+    __hash__ = None  # type: ignore[assignment]
+
+    @t.overload  # type: ignore[override]
+    def get(self, key: str) -> str | None: ...
+    @t.overload
+    def get(self, key: str, default: str) -> str: ...
+    @t.overload
+    def get(self, key: str, default: T) -> str | T: ...
+    @t.overload
+    def get(self, key: str, type: type[T]) -> T | None: ...
+    @t.overload
+    def get(self, key: str, default: T, type: type[T]) -> T: ...
+    def get(  # type: ignore[misc]
+        self, key: str, default: str | T | None = None, type: type[T] | None = None
+    ) -> str | T | None:
         """Return the default value if the requested data doesn't exist.
         If `type` is provided and is a callable it should convert the value,
         return it or raise a :exc:`ValueError` if that is not possible.  In
@@ -107,17 +142,23 @@ def get(self, key, default=None, type=None):
             The ``as_bytes`` parameter was added.
         """
         try:
-            rv = self.__getitem__(key, _get_mode=True)
+            rv = self._get_key(key)
         except KeyError:
             return default
+
         if type is None:
             return rv
+
         try:
-            return type(rv)
+            return type(rv)  # type: ignore[call-arg]
         except ValueError:
             return default
 
-    def getlist(self, key, type=None):
+    @t.overload
+    def getlist(self, key: str) -> list[str]: ...
+    @t.overload
+    def getlist(self, key: str, type: type[T]) -> list[T]: ...
+    def getlist(self, key: str, type: type[T] | None = None) -> list[str] | list[T]:
         """Return the list of items for a given key. If that key is not in the
         :class:`Headers`, the return value will be an empty list.  Just like
         :meth:`get`, :meth:`getlist` accepts a `type` parameter.  All items will
@@ -136,18 +177,22 @@ def getlist(self, key, type=None):
             The ``as_bytes`` parameter was added.
         """
         ikey = key.lower()
-        result = []
-        for k, v in self:
-            if k.lower() == ikey:
-                if type is not None:
+
+        if type is not None:
+            result = []
+
+            for k, v in self:
+                if k.lower() == ikey:
                     try:
-                        v = type(v)
+                        result.append(type(v))  # type: ignore[call-arg]
                     except ValueError:
                         continue
-                result.append(v)
-        return result
 
-    def get_all(self, name):
+            return result
+
+        return [v for k, v in self if k.lower() == ikey]
+
+    def get_all(self, name: str) -> list[str]:
         """Return a list of all the values for the named field.
 
         This method is compatible with the :mod:`wsgiref`
@@ -155,21 +200,32 @@ def get_all(self, name):
         """
         return self.getlist(name)
 
-    def items(self, lower=False):
+    def items(self, lower: bool = False) -> t.Iterable[tuple[str, str]]:  # type: ignore[override]
         for key, value in self:
             if lower:
                 key = key.lower()
             yield key, value
 
-    def keys(self, lower=False):
+    def keys(self, lower: bool = False) -> t.Iterable[str]:  # type: ignore[override]
         for key, _ in self.items(lower):
             yield key
 
-    def values(self):
+    def values(self) -> t.Iterable[str]:  # type: ignore[override]
         for _, value in self.items():
             yield value
 
-    def extend(self, *args, **kwargs):
+    def extend(
+        self,
+        arg: (
+            Headers
+            | MultiDict[str, t.Any]
+            | cabc.Mapping[str, t.Any | cabc.Collection[t.Any]]
+            | cabc.Iterable[tuple[str, t.Any]]
+            | None
+        ) = None,
+        /,
+        **kwargs: str,
+    ) -> None:
         """Extend headers in this object with items from another object
         containing header items as well as keyword arguments.
 
@@ -183,35 +239,52 @@ def extend(self, *args, **kwargs):
         .. versionchanged:: 1.0
             Support :class:`MultiDict`. Allow passing ``kwargs``.
         """
-        if len(args) > 1:
-            raise TypeError(f"update expected at most 1 arguments, got {len(args)}")
-
-        if args:
-            for key, value in iter_multi_items(args[0]):
+        if arg is not None:
+            for key, value in iter_multi_items(arg):
                 self.add(key, value)
 
         for key, value in iter_multi_items(kwargs):
             self.add(key, value)
 
-    def __delitem__(self, key, _index_operation=True):
-        if _index_operation and isinstance(key, (int, slice)):
-            del self._list[key]
+    def __delitem__(self, key: str | int | slice) -> None:
+        if isinstance(key, str):
+            self._del_key(key)
             return
+
+        del self._list[key]
+
+    def _del_key(self, key: str) -> None:
         key = key.lower()
         new = []
+
         for k, v in self._list:
             if k.lower() != key:
                 new.append((k, v))
+
         self._list[:] = new
 
-    def remove(self, key):
+    def remove(self, key: str) -> None:
         """Remove a key.
 
         :param key: The key to be removed.
         """
-        return self.__delitem__(key, _index_operation=False)
-
-    def pop(self, key=None, default=_missing):
+        return self._del_key(key)
+
+    @t.overload
+    def pop(self) -> tuple[str, str]: ...
+    @t.overload
+    def pop(self, key: str) -> str: ...
+    @t.overload
+    def pop(self, key: int | None = ...) -> tuple[str, str]: ...
+    @t.overload
+    def pop(self, key: str, default: str) -> str: ...
+    @t.overload
+    def pop(self, key: str, default: T) -> str | T: ...
+    def pop(
+        self,
+        key: str | int | None = None,
+        default: str | T = _missing,  # type: ignore[assignment]
+    ) -> str | tuple[str, str] | T:
         """Removes and returns a key or index.
 
         :param key: The key to be popped.  If this is an integer the item at
@@ -222,37 +295,42 @@ def pop(self, key=None, default=_missing):
         """
         if key is None:
             return self._list.pop()
+
         if isinstance(key, int):
             return self._list.pop(key)
+
         try:
-            rv = self[key]
-            self.remove(key)
+            rv = self._get_key(key)
         except KeyError:
             if default is not _missing:
                 return default
+
             raise
+
+        self.remove(key)
         return rv
 
-    def popitem(self):
+    def popitem(self) -> tuple[str, str]:
         """Removes a key or index and returns a (key, value) item."""
-        return self.pop()
+        return self._list.pop()
 
-    def __contains__(self, key):
+    def __contains__(self, key: str) -> bool:  # type: ignore[override]
         """Check if a key is present."""
         try:
-            self.__getitem__(key, _get_mode=True)
+            self._get_key(key)
         except KeyError:
             return False
+
         return True
 
-    def __iter__(self):
+    def __iter__(self) -> t.Iterator[tuple[str, str]]:  # type: ignore[override]
         """Yield ``(key, value)`` tuples."""
         return iter(self._list)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._list)
 
-    def add(self, _key, _value, **kw):
+    def add(self, key: str, value: t.Any, /, **kwargs: t.Any) -> None:
         """Add a new header tuple to the list.
 
         Keyword arguments can specify additional parameters for the header
@@ -265,27 +343,28 @@ def add(self, _key, _value, **kw):
         The keyword argument dumping uses :func:`dump_options_header`
         behind the scenes.
 
-        .. versionadded:: 0.4.1
+        .. versionchanged:: 0.4.1
             keyword arguments were added for :mod:`wsgiref` compatibility.
         """
-        if kw:
-            _value = _options_header_vkw(_value, kw)
-        _value = _str_header_value(_value)
-        self._list.append((_key, _value))
+        if kwargs:
+            value = _options_header_vkw(value, kwargs)
 
-    def add_header(self, _key, _value, **_kw):
+        value_str = _str_header_value(value)
+        self._list.append((key, value_str))
+
+    def add_header(self, key: str, value: t.Any, /, **kwargs: t.Any) -> None:
         """Add a new header tuple to the list.
 
         An alias for :meth:`add` for compatibility with the :mod:`wsgiref`
         :meth:`~wsgiref.headers.Headers.add_header` method.
         """
-        self.add(_key, _value, **_kw)
+        self.add(key, value, **kwargs)
 
-    def clear(self):
+    def clear(self) -> None:
         """Clears all headers."""
-        del self._list[:]
+        self._list.clear()
 
-    def set(self, _key, _value, **kw):
+    def set(self, key: str, value: t.Any, /, **kwargs: t.Any) -> None:
         """Remove all header tuples for `key` and add a new one.  The newly
         added key either appears at the end of the list if there was no
         entry or replaces the first one.
@@ -300,25 +379,32 @@ def set(self, _key, _value, **kw):
         :param key: The key to be inserted.
         :param value: The value to be inserted.
         """
-        if kw:
-            _value = _options_header_vkw(_value, kw)
-        _value = _str_header_value(_value)
+        if kwargs:
+            value = _options_header_vkw(value, kwargs)
+
+        value_str = _str_header_value(value)
+
         if not self._list:
-            self._list.append((_key, _value))
+            self._list.append((key, value_str))
             return
-        listiter = iter(self._list)
-        ikey = _key.lower()
-        for idx, (old_key, _old_value) in enumerate(listiter):
+
+        iter_list = iter(self._list)
+        ikey = key.lower()
+
+        for idx, (old_key, _) in enumerate(iter_list):
             if old_key.lower() == ikey:
                 # replace first occurrence
-                self._list[idx] = (_key, _value)
+                self._list[idx] = (key, value_str)
                 break
         else:
-            self._list.append((_key, _value))
+            # no existing occurrences
+            self._list.append((key, value_str))
             return
-        self._list[idx + 1 :] = [t for t in listiter if t[0].lower() != ikey]
 
-    def setlist(self, key, values):
+        # remove remaining occurrences
+        self._list[idx + 1 :] = [t for t in iter_list if t[0].lower() != ikey]
+
+    def setlist(self, key: str, values: cabc.Iterable[t.Any]) -> None:
         """Remove any existing values for a header and add new ones.
 
         :param key: The header key to set.
@@ -335,7 +421,7 @@ def setlist(self, key, values):
         else:
             self.remove(key)
 
-    def setdefault(self, key, default):
+    def setdefault(self, key: str, default: t.Any) -> str:
         """Return the first value for the key if it is in the headers,
         otherwise set the header to the value given by ``default`` and
         return that.
@@ -344,13 +430,15 @@ def setdefault(self, key, default):
         :param default: The value to set for the key if it is not in the
             headers.
         """
-        if key in self:
-            return self[key]
+        try:
+            return self._get_key(key)
+        except KeyError:
+            pass
 
         self.set(key, default)
-        return default
+        return self._get_key(key)
 
-    def setlistdefault(self, key, default):
+    def setlistdefault(self, key: str, default: cabc.Iterable[t.Any]) -> list[str]:
         """Return the list of values for the key if it is in the
         headers, otherwise set the header to the list of values given
         by ``default`` and return that.
@@ -369,20 +457,39 @@ def setlistdefault(self, key, default):
 
         return self.getlist(key)
 
-    def __setitem__(self, key, value):
+    @t.overload
+    def __setitem__(self, key: str, value: t.Any) -> None: ...
+    @t.overload
+    def __setitem__(self, key: int, value: tuple[str, t.Any]) -> None: ...
+    @t.overload
+    def __setitem__(
+        self, key: slice, value: cabc.Iterable[tuple[str, t.Any]]
+    ) -> None: ...
+    def __setitem__(
+        self,
+        key: str | int | slice,
+        value: t.Any | tuple[str, t.Any] | cabc.Iterable[tuple[str, t.Any]],
+    ) -> None:
         """Like :meth:`set` but also supports index/slice based setting."""
-        if isinstance(key, (slice, int)):
-            if isinstance(key, int):
-                value = [value]
-            value = [(k, _str_header_value(v)) for (k, v) in value]
-            if isinstance(key, int):
-                self._list[key] = value[0]
-            else:
-                self._list[key] = value
-        else:
+        if isinstance(key, str):
             self.set(key, value)
-
-    def update(self, *args, **kwargs):
+        elif isinstance(key, int):
+            self._list[key] = value[0], _str_header_value(value[1])  # type: ignore[index]
+        else:
+            self._list[key] = [(k, _str_header_value(v)) for k, v in value]  # type: ignore[misc]
+
+    def update(  # type: ignore[override]
+        self,
+        arg: (
+            Headers
+            | MultiDict[str, t.Any]
+            | cabc.Mapping[str, t.Any | cabc.Collection[t.Any]]
+            | cabc.Iterable[tuple[str, t.Any]]
+            | None
+        ) = None,
+        /,
+        **kwargs: t.Any | cabc.Collection[t.Any],
+    ) -> None:
         """Replace headers in this object with items from another
         headers object and keyword arguments.
 
@@ -395,57 +502,54 @@ def update(self, *args, **kwargs):
 
         .. versionadded:: 1.0
         """
-        if len(args) > 1:
-            raise TypeError(f"update expected at most 1 arguments, got {len(args)}")
-
-        if args:
-            mapping = args[0]
-
-            if isinstance(mapping, (Headers, MultiDict)):
-                for key in mapping.keys():
-                    self.setlist(key, mapping.getlist(key))
-            elif isinstance(mapping, dict):
-                for key, value in mapping.items():
-                    if isinstance(value, (list, tuple)):
+        if arg is not None:
+            if isinstance(arg, (Headers, MultiDict)):
+                for key in arg.keys():
+                    self.setlist(key, arg.getlist(key))
+            elif isinstance(arg, cabc.Mapping):
+                for key, value in arg.items():
+                    if isinstance(value, cabc.Collection) and not isinstance(
+                        value, str
+                    ):
                         self.setlist(key, value)
                     else:
                         self.set(key, value)
             else:
-                for key, value in mapping:
+                for key, value in arg:
                     self.set(key, value)
 
         for key, value in kwargs.items():
-            if isinstance(value, (list, tuple)):
+            if isinstance(value, cabc.Collection) and not isinstance(value, str):
                 self.setlist(key, value)
             else:
                 self.set(key, value)
 
-    def to_wsgi_list(self):
+    def to_wsgi_list(self) -> list[tuple[str, str]]:
         """Convert the headers into a list suitable for WSGI.
 
         :return: list
         """
-        return list(self)
+        return list(self)  # type: ignore[arg-type]
 
-    def copy(self):
+    def copy(self) -> te.Self:
         return self.__class__(self._list)
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self.copy()
 
-    def __str__(self):
+    def __str__(self) -> str:
         """Returns formatted headers suitable for HTTP transmission."""
         strs = []
-        for key, value in self.to_wsgi_list():
+        for key, value in self._list:
             strs.append(f"{key}: {value}")
         strs.append("\r\n")
         return "\r\n".join(strs)
 
-    def __repr__(self):
-        return f"{type(self).__name__}({list(self)!r})"
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._list!r})"
 
 
-def _options_header_vkw(value: str, kw: dict[str, t.Any]):
+def _options_header_vkw(value: str, kw: dict[str, t.Any]) -> str:
     return http.dump_options_header(
         value, {k.replace("_", "-"): v for k, v in kw.items()}
     )
@@ -461,10 +565,10 @@ def _str_header_value(value: t.Any) -> str:
     if _newline_re.search(value) is not None:
         raise ValueError("Header values must not contain newline characters.")
 
-    return value
+    return value  # type: ignore[no-any-return]
 
 
-class EnvironHeaders(ImmutableHeadersMixin, Headers):
+class EnvironHeaders(ImmutableHeadersMixin, Headers):  # type: ignore[misc]
     """Read only version of the headers from a WSGI environment.  This
     provides the same interface as `Headers` and is constructed from
     a WSGI environment.
@@ -474,30 +578,36 @@ class EnvironHeaders(ImmutableHeadersMixin, Headers):
     HTTP exceptions.
     """
 
-    def __init__(self, environ):
+    def __init__(self, environ: WSGIEnvironment) -> None:
+        super().__init__()
         self.environ = environ
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, EnvironHeaders):
+            return NotImplemented
+
         return self.environ is other.environ
 
-    __hash__ = None
+    __hash__ = None  # type: ignore[assignment]
+
+    def __getitem__(self, key: str) -> str:  # type: ignore[override]
+        return self._get_key(key)
 
-    def __getitem__(self, key, _get_mode=False):
-        # _get_mode is a no-op for this class as there is no index but
-        # used because get() calls it.
+    def _get_key(self, key: str) -> str:
         if not isinstance(key, str):
-            raise KeyError(key)
+            raise BadRequestKeyError(key)
+
         key = key.upper().replace("-", "_")
+
         if key in {"CONTENT_TYPE", "CONTENT_LENGTH"}:
-            return self.environ[key]
-        return self.environ[f"HTTP_{key}"]
+            return self.environ[key]  # type: ignore[no-any-return]
+
+        return self.environ[f"HTTP_{key}"]  # type: ignore[no-any-return]
 
-    def __len__(self):
-        # the iter is necessary because otherwise list calls our
-        # len which would call list again and so forth.
-        return len(list(iter(self)))
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
 
-    def __iter__(self):
+    def __iter__(self) -> cabc.Iterator[tuple[str, str]]:  # type: ignore[override]
         for key, value in self.environ.items():
             if key.startswith("HTTP_") and key not in {
                 "HTTP_CONTENT_TYPE",
@@ -507,7 +617,7 @@ def __iter__(self):
             elif key in {"CONTENT_TYPE", "CONTENT_LENGTH"} and value:
                 yield key.replace("_", "-").title(), value
 
-    def copy(self):
+    def copy(self) -> t.NoReturn:
         raise TypeError(f"cannot create {type(self).__name__!r} copies")
 
 
diff --git a/src/werkzeug/datastructures/headers.pyi b/src/werkzeug/datastructures/headers.pyi
deleted file mode 100644
index 86502221a..000000000
--- a/src/werkzeug/datastructures/headers.pyi
+++ /dev/null
@@ -1,109 +0,0 @@
-from collections.abc import Callable
-from collections.abc import Iterable
-from collections.abc import Iterator
-from collections.abc import Mapping
-from typing import Literal
-from typing import NoReturn
-from typing import overload
-from typing import TypeVar
-
-from _typeshed import SupportsKeysAndGetItem
-from _typeshed.wsgi import WSGIEnvironment
-
-from .mixins import ImmutableHeadersMixin
-
-D = TypeVar("D")
-T = TypeVar("T")
-
-class Headers(dict[str, str]):
-    _list: list[tuple[str, str]]
-    def __init__(
-        self,
-        defaults: Mapping[str, str | Iterable[str]]
-        | Iterable[tuple[str, str]]
-        | None = None,
-    ) -> None: ...
-    @overload
-    def __getitem__(self, key: str) -> str: ...
-    @overload
-    def __getitem__(self, key: int) -> tuple[str, str]: ...
-    @overload
-    def __getitem__(self, key: slice) -> Headers: ...
-    @overload
-    def __getitem__(self, key: str, _get_mode: Literal[True] = ...) -> str: ...
-    def __eq__(self, other: object) -> bool: ...
-    @overload  # type: ignore
-    def get(self, key: str, default: str) -> str: ...
-    @overload
-    def get(self, key: str, default: str | None = None) -> str | None: ...
-    @overload
-    def get(
-        self, key: str, default: T | None = None, type: Callable[[str], T] = ...
-    ) -> T | None: ...
-    @overload
-    def getlist(self, key: str) -> list[str]: ...
-    @overload
-    def getlist(self, key: str, type: Callable[[str], T]) -> list[T]: ...
-    def get_all(self, name: str) -> list[str]: ...
-    def items(  # type: ignore
-        self, lower: bool = False
-    ) -> Iterator[tuple[str, str]]: ...
-    def keys(self, lower: bool = False) -> Iterator[str]: ...  # type: ignore
-    def values(self) -> Iterator[str]: ...  # type: ignore
-    def extend(
-        self,
-        *args: Mapping[str, str | Iterable[str]] | Iterable[tuple[str, str]],
-        **kwargs: str | Iterable[str],
-    ) -> None: ...
-    @overload
-    def __delitem__(self, key: str | int | slice) -> None: ...
-    @overload
-    def __delitem__(self, key: str, _index_operation: Literal[False]) -> None: ...
-    def remove(self, key: str) -> None: ...
-    @overload  # type: ignore
-    def pop(self, key: str, default: str | None = None) -> str: ...
-    @overload
-    def pop(
-        self, key: int | None = None, default: tuple[str, str] | None = None
-    ) -> tuple[str, str]: ...
-    def popitem(self) -> tuple[str, str]: ...
-    def __contains__(self, key: str) -> bool: ...  # type: ignore
-    def has_key(self, key: str) -> bool: ...
-    def __iter__(self) -> Iterator[tuple[str, str]]: ...  # type: ignore
-    def add(self, _key: str, _value: str, **kw: str) -> None: ...
-    def _validate_value(self, value: str) -> None: ...
-    def add_header(self, _key: str, _value: str, **_kw: str) -> None: ...
-    def clear(self) -> None: ...
-    def set(self, _key: str, _value: str, **kw: str) -> None: ...
-    def setlist(self, key: str, values: Iterable[str]) -> None: ...
-    def setdefault(self, key: str, default: str) -> str: ...
-    def setlistdefault(self, key: str, default: Iterable[str]) -> None: ...
-    @overload
-    def __setitem__(self, key: str, value: str) -> None: ...
-    @overload
-    def __setitem__(self, key: int, value: tuple[str, str]) -> None: ...
-    @overload
-    def __setitem__(self, key: slice, value: Iterable[tuple[str, str]]) -> None: ...
-    @overload
-    def update(
-        self, __m: SupportsKeysAndGetItem[str, str], **kwargs: str | Iterable[str]
-    ) -> None: ...
-    @overload
-    def update(
-        self, __m: Iterable[tuple[str, str]], **kwargs: str | Iterable[str]
-    ) -> None: ...
-    @overload
-    def update(self, **kwargs: str | Iterable[str]) -> None: ...
-    def to_wsgi_list(self) -> list[tuple[str, str]]: ...
-    def copy(self) -> Headers: ...
-    def __copy__(self) -> Headers: ...
-
-class EnvironHeaders(ImmutableHeadersMixin, Headers):
-    environ: WSGIEnvironment
-    def __init__(self, environ: WSGIEnvironment) -> None: ...
-    def __eq__(self, other: object) -> bool: ...
-    def __getitem__(  # type: ignore
-        self, key: str, _get_mode: Literal[False] = False
-    ) -> str: ...
-    def __iter__(self) -> Iterator[tuple[str, str]]: ...  # type: ignore
-    def copy(self) -> NoReturn: ...
diff --git a/src/werkzeug/datastructures/mixins.py b/src/werkzeug/datastructures/mixins.py
index 2c84ca8f2..76324d5a2 100644
--- a/src/werkzeug/datastructures/mixins.py
+++ b/src/werkzeug/datastructures/mixins.py
@@ -1,11 +1,22 @@
 from __future__ import annotations
 
+import collections.abc as cabc
+import typing as t
+from functools import update_wrapper
 from itertools import repeat
 
 from .._internal import _missing
 
+if t.TYPE_CHECKING:
+    import typing_extensions as te
 
-def is_immutable(self):
+K = t.TypeVar("K")
+V = t.TypeVar("V")
+T = t.TypeVar("T")
+F = t.TypeVar("F", bound=cabc.Callable[..., t.Any])
+
+
+def _immutable_error(self: t.Any) -> t.NoReturn:
     raise TypeError(f"{type(self).__name__!r} objects are immutable")
 
 
@@ -17,52 +28,52 @@ class ImmutableListMixin:
     :private:
     """
 
-    _hash_cache = None
+    _hash_cache: int | None = None
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         if self._hash_cache is not None:
             return self._hash_cache
-        rv = self._hash_cache = hash(tuple(self))
+        rv = self._hash_cache = hash(tuple(self))  # type: ignore[arg-type]
         return rv
 
-    def __reduce_ex__(self, protocol):
-        return type(self), (list(self),)
+    def __reduce_ex__(self, protocol: t.SupportsIndex) -> t.Any:
+        return type(self), (list(self),)  # type: ignore[call-overload]
 
-    def __delitem__(self, key):
-        is_immutable(self)
+    def __delitem__(self, key: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __iadd__(self, other):
-        is_immutable(self)
+    def __iadd__(self, other: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __imul__(self, other):
-        is_immutable(self)
+    def __imul__(self, other: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __setitem__(self, key, value):
-        is_immutable(self)
+    def __setitem__(self, key: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def append(self, item):
-        is_immutable(self)
+    def append(self, item: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def remove(self, item):
-        is_immutable(self)
+    def remove(self, item: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def extend(self, iterable):
-        is_immutable(self)
+    def extend(self, iterable: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def insert(self, pos, value):
-        is_immutable(self)
+    def insert(self, pos: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def pop(self, index=-1):
-        is_immutable(self)
+    def pop(self, index: t.Any = -1) -> t.NoReturn:
+        _immutable_error(self)
 
-    def reverse(self):
-        is_immutable(self)
+    def reverse(self: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def sort(self, key=None, reverse=False):
-        is_immutable(self)
+    def sort(self, key: t.Any = None, reverse: t.Any = False) -> t.NoReturn:
+        _immutable_error(self)
 
 
-class ImmutableDictMixin:
+class ImmutableDictMixin(t.Generic[K, V]):
     """Makes a :class:`dict` immutable.
 
     .. versionadded:: 0.5
@@ -70,49 +81,59 @@ class ImmutableDictMixin:
     :private:
     """
 
-    _hash_cache = None
+    _hash_cache: int | None = None
 
     @classmethod
-    def fromkeys(cls, keys, value=None):
+    @t.overload
+    def fromkeys(
+        cls, keys: cabc.Iterable[K], value: None
+    ) -> ImmutableDictMixin[K, t.Any | None]: ...
+    @classmethod
+    @t.overload
+    def fromkeys(cls, keys: cabc.Iterable[K], value: V) -> ImmutableDictMixin[K, V]: ...
+    @classmethod
+    def fromkeys(
+        cls, keys: cabc.Iterable[K], value: V | None = None
+    ) -> ImmutableDictMixin[K, t.Any | None] | ImmutableDictMixin[K, V]:
         instance = super().__new__(cls)
-        instance.__init__(zip(keys, repeat(value)))
+        instance.__init__(zip(keys, repeat(value)))  # type: ignore[misc]
         return instance
 
-    def __reduce_ex__(self, protocol):
-        return type(self), (dict(self),)
+    def __reduce_ex__(self, protocol: t.SupportsIndex) -> t.Any:
+        return type(self), (dict(self),)  # type: ignore[call-overload]
 
-    def _iter_hashitems(self):
-        return self.items()
+    def _iter_hashitems(self) -> t.Iterable[t.Any]:
+        return self.items()  # type: ignore[attr-defined,no-any-return]
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         if self._hash_cache is not None:
             return self._hash_cache
         rv = self._hash_cache = hash(frozenset(self._iter_hashitems()))
         return rv
 
-    def setdefault(self, key, default=None):
-        is_immutable(self)
+    def setdefault(self, key: t.Any, default: t.Any = None) -> t.NoReturn:
+        _immutable_error(self)
 
-    def update(self, *args, **kwargs):
-        is_immutable(self)
+    def update(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def pop(self, key, default=None):
-        is_immutable(self)
+    def pop(self, key: t.Any, default: t.Any = None) -> t.NoReturn:
+        _immutable_error(self)
 
-    def popitem(self):
-        is_immutable(self)
+    def popitem(self) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __setitem__(self, key, value):
-        is_immutable(self)
+    def __setitem__(self, key: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __delitem__(self, key):
-        is_immutable(self)
+    def __delitem__(self, key: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def clear(self):
-        is_immutable(self)
+    def clear(self) -> t.NoReturn:
+        _immutable_error(self)
 
 
-class ImmutableMultiDictMixin(ImmutableDictMixin):
+class ImmutableMultiDictMixin(ImmutableDictMixin[K, V]):
     """Makes a :class:`MultiDict` immutable.
 
     .. versionadded:: 0.5
@@ -120,26 +141,26 @@ class ImmutableMultiDictMixin(ImmutableDictMixin):
     :private:
     """
 
-    def __reduce_ex__(self, protocol):
-        return type(self), (list(self.items(multi=True)),)
+    def __reduce_ex__(self, protocol: t.SupportsIndex) -> t.Any:
+        return type(self), (list(self.items(multi=True)),)  # type: ignore[attr-defined]
 
-    def _iter_hashitems(self):
-        return self.items(multi=True)
+    def _iter_hashitems(self) -> t.Iterable[t.Any]:
+        return self.items(multi=True)  # type: ignore[attr-defined,no-any-return]
 
-    def add(self, key, value):
-        is_immutable(self)
+    def add(self, key: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def popitemlist(self):
-        is_immutable(self)
+    def popitemlist(self) -> t.NoReturn:
+        _immutable_error(self)
 
-    def poplist(self, key):
-        is_immutable(self)
+    def poplist(self, key: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def setlist(self, key, new_list):
-        is_immutable(self)
+    def setlist(self, key: t.Any, new_list: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def setlistdefault(self, key, default_list=None):
-        is_immutable(self)
+    def setlistdefault(self, key: t.Any, default_list: t.Any = None) -> t.NoReturn:
+        _immutable_error(self)
 
 
 class ImmutableHeadersMixin:
@@ -152,63 +173,64 @@ class ImmutableHeadersMixin:
     :private:
     """
 
-    def __delitem__(self, key, **kwargs):
-        is_immutable(self)
+    def __delitem__(self, key: t.Any, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def __setitem__(self, key, value):
-        is_immutable(self)
+    def __setitem__(self, key: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def set(self, _key, _value, **kwargs):
-        is_immutable(self)
+    def set(self, key: t.Any, value: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def setlist(self, key, values):
-        is_immutable(self)
+    def setlist(self, key: t.Any, values: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def add(self, _key, _value, **kwargs):
-        is_immutable(self)
+    def add(self, key: t.Any, value: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def add_header(self, _key, _value, **_kwargs):
-        is_immutable(self)
+    def add_header(self, key: t.Any, value: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def remove(self, key):
-        is_immutable(self)
+    def remove(self, key: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def extend(self, *args, **kwargs):
-        is_immutable(self)
+    def extend(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def update(self, *args, **kwargs):
-        is_immutable(self)
+    def update(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def insert(self, pos, value):
-        is_immutable(self)
+    def insert(self, pos: t.Any, value: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def pop(self, key=None, default=_missing):
-        is_immutable(self)
+    def pop(self, key: t.Any = None, default: t.Any = _missing) -> t.NoReturn:
+        _immutable_error(self)
 
-    def popitem(self):
-        is_immutable(self)
+    def popitem(self) -> t.NoReturn:
+        _immutable_error(self)
 
-    def setdefault(self, key, default):
-        is_immutable(self)
+    def setdefault(self, key: t.Any, default: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
-    def setlistdefault(self, key, default):
-        is_immutable(self)
+    def setlistdefault(self, key: t.Any, default: t.Any) -> t.NoReturn:
+        _immutable_error(self)
 
 
-def _calls_update(name):
-    def oncall(self, *args, **kw):
-        rv = getattr(super(UpdateDictMixin, self), name)(*args, **kw)
+def _always_update(f: F) -> F:
+    def wrapper(
+        self: UpdateDictMixin[t.Any, t.Any], /, *args: t.Any, **kwargs: t.Any
+    ) -> t.Any:
+        rv = f(self, *args, **kwargs)
 
         if self.on_update is not None:
             self.on_update(self)
 
         return rv
 
-    oncall.__name__ = name
-    return oncall
+    return update_wrapper(wrapper, f)  # type: ignore[return-value]
 
 
-class UpdateDictMixin(dict):
+class UpdateDictMixin(dict[K, V]):
     """Makes dicts call `self.on_update` on modifications.
 
     .. versionadded:: 0.5
@@ -216,27 +238,59 @@ class UpdateDictMixin(dict):
     :private:
     """
 
-    on_update = None
+    on_update: cabc.Callable[[te.Self], None] | None = None
 
-    def setdefault(self, key, default=None):
+    def setdefault(self: te.Self, key: K, default: V | None = None) -> V:
         modified = key not in self
-        rv = super().setdefault(key, default)
+        rv = super().setdefault(key, default)  # type: ignore[arg-type]
         if modified and self.on_update is not None:
             self.on_update(self)
         return rv
 
-    def pop(self, key, default=_missing):
+    @t.overload
+    def pop(self: te.Self, key: K) -> V: ...
+    @t.overload
+    def pop(self: te.Self, key: K, default: V) -> V: ...
+    @t.overload
+    def pop(self: te.Self, key: K, default: T) -> T: ...
+    def pop(
+        self: te.Self,
+        key: K,
+        default: V | T = _missing,  # type: ignore[assignment]
+    ) -> V | T:
         modified = key in self
         if default is _missing:
             rv = super().pop(key)
         else:
-            rv = super().pop(key, default)
+            rv = super().pop(key, default)  # type: ignore[arg-type]
         if modified and self.on_update is not None:
             self.on_update(self)
         return rv
 
-    __setitem__ = _calls_update("__setitem__")
-    __delitem__ = _calls_update("__delitem__")
-    clear = _calls_update("clear")
-    popitem = _calls_update("popitem")
-    update = _calls_update("update")
+    @_always_update
+    def __setitem__(self, key: K, value: V) -> None:
+        super().__setitem__(key, value)
+
+    @_always_update
+    def __delitem__(self, key: K) -> None:
+        super().__delitem__(key)
+
+    @_always_update
+    def clear(self) -> None:
+        super().clear()
+
+    @_always_update
+    def popitem(self) -> tuple[K, V]:
+        return super().popitem()
+
+    @_always_update
+    def update(  # type: ignore[override]
+        self,
+        arg: cabc.Mapping[K, V] | cabc.Iterable[tuple[K, V]] | None = None,
+        /,
+        **kwargs: V,
+    ) -> None:
+        if arg is None:
+            super().update(**kwargs)
+        else:
+            super().update(arg, **kwargs)
diff --git a/src/werkzeug/datastructures/mixins.pyi b/src/werkzeug/datastructures/mixins.pyi
deleted file mode 100644
index 40453f703..000000000
--- a/src/werkzeug/datastructures/mixins.pyi
+++ /dev/null
@@ -1,97 +0,0 @@
-from collections.abc import Callable
-from collections.abc import Hashable
-from collections.abc import Iterable
-from typing import Any
-from typing import NoReturn
-from typing import overload
-from typing import SupportsIndex
-from typing import TypeVar
-
-from _typeshed import SupportsKeysAndGetItem
-
-from .headers import Headers
-
-K = TypeVar("K")
-T = TypeVar("T")
-V = TypeVar("V")
-
-def is_immutable(self: object) -> NoReturn: ...
-
-class ImmutableListMixin(list[V]):
-    _hash_cache: int | None
-    def __hash__(self) -> int: ...  # type: ignore
-    def __delitem__(self, key: SupportsIndex | slice) -> NoReturn: ...
-    def __iadd__(self, other: Any) -> NoReturn: ...  # type: ignore
-    def __imul__(self, other: SupportsIndex) -> NoReturn: ...
-    def __setitem__(self, key: int | slice, value: V) -> NoReturn: ...  # type: ignore
-    def append(self, value: V) -> NoReturn: ...
-    def remove(self, value: V) -> NoReturn: ...
-    def extend(self, values: Iterable[V]) -> NoReturn: ...
-    def insert(self, pos: SupportsIndex, value: V) -> NoReturn: ...
-    def pop(self, index: SupportsIndex = -1) -> NoReturn: ...
-    def reverse(self) -> NoReturn: ...
-    def sort(
-        self, key: Callable[[V], Any] | None = None, reverse: bool = False
-    ) -> NoReturn: ...
-
-class ImmutableDictMixin(dict[K, V]):
-    _hash_cache: int | None
-    @classmethod
-    def fromkeys(  # type: ignore
-        cls, keys: Iterable[K], value: V | None = None
-    ) -> ImmutableDictMixin[K, V]: ...
-    def _iter_hashitems(self) -> Iterable[Hashable]: ...
-    def __hash__(self) -> int: ...  # type: ignore
-    def setdefault(self, key: K, default: V | None = None) -> NoReturn: ...
-    def update(self, *args: Any, **kwargs: V) -> NoReturn: ...
-    def pop(self, key: K, default: V | None = None) -> NoReturn: ...  # type: ignore
-    def popitem(self) -> NoReturn: ...
-    def __setitem__(self, key: K, value: V) -> NoReturn: ...
-    def __delitem__(self, key: K) -> NoReturn: ...
-    def clear(self) -> NoReturn: ...
-
-class ImmutableMultiDictMixin(ImmutableDictMixin[K, V]):
-    def _iter_hashitems(self) -> Iterable[Hashable]: ...
-    def add(self, key: K, value: V) -> NoReturn: ...
-    def popitemlist(self) -> NoReturn: ...
-    def poplist(self, key: K) -> NoReturn: ...
-    def setlist(self, key: K, new_list: Iterable[V]) -> NoReturn: ...
-    def setlistdefault(
-        self, key: K, default_list: Iterable[V] | None = None
-    ) -> NoReturn: ...
-
-class ImmutableHeadersMixin(Headers):
-    def __delitem__(self, key: Any, _index_operation: bool = True) -> NoReturn: ...
-    def __setitem__(self, key: Any, value: Any) -> NoReturn: ...
-    def set(self, _key: Any, _value: Any, **kw: Any) -> NoReturn: ...
-    def setlist(self, key: Any, values: Any) -> NoReturn: ...
-    def add(self, _key: Any, _value: Any, **kw: Any) -> NoReturn: ...
-    def add_header(self, _key: Any, _value: Any, **_kw: Any) -> NoReturn: ...
-    def remove(self, key: Any) -> NoReturn: ...
-    def extend(self, *args: Any, **kwargs: Any) -> NoReturn: ...
-    def update(self, *args: Any, **kwargs: Any) -> NoReturn: ...
-    def insert(self, pos: Any, value: Any) -> NoReturn: ...
-    def pop(self, key: Any = None, default: Any = ...) -> NoReturn: ...
-    def popitem(self) -> NoReturn: ...
-    def setdefault(self, key: Any, default: Any) -> NoReturn: ...
-    def setlistdefault(self, key: Any, default: Any) -> NoReturn: ...
-
-def _calls_update(name: str) -> Callable[[UpdateDictMixin[K, V]], Any]: ...
-
-class UpdateDictMixin(dict[K, V]):
-    on_update: Callable[[UpdateDictMixin[K, V] | None, None], None]
-    def setdefault(self, key: K, default: V | None = None) -> V: ...
-    @overload
-    def pop(self, key: K) -> V: ...
-    @overload
-    def pop(self, key: K, default: V | T = ...) -> V | T: ...
-    def __setitem__(self, key: K, value: V) -> None: ...
-    def __delitem__(self, key: K) -> None: ...
-    def clear(self) -> None: ...
-    def popitem(self) -> tuple[K, V]: ...
-    @overload
-    def update(self, __m: SupportsKeysAndGetItem[K, V], **kwargs: V) -> None: ...
-    @overload
-    def update(self, __m: Iterable[tuple[K, V]], **kwargs: V) -> None: ...
-    @overload
-    def update(self, **kwargs: V) -> None: ...
diff --git a/src/werkzeug/datastructures/range.py b/src/werkzeug/datastructures/range.py
index 7011ea4ae..4c9f67d44 100644
--- a/src/werkzeug/datastructures/range.py
+++ b/src/werkzeug/datastructures/range.py
@@ -1,5 +1,14 @@
 from __future__ import annotations
 
+import collections.abc as cabc
+import typing as t
+from datetime import datetime
+
+if t.TYPE_CHECKING:
+    import typing_extensions as te
+
+T = t.TypeVar("T")
+
 
 class IfRange:
     """Very simple object that represents the `If-Range` header in parsed
@@ -9,14 +18,14 @@ class IfRange:
     .. versionadded:: 0.7
     """
 
-    def __init__(self, etag=None, date=None):
+    def __init__(self, etag: str | None = None, date: datetime | None = None):
         #: The etag parsed and unquoted.  Ranges always operate on strong
         #: etags so the weakness information is not necessary.
         self.etag = etag
         #: The date in parsed format or `None`.
         self.date = date
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Converts the object back into an HTTP header."""
         if self.date is not None:
             return http.http_date(self.date)
@@ -24,10 +33,10 @@ def to_header(self):
             return http.quote_etag(self.etag)
         return ""
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{type(self).__name__} {str(self)!r}>"
 
 
@@ -44,7 +53,9 @@ class Range:
     .. versionadded:: 0.7
     """
 
-    def __init__(self, units, ranges):
+    def __init__(
+        self, units: str, ranges: cabc.Sequence[tuple[int, int | None]]
+    ) -> None:
         #: The units of this range.  Usually "bytes".
         self.units = units
         #: A list of ``(begin, end)`` tuples for the range header provided.
@@ -55,7 +66,7 @@ def __init__(self, units, ranges):
             if start is None or (end is not None and (start < 0 or start >= end)):
                 raise ValueError(f"{(start, end)} is not a valid range.")
 
-    def range_for_length(self, length):
+    def range_for_length(self, length: int | None) -> tuple[int, int] | None:
         """If the range is for bytes, the length is not None and there is
         exactly one range and it is satisfiable it returns a ``(start, stop)``
         tuple, otherwise `None`.
@@ -71,7 +82,7 @@ def range_for_length(self, length):
             return start, min(end, length)
         return None
 
-    def make_content_range(self, length):
+    def make_content_range(self, length: int | None) -> ContentRange | None:
         """Creates a :class:`~werkzeug.datastructures.ContentRange` object
         from the current range and given content length.
         """
@@ -80,7 +91,7 @@ def make_content_range(self, length):
             return ContentRange(self.units, rng[0], rng[1], length)
         return None
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Converts the object back into an HTTP header."""
         ranges = []
         for begin, end in self.ranges:
@@ -90,7 +101,7 @@ def to_header(self):
                 ranges.append(f"{begin}-{end - 1}")
         return f"{self.units}={','.join(ranges)}"
 
-    def to_content_range_header(self, length):
+    def to_content_range_header(self, length: int | None) -> str | None:
         """Converts the object into `Content-Range` HTTP header,
         based on given length
         """
@@ -99,23 +110,34 @@ def to_content_range_header(self, length):
             return f"{self.units} {range[0]}-{range[1] - 1}/{length}"
         return None
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{type(self).__name__} {str(self)!r}>"
 
 
-def _callback_property(name):
-    def fget(self):
-        return getattr(self, name)
+class _CallbackProperty(t.Generic[T]):
+    def __set_name__(self, owner: type[ContentRange], name: str) -> None:
+        self.attr = f"_{name}"
 
-    def fset(self, value):
-        setattr(self, name, value)
-        if self.on_update is not None:
-            self.on_update(self)
+    @t.overload
+    def __get__(self, instance: None, owner: None) -> te.Self: ...
+    @t.overload
+    def __get__(self, instance: ContentRange, owner: type[ContentRange]) -> T: ...
+    def __get__(
+        self, instance: ContentRange | None, owner: type[ContentRange] | None
+    ) -> te.Self | T:
+        if instance is None:
+            return self
 
-    return property(fget, fset)
+        return instance.__dict__[self.attr]  # type: ignore[no-any-return]
+
+    def __set__(self, instance: ContentRange, value: T) -> None:
+        instance.__dict__[self.attr] = value
+
+        if instance.on_update is not None:
+            instance.on_update(instance)
 
 
 class ContentRange:
@@ -124,55 +146,67 @@ class ContentRange:
     .. versionadded:: 0.7
     """
 
-    def __init__(self, units, start, stop, length=None, on_update=None):
-        assert http.is_byte_range_valid(start, stop, length), "Bad range provided"
+    def __init__(
+        self,
+        units: str | None,
+        start: int | None,
+        stop: int | None,
+        length: int | None = None,
+        on_update: cabc.Callable[[ContentRange], None] | None = None,
+    ) -> None:
         self.on_update = on_update
         self.set(start, stop, length, units)
 
     #: The units to use, usually "bytes"
-    units = _callback_property("_units")
+    units: str | None = _CallbackProperty()  # type: ignore[assignment]
     #: The start point of the range or `None`.
-    start = _callback_property("_start")
+    start: int | None = _CallbackProperty()  # type: ignore[assignment]
     #: The stop point of the range (non-inclusive) or `None`.  Can only be
     #: `None` if also start is `None`.
-    stop = _callback_property("_stop")
+    stop: int | None = _CallbackProperty()  # type: ignore[assignment]
     #: The length of the range or `None`.
-    length = _callback_property("_length")
-
-    def set(self, start, stop, length=None, units="bytes"):
+    length: int | None = _CallbackProperty()  # type: ignore[assignment]
+
+    def set(
+        self,
+        start: int | None,
+        stop: int | None,
+        length: int | None = None,
+        units: str | None = "bytes",
+    ) -> None:
         """Simple method to update the ranges."""
         assert http.is_byte_range_valid(start, stop, length), "Bad range provided"
-        self._units = units
-        self._start = start
-        self._stop = stop
-        self._length = length
+        self._units: str | None = units
+        self._start: int | None = start
+        self._stop: int | None = stop
+        self._length: int | None = length
         if self.on_update is not None:
             self.on_update(self)
 
-    def unset(self):
+    def unset(self) -> None:
         """Sets the units to `None` which indicates that the header should
         no longer be used.
         """
         self.set(None, None, units=None)
 
-    def to_header(self):
-        if self.units is None:
+    def to_header(self) -> str:
+        if self._units is None:
             return ""
-        if self.length is None:
-            length = "*"
+        if self._length is None:
+            length: str | int = "*"
         else:
-            length = self.length
-        if self.start is None:
-            return f"{self.units} */{length}"
-        return f"{self.units} {self.start}-{self.stop - 1}/{length}"
+            length = self._length
+        if self._start is None:
+            return f"{self._units} */{length}"
+        return f"{self._units} {self._start}-{self._stop - 1}/{length}"  # type: ignore[operator]
 
-    def __bool__(self):
-        return self.units is not None
+    def __bool__(self) -> bool:
+        return self._units is not None
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{type(self).__name__} {str(self)!r}>"
 
 
diff --git a/src/werkzeug/datastructures/range.pyi b/src/werkzeug/datastructures/range.pyi
deleted file mode 100644
index f38ad69ef..000000000
--- a/src/werkzeug/datastructures/range.pyi
+++ /dev/null
@@ -1,57 +0,0 @@
-from collections.abc import Callable
-from datetime import datetime
-
-class IfRange:
-    etag: str | None
-    date: datetime | None
-    def __init__(
-        self, etag: str | None = None, date: datetime | None = None
-    ) -> None: ...
-    def to_header(self) -> str: ...
-
-class Range:
-    units: str
-    ranges: list[tuple[int, int | None]]
-    def __init__(self, units: str, ranges: list[tuple[int, int | None]]) -> None: ...
-    def range_for_length(self, length: int | None) -> tuple[int, int] | None: ...
-    def make_content_range(self, length: int | None) -> ContentRange | None: ...
-    def to_header(self) -> str: ...
-    def to_content_range_header(self, length: int | None) -> str | None: ...
-
-def _callback_property(name: str) -> property: ...
-
-class ContentRange:
-    on_update: Callable[[ContentRange], None] | None
-    def __init__(
-        self,
-        units: str | None,
-        start: int | None,
-        stop: int | None,
-        length: int | None = None,
-        on_update: Callable[[ContentRange], None] | None = None,
-    ) -> None: ...
-    @property
-    def units(self) -> str | None: ...
-    @units.setter
-    def units(self, value: str | None) -> None: ...
-    @property
-    def start(self) -> int | None: ...
-    @start.setter
-    def start(self, value: int | None) -> None: ...
-    @property
-    def stop(self) -> int | None: ...
-    @stop.setter
-    def stop(self, value: int | None) -> None: ...
-    @property
-    def length(self) -> int | None: ...
-    @length.setter
-    def length(self, value: int | None) -> None: ...
-    def set(
-        self,
-        start: int | None,
-        stop: int | None,
-        length: int | None = None,
-        units: str | None = "bytes",
-    ) -> None: ...
-    def unset(self) -> None: ...
-    def to_header(self) -> str: ...
diff --git a/src/werkzeug/datastructures/structures.py b/src/werkzeug/datastructures/structures.py
index 4279ceb98..eb54599d5 100644
--- a/src/werkzeug/datastructures/structures.py
+++ b/src/werkzeug/datastructures/structures.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from collections.abc import MutableSet
+import collections.abc as cabc
+import typing as t
 from copy import deepcopy
 
 from .. import exceptions
@@ -10,29 +11,38 @@
 from .mixins import ImmutableMultiDictMixin
 from .mixins import UpdateDictMixin
 
+if t.TYPE_CHECKING:
+    import typing_extensions as te
 
-def is_immutable(self):
-    raise TypeError(f"{type(self).__name__!r} objects are immutable")
+K = t.TypeVar("K")
+V = t.TypeVar("V")
+T = t.TypeVar("T")
 
 
-def iter_multi_items(mapping):
+def iter_multi_items(
+    mapping: (
+        MultiDict[K, V]
+        | cabc.Mapping[K, V | cabc.Collection[V]]
+        | cabc.Iterable[tuple[K, V]]
+    ),
+) -> cabc.Iterator[tuple[K, V]]:
     """Iterates over the items of a mapping yielding keys and values
     without dropping any from more complex structures.
     """
     if isinstance(mapping, MultiDict):
         yield from mapping.items(multi=True)
-    elif isinstance(mapping, dict):
+    elif isinstance(mapping, cabc.Mapping):
         for key, value in mapping.items():
-            if isinstance(value, (tuple, list)):
+            if isinstance(value, cabc.Collection) and not isinstance(value, str):
                 for v in value:
                     yield key, v
             else:
-                yield key, value
+                yield key, value  # type: ignore[misc]
     else:
         yield from mapping
 
 
-class ImmutableList(ImmutableListMixin, list):
+class ImmutableList(ImmutableListMixin, list[V]):  # type: ignore[misc]
     """An immutable :class:`list`.
 
     .. versionadded:: 0.5
@@ -40,11 +50,11 @@ class ImmutableList(ImmutableListMixin, list):
     :private:
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{type(self).__name__}({list.__repr__(self)})"
 
 
-class TypeConversionDict(dict):
+class TypeConversionDict(dict[K, V]):
     """Works like a regular dict but the :meth:`get` method can perform
     type conversions.  :class:`MultiDict` and :class:`CombinedMultiDict`
     are subclasses of this class and provide the same feature.
@@ -52,7 +62,19 @@ class TypeConversionDict(dict):
     .. versionadded:: 0.5
     """
 
-    def get(self, key, default=None, type=None):
+    @t.overload  # type: ignore[override]
+    def get(self, key: K) -> V | None: ...
+    @t.overload
+    def get(self, key: K, default: V) -> V: ...
+    @t.overload
+    def get(self, key: K, default: T) -> V | T: ...
+    @t.overload
+    def get(self, key: str, type: type[T]) -> T | None: ...
+    @t.overload
+    def get(self, key: str, default: T, type: type[T]) -> T: ...
+    def get(  # type: ignore[misc]
+        self, key: K, default: V | T | None = None, type: type[T] | None = None
+    ) -> V | T | None:
         """Return the default value if the requested data doesn't exist.
         If `type` is provided and is a callable it should convert the value,
         return it or raise a :exc:`ValueError` if that is not possible.  In
@@ -81,33 +103,35 @@ def get(self, key, default=None, type=None):
             rv = self[key]
         except KeyError:
             return default
-        if type is not None:
-            try:
-                rv = type(rv)
-            except (ValueError, TypeError):
-                rv = default
-        return rv
+
+        if type is None:
+            return rv
+
+        try:
+            return type(rv)  # type: ignore[call-arg]
+        except (ValueError, TypeError):
+            return default
 
 
-class ImmutableTypeConversionDict(ImmutableDictMixin, TypeConversionDict):
+class ImmutableTypeConversionDict(ImmutableDictMixin[K, V], TypeConversionDict[K, V]):  # type: ignore[misc]
     """Works like a :class:`TypeConversionDict` but does not support
     modifications.
 
     .. versionadded:: 0.5
     """
 
-    def copy(self):
+    def copy(self) -> TypeConversionDict[K, V]:
         """Return a shallow mutable copy of this object.  Keep in mind that
         the standard library's :func:`copy` function is a no-op for this class
         like for any other python immutable type (eg: :class:`tuple`).
         """
         return TypeConversionDict(self)
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self
 
 
-class MultiDict(TypeConversionDict):
+class MultiDict(TypeConversionDict[K, V]):
     """A :class:`MultiDict` is a dictionary subclass customized to deal with
     multiple values for the same key which is for example used by the parsing
     functions in the wrappers.  This is necessary because some HTML form
@@ -148,40 +172,52 @@ class MultiDict(TypeConversionDict):
                     or `None`.
     """
 
-    def __init__(self, mapping=None):
-        if isinstance(mapping, MultiDict):
-            dict.__init__(self, ((k, vs[:]) for k, vs in mapping.lists()))
-        elif isinstance(mapping, dict):
+    def __init__(
+        self,
+        mapping: (
+            MultiDict[K, V]
+            | cabc.Mapping[K, V | cabc.Collection[V]]
+            | cabc.Iterable[tuple[K, V]]
+            | None
+        ) = None,
+    ) -> None:
+        if mapping is None:
+            super().__init__()
+        elif isinstance(mapping, MultiDict):
+            super().__init__((k, vs[:]) for k, vs in mapping.lists())
+        elif isinstance(mapping, cabc.Mapping):
             tmp = {}
             for key, value in mapping.items():
-                if isinstance(value, (tuple, list)):
-                    if len(value) == 0:
-                        continue
+                if isinstance(value, cabc.Collection) and not isinstance(value, str):
                     value = list(value)
+
+                    if not value:
+                        continue
                 else:
                     value = [value]
                 tmp[key] = value
-            dict.__init__(self, tmp)
+            super().__init__(tmp)  # type: ignore[arg-type]
         else:
             tmp = {}
-            for key, value in mapping or ():
+            for key, value in mapping:
                 tmp.setdefault(key, []).append(value)
-            dict.__init__(self, tmp)
+            super().__init__(tmp)  # type: ignore[arg-type]
 
-    def __getstate__(self):
+    def __getstate__(self) -> t.Any:
         return dict(self.lists())
 
-    def __setstate__(self, value):
-        dict.clear(self)
-        dict.update(self, value)
+    def __setstate__(self, value: t.Any) -> None:
+        super().clear()
+        super().update(value)
 
-    def __iter__(self):
-        # Work around https://bugs.python.org/issue43246.
-        # (`return super().__iter__()` also works here, which makes this look
-        # even more like it should be a no-op, yet it isn't.)
-        return dict.__iter__(self)
+    def __iter__(self) -> cabc.Iterator[K]:
+        # https://github.com/python/cpython/issues/87412
+        # If __iter__ is not overridden, Python uses a fast path for dict(md),
+        # taking the data directly and getting lists of values, rather than
+        # calling __getitem__ and getting only the first value.
+        return super().__iter__()
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: K) -> V:
         """Return the first data value for this key;
         raises KeyError if not found.
 
@@ -190,20 +226,20 @@ def __getitem__(self, key):
         """
 
         if key in self:
-            lst = dict.__getitem__(self, key)
-            if len(lst) > 0:
-                return lst[0]
+            lst = super().__getitem__(key)
+            if len(lst) > 0:  # type: ignore[arg-type]
+                return lst[0]  # type: ignore[index,no-any-return]
         raise exceptions.BadRequestKeyError(key)
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: K, value: V) -> None:
         """Like :meth:`add` but removes an existing key first.
 
         :param key: the key for the value.
         :param value: the value to set.
         """
-        dict.__setitem__(self, key, [value])
+        super().__setitem__(key, [value])  # type: ignore[assignment]
 
-    def add(self, key, value):
+    def add(self, key: K, value: V) -> None:
         """Adds a new value for the key.
 
         .. versionadded:: 0.6
@@ -211,9 +247,13 @@ def add(self, key, value):
         :param key: the key for the value.
         :param value: the value to add.
         """
-        dict.setdefault(self, key, []).append(value)
+        super().setdefault(key, []).append(value)  # type: ignore[arg-type,attr-defined]
 
-    def getlist(self, key, type=None):
+    @t.overload
+    def getlist(self, key: K) -> list[V]: ...
+    @t.overload
+    def getlist(self, key: K, type: type[T]) -> list[T]: ...
+    def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
         """Return the list of items for a given key. If that key is not in the
         `MultiDict`, the return value will be an empty list.  Just like `get`,
         `getlist` accepts a `type` parameter.  All items will be converted
@@ -226,7 +266,7 @@ def getlist(self, key, type=None):
         :return: a :class:`list` of all the values for the key.
         """
         try:
-            rv = dict.__getitem__(self, key)
+            rv: list[V] = super().__getitem__(key)  # type: ignore[assignment]
         except KeyError:
             return []
         if type is None:
@@ -234,12 +274,12 @@ def getlist(self, key, type=None):
         result = []
         for item in rv:
             try:
-                result.append(type(item))
+                result.append(type(item))  # type: ignore[call-arg]
             except ValueError:
                 pass
         return result
 
-    def setlist(self, key, new_list):
+    def setlist(self, key: K, new_list: cabc.Iterable[V]) -> None:
         """Remove the old values for a key and add new ones.  Note that the list
         you pass the values in will be shallow-copied before it is inserted in
         the dictionary.
@@ -255,9 +295,13 @@ def setlist(self, key, new_list):
         :param new_list: An iterable with the new values for the key.  Old values
                          are removed first.
         """
-        dict.__setitem__(self, key, list(new_list))
+        super().__setitem__(key, list(new_list))  # type: ignore[assignment]
 
-    def setdefault(self, key, default=None):
+    @t.overload
+    def setdefault(self, key: K) -> None: ...
+    @t.overload
+    def setdefault(self, key: K, default: V) -> V: ...
+    def setdefault(self, key: K, default: V | None = None) -> V | None:
         """Returns the value for the key if it is in the dict, otherwise it
         returns `default` and sets that value for `key`.
 
@@ -266,12 +310,13 @@ def setdefault(self, key, default=None):
                         in the dict.  If not further specified it's `None`.
         """
         if key not in self:
-            self[key] = default
-        else:
-            default = self[key]
-        return default
+            self[key] = default  # type: ignore[assignment]
 
-    def setlistdefault(self, key, default_list=None):
+        return self[key]
+
+    def setlistdefault(
+        self, key: K, default_list: cabc.Iterable[V] | None = None
+    ) -> list[V]:
         """Like `setdefault` but sets multiple values.  The list returned
         is not a copy, but the list that is actually used internally.  This
         means that you can put new values into the dict by appending items
@@ -289,38 +334,42 @@ def setlistdefault(self, key, default_list=None):
         :return: a :class:`list`
         """
         if key not in self:
-            default_list = list(default_list or ())
-            dict.__setitem__(self, key, default_list)
-        else:
-            default_list = dict.__getitem__(self, key)
-        return default_list
+            super().__setitem__(key, list(default_list or ()))  # type: ignore[assignment]
+
+        return super().__getitem__(key)  # type: ignore[return-value]
 
-    def items(self, multi=False):
+    def items(self, multi: bool = False) -> cabc.Iterable[tuple[K, V]]:  # type: ignore[override]
         """Return an iterator of ``(key, value)`` pairs.
 
         :param multi: If set to `True` the iterator returned will have a pair
                       for each value of each key.  Otherwise it will only
                       contain pairs for the first value of each key.
         """
-        for key, values in dict.items(self):
+        values: list[V]
+
+        for key, values in super().items():  # type: ignore[assignment]
             if multi:
                 for value in values:
                     yield key, value
             else:
                 yield key, values[0]
 
-    def lists(self):
+    def lists(self) -> cabc.Iterable[tuple[K, list[V]]]:
         """Return a iterator of ``(key, values)`` pairs, where values is the list
         of all values associated with the key."""
-        for key, values in dict.items(self):
+        values: list[V]
+
+        for key, values in super().items():  # type: ignore[assignment]
             yield key, list(values)
 
-    def values(self):
+    def values(self) -> cabc.Iterable[V]:  # type: ignore[override]
         """Returns an iterator of the first value on every key's value list."""
-        for values in dict.values(self):
+        values: list[V]
+
+        for values in super().values():  # type: ignore[assignment]
             yield values[0]
 
-    def listvalues(self):
+    def listvalues(self) -> cabc.Iterable[list[V]]:
         """Return an iterator of all values associated with a key.  Zipping
         :meth:`keys` and this is the same as calling :meth:`lists`:
 
@@ -328,17 +377,21 @@ def listvalues(self):
         >>> zip(d.keys(), d.listvalues()) == d.lists()
         True
         """
-        return dict.values(self)
+        return super().values()  # type: ignore[return-value]
 
-    def copy(self):
+    def copy(self) -> te.Self:
         """Return a shallow copy of this object."""
         return self.__class__(self)
 
-    def deepcopy(self, memo=None):
+    def deepcopy(self, memo: t.Any = None) -> te.Self:
         """Return a deep copy of this object."""
         return self.__class__(deepcopy(self.to_dict(flat=False), memo))
 
-    def to_dict(self, flat=True):
+    @t.overload
+    def to_dict(self) -> dict[K, V]: ...
+    @t.overload
+    def to_dict(self, flat: t.Literal[False]) -> dict[K, list[V]]: ...
+    def to_dict(self, flat: bool = True) -> dict[K, V] | dict[K, list[V]]:
         """Return the contents as regular dict.  If `flat` is `True` the
         returned dict will only have the first item present, if `flat` is
         `False` all values will be returned as lists.
@@ -352,7 +405,14 @@ def to_dict(self, flat=True):
             return dict(self.items())
         return dict(self.lists())
 
-    def update(self, mapping):
+    def update(  # type: ignore[override]
+        self,
+        mapping: (
+            MultiDict[K, V]
+            | cabc.Mapping[K, V | cabc.Collection[V]]
+            | cabc.Iterable[tuple[K, V]]
+        ),
+    ) -> None:
         """update() extends rather than replaces existing key lists:
 
         >>> a = MultiDict({'x': 1})
@@ -371,9 +431,19 @@ def update(self, mapping):
         MultiDict([])
         """
         for key, value in iter_multi_items(mapping):
-            MultiDict.add(self, key, value)
+            self.add(key, value)
 
-    def pop(self, key, default=_missing):
+    @t.overload
+    def pop(self, key: K) -> V: ...
+    @t.overload
+    def pop(self, key: K, default: V) -> V: ...
+    @t.overload
+    def pop(self, key: K, default: T) -> V | T: ...
+    def pop(
+        self,
+        key: K,
+        default: V | T = _missing,  # type: ignore[assignment]
+    ) -> V | T:
         """Pop the first item for a list on the dict.  Afterwards the
         key is removed from the dict, so additional values are discarded:
 
@@ -387,8 +457,10 @@ def pop(self, key, default=_missing):
         :param default: if provided the value to return if the key was
                         not in the dictionary.
         """
+        lst: list[V]
+
         try:
-            lst = dict.pop(self, key)
+            lst = super().pop(key)  # type: ignore[assignment]
 
             if len(lst) == 0:
                 raise exceptions.BadRequestKeyError(key)
@@ -400,19 +472,21 @@ def pop(self, key, default=_missing):
 
             raise exceptions.BadRequestKeyError(key) from None
 
-    def popitem(self):
+    def popitem(self) -> tuple[K, V]:
         """Pop an item from the dict."""
+        item: tuple[K, list[V]]
+
         try:
-            item = dict.popitem(self)
+            item = super().popitem()  # type: ignore[assignment]
 
             if len(item[1]) == 0:
                 raise exceptions.BadRequestKeyError(item[0])
 
-            return (item[0], item[1][0])
+            return item[0], item[1][0]
         except KeyError as e:
             raise exceptions.BadRequestKeyError(e.args[0]) from None
 
-    def poplist(self, key):
+    def poplist(self, key: K) -> list[V]:
         """Pop the list for a key from the dict.  If the key is not in the dict
         an empty list is returned.
 
@@ -420,26 +494,26 @@ def poplist(self, key):
            If the key does no longer exist a list is returned instead of
            raising an error.
         """
-        return dict.pop(self, key, [])
+        return super().pop(key, [])  # type: ignore[return-value]
 
-    def popitemlist(self):
+    def popitemlist(self) -> tuple[K, list[V]]:
         """Pop a ``(key, list)`` tuple from the dict."""
         try:
-            return dict.popitem(self)
+            return super().popitem()  # type: ignore[return-value]
         except KeyError as e:
             raise exceptions.BadRequestKeyError(e.args[0]) from None
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self.copy()
 
-    def __deepcopy__(self, memo):
+    def __deepcopy__(self, memo: t.Any) -> te.Self:
         return self.deepcopy(memo=memo)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{type(self).__name__}({list(self.items(multi=True))!r})"
 
 
-class _omd_bucket:
+class _omd_bucket(t.Generic[K, V]):
     """Wraps values in the :class:`OrderedMultiDict`.  This makes it
     possible to keep an order over multiple different keys.  It requires
     a lot of extra memory and slows down access a lot, but makes it
@@ -448,11 +522,11 @@ class _omd_bucket:
 
     __slots__ = ("prev", "key", "value", "next")
 
-    def __init__(self, omd, key, value):
-        self.prev = omd._last_bucket
-        self.key = key
-        self.value = value
-        self.next = None
+    def __init__(self, omd: OrderedMultiDict[K, V], key: K, value: V) -> None:
+        self.prev: _omd_bucket[K, V] | None = omd._last_bucket
+        self.key: K = key
+        self.value: V = value
+        self.next: _omd_bucket[K, V] | None = None
 
         if omd._first_bucket is None:
             omd._first_bucket = self
@@ -460,7 +534,7 @@ def __init__(self, omd, key, value):
             omd._last_bucket.next = self
         omd._last_bucket = self
 
-    def unlink(self, omd):
+    def unlink(self, omd: OrderedMultiDict[K, V]) -> None:
         if self.prev:
             self.prev.next = self.next
         if self.next:
@@ -471,7 +545,7 @@ def unlink(self, omd):
             omd._last_bucket = self.prev
 
 
-class OrderedMultiDict(MultiDict):
+class OrderedMultiDict(MultiDict[K, V]):
     """Works like a regular :class:`MultiDict` but preserves the
     order of the fields.  To convert the ordered multi dict into a
     list you can use the :meth:`items` method and pass it ``multi=True``.
@@ -487,13 +561,22 @@ class OrderedMultiDict(MultiDict):
        the internal bucket objects are exposed.
     """
 
-    def __init__(self, mapping=None):
-        dict.__init__(self)
-        self._first_bucket = self._last_bucket = None
+    def __init__(
+        self,
+        mapping: (
+            MultiDict[K, V]
+            | cabc.Mapping[K, V | cabc.Collection[V]]
+            | cabc.Iterable[tuple[K, V]]
+            | None
+        ) = None,
+    ) -> None:
+        super().__init__()
+        self._first_bucket: _omd_bucket[K, V] | None = None
+        self._last_bucket: _omd_bucket[K, V] | None = None
         if mapping is not None:
-            OrderedMultiDict.update(self, mapping)
+            self.update(mapping)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, MultiDict):
             return NotImplemented
         if isinstance(other, OrderedMultiDict):
@@ -518,41 +601,42 @@ def __eq__(self, other):
                 return False
         return True
 
-    __hash__ = None
+    __hash__ = None  # type: ignore[assignment]
 
-    def __reduce_ex__(self, protocol):
+    def __reduce_ex__(self, protocol: t.SupportsIndex) -> t.Any:
         return type(self), (list(self.items(multi=True)),)
 
-    def __getstate__(self):
+    def __getstate__(self) -> t.Any:
         return list(self.items(multi=True))
 
-    def __setstate__(self, values):
-        dict.clear(self)
+    def __setstate__(self, values: t.Any) -> None:
+        self.clear()
+
         for key, value in values:
             self.add(key, value)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: K) -> V:
         if key in self:
-            return dict.__getitem__(self, key)[0].value
+            return dict.__getitem__(self, key)[0].value  # type: ignore[index,no-any-return]
         raise exceptions.BadRequestKeyError(key)
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: K, value: V) -> None:
         self.poplist(key)
         self.add(key, value)
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: K) -> None:
         self.pop(key)
 
-    def keys(self):
-        return (key for key, value in self.items())
+    def keys(self) -> cabc.Iterable[K]:  # type: ignore[override]
+        return (key for key, _ in self.items())
 
-    def __iter__(self):
+    def __iter__(self) -> cabc.Iterator[K]:
         return iter(self.keys())
 
-    def values(self):
+    def values(self) -> cabc.Iterable[V]:  # type: ignore[override]
         return (value for key, value in self.items())
 
-    def items(self, multi=False):
+    def items(self, multi: bool = False) -> cabc.Iterable[tuple[K, V]]:  # type: ignore[override]
         ptr = self._first_bucket
         if multi:
             while ptr is not None:
@@ -566,7 +650,7 @@ def items(self, multi=False):
                     yield ptr.key, ptr.value
                 ptr = ptr.next
 
-    def lists(self):
+    def lists(self) -> cabc.Iterable[tuple[K, list[V]]]:
         returned_keys = set()
         ptr = self._first_bucket
         while ptr is not None:
@@ -575,16 +659,22 @@ def lists(self):
                 returned_keys.add(ptr.key)
             ptr = ptr.next
 
-    def listvalues(self):
+    def listvalues(self) -> cabc.Iterable[list[V]]:
         for _key, values in self.lists():
             yield values
 
-    def add(self, key, value):
-        dict.setdefault(self, key, []).append(_omd_bucket(self, key, value))
+    def add(self, key: K, value: V) -> None:
+        dict.setdefault(self, key, []).append(_omd_bucket(self, key, value))  # type: ignore[arg-type,attr-defined]
+
+    @t.overload
+    def getlist(self, key: K) -> list[V]: ...
+    @t.overload
+    def getlist(self, key: K, type: type[T]) -> list[T]: ...
+    def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
+        rv: list[_omd_bucket[K, V]]
 
-    def getlist(self, key, type=None):
         try:
-            rv = dict.__getitem__(self, key)
+            rv = dict.__getitem__(self, key)  # type: ignore[index]
         except KeyError:
             return []
         if type is None:
@@ -592,32 +682,51 @@ def getlist(self, key, type=None):
         result = []
         for item in rv:
             try:
-                result.append(type(item.value))
+                result.append(type(item.value))  # type: ignore[call-arg]
             except ValueError:
                 pass
         return result
 
-    def setlist(self, key, new_list):
+    def setlist(self, key: K, new_list: cabc.Iterable[V]) -> None:
         self.poplist(key)
         for value in new_list:
             self.add(key, value)
 
-    def setlistdefault(self, key, default_list=None):
+    def setlistdefault(self, key: t.Any, default_list: t.Any = None) -> t.NoReturn:
         raise TypeError("setlistdefault is unsupported for ordered multi dicts")
 
-    def update(self, mapping):
+    def update(  # type: ignore[override]
+        self,
+        mapping: (
+            MultiDict[K, V]
+            | cabc.Mapping[K, V | cabc.Collection[V]]
+            | cabc.Iterable[tuple[K, V]]
+        ),
+    ) -> None:
         for key, value in iter_multi_items(mapping):
-            OrderedMultiDict.add(self, key, value)
+            self.add(key, value)
 
-    def poplist(self, key):
-        buckets = dict.pop(self, key, ())
+    def poplist(self, key: K) -> list[V]:
+        buckets: cabc.Iterable[_omd_bucket[K, V]] = dict.pop(self, key, ())  # type: ignore[arg-type]
         for bucket in buckets:
             bucket.unlink(self)
         return [x.value for x in buckets]
 
-    def pop(self, key, default=_missing):
+    @t.overload
+    def pop(self, key: K) -> V: ...
+    @t.overload
+    def pop(self, key: K, default: V) -> V: ...
+    @t.overload
+    def pop(self, key: K, default: T) -> V | T: ...
+    def pop(
+        self,
+        key: K,
+        default: V | T = _missing,  # type: ignore[assignment]
+    ) -> V | T:
+        buckets: list[_omd_bucket[K, V]]
+
         try:
-            buckets = dict.pop(self, key)
+            buckets = dict.pop(self, key)  # type: ignore[arg-type]
         except KeyError:
             if default is not _missing:
                 return default
@@ -629,9 +738,12 @@ def pop(self, key, default=_missing):
 
         return buckets[0].value
 
-    def popitem(self):
+    def popitem(self) -> tuple[K, V]:
+        key: K
+        buckets: list[_omd_bucket[K, V]]
+
         try:
-            key, buckets = dict.popitem(self)
+            key, buckets = dict.popitem(self)  # type: ignore[arg-type,assignment]
         except KeyError as e:
             raise exceptions.BadRequestKeyError(e.args[0]) from None
 
@@ -640,9 +752,12 @@ def popitem(self):
 
         return key, buckets[0].value
 
-    def popitemlist(self):
+    def popitemlist(self) -> tuple[K, list[V]]:
+        key: K
+        buckets: list[_omd_bucket[K, V]]
+
         try:
-            key, buckets = dict.popitem(self)
+            key, buckets = dict.popitem(self)  # type: ignore[arg-type,assignment]
         except KeyError as e:
             raise exceptions.BadRequestKeyError(e.args[0]) from None
 
@@ -652,7 +767,7 @@ def popitemlist(self):
         return key, [x.value for x in buckets]
 
 
-class CombinedMultiDict(ImmutableMultiDictMixin, MultiDict):
+class CombinedMultiDict(ImmutableMultiDictMixin[K, V], MultiDict[K, V]):  # type: ignore[misc]
     """A read only :class:`MultiDict` that you can pass multiple :class:`MultiDict`
     instances as sequence and it will combine the return values of all wrapped
     dicts:
@@ -675,54 +790,75 @@ class CombinedMultiDict(ImmutableMultiDictMixin, MultiDict):
     exceptions.
     """
 
-    def __reduce_ex__(self, protocol):
+    def __reduce_ex__(self, protocol: t.SupportsIndex) -> t.Any:
         return type(self), (self.dicts,)
 
-    def __init__(self, dicts=None):
-        self.dicts = list(dicts) or []
+    def __init__(self, dicts: cabc.Iterable[MultiDict[K, V]] | None = None) -> None:
+        super().__init__()
+        self.dicts: list[MultiDict[K, V]] = list(dicts or ())
 
     @classmethod
-    def fromkeys(cls, keys, value=None):
+    def fromkeys(cls, keys: t.Any, value: t.Any = None) -> t.NoReturn:
         raise TypeError(f"cannot create {cls.__name__!r} instances by fromkeys")
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: K) -> V:
         for d in self.dicts:
             if key in d:
                 return d[key]
         raise exceptions.BadRequestKeyError(key)
 
-    def get(self, key, default=None, type=None):
+    @t.overload  # type: ignore[override]
+    def get(self, key: K) -> V | None: ...
+    @t.overload
+    def get(self, key: K, default: V) -> V: ...
+    @t.overload
+    def get(self, key: K, default: T) -> V | T: ...
+    @t.overload
+    def get(self, key: str, type: type[T]) -> T | None: ...
+    @t.overload
+    def get(self, key: str, default: T, type: type[T]) -> T: ...
+    def get(  # type: ignore[misc]
+        self, key: K, default: V | T | None = None, type: type[T] | None = None
+    ) -> V | T | None:
         for d in self.dicts:
             if key in d:
                 if type is not None:
                     try:
-                        return type(d[key])
+                        return type(d[key])  # type: ignore[call-arg]
                     except ValueError:
                         continue
                 return d[key]
         return default
 
-    def getlist(self, key, type=None):
+    @t.overload
+    def getlist(self, key: K) -> list[V]: ...
+    @t.overload
+    def getlist(self, key: K, type: type[T]) -> list[T]: ...
+    def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
         rv = []
         for d in self.dicts:
-            rv.extend(d.getlist(key, type))
+            rv.extend(d.getlist(key, type))  # type: ignore[arg-type]
         return rv
 
-    def _keys_impl(self):
+    def _keys_impl(self) -> set[K]:
         """This function exists so __len__ can be implemented more efficiently,
         saving one list creation from an iterator.
         """
-        rv = set()
-        rv.update(*self.dicts)
-        return rv
+        return set(k for d in self.dicts for k in d)
 
-    def keys(self):
+    def keys(self) -> cabc.Iterable[K]:  # type: ignore[override]
         return self._keys_impl()
 
-    def __iter__(self):
-        return iter(self.keys())
+    def __iter__(self) -> cabc.Iterator[K]:
+        return iter(self._keys_impl())
 
-    def items(self, multi=False):
+    @t.overload  # type: ignore[override]
+    def items(self) -> cabc.Iterable[tuple[K, V]]: ...
+    @t.overload
+    def items(self, multi: t.Literal[True]) -> cabc.Iterable[tuple[K, list[V]]]: ...
+    def items(
+        self, multi: bool = False
+    ) -> cabc.Iterable[tuple[K, V]] | cabc.Iterable[tuple[K, list[V]]]:
         found = set()
         for d in self.dicts:
             for key, value in d.items(multi):
@@ -732,21 +868,21 @@ def items(self, multi=False):
                     found.add(key)
                     yield key, value
 
-    def values(self):
-        for _key, value in self.items():
+    def values(self) -> cabc.Iterable[V]:  # type: ignore[override]
+        for _, value in self.items():
             yield value
 
-    def lists(self):
-        rv = {}
+    def lists(self) -> cabc.Iterable[tuple[K, list[V]]]:
+        rv: dict[K, list[V]] = {}
         for d in self.dicts:
             for key, values in d.lists():
                 rv.setdefault(key, []).extend(values)
-        return list(rv.items())
+        return rv.items()
 
-    def listvalues(self):
+    def listvalues(self) -> cabc.Iterable[list[V]]:
         return (x[1] for x in self.lists())
 
-    def copy(self):
+    def copy(self) -> MultiDict[K, V]:  # type: ignore[override]
         """Return a shallow mutable copy of this object.
 
         This returns a :class:`MultiDict` representing the data at the
@@ -758,105 +894,113 @@ def copy(self):
         """
         return MultiDict(self)
 
-    def to_dict(self, flat=True):
-        """Return the contents as regular dict.  If `flat` is `True` the
-        returned dict will only have the first item present, if `flat` is
-        `False` all values will be returned as lists.
-
-        :param flat: If set to `False` the dict returned will have lists
-                     with all the values in it.  Otherwise it will only
-                     contain the first item for each key.
-        :return: a :class:`dict`
-        """
-        if flat:
-            return dict(self.items())
-
-        return dict(self.lists())
-
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._keys_impl())
 
-    def __contains__(self, key):
+    def __contains__(self, key: K) -> bool:  # type: ignore[override]
         for d in self.dicts:
             if key in d:
                 return True
         return False
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{type(self).__name__}({self.dicts!r})"
 
 
-class ImmutableDict(ImmutableDictMixin, dict):
+class ImmutableDict(ImmutableDictMixin[K, V], dict[K, V]):  # type: ignore[misc]
     """An immutable :class:`dict`.
 
     .. versionadded:: 0.5
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{type(self).__name__}({dict.__repr__(self)})"
 
-    def copy(self):
+    def copy(self) -> dict[K, V]:
         """Return a shallow mutable copy of this object.  Keep in mind that
         the standard library's :func:`copy` function is a no-op for this class
         like for any other python immutable type (eg: :class:`tuple`).
         """
         return dict(self)
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self
 
 
-class ImmutableMultiDict(ImmutableMultiDictMixin, MultiDict):
+class ImmutableMultiDict(ImmutableMultiDictMixin[K, V], MultiDict[K, V]):  # type: ignore[misc]
     """An immutable :class:`MultiDict`.
 
     .. versionadded:: 0.5
     """
 
-    def copy(self):
+    def copy(self) -> MultiDict[K, V]:  # type: ignore[override]
         """Return a shallow mutable copy of this object.  Keep in mind that
         the standard library's :func:`copy` function is a no-op for this class
         like for any other python immutable type (eg: :class:`tuple`).
         """
         return MultiDict(self)
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self
 
 
-class ImmutableOrderedMultiDict(ImmutableMultiDictMixin, OrderedMultiDict):
+class ImmutableOrderedMultiDict(ImmutableMultiDictMixin[K, V], OrderedMultiDict[K, V]):  # type: ignore[misc]
     """An immutable :class:`OrderedMultiDict`.
 
     .. versionadded:: 0.6
     """
 
-    def _iter_hashitems(self):
+    def __init__(
+        self,
+        mapping: (
+            MultiDict[K, V]
+            | cabc.Mapping[K, V | cabc.Collection[V]]
+            | cabc.Iterable[tuple[K, V]]
+            | None
+        ) = None,
+    ) -> None:
+        super().__init__()
+
+        if mapping is not None:
+            for k, v in iter_multi_items(mapping):
+                OrderedMultiDict.add(self, k, v)
+
+    def _iter_hashitems(self) -> cabc.Iterable[t.Any]:
         return enumerate(self.items(multi=True))
 
-    def copy(self):
+    def copy(self) -> OrderedMultiDict[K, V]:  # type: ignore[override]
         """Return a shallow mutable copy of this object.  Keep in mind that
         the standard library's :func:`copy` function is a no-op for this class
         like for any other python immutable type (eg: :class:`tuple`).
         """
         return OrderedMultiDict(self)
 
-    def __copy__(self):
+    def __copy__(self) -> te.Self:
         return self
 
 
-class CallbackDict(UpdateDictMixin, dict):
+class CallbackDict(UpdateDictMixin[K, V], dict[K, V]):
     """A dict that calls a function passed every time something is changed.
     The function is passed the dict instance.
     """
 
-    def __init__(self, initial=None, on_update=None):
-        dict.__init__(self, initial or ())
+    def __init__(
+        self,
+        initial: cabc.Mapping[K, V] | cabc.Iterable[tuple[K, V]] | None = None,
+        on_update: cabc.Callable[[te.Self], None] | None = None,
+    ) -> None:
+        if initial is None:
+            super().__init__()
+        else:
+            super().__init__(initial)
+
         self.on_update = on_update
 
-    def __repr__(self):
-        return f"<{type(self).__name__} {dict.__repr__(self)}>"
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {super().__repr__()}>"
 
 
-class HeaderSet(MutableSet):
+class HeaderSet(cabc.MutableSet[str]):
     """Similar to the :class:`ETags` class this implements a set-like structure.
     Unlike :class:`ETags` this is case insensitive and used for vary, allow, and
     content-language headers.
@@ -869,16 +1013,20 @@ class HeaderSet(MutableSet):
     HeaderSet(['foo', 'bar', 'baz'])
     """
 
-    def __init__(self, headers=None, on_update=None):
+    def __init__(
+        self,
+        headers: cabc.Iterable[str] | None = None,
+        on_update: cabc.Callable[[te.Self], None] | None = None,
+    ) -> None:
         self._headers = list(headers or ())
         self._set = {x.lower() for x in self._headers}
         self.on_update = on_update
 
-    def add(self, header):
+    def add(self, header: str) -> None:
         """Add a new header to the set."""
         self.update((header,))
 
-    def remove(self, header):
+    def remove(self: te.Self, header: str) -> None:
         """Remove a header from the set.  This raises an :exc:`KeyError` if the
         header is not in the set.
 
@@ -899,7 +1047,7 @@ def remove(self, header):
         if self.on_update is not None:
             self.on_update(self)
 
-    def update(self, iterable):
+    def update(self: te.Self, iterable: cabc.Iterable[str]) -> None:
         """Add all the headers from the iterable to the set.
 
         :param iterable: updates the set with the items from the iterable.
@@ -914,7 +1062,7 @@ def update(self, iterable):
         if inserted_any and self.on_update is not None:
             self.on_update(self)
 
-    def discard(self, header):
+    def discard(self, header: str) -> None:
         """Like :meth:`remove` but ignores errors.
 
         :param header: the header to be discarded.
@@ -924,7 +1072,7 @@ def discard(self, header):
         except KeyError:
             pass
 
-    def find(self, header):
+    def find(self, header: str) -> int:
         """Return the index of the header in the set or return -1 if not found.
 
         :param header: the header to be looked up.
@@ -935,7 +1083,7 @@ def find(self, header):
                 return idx
         return -1
 
-    def index(self, header):
+    def index(self, header: str) -> int:
         """Return the index of the header in the set or raise an
         :exc:`IndexError`.
 
@@ -946,14 +1094,15 @@ def index(self, header):
             raise IndexError(header)
         return rv
 
-    def clear(self):
+    def clear(self: te.Self) -> None:
         """Clear the set."""
         self._set.clear()
-        del self._headers[:]
+        self._headers.clear()
+
         if self.on_update is not None:
             self.on_update(self)
 
-    def as_set(self, preserve_casing=False):
+    def as_set(self, preserve_casing: bool = False) -> set[str]:
         """Return the set as real python set type.  When calling this, all
         the items are converted to lowercase and the ordering is lost.
 
@@ -966,20 +1115,20 @@ def as_set(self, preserve_casing=False):
             return set(self._headers)
         return set(self._set)
 
-    def to_header(self):
+    def to_header(self) -> str:
         """Convert the header set into an HTTP header string."""
         return ", ".join(map(http.quote_header_value, self._headers))
 
-    def __getitem__(self, idx):
+    def __getitem__(self, idx: t.SupportsIndex) -> str:
         return self._headers[idx]
 
-    def __delitem__(self, idx):
+    def __delitem__(self: te.Self, idx: t.SupportsIndex) -> None:
         rv = self._headers.pop(idx)
         self._set.remove(rv.lower())
         if self.on_update is not None:
             self.on_update(self)
 
-    def __setitem__(self, idx, value):
+    def __setitem__(self: te.Self, idx: t.SupportsIndex, value: str) -> None:
         old = self._headers[idx]
         self._set.remove(old.lower())
         self._headers[idx] = value
@@ -987,22 +1136,22 @@ def __setitem__(self, idx, value):
         if self.on_update is not None:
             self.on_update(self)
 
-    def __contains__(self, header):
+    def __contains__(self, header: str) -> bool:  # type: ignore[override]
         return header.lower() in self._set
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self._set)
 
-    def __iter__(self):
+    def __iter__(self) -> cabc.Iterator[str]:
         return iter(self._headers)
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return bool(self._set)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.to_header()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"{type(self).__name__}({self._headers!r})"
 
 
diff --git a/src/werkzeug/datastructures/structures.pyi b/src/werkzeug/datastructures/structures.pyi
deleted file mode 100644
index 7086ddae1..000000000
--- a/src/werkzeug/datastructures/structures.pyi
+++ /dev/null
@@ -1,206 +0,0 @@
-from collections.abc import Callable
-from collections.abc import Iterable
-from collections.abc import Iterator
-from collections.abc import Mapping
-from typing import Any
-from typing import Generic
-from typing import Literal
-from typing import NoReturn
-from typing import overload
-from typing import TypeVar
-
-from .mixins import ImmutableDictMixin
-from .mixins import ImmutableListMixin
-from .mixins import ImmutableMultiDictMixin
-from .mixins import UpdateDictMixin
-
-D = TypeVar("D")
-K = TypeVar("K")
-T = TypeVar("T")
-V = TypeVar("V")
-_CD = TypeVar("_CD", bound="CallbackDict[Any, Any]")
-
-def is_immutable(self: object) -> NoReturn: ...
-def iter_multi_items(
-    mapping: Mapping[K, V | Iterable[V]] | Iterable[tuple[K, V]],
-) -> Iterator[tuple[K, V]]: ...
-
-class ImmutableList(ImmutableListMixin[V]): ...
-
-class TypeConversionDict(dict[K, V]):
-    @overload
-    def get(self, key: K, default: None = ..., type: None = ...) -> V | None: ...
-    @overload
-    def get(self, key: K, default: D, type: None = ...) -> D | V: ...
-    @overload
-    def get(self, key: K, default: D, type: Callable[[V], T]) -> D | T: ...
-    @overload
-    def get(self, key: K, type: Callable[[V], T]) -> T | None: ...
-
-class ImmutableTypeConversionDict(ImmutableDictMixin[K, V], TypeConversionDict[K, V]):
-    def copy(self) -> TypeConversionDict[K, V]: ...
-    def __copy__(self) -> ImmutableTypeConversionDict[K, V]: ...
-
-class MultiDict(TypeConversionDict[K, V]):
-    def __init__(
-        self,
-        mapping: Mapping[K, Iterable[V] | V] | Iterable[tuple[K, V]] | None = None,
-    ) -> None: ...
-    def __getitem__(self, item: K) -> V: ...
-    def __setitem__(self, key: K, value: V) -> None: ...
-    def add(self, key: K, value: V) -> None: ...
-    @overload
-    def getlist(self, key: K) -> list[V]: ...
-    @overload
-    def getlist(self, key: K, type: Callable[[V], T] = ...) -> list[T]: ...
-    def setlist(self, key: K, new_list: Iterable[V]) -> None: ...
-    def setdefault(self, key: K, default: V | None = None) -> V: ...
-    def setlistdefault(
-        self, key: K, default_list: Iterable[V] | None = None
-    ) -> list[V]: ...
-    def items(self, multi: bool = False) -> Iterator[tuple[K, V]]: ...  # type: ignore
-    def lists(self) -> Iterator[tuple[K, list[V]]]: ...
-    def values(self) -> Iterator[V]: ...  # type: ignore
-    def listvalues(self) -> Iterator[list[V]]: ...
-    def copy(self) -> MultiDict[K, V]: ...
-    def deepcopy(self, memo: Any = None) -> MultiDict[K, V]: ...
-    @overload
-    def to_dict(self) -> dict[K, V]: ...
-    @overload
-    def to_dict(self, flat: Literal[False]) -> dict[K, list[V]]: ...
-    def update(  # type: ignore
-        self, mapping: Mapping[K, Iterable[V] | V] | Iterable[tuple[K, V]]
-    ) -> None: ...
-    @overload
-    def pop(self, key: K) -> V: ...
-    @overload
-    def pop(self, key: K, default: V | T = ...) -> V | T: ...
-    def popitem(self) -> tuple[K, V]: ...
-    def poplist(self, key: K) -> list[V]: ...
-    def popitemlist(self) -> tuple[K, list[V]]: ...
-    def __copy__(self) -> MultiDict[K, V]: ...
-    def __deepcopy__(self, memo: Any) -> MultiDict[K, V]: ...
-
-class _omd_bucket(Generic[K, V]):
-    prev: _omd_bucket[K, V] | None
-    next: _omd_bucket[K, V] | None
-    key: K
-    value: V
-    def __init__(self, omd: OrderedMultiDict[K, V], key: K, value: V) -> None: ...
-    def unlink(self, omd: OrderedMultiDict[K, V]) -> None: ...
-
-class OrderedMultiDict(MultiDict[K, V]):
-    _first_bucket: _omd_bucket[K, V] | None
-    _last_bucket: _omd_bucket[K, V] | None
-    def __init__(self, mapping: Mapping[K, V] | None = None) -> None: ...
-    def __eq__(self, other: object) -> bool: ...
-    def __getitem__(self, key: K) -> V: ...
-    def __setitem__(self, key: K, value: V) -> None: ...
-    def __delitem__(self, key: K) -> None: ...
-    def keys(self) -> Iterator[K]: ...  # type: ignore
-    def __iter__(self) -> Iterator[K]: ...
-    def values(self) -> Iterator[V]: ...  # type: ignore
-    def items(self, multi: bool = False) -> Iterator[tuple[K, V]]: ...  # type: ignore
-    def lists(self) -> Iterator[tuple[K, list[V]]]: ...
-    def listvalues(self) -> Iterator[list[V]]: ...
-    def add(self, key: K, value: V) -> None: ...
-    @overload
-    def getlist(self, key: K) -> list[V]: ...
-    @overload
-    def getlist(self, key: K, type: Callable[[V], T] = ...) -> list[T]: ...
-    def setlist(self, key: K, new_list: Iterable[V]) -> None: ...
-    def setlistdefault(
-        self, key: K, default_list: Iterable[V] | None = None
-    ) -> list[V]: ...
-    def update(  # type: ignore
-        self, mapping: Mapping[K, V] | Iterable[tuple[K, V]]
-    ) -> None: ...
-    def poplist(self, key: K) -> list[V]: ...
-    @overload
-    def pop(self, key: K) -> V: ...
-    @overload
-    def pop(self, key: K, default: V | T = ...) -> V | T: ...
-    def popitem(self) -> tuple[K, V]: ...
-    def popitemlist(self) -> tuple[K, list[V]]: ...
-
-class CombinedMultiDict(ImmutableMultiDictMixin[K, V], MultiDict[K, V]):  # type: ignore
-    dicts: list[MultiDict[K, V]]
-    def __init__(self, dicts: Iterable[MultiDict[K, V]] | None) -> None: ...
-    @classmethod
-    def fromkeys(cls, keys: Any, value: Any = None) -> NoReturn: ...
-    def __getitem__(self, key: K) -> V: ...
-    @overload  # type: ignore
-    def get(self, key: K) -> V | None: ...
-    @overload
-    def get(self, key: K, default: V | T = ...) -> V | T: ...
-    @overload
-    def get(
-        self, key: K, default: T | None = None, type: Callable[[V], T] = ...
-    ) -> T | None: ...
-    @overload
-    def getlist(self, key: K) -> list[V]: ...
-    @overload
-    def getlist(self, key: K, type: Callable[[V], T] = ...) -> list[T]: ...
-    def _keys_impl(self) -> set[K]: ...
-    def keys(self) -> set[K]: ...  # type: ignore
-    def __iter__(self) -> set[K]: ...  # type: ignore
-    def items(self, multi: bool = False) -> Iterator[tuple[K, V]]: ...  # type: ignore
-    def values(self) -> Iterator[V]: ...  # type: ignore
-    def lists(self) -> Iterator[tuple[K, list[V]]]: ...
-    def listvalues(self) -> Iterator[list[V]]: ...
-    def copy(self) -> MultiDict[K, V]: ...
-    @overload
-    def to_dict(self) -> dict[K, V]: ...
-    @overload
-    def to_dict(self, flat: Literal[False]) -> dict[K, list[V]]: ...
-    def __contains__(self, key: K) -> bool: ...  # type: ignore
-    def has_key(self, key: K) -> bool: ...
-
-class ImmutableDict(ImmutableDictMixin[K, V], dict[K, V]):
-    def copy(self) -> dict[K, V]: ...
-    def __copy__(self) -> ImmutableDict[K, V]: ...
-
-class ImmutableMultiDict(  # type: ignore
-    ImmutableMultiDictMixin[K, V], MultiDict[K, V]
-):
-    def copy(self) -> MultiDict[K, V]: ...
-    def __copy__(self) -> ImmutableMultiDict[K, V]: ...
-
-class ImmutableOrderedMultiDict(  # type: ignore
-    ImmutableMultiDictMixin[K, V], OrderedMultiDict[K, V]
-):
-    def _iter_hashitems(self) -> Iterator[tuple[int, tuple[K, V]]]: ...
-    def copy(self) -> OrderedMultiDict[K, V]: ...
-    def __copy__(self) -> ImmutableOrderedMultiDict[K, V]: ...
-
-class CallbackDict(UpdateDictMixin[K, V], dict[K, V]):
-    def __init__(
-        self,
-        initial: Mapping[K, V] | Iterable[tuple[K, V]] | None = None,
-        on_update: Callable[[_CD], None] | None = None,
-    ) -> None: ...
-
-class HeaderSet(set[str]):
-    _headers: list[str]
-    _set: set[str]
-    on_update: Callable[[HeaderSet], None] | None
-    def __init__(
-        self,
-        headers: Iterable[str] | None = None,
-        on_update: Callable[[HeaderSet], None] | None = None,
-    ) -> None: ...
-    def add(self, header: str) -> None: ...
-    def remove(self, header: str) -> None: ...
-    def update(self, iterable: Iterable[str]) -> None: ...  # type: ignore
-    def discard(self, header: str) -> None: ...
-    def find(self, header: str) -> int: ...
-    def index(self, header: str) -> int: ...
-    def clear(self) -> None: ...
-    def as_set(self, preserve_casing: bool = False) -> set[str]: ...
-    def to_header(self) -> str: ...
-    def __getitem__(self, idx: int) -> str: ...
-    def __delitem__(self, idx: int) -> None: ...
-    def __setitem__(self, idx: int, value: str) -> None: ...
-    def __contains__(self, header: str) -> bool: ...  # type: ignore
-    def __len__(self) -> int: ...
-    def __iter__(self) -> Iterator[str]: ...
diff --git a/src/werkzeug/exceptions.py b/src/werkzeug/exceptions.py
index 02af2c15d..ddb621032 100644
--- a/src/werkzeug/exceptions.py
+++ b/src/werkzeug/exceptions.py
@@ -197,7 +197,7 @@ class BadRequestKeyError(BadRequest, KeyError):
     #: useful in a debug mode.
     show_exception = False
 
-    def __init__(self, arg: str | None = None, *args: t.Any, **kwargs: t.Any):
+    def __init__(self, arg: object | None = None, *args: t.Any, **kwargs: t.Any):
         super().__init__(*args, **kwargs)
 
         if arg is None:
diff --git a/src/werkzeug/http.py b/src/werkzeug/http.py
index 56fc839f9..f1dbb850a 100644
--- a/src/werkzeug/http.py
+++ b/src/werkzeug/http.py
@@ -914,6 +914,10 @@ def quote_etag(etag: str, weak: bool = False) -> str:
     return etag
 
 
+@t.overload
+def unquote_etag(etag: str) -> tuple[str, bool]: ...
+@t.overload
+def unquote_etag(etag: None) -> tuple[None, None]: ...
 def unquote_etag(
     etag: str | None,
 ) -> tuple[str, bool] | tuple[None, None]:
diff --git a/src/werkzeug/sansio/http.py b/src/werkzeug/sansio/http.py
index b2b887799..f02d7fd54 100644
--- a/src/werkzeug/sansio/http.py
+++ b/src/werkzeug/sansio/http.py
@@ -72,7 +72,6 @@ def is_resource_modified(
 
     if etag:
         etag, _ = unquote_etag(etag)
-        etag = t.cast(str, etag)
 
         if if_range is not None and if_range.etag is not None:
             unmodified = parse_etags(if_range.etag).contains(etag)
diff --git a/src/werkzeug/test.py b/src/werkzeug/test.py
index 1dfb9320e..5c3c60883 100644
--- a/src/werkzeug/test.py
+++ b/src/werkzeug/test.py
@@ -656,7 +656,7 @@ def close(self) -> None:
         try:
             files = self.files.values()
         except AttributeError:
-            files = ()  # type: ignore
+            files = ()
         for f in files:
             try:
                 f.close()
@@ -1431,7 +1431,7 @@ def _to_request_header(self) -> str:
     def _from_response_header(cls, server_name: str, path: str, header: str) -> te.Self:
         header, _, parameters_str = header.partition(";")
         key, _, value = header.partition("=")
-        decoded_key, decoded_value = next(parse_cookie(header).items())
+        decoded_key, decoded_value = next(parse_cookie(header).items())  # type: ignore[call-overload]
         params = {}
 
         for item in parameters_str.split(";"):
diff --git a/src/werkzeug/utils.py b/src/werkzeug/utils.py
index b68ac18ca..59b97b732 100644
--- a/src/werkzeug/utils.py
+++ b/src/werkzeug/utils.py
@@ -497,7 +497,7 @@ def send_file(
     elif mtime is not None:
         rv.last_modified = mtime  # type: ignore
 
-    rv.cache_control.no_cache = True  # type: ignore[assignment]
+    rv.cache_control.no_cache = True
 
     # Flask will pass app.get_send_file_max_age, allowing its send_file
     # wrapper to not have to deal with paths.

From 3720e3e84d7de619356e0b5fddb8b342d81d975d Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Sun, 27 Oct 2024 18:39:40 -0700
Subject: [PATCH 2/5] deprecate OrderedMultiDict

---
 CHANGES.rst                               |  2 +
 docs/datastructures.rst                   | 29 ++++++++++--
 src/werkzeug/datastructures/__init__.py   | 34 +++++++++++++-
 src/werkzeug/datastructures/structures.py | 56 +++++++++++++++++++----
 src/werkzeug/sansio/request.py            |  6 +--
 tests/test_datastructures.py              |  8 +++-
 tests/test_wrappers.py                    |  7 +--
 7 files changed, 120 insertions(+), 22 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 2976f889a..c73bcaa89 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -10,6 +10,8 @@ Unreleased
 -   ``Request.max_form_memory_size`` defaults to 500kB instead of unlimited.
     Non-file form fields over this size will cause a ``RequestEntityTooLarge``
     error. :issue:`2964`
+-   ``OrderedMultiDict`` and ``ImmutableOrderedMultiDict`` are deprecated.
+    Use ``MultiDict`` and ``ImmutableMultiDict`` instead. :issue:`2968`
 -  Support Cookie CHIPS (Partitioned Cookies). :issue:`2797`
 -   ``CacheControl.no_transform`` is a boolean when present. ``min_fresh`` is
     ``None`` when not present. Added the ``must_understand`` attribute. Fixed
diff --git a/docs/datastructures.rst b/docs/datastructures.rst
index 92c969932..bd2c0d223 100644
--- a/docs/datastructures.rst
+++ b/docs/datastructures.rst
@@ -27,10 +27,33 @@ General Purpose
    :members:
    :inherited-members:
 
-.. autoclass:: OrderedMultiDict
+.. class:: OrderedMultiDict
 
-.. autoclass:: ImmutableMultiDict
-   :members: copy
+    Works like a regular :class:`MultiDict` but preserves the
+    order of the fields.  To convert the ordered multi dict into a
+    list you can use the :meth:`items` method and pass it ``multi=True``.
+
+    In general an :class:`OrderedMultiDict` is an order of magnitude
+    slower than a :class:`MultiDict`.
+
+    .. admonition:: note
+
+       Due to a limitation in Python you cannot convert an ordered
+       multi dict into a regular dict by using ``dict(multidict)``.
+       Instead you have to use the :meth:`to_dict` method, otherwise
+       the internal bucket objects are exposed.
+
+    .. deprecated:: 3.1
+        Will be removed in Werkzeug 3.2. Use ``MultiDict`` instead.
+
+.. class:: ImmutableMultiDict
+
+    An immutable :class:`OrderedMultiDict`.
+
+    .. deprecated:: 3.1
+        Will be removed in Werkzeug 3.2. Use ``ImmutableMultiDict`` instead.
+
+    .. versionadded:: 0.6
 
 .. autoclass:: ImmutableOrderedMultiDict
    :members: copy
diff --git a/src/werkzeug/datastructures/__init__.py b/src/werkzeug/datastructures/__init__.py
index 846ffce67..6582de02c 100644
--- a/src/werkzeug/datastructures/__init__.py
+++ b/src/werkzeug/datastructures/__init__.py
@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+import typing as t
+
 from .accept import Accept as Accept
 from .accept import CharsetAccept as CharsetAccept
 from .accept import LanguageAccept as LanguageAccept
@@ -26,9 +30,35 @@
 from .structures import ImmutableDict as ImmutableDict
 from .structures import ImmutableList as ImmutableList
 from .structures import ImmutableMultiDict as ImmutableMultiDict
-from .structures import ImmutableOrderedMultiDict as ImmutableOrderedMultiDict
 from .structures import ImmutableTypeConversionDict as ImmutableTypeConversionDict
 from .structures import iter_multi_items as iter_multi_items
 from .structures import MultiDict as MultiDict
-from .structures import OrderedMultiDict as OrderedMultiDict
 from .structures import TypeConversionDict as TypeConversionDict
+
+
+def __getattr__(name: str) -> t.Any:
+    import warnings
+
+    if name == "OrderedMultiDict":
+        from .structures import _OrderedMultiDict
+
+        warnings.warn(
+            "'OrderedMultiDict' is deprecated and will be removed in Werkzeug"
+            " 3.2. Use 'MultiDict' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _OrderedMultiDict
+
+    if name == "ImmutableOrderedMultiDict":
+        from .structures import _ImmutableOrderedMultiDict
+
+        warnings.warn(
+            "'OrderedMultiDict' is deprecated and will be removed in Werkzeug"
+            " 3.2. Use 'ImmutableMultiDict' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _ImmutableOrderedMultiDict
+
+    raise AttributeError(name)
diff --git a/src/werkzeug/datastructures/structures.py b/src/werkzeug/datastructures/structures.py
index eb54599d5..34863ccc3 100644
--- a/src/werkzeug/datastructures/structures.py
+++ b/src/werkzeug/datastructures/structures.py
@@ -522,7 +522,7 @@ class _omd_bucket(t.Generic[K, V]):
 
     __slots__ = ("prev", "key", "value", "next")
 
-    def __init__(self, omd: OrderedMultiDict[K, V], key: K, value: V) -> None:
+    def __init__(self, omd: _OrderedMultiDict[K, V], key: K, value: V) -> None:
         self.prev: _omd_bucket[K, V] | None = omd._last_bucket
         self.key: K = key
         self.value: V = value
@@ -534,7 +534,7 @@ def __init__(self, omd: OrderedMultiDict[K, V], key: K, value: V) -> None:
             omd._last_bucket.next = self
         omd._last_bucket = self
 
-    def unlink(self, omd: OrderedMultiDict[K, V]) -> None:
+    def unlink(self, omd: _OrderedMultiDict[K, V]) -> None:
         if self.prev:
             self.prev.next = self.next
         if self.next:
@@ -545,7 +545,7 @@ def unlink(self, omd: OrderedMultiDict[K, V]) -> None:
             omd._last_bucket = self.prev
 
 
-class OrderedMultiDict(MultiDict[K, V]):
+class _OrderedMultiDict(MultiDict[K, V]):
     """Works like a regular :class:`MultiDict` but preserves the
     order of the fields.  To convert the ordered multi dict into a
     list you can use the :meth:`items` method and pass it ``multi=True``.
@@ -559,6 +559,9 @@ class OrderedMultiDict(MultiDict[K, V]):
        multi dict into a regular dict by using ``dict(multidict)``.
        Instead you have to use the :meth:`to_dict` method, otherwise
        the internal bucket objects are exposed.
+
+    .. deprecated:: 3.1
+        Will be removed in Werkzeug 3.2. Use ``MultiDict`` instead.
     """
 
     def __init__(
@@ -570,6 +573,14 @@ def __init__(
             | None
         ) = None,
     ) -> None:
+        import warnings
+
+        warnings.warn(
+            "'OrderedMultiDict' is deprecated and will be removed in Werkzeug"
+            " 3.2. Use 'MultiDict' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__()
         self._first_bucket: _omd_bucket[K, V] | None = None
         self._last_bucket: _omd_bucket[K, V] | None = None
@@ -579,7 +590,7 @@ def __init__(
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, MultiDict):
             return NotImplemented
-        if isinstance(other, OrderedMultiDict):
+        if isinstance(other, _OrderedMultiDict):
             iter1 = iter(self.items(multi=True))
             iter2 = iter(other.items(multi=True))
             try:
@@ -944,9 +955,14 @@ def __copy__(self) -> te.Self:
         return self
 
 
-class ImmutableOrderedMultiDict(ImmutableMultiDictMixin[K, V], OrderedMultiDict[K, V]):  # type: ignore[misc]
+class _ImmutableOrderedMultiDict(  # type: ignore[misc]
+    ImmutableMultiDictMixin[K, V], _OrderedMultiDict[K, V]
+):
     """An immutable :class:`OrderedMultiDict`.
 
+    .. deprecated:: 3.1
+        Will be removed in Werkzeug 3.2. Use ``ImmutableMultiDict`` instead.
+
     .. versionadded:: 0.6
     """
 
@@ -963,17 +979,17 @@ def __init__(
 
         if mapping is not None:
             for k, v in iter_multi_items(mapping):
-                OrderedMultiDict.add(self, k, v)
+                _OrderedMultiDict.add(self, k, v)
 
     def _iter_hashitems(self) -> cabc.Iterable[t.Any]:
         return enumerate(self.items(multi=True))
 
-    def copy(self) -> OrderedMultiDict[K, V]:  # type: ignore[override]
+    def copy(self) -> _OrderedMultiDict[K, V]:  # type: ignore[override]
         """Return a shallow mutable copy of this object.  Keep in mind that
         the standard library's :func:`copy` function is a no-op for this class
         like for any other python immutable type (eg: :class:`tuple`).
         """
-        return OrderedMultiDict(self)
+        return _OrderedMultiDict(self)
 
     def __copy__(self) -> te.Self:
         return self
@@ -1157,3 +1173,27 @@ def __repr__(self) -> str:
 
 # circular dependencies
 from .. import http
+
+
+def __getattr__(name: str) -> t.Any:
+    import warnings
+
+    if name == "OrderedMultiDict":
+        warnings.warn(
+            "'OrderedMultiDict' is deprecated and will be removed in Werkzeug"
+            " 3.2. Use 'MultiDict' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _OrderedMultiDict
+
+    if name == "ImmutableOrderedMultiDict":
+        warnings.warn(
+            "'ImmutableOrderedMultiDict' is deprecated and will be removed in"
+            " Werkzeug 3.2. Use 'ImmutableMultiDict' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _ImmutableOrderedMultiDict
+
+    raise AttributeError(name)
diff --git a/src/werkzeug/sansio/request.py b/src/werkzeug/sansio/request.py
index dd0805d71..8d5fbd8f8 100644
--- a/src/werkzeug/sansio/request.py
+++ b/src/werkzeug/sansio/request.py
@@ -67,10 +67,8 @@ class Request:
 
     #: the class to use for `args` and `form`.  The default is an
     #: :class:`~werkzeug.datastructures.ImmutableMultiDict` which supports
-    #: multiple values per key.  alternatively it makes sense to use an
-    #: :class:`~werkzeug.datastructures.ImmutableOrderedMultiDict` which
-    #: preserves order or a :class:`~werkzeug.datastructures.ImmutableDict`
-    #: which is the fastest but only remembers the last key.  It is also
+    #: multiple values per key. A :class:`~werkzeug.datastructures.ImmutableDict`
+    #: is faster but only remembers the last key. It is also
     #: possible to use mutable structures, but this is not recommended.
     #:
     #: .. versionadded:: 0.6
diff --git a/tests/test_datastructures.py b/tests/test_datastructures.py
index 76de1d849..9d11d2aab 100644
--- a/tests/test_datastructures.py
+++ b/tests/test_datastructures.py
@@ -9,6 +9,8 @@
 
 from werkzeug import datastructures as ds
 from werkzeug import http
+from werkzeug.datastructures.structures import _ImmutableOrderedMultiDict
+from werkzeug.datastructures.structures import _OrderedMultiDict
 from werkzeug.exceptions import BadRequestKeyError
 
 
@@ -333,8 +335,9 @@ class TestImmutableDict(_ImmutableDictTests):
     storage_class = ds.ImmutableDict
 
 
+@pytest.mark.filterwarnings("ignore:'OrderedMultiDict':DeprecationWarning")
 class TestImmutableOrderedMultiDict(_ImmutableDictTests):
-    storage_class = ds.ImmutableOrderedMultiDict
+    storage_class = _ImmutableOrderedMultiDict
 
     def test_ordered_multidict_is_hashable(self):
         a = self.storage_class([("a", 1), ("b", 1), ("a", 2)])
@@ -412,8 +415,9 @@ def test_getitem_raise_badrequestkeyerror_for_empty_list_value(self):
             md["empty"]
 
 
+@pytest.mark.filterwarnings("ignore:'OrderedMultiDict':DeprecationWarning")
 class TestOrderedMultiDict(_MutableMultiDictTests):
-    storage_class = ds.OrderedMultiDict
+    storage_class = _OrderedMultiDict
 
     def test_ordered_interface(self):
         cls = self.storage_class
diff --git a/tests/test_wrappers.py b/tests/test_wrappers.py
index f75694459..8bc063c74 100644
--- a/tests/test_wrappers.py
+++ b/tests/test_wrappers.py
@@ -16,11 +16,11 @@
 from werkzeug.datastructures import Headers
 from werkzeug.datastructures import ImmutableList
 from werkzeug.datastructures import ImmutableMultiDict
-from werkzeug.datastructures import ImmutableOrderedMultiDict
 from werkzeug.datastructures import LanguageAccept
 from werkzeug.datastructures import MIMEAccept
 from werkzeug.datastructures import MultiDict
 from werkzeug.datastructures import WWWAuthenticate
+from werkzeug.datastructures.structures import _ImmutableOrderedMultiDict
 from werkzeug.exceptions import BadRequest
 from werkzeug.exceptions import RequestedRangeNotSatisfiable
 from werkzeug.exceptions import SecurityError
@@ -998,9 +998,10 @@ def generate_items():
         assert resp.response == ["foo", "bar", "baz"]
 
 
+@pytest.mark.filterwarnings("ignore:'OrderedMultiDict':DeprecationWarning")
 def test_form_data_ordering():
     class MyRequest(wrappers.Request):
-        parameter_storage_class = ImmutableOrderedMultiDict
+        parameter_storage_class = _ImmutableOrderedMultiDict
 
     req = MyRequest.from_values("/?foo=1&bar=0&foo=3")
     assert list(req.args) == ["foo", "bar"]
@@ -1009,7 +1010,7 @@ class MyRequest(wrappers.Request):
         ("bar", "0"),
         ("foo", "3"),
     ]
-    assert isinstance(req.args, ImmutableOrderedMultiDict)
+    assert isinstance(req.args, _ImmutableOrderedMultiDict)
     assert isinstance(req.values, CombinedMultiDict)
     assert req.values["foo"] == "1"
     assert req.values.getlist("foo") == ["1", "3"]

From e9f87fdcdacb84c0647742b3c156b896982ee5b2 Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 29 Oct 2024 17:04:30 -0700
Subject: [PATCH 3/5] fix formatting

---
 CHANGES.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index c73bcaa89..7dc7f0bd9 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -12,14 +12,15 @@ Unreleased
     error. :issue:`2964`
 -   ``OrderedMultiDict`` and ``ImmutableOrderedMultiDict`` are deprecated.
     Use ``MultiDict`` and ``ImmutableMultiDict`` instead. :issue:`2968`
--  Support Cookie CHIPS (Partitioned Cookies). :issue:`2797`
+-   Support Cookie CHIPS (Partitioned Cookies). :issue:`2797`
 -   ``CacheControl.no_transform`` is a boolean when present. ``min_fresh`` is
     ``None`` when not present. Added the ``must_understand`` attribute. Fixed
     some typing issues on cache control. :issue:`2881`
 -   Add ``stale_while_revalidate`` and ``stale_if_error`` properties to
     ``ResponseCacheControl``. :issue:`2948`
 -   Add 421 ``MisdirectedRequest`` HTTP exception. :issue:`2850`
--   Increase default work factor for PBKDF2 to 1,000,000 iterations. :issue:`2969`
+-   Increase default work factor for PBKDF2 to 1,000,000 iterations.
+    :issue:`2969`
 -   Inline annotations for ``datastructures``, removing stub files.
     :issue:`2970`
 

From e550ef8b313324d2efc0b9385be4c8c5739df36b Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 29 Oct 2024 17:42:31 -0700
Subject: [PATCH 4/5] getlist catches TypeError

---
 CHANGES.rst                               |  3 ++-
 src/werkzeug/datastructures/structures.py | 14 ++++++++------
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 7dc7f0bd9..c76cce4c5 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -23,7 +23,8 @@ Unreleased
     :issue:`2969`
 -   Inline annotations for ``datastructures``, removing stub files.
     :issue:`2970`
-
+-   ``MultiDict.getlist`` catches ``TypeError`` in addition to ``ValueError``
+    when doing type conversion. :issue:`2976`
 
 
 Version 3.0.6
diff --git a/src/werkzeug/datastructures/structures.py b/src/werkzeug/datastructures/structures.py
index 34863ccc3..a48d504e4 100644
--- a/src/werkzeug/datastructures/structures.py
+++ b/src/werkzeug/datastructures/structures.py
@@ -260,10 +260,12 @@ def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
         with the callable defined there.
 
         :param key: The key to be looked up.
-        :param type: A callable that is used to cast the value in the
-                     :class:`MultiDict`.  If a :exc:`ValueError` is raised
-                     by this callable the value will be removed from the list.
+        :param type: Callable to convert each value. If a ``ValueError`` or
+            ``TypeError`` is raised, the value is omitted.
         :return: a :class:`list` of all the values for the key.
+
+        .. versionchanged:: 3.1
+            Catches ``TypeError`` in addition to ``ValueError``.
         """
         try:
             rv: list[V] = super().__getitem__(key)  # type: ignore[assignment]
@@ -275,7 +277,7 @@ def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
         for item in rv:
             try:
                 result.append(type(item))  # type: ignore[call-arg]
-            except ValueError:
+            except (ValueError, TypeError):
                 pass
         return result
 
@@ -694,7 +696,7 @@ def getlist(self, key: K, type: type[T] | None = None) -> list[V] | list[T]:
         for item in rv:
             try:
                 result.append(type(item.value))  # type: ignore[call-arg]
-            except ValueError:
+            except (ValueError, TypeError):
                 pass
         return result
 
@@ -836,7 +838,7 @@ def get(  # type: ignore[misc]
                 if type is not None:
                     try:
                         return type(d[key])  # type: ignore[call-arg]
-                    except ValueError:
+                    except (ValueError, TypeError):
                         continue
                 return d[key]
         return default

From b65b587aa12ec40df1eecb4c6aadaf8de8931187 Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 29 Oct 2024 19:20:33 -0700
Subject: [PATCH 5/5] implement or and ior operators

---
 CHANGES.rst                               |  2 +
 src/werkzeug/datastructures/headers.py    | 31 +++++++++++++++
 src/werkzeug/datastructures/mixins.py     | 21 ++++++++++
 src/werkzeug/datastructures/structures.py | 25 ++++++++++++
 tests/test_datastructures.py              | 48 ++++++++++++++++++++++-
 5 files changed, 126 insertions(+), 1 deletion(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index c76cce4c5..0a0616d57 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -25,6 +25,8 @@ Unreleased
     :issue:`2970`
 -   ``MultiDict.getlist`` catches ``TypeError`` in addition to ``ValueError``
     when doing type conversion. :issue:`2976`
+-   Implement ``|`` and ``|=`` operators for ``MultiDict``, ``Headers``, and
+    ``CallbackDict``, and disallow ``|=`` on immutable types. :issue:`2977`
 
 
 Version 3.0.6
diff --git a/src/werkzeug/datastructures/headers.py b/src/werkzeug/datastructures/headers.py
index a23a0e0b1..db53cda7b 100644
--- a/src/werkzeug/datastructures/headers.py
+++ b/src/werkzeug/datastructures/headers.py
@@ -41,6 +41,9 @@ class Headers(cabc.MutableMapping[str, str]):
 
     :param defaults: The list of default values for the :class:`Headers`.
 
+    .. versionchanged:: 3.1
+        Implement ``|`` and ``|=`` operators.
+
     .. versionchanged:: 2.1.0
         Default values are validated the same as values added later.
 
@@ -524,6 +527,31 @@ def update(  # type: ignore[override]
             else:
                 self.set(key, value)
 
+    def __or__(
+        self, other: cabc.Mapping[str, t.Any | cabc.Collection[t.Any]]
+    ) -> te.Self:
+        if not isinstance(other, cabc.Mapping):
+            return NotImplemented
+
+        rv = self.copy()
+        rv.update(other)
+        return rv
+
+    def __ior__(
+        self,
+        other: (
+            cabc.Mapping[str, t.Any | cabc.Collection[t.Any]]
+            | cabc.Iterable[tuple[str, t.Any]]
+        ),
+    ) -> te.Self:
+        if not isinstance(other, (cabc.Mapping, cabc.Iterable)) or isinstance(
+            other, str
+        ):
+            return NotImplemented
+
+        self.update(other)
+        return self
+
     def to_wsgi_list(self) -> list[tuple[str, str]]:
         """Convert the headers into a list suitable for WSGI.
 
@@ -620,6 +648,9 @@ def __iter__(self) -> cabc.Iterator[tuple[str, str]]:  # type: ignore[override]
     def copy(self) -> t.NoReturn:
         raise TypeError(f"cannot create {type(self).__name__!r} copies")
 
+    def __or__(self, other: t.Any) -> t.NoReturn:
+        raise TypeError(f"cannot create {type(self).__name__!r} copies")
+
 
 # circular dependencies
 from .. import http
diff --git a/src/werkzeug/datastructures/mixins.py b/src/werkzeug/datastructures/mixins.py
index 76324d5a2..03d461ad8 100644
--- a/src/werkzeug/datastructures/mixins.py
+++ b/src/werkzeug/datastructures/mixins.py
@@ -76,6 +76,9 @@ def sort(self, key: t.Any = None, reverse: t.Any = False) -> t.NoReturn:
 class ImmutableDictMixin(t.Generic[K, V]):
     """Makes a :class:`dict` immutable.
 
+    .. versionchanged:: 3.1
+        Disallow ``|=`` operator.
+
     .. versionadded:: 0.5
 
     :private:
@@ -117,6 +120,9 @@ def setdefault(self, key: t.Any, default: t.Any = None) -> t.NoReturn:
     def update(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
         _immutable_error(self)
 
+    def __ior__(self, other: t.Any) -> t.NoReturn:
+        _immutable_error(self)
+
     def pop(self, key: t.Any, default: t.Any = None) -> t.NoReturn:
         _immutable_error(self)
 
@@ -168,6 +174,9 @@ class ImmutableHeadersMixin:
     hashable though since the only usecase for this datastructure
     in Werkzeug is a view on a mutable structure.
 
+    .. versionchanged:: 3.1
+        Disallow ``|=`` operator.
+
     .. versionadded:: 0.5
 
     :private:
@@ -200,6 +209,9 @@ def extend(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
     def update(self, arg: t.Any, /, **kwargs: t.Any) -> t.NoReturn:
         _immutable_error(self)
 
+    def __ior__(self, other: t.Any) -> t.NoReturn:
+        _immutable_error(self)
+
     def insert(self, pos: t.Any, value: t.Any) -> t.NoReturn:
         _immutable_error(self)
 
@@ -233,6 +245,9 @@ def wrapper(
 class UpdateDictMixin(dict[K, V]):
     """Makes dicts call `self.on_update` on modifications.
 
+    .. versionchanged:: 3.1
+        Implement ``|=`` operator.
+
     .. versionadded:: 0.5
 
     :private:
@@ -294,3 +309,9 @@ def update(  # type: ignore[override]
             super().update(**kwargs)
         else:
             super().update(arg, **kwargs)
+
+    @_always_update
+    def __ior__(  # type: ignore[override]
+        self, other: cabc.Mapping[K, V] | cabc.Iterable[tuple[K, V]]
+    ) -> te.Self:
+        return super().__ior__(other)
diff --git a/src/werkzeug/datastructures/structures.py b/src/werkzeug/datastructures/structures.py
index a48d504e4..db2f99800 100644
--- a/src/werkzeug/datastructures/structures.py
+++ b/src/werkzeug/datastructures/structures.py
@@ -170,6 +170,9 @@ class MultiDict(TypeConversionDict[K, V]):
     :param mapping: the initial value for the :class:`MultiDict`.  Either a
                     regular dict, an iterable of ``(key, value)`` tuples
                     or `None`.
+
+    .. versionchanged:: 3.1
+        Implement ``|`` and ``|=`` operators.
     """
 
     def __init__(
@@ -435,6 +438,28 @@ def update(  # type: ignore[override]
         for key, value in iter_multi_items(mapping):
             self.add(key, value)
 
+    def __or__(  # type: ignore[override]
+        self, other: cabc.Mapping[K, V | cabc.Collection[V]]
+    ) -> MultiDict[K, V]:
+        if not isinstance(other, cabc.Mapping):
+            return NotImplemented
+
+        rv = self.copy()
+        rv.update(other)
+        return rv
+
+    def __ior__(  # type: ignore[override]
+        self,
+        other: cabc.Mapping[K, V | cabc.Collection[V]] | cabc.Iterable[tuple[K, V]],
+    ) -> te.Self:
+        if not isinstance(other, (cabc.Mapping, cabc.Iterable)) or isinstance(
+            other, str
+        ):
+            return NotImplemented
+
+        self.update(other)
+        return self
+
     @t.overload
     def pop(self, key: K) -> V: ...
     @t.overload
diff --git a/tests/test_datastructures.py b/tests/test_datastructures.py
index 9d11d2aab..76a5530fc 100644
--- a/tests/test_datastructures.py
+++ b/tests/test_datastructures.py
@@ -258,6 +258,17 @@ def test_basic_interface(self):
         md.setlist("foo", [1, 2])
         assert md.getlist("foo") == [1, 2]
 
+    def test_or(self) -> None:
+        a = self.storage_class({"x": 1})
+        b = a | {"y": 2}
+        assert isinstance(b, self.storage_class)
+        assert "x" in b and "y" in b
+
+    def test_ior(self) -> None:
+        a = self.storage_class({"x": 1})
+        a |= {"y": 2}
+        assert "x" in a and "y" in a
+
 
 class _ImmutableDictTests:
     storage_class: type[dict]
@@ -305,6 +316,17 @@ def test_dict_is_hashable(self):
         assert immutable in x
         assert immutable2 in x
 
+    def test_or(self) -> None:
+        a = self.storage_class({"x": 1})
+        b = a | {"y": 2}
+        assert "x" in b and "y" in b
+
+    def test_ior(self) -> None:
+        a = self.storage_class({"x": 1})
+
+        with pytest.raises(TypeError):
+            a |= {"y": 2}
+
 
 class TestImmutableTypeConversionDict(_ImmutableDictTests):
     storage_class = ds.ImmutableTypeConversionDict
@@ -799,6 +821,17 @@ def test_equality(self):
 
         assert h1 == h2
 
+    def test_or(self) -> None:
+        a = ds.Headers({"x": 1})
+        b = a | {"y": 2}
+        assert isinstance(b, ds.Headers)
+        assert "x" in b and "y" in b
+
+    def test_ior(self) -> None:
+        a = ds.Headers({"x": 1})
+        a |= {"y": 2}
+        assert "x" in a and "y" in a
+
 
 class TestEnvironHeaders:
     storage_class = ds.EnvironHeaders
@@ -840,6 +873,18 @@ def test_return_type_is_str(self):
         assert headers["Foo"] == "\xe2\x9c\x93"
         assert next(iter(headers)) == ("Foo", "\xe2\x9c\x93")
 
+    def test_or(self) -> None:
+        headers = ds.EnvironHeaders({"x": "1"})
+
+        with pytest.raises(TypeError):
+            headers | {"y": "2"}
+
+    def test_ior(self) -> None:
+        headers = ds.EnvironHeaders({})
+
+        with pytest.raises(TypeError):
+            headers |= {"y": "2"}
+
 
 class TestHeaderSet:
     storage_class = ds.HeaderSet
@@ -927,7 +972,7 @@ def test_callback_dict_writes(self):
         assert_calls, func = make_call_asserter()
         initial = {"a": "foo", "b": "bar"}
         dct = self.storage_class(initial=initial, on_update=func)
-        with assert_calls(8, "callback not triggered by write method"):
+        with assert_calls(9, "callback not triggered by write method"):
             # always-write methods
             dct["z"] = 123
             dct["z"] = 123  # must trigger again
@@ -937,6 +982,7 @@ def test_callback_dict_writes(self):
             dct.popitem()
             dct.update([])
             dct.clear()
+            dct |= {}
         with assert_calls(0, "callback triggered by failed del"):
             pytest.raises(KeyError, lambda: dct.__delitem__("x"))
         with assert_calls(0, "callback triggered by failed pop"):