feat: add zstd request body compression by apify-factory · Pull Request #1218 · apify/apify-client-python

apify-factory · 2026-11-10T09:40:51Z

Reference change

Ported change

HttpCompressionAlgorithm (apify_client.types) now accepts 'zstd', and resolve_compressor maps it to the new compressor. The compression argument of ApifyClient / ApifyClientAsync and of ActorServerClient.request therefore accepts 'zstd'.
New public apify_client.http_compressors.ZstdHttpCompressor (http_compressors/_zstd.py), modeled on the gzip and brotli compressors. It reports content_encoding = 'zstd' and takes a keyword-only quality from 1 to 19, defaulting to 3. Levels 20–22 are rejected because their window exceeds the 8 MB that RFC 9659 requires HTTP decoders to support. The body-selection rules (minimum size, already-compressed content types, caller-set Content-Encoding) are the same as for the other algorithms.
Python-specific differences from the reference:
- Source of zstd. Python 3.14+ uses the standard library's compression.zstd. Older versions use the official backports.zstd package through a new optional zstd extra (pip install "apify-client[zstd]"), following the pattern of the brotli extra.
- Missing zstd. If the extra is missing, or a 3.14+ Python was built without zstd, import apify_client still works. Only accessing ZstdHttpCompressor or passing compression='zstd' raises a clear ImportError.
- Supporting changes. try_import now treats a missing parent package of a dotted dependency name as the dependency being missing, and accepts extra_name=None for dependencies no extra can install. [tool.ty.analysis] allowed-unresolved-imports lists backports.zstd, because ty checks against Python 3.11 even in 3.14+ environments, where the package is not installed.
- Invalid quality. An invalid quality raises ValueError, like the existing Python compressors, rather than the JS ArgumentValidationError.

…endencies

codecov · 2026-11-10T09:43:03Z

Codecov Report

❌ Patch coverage is 90.69767% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.69%. Comparing base (eb8ded4) to head (845edaf).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/apify_client/http_compressors/_zstd.py	91.30%	2 Missing ⚠️
src/apify_client/http_compressors/__init__.py	90.90%	1 Missing ⚠️
src/apify_client/types.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1218      +/-   ##
==========================================
- Coverage   95.76%   95.69%   -0.07%     
==========================================
  Files          63       64       +1     
  Lines        6676     6712      +36     
==========================================
+ Hits         6393     6423      +30     
- Misses        283      289       +6

