[tongwentao]

Sizes below 1 have been accepted since batcher was introduced. Rejecting them immediately would break existing 4.x callers, including batcher([], 0) and sizes computed from a small input. This revision follows the maintainer's compatibility plan: warn in 4.x and reserve ValueError for 5.0.

• batcher emits one DeprecationWarning for a size below 1 when iteration begins, before consuming the source. Its existing result is preserved: one batch containing all items, or no batches for an empty source.
• Without an interval, abatcher emits the same warning and preserves existing behavior, including the assertion for size 0 and the single final batch for a negative size.
• With an interval, abatcher accepts None, 0 and negative sizes as no size limit, without warning. Interval deadlines and cancellation behavior remain covered by the existing tests, now also exercised with 0 and -1.
• Warnings point to the caller. Callers who turn deprecations into errors fail before any source items are consumed or scheduled. Positive sizes retain lazy, bounded consumption and issue no warning.

Both docstrings and the changelog explain the staged deprecation. This PR does not implement the future 5.0 exception.

Validation on Python 3.13.5, using the existing development environment over SSH on Linux:

• Full tests and doctests: 405 passed, 100% statement and branch coverage.
• Batching module: 51 passed, covering empty/nonempty sources, warning timing/category/location, warnings promoted to errors, positive sizes, and interval-only behavior and deadlines.
• Ruff lint and format, Mypy, basedpyright, Pyrefly and Codespell passed.
• Sphinx HTML build with warnings treated as errors passed.

Other interpreter versions are left to CI. This revision was prepared and validated with Codex.

[wolph]

Thank you for the pull request. The tests that check nothing is consumed are a nice touch.

The catch is that sizes below 1 have been accepted since batcher was added in 3.3.0, and they're easy to reach by accident: batcher(rows, len(rows) // workers) gets a size of 0 whenever there are fewer rows than workers, and batcher([], 0) returns [] on 4.1.4. With this change those jobs start raising ValueError, and since many people install python-utils without an upper bound, they would get that from a minor release. abatcher(source, batch_size=0, interval=5) is a similar case: it batches by interval only today, and the interval already keeps the buffer bounded.

I wouldn't oppose rejecting these sizes, but I'd rather do it in two steps: a DeprecationWarning for sizes below 1 in 4.x that keeps the current result, and the ValueError in 5.0. For abatcher with an interval, a size below 1 could simply keep meaning "no size limit". Would you be up for changing the PR that way?