Add support for RFC5861 Cache-Control headers

CHANGES.rst

@@ -9,6 +9,8 @@ Unreleased
 -   ``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`
 
 

docs/datastructures.rst

@@ -69,26 +69,12 @@ HTTP Related
 .. autoclass:: LanguageAccept
 
 .. autoclass:: RequestCacheControl
-   :members:
-
-   .. autoattribute:: no_cache
-
-   .. autoattribute:: no_store
-
-   .. autoattribute:: max_age
-
-   .. autoattribute:: no_transform
+    :members:
+    :inherited-members:
 
 .. autoclass:: ResponseCacheControl
-   :members:
-
-   .. autoattribute:: no_cache
-
-   .. autoattribute:: no_store
-
-   .. autoattribute:: max_age
-
-   .. autoattribute:: no_transform
+    :members:
+    :inherited-members:
 
 .. autoclass:: ETags
    :members:

src/werkzeug/datastructures/cache_control.py

@@ -165,7 +165,8 @@ class ResponseCacheControl(_CacheControl):
        ``no_transform`` is a boolean when present.
 
     .. versionchanged:: 3.1
-        Added the ``must_understand`` attribute.
+        Added the ``must_understand``, ``stale_while_revalidate``, and
+        ``stale_if_error`` attributes.
 
     .. versionchanged:: 2.1.1
         ``s_maxage`` converts the value to an int.
@@ -186,6 +187,8 @@ class ResponseCacheControl(_CacheControl):
     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)
 
 
 # circular dependencies

src/werkzeug/datastructures/cache_control.pyi

@@ -116,3 +116,15 @@ class ResponseCacheControl(_CacheControl):
     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: ...

tests/test_datastructures.py

@@ -973,6 +973,18 @@ def test_must_understand(self):
         cc = ds.ResponseCacheControl()
         assert cc.must_understand is False
 
+    def test_stale_while_revalidate(self):
+        cc = ds.ResponseCacheControl([("stale-while-revalidate", "1")])
+        assert cc.stale_while_revalidate == 1
+        cc = ds.ResponseCacheControl()
+        assert cc.stale_while_revalidate is None
+
+    def test_stale_if_error(self):
+        cc = ds.ResponseCacheControl([("stale-if-error", "1")])
+        assert cc.stale_if_error == 1
+        cc = ds.ResponseCacheControl()
+        assert cc.stale_while_revalidate is None
+
 
 class TestContentSecurityPolicy:
     def test_construct(self):