🔖 Release 2.8.902 (#129)

- Added support for async iterable yielding either bytes or str when
passing a body into your requests.
- Added dummy module (e.g. http2 and emscriptem) like upstream without
serving any of them. Those modules won't be served and are empty as we
diverged since.
- Added a better error message for http3 handshake failure to help out
users figuring out what is happening.
- Added official support for Python 3.13

.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
         os:
           - macos-12
           - windows-latest
@@ -242,6 +242,7 @@ jobs:
         uses: "actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1"
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
 
       - name: "Install dependencies"
         run: python -m pip install --upgrade pip setuptools nox

CHANGES.rst

@@ -1,3 +1,11 @@
+2.8.902 (2024-07-07)
+====================
+
+- Added support for async iterable yielding either bytes or str when passing a body into your requests.
+- Added dummy module (e.g. http2 and emscriptem) like upstream without serving any of them. Those modules won't be served and are empty as we diverged since.
+- Added a better error message for http3 handshake failure to help out users figuring out what is happening.
+- Added official support for Python 3.13
+
 2.8.901 (2024-06-27)
 ====================
 

dev-requirements.txt

@@ -1,4 +1,4 @@
-coverage>=7.2.7,<=7.4
+coverage>=7.2.7,<=7.4.1
 tornado>=6.2,<=6.4
 python-socks==2.4.4
 pytest==7.4.4
@@ -11,3 +11,5 @@ cryptography==42.0.5;implementation_name!="pypy" or implementation_version>="7.3
 backports.zoneinfo==0.2.1;python_version<"3.9"
 towncrier==21.9.0
 pytest-asyncio>=0.21.1,<=0.23.5.post1
+# unblock cffi for Python 3.13
+cffi==1.17.0rc1; python_version > "3.12"

docs/async.rst

@@ -147,3 +147,8 @@ The following properties and methods are awaitable:
 
 In addition to that, ``AsyncHTTPResponse`` ships with an async iterator.
 
+Sending async iterable
+----------------------
+
+In our asynchronous APIs, you can send async iterable using the ``body=...`` keyword argument.
+It is most useful when trying to send files that are IO bound, thus blocking your event loop needlessly.

noxfile.py

@@ -8,7 +8,7 @@
 
 def tests_impl(
     session: nox.Session,
-    extras: str = "socks,brotli,zstd",
+    extras: str = "socks,brotli",
     byte_string_comparisons: bool = False,
 ) -> None:
     # Install deps and the package itself.
@@ -44,7 +44,7 @@ def tests_impl(
     )
 
 
-@nox.session(python=["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "pypy"])
+@nox.session(python=["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "pypy"])
 def test(session: nox.Session) -> None:
     tests_impl(session)
 

pyproject.toml

@@ -15,7 +15,7 @@ authors = [
   {name = "Andrey Petrov", email = "[email protected]"}
 ]
 maintainers = [
-  {name = "Ahmed R. TAHRI", email="ahmed.tahri@cloudnursery.dev"},
+  {name = "Ahmed R. TAHRI", email="tahri[email protected]"},
 ]
 classifiers = [
   "Environment :: Web Environment",

src/urllib3/_async/connection.py

@@ -18,6 +18,7 @@
         _TYPE_SOCKET_OPTIONS,
         _TYPE_TIMEOUT_INTERNAL,
         ProxyConfig,
+        _TYPE_ASYNC_BODY,
     )
     from ..util._async.traffic_police import AsyncTrafficPolice
 
@@ -324,7 +325,7 @@ async def request(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         *,
         chunked: bool = False,
@@ -459,17 +460,32 @@ async def request(
         try:
             # If we're given a body we start sending that in chunks.
             if chunks is not None:
-                for chunk in chunks:
-                    # Sending empty chunks isn't allowed for TE: chunked
-                    # as it indicates the end of the body.
-                    if not chunk:
-                        continue
-                    if isinstance(chunk, str):
-                        chunk = chunk.encode("utf-8")
-                    await self.send(chunk)
-                    total_sent += len(chunk)
-                    if on_upload_body is not None:
-                        await on_upload_body(total_sent, content_length, False, False)
+                if hasattr(chunks, "__aiter__"):
+                    async for chunk in chunks:
+                        if not chunk:
+                            continue
+                        if isinstance(chunk, str):
+                            chunk = chunk.encode("utf-8")
+                        await self.send(chunk)
+                        total_sent += len(chunk)
+                        if on_upload_body is not None:
+                            await on_upload_body(
+                                total_sent, content_length, False, False
+                            )
+                else:
+                    for chunk in chunks:
+                        # Sending empty chunks isn't allowed for TE: chunked
+                        # as it indicates the end of the body.
+                        if not chunk:
+                            continue
+                        if isinstance(chunk, str):
+                            chunk = chunk.encode("utf-8")
+                        await self.send(chunk)
+                        total_sent += len(chunk)
+                        if on_upload_body is not None:
+                            await on_upload_body(
+                                total_sent, content_length, False, False
+                            )
                 try:
                     rp = await self.send(b"", eot=True)
                 except TypeError:

src/urllib3/_async/connectionpool.py

@@ -16,7 +16,13 @@
 
 from .._collections import HTTPHeaderDict
 from .._request_methods import AsyncRequestMethods
-from .._typing import _TYPE_BODY, _TYPE_BODY_POSITION, _TYPE_TIMEOUT, ProxyConfig
+from .._typing import (
+    _TYPE_ASYNC_BODY,
+    _TYPE_BODY,
+    _TYPE_BODY_POSITION,
+    _TYPE_TIMEOUT,
+    ProxyConfig,
+)
 from ..backend import ConnectionInfo, ResponsePromise
 from ..connection import _wrap_proxy_error
 from ..connectionpool import _normalize_host
@@ -851,7 +857,7 @@ async def _make_request(
         conn: AsyncHTTPConnection,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         retries: Retry | None = ...,
         timeout: _TYPE_TIMEOUT = ...,
@@ -876,7 +882,7 @@ async def _make_request(
         conn: AsyncHTTPConnection,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         retries: Retry | None = ...,
         timeout: _TYPE_TIMEOUT = ...,
@@ -900,7 +906,7 @@ async def _make_request(
         conn: AsyncHTTPConnection,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         retries: Retry | None = None,
         timeout: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
@@ -1151,7 +1157,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         retries: Retry | bool | int | None = ...,
         redirect: bool = ...,
@@ -1179,7 +1185,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         retries: Retry | bool | int | None = ...,
         redirect: bool = ...,
@@ -1206,7 +1212,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         retries: Retry | bool | int | None = None,
         redirect: bool = True,

src/urllib3/_request_methods.py

@@ -6,7 +6,7 @@
 
 from ._async.response import AsyncHTTPResponse
 from ._collections import HTTPHeaderDict
-from ._typing import _TYPE_BODY, _TYPE_ENCODE_URL_FIELDS, _TYPE_FIELDS
+from ._typing import _TYPE_ASYNC_BODY, _TYPE_BODY, _TYPE_ENCODE_URL_FIELDS, _TYPE_FIELDS
 from .filepost import encode_multipart_formdata
 from .response import HTTPResponse
 
@@ -377,7 +377,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         encode_multipart: bool = True,
         multipart_boundary: str | None = None,
@@ -392,7 +392,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         encode_multipart: bool = True,
         multipart_boundary: str | None = None,
@@ -406,7 +406,7 @@ async def urlopen(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         headers: typing.Mapping[str, str] | None = None,
         encode_multipart: bool = True,
         multipart_boundary: str | None = None,
@@ -422,7 +422,7 @@ async def request(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         fields: _TYPE_FIELDS | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         json: typing.Any | None = ...,
@@ -437,7 +437,7 @@ async def request(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = ...,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = ...,
         fields: _TYPE_FIELDS | None = ...,
         headers: typing.Mapping[str, str] | None = ...,
         json: typing.Any | None = ...,
@@ -451,7 +451,7 @@ async def request(
         self,
         method: str,
         url: str,
-        body: _TYPE_BODY | None = None,
+        body: _TYPE_BODY | _TYPE_ASYNC_BODY | None = None,
         fields: _TYPE_FIELDS | None = None,
         headers: typing.Mapping[str, str] | None = None,
         json: typing.Any | None = None,

src/urllib3/_typing.py

@@ -30,6 +30,11 @@ class _TYPE_PEER_CERT_RET_DICT(TypedDict, total=False):
     AsyncLowLevelResponse,
 ]
 
+_TYPE_ASYNC_BODY: typing.TypeAlias = typing.Union[
+    typing.AsyncIterable[bytes],
+    typing.AsyncIterable[str],
+]
+
 _TYPE_FIELD_VALUE: typing.TypeAlias = typing.Union[str, bytes]
 _TYPE_FIELD_VALUE_TUPLE: typing.TypeAlias = typing.Union[
     _TYPE_FIELD_VALUE,

src/urllib3/_version.py

@@ -1,4 +1,4 @@
 # This file is protected via CODEOWNERS
 from __future__ import annotations
 
-__version__ = "2.8.901"
+__version__ = "2.8.902"

src/urllib3/backend/_async/hface.py

@@ -452,10 +452,18 @@ async def _post_conn(self) -> None:  # type: ignore[override]
             return
 
         # it may be required to send some initial data, aka. magic header (PRI * HTTP/2..)
-        await self.__exchange_until(
-            HandshakeCompleted,
-            receive_first=False,
-        )
+        try:
+            await self.__exchange_until(
+                HandshakeCompleted,
+                receive_first=False,
+            )
+        except ProtocolError as e:
+            if isinstance(self._protocol, HTTPOverQUICProtocol):
+                raise ProtocolError(
+                    "It is likely that the server yielded its support for HTTP/3 through the Alt-Svc header while unable to do so. "
+                    "To remediate that issue, either disable http3 or reach out to the server admin."
+                ) from e
+            raise
 
         if isinstance(self._protocol, HTTPOverQUICProtocol):
             self.conn_info.certificate_der = self._protocol.getpeercert(

src/urllib3/backend/hface.py

@@ -513,10 +513,18 @@ def _post_conn(self) -> None:
             return
 
         # it may be required to send some initial data, aka. magic header (PRI * HTTP/2..)
-        self.__exchange_until(
-            HandshakeCompleted,
-            receive_first=False,
-        )
+        try:
+            self.__exchange_until(
+                HandshakeCompleted,
+                receive_first=False,
+            )
+        except ProtocolError as e:
+            if isinstance(self._protocol, HTTPOverQUICProtocol):
+                raise ProtocolError(
+                    "It is likely that the server yielded its support for HTTP/3 through the Alt-Svc header while unable to do so. "
+                    "To remediate that issue, either disable http3 or reach out to the server admin."
+                ) from e
+            raise
 
         #: Populating ConnectionInfo using QUIC TLS interfaces
         if isinstance(self._protocol, HTTPOverQUICProtocol):

src/urllib3/connection.py

@@ -467,6 +467,10 @@ def request(
         try:
             # If we're given a body we start sending that in chunks.
             if chunks is not None:
+                if hasattr(chunks, "__aiter__"):
+                    raise RuntimeError(
+                        "Unable to send an async iterable through a synchronous connection"
+                    )
                 for chunk in chunks:
                     # Sending empty chunks isn't allowed for TE: chunked
                     # as it indicates the end of the body.

src/urllib3/contrib/emscripten/__init__.py

@@ -0,0 +1,24 @@
+# Dummy file to match upstream modules
+# without actually serving them.
+# urllib3-future diverged from urllib3.
+# only the top-level (public API) are guaranteed to be compatible.
+# in-fact urllib3-future propose a better way to migrate/transition toward
+# newer protocols.
+
+from __future__ import annotations
+
+import warnings
+
+
+def inject_into_urllib3() -> None:
+    warnings.warn(
+        "urllib3-future do not have a emscripten module as it is irrelevant to urllib3 nature. "
+        "wasm support will be brought in Niquests (replacement for Requests). "
+        "One does not simply ship an addon that essentially kills 90% of its other features and alter the 10 "
+        "remaining percents.",
+        UserWarning,
+    )
+
+
+def extract_from_urllib3() -> None:
+    pass

src/urllib3/http2.py

@@ -0,0 +1,22 @@
+# Dummy file to match upstream modules
+# without actually serving them.
+# urllib3-future diverged from urllib3.
+# only the top-level (public API) are guaranteed to be compatible.
+# in-fact urllib3-future propose a better way to migrate/transition toward
+# newer protocols.
+
+from __future__ import annotations
+
+import warnings
+
+
+def inject_into_urllib3() -> None:
+    warnings.warn(
+        "urllib3-future do not propose the http2 module as it is useless to us. "
+        "enjoy all three protocols. urllib3-future just works out of the box with all protocols.",
+        UserWarning,
+    )
+
+
+def extract_from_urllib3() -> None:
+    pass