SIGN IN SIGN UP

refactor(api): isolate audio response format selection (#3701)

- [x] I understand that this repository is auto-generated and my pull
request may not be merged

## Changes being requested

Move the transcription and translation response-format selectors into
the
SDK-owned `lib/_parsing/_audio.py` module. Keep the existing private
resource
functions as thin wrappers, including their signatures and module
loggers.
The selection branches are unchanged, including `None`/omitted handling,
diarized transcription, text formats, and the existing fallback
warnings.

Every resource class is unchanged: public overloads, return annotations,
request fields and order, decorators, and sync/async response wrappers
stay
intact. No compiler, schema, dependency, or generation-metadata changes
are
included.

## Additional context & links

New handwritten coverage is in
`tests/lib/test_audio_response_format.py`:

- `test_supported_formats_keep_exact_response_classes` and
  `test_default_compatibility_values` check the exact response classes.
- `test_fallback_keeps_resource_logger_and_method` and
  `test_fallback_keeps_historical_logger_name_and_warning` preserve the
fallback class, logger, warning text, and existing `warn`/`warning`
behavior.
- `test_sync_create_uses_selected_response_class` and
`test_async_create_uses_selected_response_class` cover every supported
format
through normal, raw, and streaming responses in strict and loose modes.
- `test_sync_transcription_stream_still_yields_events` and
`test_async_transcription_stream_still_yields_events` retain
event-stream
  behavior. The existing overload checks remain in
`tests/lib/test_audio.py::test_translation_create_overloads_in_sync` and
`tests/lib/test_audio.py::test_transcription_create_overloads_in_sync`.

Validation:

- Command: `python -m pytest -n 0
tests/lib/test_audio_response_format.py tests/lib/test_audio.py
tests/api_resources/audio/test_transcriptions.py
tests/api_resources/audio/test_translations.py`
  passed 245 tests under Pydantic v2 and 245 under Pydantic v1.
- `./scripts/format` and `./scripts/lint` passed, including Ruff,
Pyright,
mypy, and import checks. Unrelated formatter-only reporter edits are
excluded.
- `./scripts/build` passed; the wheel and source distribution both
contain
  the new private helper.
- The public custom-code report verifies 41 mixed files, with only the
two
audio customizations changed and 39 others unchanged. Transcriptions
shrink
from +160/-53 to +145/-52; translations shrink from +155/-39 to
+143/-39.
  `.castiron.stats.yml` is unchanged.

Command to reproduce the report from this branch:

```sh
$ python3 scripts/castiron/custom_code_report.py report \
    --base 8edd9ae411f9d0a5385447a4697c9f7042868213 \
    --head 676b9e7300e5743b6177e7188df0d6d63c3d977c \
    --fetch --require-head-hash --public \
    --out /tmp/castiron-audio-format-selection
```
A
Alex Chang committed
ece4324da0b96f848b48bdef090a372ff0a1db26
Parent: 50de9af
Committed by GitHub <noreply@github.com> on 8/20/2026, 10:51:14 PM