Merge branch 'master' into modernize_setup.py

# Conflicts:
#	setup.py

docs/_newsfragments/2213.newandimproved.rst

@@ -0,0 +1,6 @@
+Added kwarg ``partitioned`` to :py:meth:`~falcon.Response.set_cookie`
+to opt a cookie into partitioned storage, with a separate cookie jar per
+top-level site.
+See also
+`CHIPS <https://developer.mozilla.org/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies>`__
+for a more detailed description of this experimental web technology.

docs/api/cookies.rst

@@ -168,3 +168,26 @@ default, although this may change in a future release.
 When unsetting a cookie, :py:meth:`~falcon.Response.unset_cookie`,
 the default `SameSite` setting of the unset cookie is ``'Lax'``, but can be changed
 by setting the 'samesite' kwarg.
+
+The Partitioned Attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting from Q1 2024, Google Chrome will start to
+`phase out support for third-party cookies
+<https://developers.google.com/privacy-sandbox/3pcd/prepare/prepare-for-phaseout>`__.
+If your site is relying on cross-site cookies, it might be necessary to set the
+``Partitioned`` attribute. ``Partitioned`` usually requires the
+:ref:`Secure <cookie-secure-attribute>` attribute to be set. While this is not
+enforced by Falcon, the framework does set ``Secure`` by default, unless
+specified otherwise
+(see also :attr:`~falcon.ResponseOptions.secure_cookies_by_default`).
+
+Currently, :py:meth:`~falcon.Response.set_cookie` does not set ``Partitioned``
+automatically depending on other attributes (like ``SameSite``),
+although this may change in a future release.
+
+.. note::
+    Similar to ``SameSite`` on older Python versions, the standard
+    :mod:`http.cookies` module does not support the ``Partitioned`` attribute
+    yet, and Falcon performs the same monkey-patching as it did for
+    ``SameSite``.

docs/user/tutorial-asgi.rst

@@ -175,9 +175,10 @@ We can now implement a basic async image store. Save the following code as
     import io
 
     import aiofiles
-    import falcon
     import PIL.Image
 
+    import falcon
+
 
     class Image:
         def __init__(self, config, image_id, size):
@@ -266,6 +267,7 @@ of images. Place the code below in a file named ``images.py``:
 .. code:: python
 
     import aiofiles
+
     import falcon
 
 
@@ -670,8 +672,6 @@ The new ``thumbnails`` end-point should now render thumbnails on the fly::
 Again, we could also verify thumbnail URIs in the browser or image viewer that
 supports HTTP input.
 
-
-
 .. _asgi_tutorial_caching:
 
 Caching Responses
@@ -979,9 +979,11 @@ your ASGI Falcon application:
 
 .. code:: python
 
-    import falcon
     import logging
 
+    import falcon
+
+
     logging.basicConfig(level=logging.INFO)
 
     class ErrorResource:

docs/user/tutorial.rst

@@ -383,10 +383,9 @@ Then, update the responder to use the new media type:
 
 .. code:: python
 
-    import falcon
-
     import msgpack
 
+    import falcon
 
     class Resource:
 
@@ -467,11 +466,12 @@ Next, edit ``test_app.py`` to look like this:
 
 .. code:: python
 
-    import falcon
-    from falcon import testing
     import msgpack
     import pytest
 
+    import falcon
+    from falcon import testing
+
     from look.app import app
 
 
@@ -601,9 +601,10 @@ POSTs. Open ``images.py`` and add a POST responder to the
     import uuid
     import mimetypes
 
-    import falcon
     import msgpack
 
+    import falcon
+
 
     class Resource:
 
@@ -723,9 +724,10 @@ operation:
     import os
     import uuid
 
-    import falcon
     import msgpack
 
+    import falcon
+
 
     class Resource:
 
@@ -789,7 +791,8 @@ Hmm, it looks like we forgot to update ``app.py``. Let's do that now:
 
     import falcon
 
-    from .images import ImageStore, Resource
+    from .images import ImageStore
+    from .images import Resource
 
 
     app = application = falcon.App()
@@ -813,7 +816,8 @@ similar to the following:
 
     import falcon
 
-    from .images import ImageStore, Resource
+    from .images import ImageStore
+    from .images import Resource
 
 
     def create_app(image_store):
@@ -849,11 +853,12 @@ look similar to this:
 
     from unittest.mock import call, MagicMock, mock_open
 
-    import falcon
-    from falcon import testing
     import msgpack
     import pytest
 
+    import falcon
+    from falcon import testing
+
     import look.app
     import look.images
 
@@ -1041,7 +1046,8 @@ the image storage directory with an environment variable:
 
     import falcon
 
-    from .images import ImageStore, Resource
+    from .images import ImageStore
+    from .images import Resource
 
 
     def create_app(image_store):
@@ -1123,9 +1129,10 @@ Go ahead and edit your ``images.py`` file to look something like this:
     import uuid
     import mimetypes
 
-    import falcon
     import msgpack
 
