Document exceptions raised by send_frame et al. #11234

DoctorJohn · 2025-06-22T15:40:37Z

What do these changes do?

This PR updates the web reference docs of aiohttp.web.WebSocketResponse.send_frame et al. with previously missing :raise declarations.

Most notably, send_frame, send_str, send_bytes, and send_json all raise aiohttp.ClientConnectionResetError, which was previously undocumented. Additionally, it was not documented that send_frame may raise a RuntimeError if the connection is not started yet.

For reference, here are the relevant code snippets:

send_frame raising RuntimeError if the connection is not started yet:

aiohttp/aiohttp/web_ws.py

Lines 405 to 411 in 7c3afd2

    
           async def send_frame( 
        
               self, message: bytes, opcode: WSMsgType, compress: Optional[int] = None 
        
           ) -> None: 
        
               """Send a frame over the websocket.""" 
        
               if self._writer is None: 
        
                   raise RuntimeError("Call .prepare() first") 
        
               await self._writer.send_frame(message, opcode, compress)

send_frame et al. raising aiohttp.ClientConnectionResetError if the connection is closing:

aiohttp/aiohttp/_websocket/writer.py

Lines 71 to 72 in 7c3afd2

    
           if self._closing and not (opcode & WSMsgType.CLOSE): 
        
               raise ClientConnectionResetError("Cannot write to closing transport")

aiohttp/aiohttp/_websocket/writer.py

Lines 125 to 126 in 7c3afd2

    
           if self.transport.is_closing(): 
        
               raise ClientConnectionResetError("Cannot write to closing transport")

Are there changes in behavior for the user?

No

Is it a substantial burden for the maintainers to support this?

pause

No

Related issue number

n/a

Checklist

I think the code is well written
Unit tests for the changes exist
Documentation reflects the changes
If you provide code modification, please add yourself to CONTRIBUTORS.txt
- The format is <Name> <Surname>.
- Please keep alphabetical order, the file is sorted by names.
Add a new news fragment into the CHANGES/ folder
- name it <issue_or_pr_num>.<type>.rst (e.g. 588.bugfix.rst)
- if you don't have an issue number, change it to the pull request
  number after creating the PR
  - .bugfix: A bug fix for something the maintainers deemed an
    improper undesired behavior that got corrected to match
    pre-agreed expectations.
  - .feature: A new behavior, public APIs. That sort of stuff.
  - .deprecation: A declaration of future API removals and breaking
    changes in behavior.
  - .breaking: When something public is removed in a breaking way.
    Could be deprecated in an earlier release.
  - .doc: Notable updates to the documentation structure or build
    process.
  - .packaging: Notes for downstreams about unobvious side effects
    and tooling. Changes in the test invocation considerations and
    runtime assumptions.
  - .contrib: Stuff that affects the contributor experience. e.g.
    Running tests, building the docs, setting up the development
    environment.
  - .misc: Changes that are hard to assign to any of the above
    categories.
- Make sure to use full sentences with correct case and punctuation,
  for example:
```
Fixed issue with non-ascii contents in doctest text files
-- by :user:`contributor-gh-handle`.
```
  Use the past tense or the present tense a non-imperative mood,
  referring to what's changed compared to the last released version
  of this project.

codspeed-hq · 2025-06-22T15:50:06Z

CodSpeed Performance Report

Merging #11234 will not alter performance

_{Comparing DoctorJohn:fix-outdated-docs-on-ws-exceptions (749268f) with master (2dcf534)}

Summary

✅ 59 untouched benchmarks

codecov · 2025-06-22T15:50:22Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.84%. Comparing base (2dcf534) to head (749268f).
Report is 7 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #11234      +/-   ##
==========================================
- Coverage   98.84%   98.84%   -0.01%     
==========================================
  Files         131      131              
  Lines       43280    43280              
  Branches     2328     2328              
==========================================
- Hits        42782    42779       -3     
- Misses        343      346       +3     
  Partials      155      155

Flag	Coverage Δ
CI-GHA	`98.73% <ø> (-0.01%)`	⬇️
OS-Linux	`98.46% <ø> (-0.01%)`	⬇️
OS-Windows	`96.79% <ø> (-0.02%)`	⬇️
OS-macOS	`97.68% <ø> (ø)`
Py-3.10.11	`97.33% <ø> (-0.01%)`	⬇️
Py-3.10.18	`97.81% <ø> (-0.02%)`	⬇️
Py-3.11.13	`98.00% <ø> (-0.01%)`	⬇️
Py-3.11.9	`97.52% <ø> (-0.01%)`	⬇️
Py-3.12.10	`97.62% <ø> (ø)`
Py-3.12.11	`98.10% <ø> (-0.01%)`	⬇️
Py-3.13.3	`98.37% <ø> (ø)`
Py-3.9.13	`97.21% <ø> (-0.01%)`	⬇️
Py-3.9.23	`97.53% <ø> (-0.17%)`	⬇️
Py-pypy7.3.16	`85.17% <ø> (-9.49%)`	⬇️
VM-macos	`97.68% <ø> (ø)`
VM-ubuntu	`98.46% <ø> (-0.01%)`	⬇️
VM-windows	`96.79% <ø> (-0.02%)`	⬇️

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

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

