fix: prevent OOM by using file handles and chunked base64 encoding

[anthonymq]

Summary

This PR fixes memory spikes that can cause OOM (Out of Memory) errors in the _interactions layer when handling file uploads and inline data.

Problem

Several functions in the _interactions layer were loading entire files into memory before processing, causing OOM errors for large files.

Note: The main aio.files.upload() API (files.py → _api_client.py) is already memory-efficient - it uses 8MB chunked streaming via anyio.Path().open('rb'). The OOM issues occur in the experimental _interactions layer.

Root Causes Identified

1. _interactions/_files.py: Used path.read_bytes() to load entire files before passing to httpx
2. _interactions/_utils/_transform.py: Base64 encoding loaded entire files with read_bytes() before encoding
3. _interactions/_utils/_utils.py: file_from_path() loaded entire files with read_bytes()

Solution

1. File Handle Streaming (_interactions/_files.py)

• Return open file handles (open(path, 'rb')) instead of loading bytes with read_bytes()
• httpx natively supports IO[bytes] file handles, so this is a drop-in fix
• Applies to both sync and async code paths

2. Chunked Base64 Encoding (_interactions/_utils/_transform.py)

• Implement chunked reading with 3MB chunks for base64 encoding
• Chunk size is a multiple of 3 (required for correct base64 encoding without padding issues)
• Reduces peak memory from O(file_size) to O(chunk_size)

3. File Handle in Utility (_interactions/_utils/_utils.py)

• file_from_path() now returns a file handle instead of loaded bytes

Memory Flow (Before vs After)

Before:

File path → read_bytes() (🔴 entire file in memory) → process

After:

File path → open() → file handle → stream in chunks (✅ memory-efficient)

Testing

• Verified Python syntax compiles correctly
• Verified file handle approach works with httpx's expected types
• Verified chunked base64 encoding produces identical output to original implementation

Backwards Compatibility

This is a fully backwards-compatible change:

• Public API remains unchanged
• Return types are compatible (httpx accepts both bytes and IO[bytes])
• Base64 output is identical (chunked encoding with multiples of 3 produces same result)

[janasangeetha]

Hey @anthonymq
Thanks for contributing!
The branch is out-of-date. Kindly update the same.

[anthonymq]

Branch updated,
Cheers