[deanrie]

Stacked on #232 (same file, same helper); the diff here is the last commit. Merge #232 first, or merge this and #232 comes with it.

Checklist

• I have read both the CONTRIBUTING.md and Contributor License Agreement documents.
• I have created an issue or feature request and received approval from xAI maintainers. (defect found while working on files: decide progress callback arity from its signature; total counts from the current position #232; no issue filed)
• I have tested my changes locally and they pass all CI checks.
• I have added necessary documentation or updated existing documentation. (CHANGELOG)

Description

AsyncClient.files.upload accepts an on_progress callback and calls it from the three async chunk generators through the sync _invoke_progress. When the callback is an async def, the natural shape in async code and one the ProgressCallback type did not forbid, the call returns a coroutine that nobody awaits: the callback body never runs, and Python warns coroutine '...' was never awaited once per chunk.

async def progress(uploaded, total): ...
await client.files.upload("big.bin", on_progress=progress)
# main: progress body never runs; RuntimeWarning per chunk

Change

• _invoke_progress returns whatever the callback returned.
• The async generators call a new _async_invoke_progress, which awaits that value when it is awaitable. Sync callbacks and tqdm-like objects take the same path as before (their return value is None).
• ProgressCallback admits callables returning Awaitable[None], so an async def type-checks.

The sync client is unchanged: it cannot await, and an async def passed there still produces the same warning it always did; that remains a caller error on the sync path.

Tests

tests/aio/files_test.py: an async def callback on AsyncClient.files.upload is called for both chunks with (uploaded, total) and ends at (len(data), len(data)), with RuntimeWarning turned into an error for the duration. Fails on main with the never-awaited warning. uv run pytest tests/aio/files_test.py tests/sync/files_test.py: 75 passed. ruff check, ruff format --check, pyright clean on the touched files.