Merge branch 'master' into static-route-head-sp

Author: AbduazizZiyodov

.devcontainer/devcontainer.json

@@ -1,24 +1,39 @@
 // For format details, see https://aka.ms/devcontainer.json. For config options, see the
 // README at: https://github.com/devcontainers/templates/tree/main/src/python
 {
-	"name": "Python 3",
-	"image": "mcr.microsoft.com/devcontainers/python:3.11",
+	"name": "Falcon (CPython 3.14)",
+	"image": "mcr.microsoft.com/devcontainers/python:3.14",
 	"features": {
-		"ghcr.io/devcontainers-contrib/features/tox:1": {}
-	}
-
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
+		"ghcr.io/devcontainers-extra/features/ruff:1": {},
+		"ghcr.io/devcontainers-extra/features/tox:2": {}
+	},
 
 	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "pip3 install --user -r requirements.txt",
+	// NOTE(vytas): We install pytest not via pipx or features so that test collection works via the default interpreter.
+	"postCreateCommand": "pip install --upgrade pip pytest && FALCON_DISABLE_CYTHON=y pip install -e .",
 
 	// Configure tool-specific properties.
-	// "customizations": {},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance",
+				"charliermarsh.ruff"
+			],
+			"settings": {
+				"python.defaultInterpreterPath": "/usr/local/bin/python",
+				"python.linting.enabled": true,
+				"python.testing.pytestEnabled": true,
+				"python.testing.unittestEnabled": false,
+				// NOTE(vytas): Disable automatic random port-forwarding as running tox doesn't need it.
+				"remote.autoForwardPorts": false
+			}
+		}
+	}
 
 	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// NOTE(vytas): You will probably want to connect as root on rootless Docker/Podman/etc.
+	//   In rootless setups, the current user is typically mapped to root's UID inside the container.
+	//   (You may run into permission problems otherwise as the vscode user gets mapped to an ephemeral UID.)
 	// "remoteUser": "root"
 }

.github/workflows/cibuildwheel.yaml

@@ -153,6 +153,23 @@ jobs:
           - cp312
           - cp313
           - cp314
+        include:
+          - platform:
+              name: manylinux_x86_64
+              os: ubuntu-latest
+            python: cp314t
+          - platform:
+              name: musllinux_x86_64
+              os: ubuntu-latest
+            python: cp314t
+          - platform:
+              name: manylinux_aarch64
+              os: ubuntu-24.04-arm
+            python: cp314t
+          - platform:
+              name: musllinux_aarch64
+              os: ubuntu-24.04-arm
+            python: cp314t
 
     defaults:
       run:
@@ -171,7 +188,7 @@ jobs:
           platforms: all
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.1.0
+        uses: pypa/cibuildwheel@v3.2.1
         env:
           # NOTE(vytas): Uncomment to test against alpha/beta CPython
           #   (usually May-July until rc1).

.github/workflows/test-wheels.yaml

@@ -23,7 +23,7 @@ jobs:
             emulation: true
           - build: "cp39-manylinux_x86_64"
             os: ubuntu-latest
-          - build: "cp314-musllinux_x86_64"
+          - build: "cp314t-musllinux_x86_64"
             os: ubuntu-latest
           - build: "cp313-macosx_arm64"
             os: macos-15
@@ -43,7 +43,7 @@ jobs:
           platforms: all
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.1.0
+        uses: pypa/cibuildwheel@v3.2.1
         env:
           # NOTE(vytas): Uncomment to test against alpha/beta CPython
           #   (usually May-July until rc1).

.github/workflows/tests.yaml

@@ -61,6 +61,8 @@ jobs:
             python-version: "3.14"
           - env: py314_cython
             python-version: "3.14"
+          - env: py315
+            python-version: "3.15.0-alpha.1 - 3.15.0"
           - env: py312_nocover
             os: macos-latest
             platform-label: ' (macos)'

AUTHORS

@@ -214,6 +214,11 @@ listed below by date of first contribution:
 * Soubhik Kumar Mitra (x612skm)
 * Sviatoslav Sydorenko (webknjaz)
 * Soney (sonephyo)
+* Ayan Ahmed Khan (AyanAhmedKhan)
+* Parman Mohammadalizadeh (MannXo)
+* Tudor Gradinaru (TudorGR)
+* Swapnaneel Patra (thisisrick25)
+* 0x1618
 
 (et al.)
 

CONTRIBUTING.md

@@ -153,7 +153,25 @@ This helps to ensure that our recipes stay up-to-date as the framework's develop
 
 ## VS Code Dev Container development environment
 
