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

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

This is a backport of PR #11234 as merged into master (a83597f).

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.

(cherry picked from commit a83597f)

codspeed-hq · 2025-07-03T20:04:57Z

CodSpeed Performance Report

Merging #11262 will not alter performance

_{Comparing patchback/backports/3.12/a83597fa88be7ac7dd5f6081d236d751cb40fe4d/pr-11234 (00c2f21) with 3.12 (4ad78b3)}

Summary

✅ 59 untouched benchmarks

codecov · 2025-07-03T20:09:50Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.30%. Comparing base (4ad78b3) to head (00c2f21).
Report is 1 commits behind head on 3.12.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             3.12   #11262      +/-   ##
==========================================
- Coverage   98.31%   98.30%   -0.02%     
==========================================
  Files         132      132              
  Lines       43506    43506              
  Branches     2380     2380              
==========================================
- Hits        42775    42769       -6     
- Misses        555      561       +6     
  Partials      176      176

Flag	Coverage Δ
CI-GHA	`98.20% <ø> (-0.02%)`	⬇️
OS-Linux	`97.94% <ø> (-0.02%)`	⬇️
OS-Windows	`95.65% <ø> (-0.01%)`	⬇️
OS-macOS	`97.20% <ø> (ø)`
Py-3.10.11	`96.60% <ø> (-0.25%)`	⬇️
Py-3.10.18	`97.33% <ø> (-0.01%)`	⬇️
Py-3.11.13	`?`
Py-3.11.9	`96.80% <ø> (-0.25%)`	⬇️
Py-3.12.10	`97.13% <ø> (ø)`
Py-3.12.11	`97.62% <ø> (ø)`
Py-3.13.3	`97.85% <ø> (-0.03%)`	⬇️
Py-3.9.13	`96.74% <ø> (ø)`
Py-3.9.23	`97.22% <ø> (ø)`
Py-pypy7.3.16	`88.64% <ø> (-0.04%)`	⬇️
VM-macos	`97.20% <ø> (ø)`
VM-ubuntu	`97.94% <ø> (-0.02%)`	⬇️
VM-windows	`95.65% <ø> (-0.01%)`	⬇️

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.

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

00c2f21

(cherry picked from commit a83597f)

patchback bot requested review from webknjaz and asvetlov as code owners July 3, 2025 19:54

patchback bot mentioned this pull request Jul 3, 2025

Document exceptions raised by send_frame et al. #11234

Merged

5 tasks

Dreamsorcerer merged commit 133e254 into 3.12 Jul 3, 2025
36 checks passed

Dreamsorcerer deleted the patchback/backports/3.12/a83597fa88be7ac7dd5f6081d236d751cb40fe4d/pr-11234 branch July 3, 2025 20:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

Uh oh!

patchback bot commented Jul 3, 2025

Uh oh!

codspeed-hq bot commented Jul 3, 2025

Uh oh!

codecov bot commented Jul 3, 2025 •

edited

Loading

Uh oh!

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!

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

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

Uh oh!

Conversation

patchback bot commented Jul 3, 2025

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 Jul 3, 2025

CodSpeed Performance Report

Merging #11262 will not alter performance

Summary

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jul 3, 2025 •

edited

Loading