Flag	Coverage Δ
integration	`90.98% <58.13%> (+0.31%)`	⬆️
unit	`91.07% <90.69%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

vdusek

Could you add a self-review / staff review to the porting process?

vdusek · 2026-11-10T11:41:33Z

 brotli = ["brotli>=1.0.9"]
 httpx2 = ["httpx2>=2.0.0"]
+# zstd is in the standard library (`compression.zstd`) from Python 3.14; older versions use its official backport.
+zstd = ["backports.zstd>=1.0.0; python_version < '3.14'"]


uv.lock isn't updated for the new zstd extra, so uv lock --check fails. CI passes because it doesn't sync with --locked, but every uv sync rewrites the lock and leaves the tree dirty. Please run uv lock and commit the result.

✍️ Drafted by Claude Code

Done in 19d5957: uv.lock now includes backports-zstd for the zstd extra, and uv lock --check passes.

vdusek · 2026-11-10T11:41:33Z

+# zstd is in the standard library from Python 3.14, though a Python build can leave it out, which no extra can fix.
+# Older versions need the `backports.zstd` package from the `zstd` extra. Either way it's wrapped in try_import.


The note about builds without zstd repeats the comment in _zstd.py, and the last sentence says what the next lines show. One line about the version split is enough.

Suggested change

# zstd is in the standard library from Python 3.14, though a Python build can leave it out, which no extra can fix.

# Older versions need the `backports.zstd` package from the `zstd` extra. Either way it's wrapped in try_import.

# zstd is in the standard library from Python 3.14. Older versions need `backports.zstd` from the `zstd` extra.

✍️ Drafted by Claude Code

Applied in 845edaf.

vdusek · 2026-11-10T11:41:33Z


        return BrotliHttpCompressor()
+    if compression == 'zstd':
+        # Imported here for the same reason as brotli: before Python 3.14 zstd needs the `zstd` extra.


This import also fails on a Python 3.14+ build without zstd, not only before 3.14. The short form covers both cases.

Suggested change

# Imported here for the same reason as brotli: before Python 3.14 zstd needs the `zstd` extra.

# Imported here for the same reason as brotli.

✍️ Drafted by Claude Code

Already covered: the comment was updated before this review landed and now reads "Imported here so a missing zstd extra, or a Python build without zstd, raises ImportError at call time." That names both cases, so I left it as is.

vdusek · 2026-11-10T11:41:33Z


+## Enabling zstd
+
+Python 3.14 and newer ship zstd in the standard library as `compression.zstd`, so pass `compression='zstd'` and nothing else is needed, as long as your Python build includes zstd support, which the python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:


This sentence joins four clauses. Could you split it?

Suggested change

Python 3.14 and newer ship zstd in the standard library as `compression.zstd`, so pass `compression='zstd'` and nothing else is needed, as long as your Python build includes zstd support, which the python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:

Python 3.14 and newer include zstd in the standard library as `compression.zstd`, so you only need to pass `compression='zstd'`. Your Python build must include zstd support. The python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:

✍️ Drafted by Claude Code

Addressed in 7f623d3: the sentence about builds without zstd was dropped. The paragraph now reads "Python 3.14 and newer ship zstd in the standard library as compression.zstd, so compression='zstd' works there without an extra. On older Python versions, install the optional extra, which brings in the backports.zstd package:". The no-zstd build case is still covered by the ImportError note below the install block.

vdusek · 2026-11-10T11:41:33Z

    </TabItem>
 </Tabs>

+To compress with `zstd` instead, pass `compression='zstd'`. On Python 3.14 and newer it uses the standard library; on older versions install the optional `zstd` extra with `pip install "apify-client[zstd]"`.


Split at the semicolon into two sentences, as the docs style asks.

Suggested change

To compress with `zstd` instead, pass `compression='zstd'`. On Python 3.14 and newer it uses the standard library; on older versions install the optional `zstd` extra with `pip install "apify-client[zstd]"`.

To compress with `zstd` instead, pass `compression='zstd'`. On Python 3.14 and newer it uses the standard library. On older versions, install the optional `zstd` extra with `pip install "apify-client[zstd]"`.

✍️ Drafted by Claude Code

Applied in 845edaf.

vdusek · 2026-11-10T11:41:33Z

+    To compress with `zstd`, pass `compression='zstd'`. Python 3.14 and newer have it in the standard library; on older
+    versions install the optional `zstd` extra: `pip install "apify-client[zstd]"`.


Same here: split at the semicolon.

Suggested change

To compress with `zstd`, pass `compression='zstd'`. Python 3.14 and newer have it in the standard library; on older

versions install the optional `zstd` extra: `pip install "apify-client[zstd]"`.

To compress with `zstd`, pass `compression='zstd'`. Python 3.14 and newer have it in the standard library. On older

versions, install the optional `zstd` extra: `pip install "apify-client[zstd]"`.

✍️ Drafted by Claude Code

Applied in 845edaf.

apify-factory added 10 commits November 10, 2026 10:22

feat: add zstd request body compression

f94f98c

feat: accept 'zstd' as a compression algorithm and add the zstd extra

08a3d81

docs: document zstd request body compression

0ec8a9d

docs: mention the zstd extra in the README

53a447b

test: cover the zstd compressor

8edd3bd

test: cover the optional-import handling of dotted and extra-less dep…

01a571f

…endencies

docs: note the zstd build requirement in the Actor server Raises section

bc033f7

docs: document the zstd compression option on the client constructors

214c2fd

docs: list zstd among the encodings set_record accepts

212ce68

build: let ty resolve without backports.zstd on Python 3.14+

ced1d0e

apify-factory requested a review from szaganek as a code owner November 10, 2026 09:40

apify-factory added the api-client-sync label Nov 10, 2026

github-actions Bot added the t-tooling Issues with this label are in the ownership of the tooling team. label Nov 10, 2026

Pijukatel requested a review from vdusek November 10, 2026 10:17

vdusek reviewed Nov 10, 2026

View reviewed changes

apify-factory and others added 5 commits November 10, 2026 14:18

feat: tolerate a zstd module that fails to load on Python 3.14+

d68f6a0

chore: lock backports.zstd for the zstd extra

19d5957

feat: suggest gzip or brotli when the Python build lacks zstd

a155d9a

docs: tighten the zstd availability notes

7f623d3

docs: split the zstd install notes and shorten the zstd import comment

845edaf

Pijukatel requested a review from vdusek November 10, 2026 14:57

Pijukatel approved these changes Nov 10, 2026

View reviewed changes

		# zstd is in the standard library from Python 3.14, though a Python build can leave it out, which no extra can fix.
		# Older versions need the `backports.zstd` package from the `zstd` extra. Either way it's wrapped in try_import.

	# Imported here for the same reason as brotli: before Python 3.14 zstd needs the `zstd` extra.
	# Imported here for the same reason as brotli.


		## Enabling zstd

		Python 3.14 and newer ship zstd in the standard library as `compression.zstd`, so pass `compression='zstd'` and nothing else is needed, as long as your Python build includes zstd support, which the python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:

	Python 3.14 and newer ship zstd in the standard library as `compression.zstd`, so pass `compression='zstd'` and nothing else is needed, as long as your Python build includes zstd support, which the python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:
	Python 3.14 and newer include zstd in the standard library as `compression.zstd`, so you only need to pass `compression='zstd'`. Your Python build must include zstd support. The python.org builds do. On older Python versions, install the optional extra, which brings in the `backports.zstd` package:

	To compress with `zstd` instead, pass `compression='zstd'`. On Python 3.14 and newer it uses the standard library; on older versions install the optional `zstd` extra with `pip install "apify-client[zstd]"`.
	To compress with `zstd` instead, pass `compression='zstd'`. On Python 3.14 and newer it uses the standard library. On older versions, install the optional `zstd` extra with `pip install "apify-client[zstd]"`.

		To compress with `zstd`, pass `compression='zstd'`. Python 3.14 and newer have it in the standard library; on older
		versions install the optional `zstd` extra: `pip install "apify-client[zstd]"`.

Conversation

apify-factory commented Nov 10, 2026 • edited by Pijukatel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reference change

Ported change

Uh oh!

codecov Bot commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vdusek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

apify-factory commented Nov 10, 2026 •

edited by Pijukatel

Loading

codecov Bot commented Nov 10, 2026 •

edited

Loading