-When opening the project using the [VS Code](https://code.visualstudio.com/) IDE, if you have [Docker](https://www.docker.com/) (or some drop-in replacement such as [Podman](https://podman.io/) or [Colima](https://github.com/abiosoft/colima) or [Rancher Desktop](https://rancherdesktop.io/)) installed, you can leverage the [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) feature to start a container in the background with all the dependencies required to test and debug the Falcon code. VS Code integrates with the Dev Container seamlessly, which can be configured via [devcontainer.json][devcontainer]. Once you open the project in VS Code, you can execute the "Reopen in Container" command to start the Dev Container which will run the headless VS Code Server process that the local VS Code app will connect to via a [published port](https://docs.docker.com/config/containers/container-networking/#published-ports).
+When opening the project using the [VS Code](https://code.visualstudio.com/) IDE,
+if you have [Docker](https://www.docker.com/) (or some drop-in replacement such as
+[Podman](https://podman.io/), [Colima](https://github.com/abiosoft/colima), or
+[Rancher Desktop](https://rancherdesktop.io/), etc) installed, you can leverage the
+[Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers)
+feature to start a container in the background with all the dependencies
+required to test and debug the Falcon code base.
+
+Once you open the project in VS Code, you can execute the "Reopen in Container"
+command to start the Dev Container which will run a headless VS Code Server
+process. In the connected Terminal, you can run the above referenced ``ruff``
+and ``tox`` commands inside the container (both tools are already pre-installed).
+
+VS Code test collection also works, both in the container and without it.
+Open the "Testing" View, and you should see all the ~300 (at the time of
+writing) tests discovered via ``pytest``.
+
+(If needed, the Dev Container's configuration can be tweaked via
+[devcontainer.json][devcontainer].)
 
 ## Use of LLMs ("AI")
 

README.rst

@@ -444,12 +444,12 @@ Note that this example assumes that the
     import uuid
     from wsgiref import simple_server
 
-    import falcon
     import requests
 
+    import falcon
+
 
     class StorageEngine:
-
         def get_things(self, marker, limit):
             return [{'id': str(uuid.uuid4()), 'color': 'green'}]
 
@@ -459,15 +459,13 @@ Note that this example assumes that the
 
 
     class StorageError(Exception):
-
         @staticmethod
-        def handle(ex, req, resp, params):
+        def handle(req, resp, ex, params):
             # TODO: Log the error, clean up, etc. before raising
             raise falcon.HTTPInternalServerError()
 
 
     class SinkAdapter:
-
         engines = {
             'ddg': 'https://duckduckgo.com',
             'y': 'https://search.yahoo.com/search',
@@ -478,54 +476,59 @@ Note that this example assumes that the
             params = {'q': req.get_param('q', True)}
             result = requests.get(url, params=params)
 
-            resp.status = str(result.status_code) + ' ' + result.reason
+            resp.status = falcon.code_to_http_status(result.status_code)
             resp.content_type = result.headers['content-type']
             resp.text = result.text
 
 
     class AuthMiddleware:
-
         def process_request(self, req, resp):
             token = req.get_header('Authorization')
             account_id = req.get_header('Account-ID')
 
             challenges = ['Token type="Fernet"']
 
             if token is None:
-                description = ('Please provide an auth token '
-                               'as part of the request.')
+                description = 'Please provide an auth token as part of the request.'
 
-                raise falcon.HTTPUnauthorized(title='Auth token required',
-                                              description=description,
-                                              challenges=challenges,
-                                              href='http://docs.example.com/auth')
+                raise falcon.HTTPUnauthorized(
+                    title='Auth token required',
+                    description=description,
+                    challenges=challenges,
+                    href='http://docs.example.com/auth',
+                )
 
             if not self._token_is_valid(token, account_id):
-                description = ('The provided auth token is not valid. '
-                               'Please request a new token and try again.')
+                description = (
+                    'The provided auth token is not valid. '
+                    'Please request a new token and try again.'
+                )
 
-                raise falcon.HTTPUnauthorized(title='Authentication required',
-                                              description=description,
-                                              challenges=challenges,
-                                              href='http://docs.example.com/auth')
+                raise falcon.HTTPUnauthorized(
+                    title='Authentication required',
+                    description=description,
+                    challenges=challenges,
+                    href='http://docs.example.com/auth',
+                )
 
         def _token_is_valid(self, token, account_id):
             return True  # Suuuuuure it's valid...
 
 
     class RequireJSON:
-
         def process_request(self, req, resp):
             if not req.client_accepts_json:
                 raise falcon.HTTPNotAcceptable(
                     description='This API only supports responses encoded as JSON.',
-                    href='http://docs.examples.com/api/json')
+                    href='http://docs.examples.com/api/json',
+                )
 
             if req.method in ('POST', 'PUT'):
                 if 'application/json' not in req.content_type:
                     raise falcon.HTTPUnsupportedMediaType(
                         title='This API only supports requests encoded as JSON.',
-                        href='http://docs.examples.com/api/json')
+                        href='http://docs.examples.com/api/json',
+                    )
 
 
     class JSONTranslator:
@@ -542,21 +545,24 @@ Note that this example assumes that the
                 # Nothing to do
                 return
 
-            body = req.stream.read()
+            body = req.bounded_stream.read()
             if not body:
-                raise falcon.HTTPBadRequest(title='Empty request body',
-                                            description='A valid JSON document is required.')
+                raise falcon.HTTPBadRequest(
+                    title='Empty request body',
+                    description='A valid JSON document is required.',
+                )
 
             try:
                 req.context.doc = json.loads(body.decode('utf-8'))
 
             except (ValueError, UnicodeDecodeError):
-                description = ('Could not decode the request body. The '
-                               'JSON was incorrect or not encoded as '
-                               'UTF-8.')
+                description = (
+                    'Could not decode the request body. The '
+                    'JSON was incorrect or not encoded as '
+                    'UTF-8.'
+                )
 
-                raise falcon.HTTPBadRequest(title='Malformed JSON',
-                                            description=description)
+                raise falcon.HTTPBadRequest(title='Malformed JSON', description=description)
 
         def process_response(self, req, resp, resource, req_succeeded):
             if not hasattr(resp.context, 'result'):
@@ -566,21 +572,22 @@ Note that this example assumes that the
 
 
     def max_body(limit):
-
         def hook(req, resp, resource, params):
             length = req.content_length
             if length is not None and length > limit:
-                msg = ('The size of the request is too large. The body must not '
-                       'exceed ' + str(limit) + ' bytes in length.')
+                msg = (
+                    'The size of the request is too large. The body must not '
+                    'exceed ' + str(limit) + ' bytes in length.'
+                )
 
                 raise falcon.HTTPContentTooLarge(
-                    title='Request body is too large', description=msg)
+                    title='Request body is too large', description=msg
+                )
 
         return hook
 
 
     class ThingsResource:
-
         def __init__(self, db):
             self.db = db
             self.logger = logging.getLogger('thingsapp.' + __name__)
@@ -594,14 +601,15 @@ Note that this example assumes that the
             except Exception as ex:
                 self.logger.error(ex)
 
-                description = ('Aliens have attacked our base! We will '
-                               'be back as soon as we fight them off. '
-                               'We appreciate your patience.')
+                description = (
+                    'Aliens have attacked our base! We will '
+                    'be back as soon as we fight them off. '
+                    'We appreciate your patience.'
+                )
 
                 raise falcon.HTTPServiceUnavailable(
-                    title='Service Outage',
-                    description=description,
-                    retry_after=30)
+                    title='Service Outage', description=description, retry_after=30
+                )
 
             # NOTE: Normally you would use resp.media for this sort of thing;
             # this example serves only to demonstrate how the context can be
@@ -619,19 +627,23 @@ Note that this example assumes that the
             except AttributeError:
                 raise falcon.HTTPBadRequest(
                     title='Missing thing',
-                    description='A thing must be submitted in the request body.')
+                    description='A thing must be submitted in the request body.',
+                )
 
             proper_thing = self.db.add_thing(doc)
 
             resp.status = falcon.HTTP_201
-            resp.location = '/%s/things/%s' % (user_id, proper_thing['id'])
+            resp.location = '/{}/things/{}'.format(user_id, proper_thing['id'])
+
 
     # Configure your WSGI server to load "things.app" (app is a WSGI callable)
-    app = falcon.App(middleware=[
-        AuthMiddleware(),
-        RequireJSON(),
-        JSONTranslator(),
-    ])
+    app = falcon.App(
+        middleware=[
+            AuthMiddleware(),
+            RequireJSON(),
+            JSONTranslator(),
+        ]
+    )
 
     db = StorageEngine()
     things = ThingsResource(db)

docs/_newsfragments/1169.newandimproved.rst

@@ -0,0 +1,5 @@
+The :meth:`req.get_param_as_list <falcon.Request.get_param_as_list>` method now
+supports a new argument, `delimiter`, for splitting of values.
+In line with the OpenAPI v3 parameter specification, the supported delimiters
+currently include the ``'pipeDelimited'`` and ``'spaceDelimited'`` symbolic
+constants, as well as the literal ``','``, ``'|'``, and ``' '`` characters.