docs: Tighten the request-body compression docstrings and comments

Author: vdusek

src/apify_client/http_clients/_base.py

@@ -227,11 +227,9 @@ def _compute_timeout(self, timeout: Timeout, *, attempt: int) -> int | float | N
     def _is_body_worth_compressing(data: str | bytes | bytearray | None) -> bool:
         """Whether `_prepare_request_call` would compress this body, decided without encoding a large `str`.
 
-        Mirrors the rule applied in `_prepare_request_call`, which measures the threshold on the encoded
-        bytes. A `str` therefore cannot be judged by its character count alone. That count is a lower
-        bound on the UTF-8 length, so a `str` reaching the threshold in characters reaches it in bytes
-        too. Below that, the encoded length decides, and such a body is under 4 KiB, so encoding it here
-        is cheap. Any other type is passed through uncompressed.
+        The threshold is measured on encoded bytes, so a character count alone cannot decide a `str`. It
+        is a lower bound, so a `str` long enough in characters is long enough in bytes too. Below that the
+        encoded length decides, and the body is then under 4 KiB, so encoding it here is cheap.
         """
         if isinstance(data, str):
             return len(data) >= MIN_COMPRESSION_SIZE or len(data.encode('utf-8')) >= MIN_COMPRESSION_SIZE
@@ -275,8 +273,8 @@ def _prepare_request_call(
                 data = self._http_compressor.compress(data)
                 headers = self._merge_headers(headers, {'Content-Encoding': self._http_compressor.content_encoding})
             else:
-                # `Content-Encoding` must always describe what was actually applied, so a value the
-                # caller supplied is dropped rather than left to mislabel an uncompressed body.
+                # `Content-Encoding` must describe what was actually applied, so drop a caller
+                # value rather than let it mislabel an uncompressed body.
                 headers = {key: value for key, value in headers.items() if key.lower() != 'content-encoding'}
 
         return (headers, self._parse_params(params), data)

src/apify_client/http_clients/_impit.py

@@ -395,10 +395,9 @@ async def call(
         self._statistics.calls += 1
 
         # Serializing and compressing a request body is CPU-bound and would block the event loop, so
-        # offload request preparation to a worker thread whenever there is a body to compress. Bodyless
-        # requests skip the thread hop, as they have no expensive work to move off the loop. So do raw
-        # bodies the client sends as they are, for which the hop would cost more than preparing them
-        # inline. The size of a `json` body is only known once serialized, so it always hops.
+        # offload preparation to a worker thread whenever there is something to compress. A body the
+        # client sends as it is costs less to prepare inline than the hop itself. A `json` body always
+        # hops, as its size is only known once serialized.
         if json is not None or self._is_body_worth_compressing(data):
             prepared_headers, prepared_params, content = await asyncio.to_thread(
                 self._prepare_request_call,

tests/unit/test_http_clients.py

@@ -467,8 +467,7 @@ def test_prepare_request_call_measures_threshold_in_bytes_not_characters(compres
     """A `str` body under the threshold in characters but over it in UTF-8 bytes is still compressed."""
     compressor, content_encoding, decompress = compressor_case
     client = _ConcreteHttpClient(http_compressor=compressor)
-    # U+00E9 (e with an acute accent) encodes to 2 bytes, so this body is half the threshold
-    # in characters but just above it in bytes.
+    # U+00E9 encodes to 2 bytes, so this body is under the threshold in characters but over it in bytes.
     body = '\u00e9' * (MIN_COMPRESSION_SIZE // 2 + 1)
 
     headers, _params, data = client._prepare_request_call(data=body)
@@ -658,7 +657,7 @@ async def test_async_call_compresses_request_body_off_the_event_loop() -> None:
 
 
 async def test_async_call_compresses_a_multibyte_str_body_off_the_event_loop() -> None:
-    """A `str` body under the threshold in characters but over it in bytes gets compressed, so it must be offloaded."""
+    """A `str` body over the threshold only once encoded is still compressed, so it must be offloaded."""
     compressor = _ThreadRecordingCompressor()
     client = ImpitHttpClientAsync(token='test_token', http_compressor=compressor)
     client._impit_async_client = Mock(request=AsyncMock(return_value=Mock(status_code=200)))
@@ -718,13 +717,12 @@ async def test_async_call_offloads_a_body_at_the_threshold(monkeypatch: pytest.M
 async def test_async_call_skips_thread_offload_for_a_body_it_cannot_compress(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """A body of a type the client passes through has nothing to compress, so deciding must not need its length."""
+    """A body of a type the client passes through needs no hop, and deciding that must not need its length."""
     client = ImpitHttpClientAsync(token='test_token')
     client._impit_async_client = Mock(request=AsyncMock(return_value=Mock(status_code=200)))
     spy = _to_thread_spy(monkeypatch)
 
-    # A file-like body sits outside the declared type, but `encode_key_value_store_record_value` passes
-    # one through, so the gate must not assume every body has a length.
+    # `encode_key_value_store_record_value` passes file-like bodies through, so the gate cannot assume a length.
     body: Any = BytesIO(b'x' * MIN_COMPRESSION_SIZE)
 
     await client.call(method='PUT', url='https://api.test.com/endpoint', data=body)