+    import falcon
+
 
     class Collection:
 
@@ -1234,7 +1241,9 @@ similar to the following:
 
     import falcon
 
-    from .images import Collection, ImageStore, Item
+    from .images import Collection
+    from .images import ImageStore
+    from .images import Item
 
 
     def create_app(image_store):

e2e-tests/conftest.py

@@ -21,7 +21,6 @@
 
 import falcon.testing
 
-
 HERE = pathlib.Path(__file__).resolve().parent
 INDEX = '/static/index.html'
 

e2e-tests/server/app.py

@@ -2,8 +2,10 @@
 
 import falcon
 import falcon.asgi
+
 from .chat import Chat
-from .hub import Events, Hub
+from .hub import Events
+from .hub import Hub
 from .ping import Pong
 
 HERE = pathlib.Path(__file__).resolve().parent

e2e-tests/server/chat.py

@@ -1,6 +1,7 @@
 import re
 
-from falcon.asgi import Request, WebSocket
+from falcon.asgi import Request
+from falcon.asgi import WebSocket
 
 from .hub import Hub
 

e2e-tests/server/hub.py

@@ -2,7 +2,10 @@
 import typing
 import uuid
 
-from falcon.asgi import Request, Response, SSEvent, WebSocket
+from falcon.asgi import Request
+from falcon.asgi import Response
+from falcon.asgi import SSEvent
+from falcon.asgi import WebSocket
 
 
 class Emitter:

e2e-tests/server/ping.py

@@ -1,7 +1,8 @@
 from http import HTTPStatus
 
 import falcon
-from falcon.asgi import Request, Response
+from falcon.asgi import Request
+from falcon.asgi import Response
 
 
 class Pong:

examples/asgilook/asgilook/app.py

@@ -2,7 +2,8 @@
 
 from .cache import RedisCache
 from .config import Config
-from .images import Images, Thumbnails
+from .images import Images
+from .images import Thumbnails
 from .store import Store
 
 

examples/asgilook/asgilook/cache.py

@@ -1,5 +1,4 @@
 import msgpack
-import redis.asyncio as redis
 
 
 class RedisCache:

examples/asgilook/asgilook/config.py

@@ -1,8 +1,9 @@
 import os
 import pathlib
-import redis.asyncio
 import uuid
 
+import redis.asyncio
+
 
 class Config:
     DEFAULT_CONFIG_PATH = '/tmp/asgilook'

examples/asgilook/asgilook/images.py

@@ -1,4 +1,5 @@
 import aiofiles
+
 import falcon
 
 

examples/asgilook/asgilook/store.py

@@ -3,9 +3,10 @@
 import io
 
 import aiofiles
-import falcon
 import PIL.Image
 
+import falcon
+
 
 class Image:
     def __init__(self, config, image_id, size):

examples/asgilook/tests/conftest.py

@@ -3,12 +3,13 @@
 import uuid
 
 import fakeredis.aioredis
-import falcon.asgi
-import falcon.testing
 import PIL.Image
 import PIL.ImageDraw
 import pytest
 
+import falcon.asgi
+import falcon.testing
+
 from asgilook.app import create_app
 from asgilook.config import Config
 

examples/look/look/app.py

@@ -2,7 +2,8 @@
 
 import falcon
 
-from .images import ImageStore, Resource
+from .images import ImageStore
+from .images import Resource
 
 
 def create_app(image_store):

examples/look/look/images.py

@@ -3,9 +3,10 @@
 import os
 import uuid
 
-import falcon
 import msgpack
 
+import falcon
+
 
 class Resource:
     def __init__(self, image_store):

examples/look/tests/conftest.py

@@ -5,7 +5,6 @@
 
 import requests
 
-
 LOOK_PATH = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
 
 gunicorn = None

examples/look/tests/test_app.py

@@ -1,12 +1,15 @@
 import io
+from unittest.mock import call
+from unittest.mock import MagicMock
+from unittest.mock import mock_open
 from wsgiref.validate import InputWrapper
 
-import falcon
-from falcon import testing
-from unittest.mock import call, MagicMock, mock_open
 import msgpack
 import pytest
 
+import falcon
+from falcon import testing
+
 import look.app
 import look.images
 

examples/things_advanced.py

@@ -5,9 +5,10 @@
 import uuid
 from wsgiref import simple_server
 
-import falcon
 import requests
 
+import falcon
+
 
 class StorageEngine:
     def get_things(self, marker, limit):

examples/things_advanced_asgi.py

@@ -4,9 +4,10 @@
 import logging
 import uuid
 
+import httpx
+
 import falcon
 import falcon.asgi
-import httpx
 
 
 class StorageEngine:

falcon/__init__.py

@@ -93,7 +93,6 @@
 from falcon.util import wrap_sync_to_async_unsafe
 from falcon.version import __version__
 
-
 # NOTE(kgriffs): Only to be used internally on the rare occasion that we
 #   need to log something that we can't communicate any other way.
 _logger = _logging.getLogger('falcon')