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

[patchback]

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.

[codspeed-hq]

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.30%. Comparing base (4ad78b3) to head (00c2f21).
⚠️ Report is 57 commits behind head on 3.12.

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.