HTTPX Bug Report

[Az-yaro]

Hi everyone! I ran the test suite on Windows with Python 3.13 and found a failing test case in test_multipart.py. I wanted to share it here first to see if a PR would be welcome

Bug Description
On Windows environments running Python 3.13+, test_multipart_encode_files_raises_exception_with_text_mode_file consistently fails. The test expects a TypeError when a file opened in text mode (mode="w") is passed into multipart file encoding, but under Python 3.13 on Windows, no exception is thrown.
Environment Information

OS: Windows (win32) 
Python Version: 3.13.15 
HTTPX Version: Latest master branch (development installation) 
Pytest Version: 8.4.1 

To Reproduce
Run the multipart unit tests on a Windows environment with Python 3.13:

pytest tests/test_multipart.py

Alternatively, executing the core logic manually in an interactive prompt:

import tempfile
import httpx

url = "https://www.example.com"
with tempfile.TemporaryFile(mode="w") as upload:
    files = {"file": ("test.txt", upload, "text/plain")}
    # On Windows + Python 3.13, this finishes without throwing any error
    req = httpx.Request("POST", url, files=files)
    print("Result: No error was raised at all!")

Expected Behavior
A TypeError should be explicitly raised to catch text-mode file streams uniformly across platforms, ensuring data integrity before multipart payload assembly.
Actual Behavior
The test suite fails with:

Failed: DID NOT RAISE <class 'TypeError'>

Proposed Solution / Context
The underlying behavior of empty text-mode tempfile.TemporaryFile objects appears to skip typical stream type check constraints under Python 3.13 on the Windows platform. I can submit a patch to strictly check the file stream typing or check if binary mode is explicitly missing within httpx/_multipart.py to fix this consistently if you'd like!

[oiltea94]

I reproduced the missing exception on Windows 11 with Python 3.15.1, using HTTPX source at b5addb64f0161ff6bfe94c124ef76f6a1fba5254 (so this is an additional environment, not a reproduction on your exact Python 3.13 setup). No HTTP requests were sent.

The distinguishing factor appears to be the temporary-file wrapper, rather than an empty file:

import io
import tempfile

with tempfile.TemporaryFile(mode="w") as upload:
    print(type(upload).__name__, isinstance(upload, io.TextIOBase))
    print(type(upload.file).__name__, isinstance(upload.file, io.TextIOBase))

On this Windows environment, the first line reports _TemporaryFileWrapper False; the underlying file is a TextIOWrapper and reports True. Python documents that TemporaryFile aliases NamedTemporaryFile on non-POSIX/non-Cygwin platforms.

The FileField constructor checks io.StringIO and io.TextIOBase, so the wrapper misses both guards. My checks produced:

Input	Observed result
Empty TemporaryFile(mode="w") wrapper	Request construction accepted
That wrapper's underlying .file (diagnostic only)	TypeError
Nonempty TemporaryFile(mode="w+"), including request.read()	Accepted
TemporaryFile(mode="w+b")	Accepted
Ordinary file opened with open(..., "w")	TypeError
io.StringIO	TypeError

For regression coverage, explicitly using NamedTemporaryFile(mode="w") would exercise the wrapper case on POSIX too. I would retain binary-file and custom binary-file-like controls when evaluating a stricter guard. The nonempty w+ case is useful evidence that this is not just an empty-stream optimization.

I cannot speak for the maintainers about accepting a PR, but these results narrow down the behavior your proposed change would need to cover.

[Az-yaro]

Thank you so much for this incredible, detailed breakdown! 

The point about _TemporaryFileWrapper masking the underlying file object on non-POSIX platforms explains the platform discrepancy perfectly. That completely clarifies why the io.TextIOBase check is missed on Windows. 

I am working on a patch locally to address the wrapper case while preserving the existing controls for binary files and custom file-like objects. I will also incorporate NamedTemporaryFile(mode="w") into the test suite as suggested to ensure regression coverage across all platforms. 

Once I have the local implementation passing formatting, type checks, and tests, I'll check back here or link a draft PR. Thanks again for narrowing down the behavior so precisely!

[lovelydinosaur]

The typing for this in hip is much more carefully constrained.

Compare:

url = "https://www.example.com"
with tempfile.TemporaryFile(mode="w") as upload:
    files = {"file": ("test.txt", upload, "text/plain")}
    req = httpx.Request("POST", url, files=files)

To:

url = "https://www.example.com"
content = hip.MultiPart({"file": hip.File("test.txt")})
req = hip.Request("POST", url, content=content)

[Az-yaro]

That design makes complete sense! Forcing explicit initialization via hip.File definitely eliminates these edge cases by design rather than relying on weak runtime type guessing on varying platforms. 

Since this issue is causing a failure in the current HTTPX unit test suite on Windows (test_multipart_encode_files_raises_exception_with_text_mode_file), would you still welcome a small, isolated patch to httpx/_multipart.py to handle the _TemporaryFileWrapper mismatch and get the legacy test suite back to 100% green on Windows? Or do you prefer to leave it as-is given the architectural shift?