Add optional charset parameter to web.FileResponse

[pctablet505]

Fixes #4559

Adds an optional charset parameter to web.FileResponse so callers can set an explicit charset on the response content-type.

[codspeed-hq]

Merging this PR will not alter performance

✅ 83 untouched benchmarks
⏩ 83 skipped benchmarks¹

---

_{Comparing pctablet505:fix-4559-fileresponse-charset (093f651) with master (cba121d)}

Footnotes

1. 83 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.97%. Comparing base (cba121d) to head (093f651).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #13151   +/-   ##
=======================================
  Coverage   98.97%   98.97%           
=======================================
  Files         131      131           
  Lines       48824    48856   +32     
  Branches     2546     2547    +1     
=======================================
+ Hits        48324    48356   +32     
  Misses        376      376           
  Partials      124      124           

Flag	Coverage Δ
Autobahn	22.11% <9.37%> (-0.01%)	⬇️
CI-GHA	98.90% <100.00%> (+<0.01%)	⬆️
OS-Linux	98.67% <100.00%> (+<0.01%)	⬆️
OS-Windows	97.03% <100.00%> (+<0.01%)	⬆️
OS-macOS	97.93% <100.00%> (+<0.01%)	⬆️
Py-3.10	98.12% <100.00%> (+<0.01%)	⬆️
Py-3.11	98.38% <100.00%> (+<0.01%)	⬆️
Py-3.12	98.46% <100.00%> (-0.01%)	⬇️
Py-3.13	98.45% <100.00%> (+<0.01%)	⬆️
Py-3.14	98.47% <100.00%> (+<0.01%)	⬆️
Py-3.14t	97.56% <100.00%> (+<0.01%)	⬆️
Py-pypy-3.11	97.43% <100.00%> (-0.01%)	⬇️
VM-macos	97.93% <100.00%> (+<0.01%)	⬆️
VM-ubuntu	98.67% <100.00%> (+<0.01%)	⬆️
VM-windows	97.03% <100.00%> (+<0.01%)	⬆️
cython-coverage	37.86% <3.12%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[Dreamsorcerer]

@aiolibsbot review

[aiolibsbot]

PR Review — Add optional charset parameter to web.FileResponse

Clean, well-scoped addition of an optional charset parameter to FileResponse. Merge-ready; one design nit to consider.

Strengths:

• The startswith("text/") guard correctly sidesteps the charset setter's RuntimeError on application/octet-stream (web_response.py:239), so binary files won't crash.

• Charset block is placed outside the CONTENT_TYPE not in headers branch, so it also applies when the content-type is user-supplied via headers — sensible.

• Good test coverage: parametrized text cases plus an explicit non-text "ignored" case; changelog fragment and docs param both included.

• Suggestion: the text/ prefix restriction silently ignores charset for application/json/xml/javascript and +xml/+json types, which is narrower than an explicitly-passed parameter suggests — documented, so a maintainer call rather than a blocker.

---

🟢 Suggestions

1. `charset` silently ignored for non-`text/` text-based media types
aiohttp/web_fileresponse.py:388-389

The guard self.content_type.startswith("text/") means an explicitly-passed charset is silently dropped for media types that are genuinely text and legitimately carry a charset but do not live under the text/ tree — notably application/json, application/xml, application/javascript, and image/svg+xml.

Why it matters: a caller serving a .json static file with charset="utf-8" will get back application/json with no charset and no error, which is surprising for an explicitly-supplied parameter. Since static JSON/XML/JS files are a common FileResponse use case, the restriction is narrower than users may expect.

The startswith("text/") check does serve a real purpose — it protects against the charset setter raising RuntimeError on application/octet-stream (see web_response.py:239). So you can't just drop the guard.

Options:

• Broaden the predicate to cover known text-based types (e.g. also allow application/json, application/xml, +xml/+json suffixes, application/javascript).
• Or keep the narrow scope but the docs already say "text-like MIME types (e.g. text/plain)", so this is defensible as-is — worth a maintainer decision.

Non-blocking; the current behavior is documented and internally consistent.

if self._charset is not None and self.content_type.startswith("text/"):
    self.charset = self._charset

---

Checklist

• New behavior covered by tests
• Charset setter RuntimeError avoided for binary types
• Docs and changelog updated for public API change
• API scope matches user expectations — suggestion ＃1

---

Automated review by Kōan (Claude) HEAD=093f651 1 min 47s

[Dreamsorcerer]

charset silently ignored for non-text/ text-based media types

Yeah, this is what was standing out to me as a bit odd. I'm not sure this is the right design. I'm also wondering about getting the charset automatically..