feat(py-client): Add many API

[jan-auer]

Adds session.many() to the Python client for executing multiple get/put/delete operations in batches, with a fully streaming request/response pipeline.

The batch protocol uses multipart/form-data with per-part custom headers (x-sn-batch-operation-kind, x-sn-batch-operation-key, etc.). No existing Python library supports both streaming encoding with arbitrary per-part headers and streaming decoding, so both are implemented in multipart.py.

Streaming pipeline (no buffering):

• Request: _build_batch_parts (generator) → encode_multipart (yields bytes lazily) → urllib3 chunked transfer encoding
• Response: response.stream(65536) → iter_multipart_response (incremental boundary detection across arbitrary chunks) → _parse_batch_response (generator) → caller receives Iterator[ManyResponse]

Operation classification:

• bytes Put bodies: compressed eagerly (required for size-based batching), then classified — ≤1 MB goes in a batch request, >1 MB goes individually via the standard PUT endpoint
• IO[bytes] Put bodies: always sent individually to avoid eager reading
• Get and Delete: always batched (zero body size)

Concurrency: ThreadPoolExecutor dispatches batch chunks and individual ops concurrently (default concurrency=3). Results arrive in completion order, matching the Rust client's buffer_unordered semantics. Sequential execution (concurrency=1) preserves input order.

Close FS-330

[sentry]

Bug: The _send_batch generator is iterated on the main thread instead of the worker thread, causing concurrent batch operations to execute sequentially.
_{Severity: HIGH}

Suggested Fix

To ensure the generator's logic runs in the worker thread, wrap the call in a function that consumes the generator. For example, create a helper function def _run_send_batch(*args): return list(_send_batch(*args)) and submit this new function to the executor: executor.submit(_run_send_batch, session, chunk). This forces the I/O operations to complete within the worker thread before the result is returned.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: clients/python/src/objectstore_client/many.py#L546

Potential issue: The `_send_batch` function is a generator. When submitted to a
`ThreadPoolExecutor` via `executor.submit`, the worker thread immediately returns a
generator object without executing the function's body. The main thread later retrieves
this generator via `future.result()` and iterates over it. This causes all HTTP I/O for
the batch operation to execute sequentially on the main thread, defeating the purpose of
the thread pool. As a result, setting `concurrency > 1` for batch operations has no
effect on performance, as requests are not parallelized.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[linear-code]

FS-330 Many-API for Python

[cursor]

Duplicate results yielded on mid-parse exception in batch

Medium Severity

If _parse_batch_response (or iter_multipart_response) partially yields successful results and then raises an exception (e.g., NotImplementedError for non-zstd compression, ValueError from malformed server data, or a decompression error), those results have already been passed to the caller via yield from. The outer except Exception handler then calls yield from _batch_level_error(ops, error), which yields error results for ALL operations — including those already successfully yielded. Callers (list(_send_batch(...)) or sorted(_send_batch(...))) collect all values, producing duplicate ManyResponse entries for the same operations.

Additional Locations (1)

• clients/python/src/objectstore_client/many.py#L463-L468

 

^{Reviewed by Cursor Bugbot for commit 837b455. Configure here.}

[lcian]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 837b455. Configure here.}

[cursor]

Concurrent path ignores key-conflict batch splitting

High Severity

The concurrency > 1 path re-batches all operations from the batchable list (line 625), which unconditionally accumulates every batchable op (line 592) regardless of key conflicts. The careful key-conflict splitting done by flush_pending_batchable() only affects sequential_work, used exclusively by the concurrency == 1 path. With concurrency > 1, same-key Put and Get operations end up in the same batch, causing guaranteed server-side race conditions since the server processes intra-batch operations concurrently.

Additional Locations (1)

• clients/python/src/objectstore_client/many.py#L591-L592

 

^{Reviewed by Cursor Bugbot for commit 837b455. Configure here.}