patchback · 2025-07-03T19:54:10Z

Backport to 3.12: 💚 backport PR created

✅ Backport PR branch: patchback/backports/3.12/a83597fa88be7ac7dd5f6081d236d751cb40fe4d/pr-11234

Backported as #11262

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

(cherry picked from commit a83597f)

patchback · 2025-07-03T19:54:27Z

Backport to 3.13: 💚 backport PR created

✅ Backport PR branch: patchback/backports/3.13/a83597fa88be7ac7dd5f6081d236d751cb40fe4d/pr-11234

Backported as #11263

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

(cherry picked from commit a83597f)

…d_frame et al. (#11263) **This is a backport of PR #11234 as merged into master (a83597f).** Co-authored-by: Jonathan Ehwald <github@ehwald.info>

…d_frame et al. (#11262) **This is a backport of PR #11234 as merged into master (a83597f).** Co-authored-by: Jonathan Ehwald <github@ehwald.info>

DoctorJohn requested review from webknjaz and asvetlov as code owners June 22, 2025 15:40

psf-chronographer bot added the bot:chronographer:provided There is a change note present in this PR label Jun 22, 2025

Dreamsorcerer added backport-3.12 Trigger automatic backporting to the 3.12 release branch by Patchback robot backport-3.13 Trigger automatic backporting to the 3.13 release branch by Patchback robot labels Jun 26, 2025

DoctorJohn changed the title ~~Document exceptions raises by send_frame et al.~~ Document exceptions raised by send_frame et al. Jun 27, 2025

DoctorJohn added 2 commits June 27, 2025 22:16

Document exceptions raises by send_frame et al.

142b10e

Add CHANGES files

749268f

DoctorJohn force-pushed the fix-outdated-docs-on-ws-exceptions branch from 8467f50 to 749268f Compare June 27, 2025 20:16

Dreamsorcerer merged commit a83597f into aio-libs:master Jul 3, 2025
40 checks passed

patchback bot pushed a commit that referenced this pull request Jul 3, 2025

Document exceptions raised by send_frame et al. (#11234)

00c2f21

(cherry picked from commit a83597f)

patchback bot mentioned this pull request Jul 3, 2025

[PR #11234/a83597fa backport][3.12] Document exceptions raised by send_frame et al. #11262

Merged

5 tasks

patchback bot pushed a commit that referenced this pull request Jul 3, 2025

Document exceptions raised by send_frame et al. (#11234)

db64df3

(cherry picked from commit a83597f)

patchback bot mentioned this pull request Jul 3, 2025

[PR #11234/a83597fa backport][3.13] Document exceptions raised by send_frame et al. #11263

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Document exceptions raised by send_frame et al. #11234

Document exceptions raised by send_frame et al. #11234

Uh oh!

DoctorJohn commented Jun 22, 2025 •

edited

Loading

Uh oh!

codspeed-hq bot commented Jun 22, 2025 •

edited

Loading

Uh oh!

codecov bot commented Jun 22, 2025 •

edited

Loading

Uh oh!

Uh oh!

patchback bot commented Jul 3, 2025 •

edited

Loading

Uh oh!

patchback bot commented Jul 3, 2025 •

edited

Loading

Uh oh!

Uh oh!

	async def send_frame(
	self, message: bytes, opcode: WSMsgType, compress: Optional[int] = None
	) -> None:
	"""Send a frame over the websocket."""
	if self._writer is None:
	raise RuntimeError("Call .prepare() first")
	await self._writer.send_frame(message, opcode, compress)

	if self._closing and not (opcode & WSMsgType.CLOSE):
	raise ClientConnectionResetError("Cannot write to closing transport")

	if self.transport.is_closing():
	raise ClientConnectionResetError("Cannot write to closing transport")

Uh oh!

Document exceptions raised by send_frame et al. #11234

Document exceptions raised by send_frame et al. #11234

Uh oh!

Conversation

DoctorJohn commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What do these changes do?

Are there changes in behavior for the user?

Is it a substantial burden for the maintainers to support this?

Related issue number

Checklist

Uh oh!

codspeed-hq bot commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #11234 will not alter performance

Summary

Uh oh!

codecov bot commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

patchback bot commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backport to 3.12: 💚 backport PR created

Uh oh!

patchback bot commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backport to 3.13: 💚 backport PR created

Uh oh!

Uh oh!

DoctorJohn commented Jun 22, 2025 •

edited

Loading

codspeed-hq bot commented Jun 22, 2025 •

edited

Loading

codecov bot commented Jun 22, 2025 •

edited

Loading

patchback bot commented Jul 3, 2025 •

edited

Loading

patchback bot commented Jul 3, 2025 •

edited

Loading