docs: Add exception handling guidance for background tasks

[tsayin4]

What do these changes do?

Adds documentation and runnable examples explaining how to handle exceptions in background tasks created with asyncio.create_task().

The changes address a common pitfall where developers use fire-and-forget task patterns with aiohttp requests, unaware that exceptions raised in background tasks do not propagate to the spawning context. This can lead to silent failures in production systems.

Are there changes in behavior for the user?

No behavioral changes to the library. This is documentation-only.

Users will now find:

• A clear warning in the quickstart guide about background task exception handling
• A dedicated section in the advanced guide explaining the semantics
• A runnable example demonstrating both unsafe and safe patterns

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

No. This is purely additive documentation with no code changes.

• No new APIs or features to maintain
• The example follows existing aiohttp patterns (proper response release, standard ClientSession usage)
• The documented patterns are already recommended best practices in the asyncio ecosystem
• Future maintenance burden is minimal: updates would only be needed if asyncio exception semantics or aiohttp background task guidance changes

Related issue number

No existing issue. This addresses a documentation gap identified through production experience.

Checklist

• I think the code is well written
• Unit tests for the changes exist (N/A - documentation only)
• Documentation reflects the changes
• If you provide code modification, please add yourself to CONTRIBUTORS.txt
  • Will add after PR number is assigned
• Add a new news fragment into the CHANGES/ folder

• Will add after PR number is assigned

[tsayin4]

Added news fragment and contributor entry.

[codspeed-hq]

CodSpeed Performance Report

Merging #11870 will not alter performance

_{Comparing tsayin4:docs-background-task-exceptions (3a88a79) with master (c3b08f7)}

Summary

✅ 59 untouched

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.75%. Comparing base (c3b08f7) to head (3a88a79).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #11870   +/-   ##
=======================================
  Coverage   98.74%   98.75%           
=======================================
  Files         127      127           
  Lines       44172    44172           
  Branches     2342     2342           
=======================================
+ Hits        43619    43620    +1     
  Misses        392      392           
+ Partials      161      160    -1     

Flag	Coverage Δ
CI-GHA	98.60% <ø> (+<0.01%)	⬆️
OS-Linux	98.34% <ø> (ø)
OS-Windows	96.68% <ø> (ø)
OS-macOS	97.57% <ø> (+<0.01%)	⬆️
Py-3.10.11	97.11% <ø> (+<0.01%)	⬆️
Py-3.10.19	97.60% <ø> (ø)
Py-3.11.14	97.81% <ø> (ø)
Py-3.11.9	97.32% <ø> (ø)
Py-3.12.10	97.41% <ø> (ø)
Py-3.12.12	97.91% <ø> (ø)
Py-3.13.11	98.16% <ø> (ø)
Py-3.14.2	98.17% <ø> (-0.01%)	⬇️
Py-3.14.2t	97.25% <ø> (+<0.01%)	⬆️
Py-pypy3.11.13-7.3.20	97.41% <ø> (+<0.01%)	⬆️
VM-macos	97.57% <ø> (+<0.01%)	⬆️
VM-ubuntu	98.34% <ø> (ø)
VM-windows	96.68% <ø> (ø)

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.

[Dreamsorcerer]

As part of the client docs, this doesn't seem like it has anything to do with aiohttp? This feels like general asyncio knowledge and should appear in the asyncio.create_task() docs.

For the server docs, we already have:
https://docs.aiohttp.org/en/stable/web_advanced.html#background-tasks
https://docs.aiohttp.org/en/stable/web_advanced.html#complex-applications
https://docs.aiohttp.org/en/stable/web_advanced.html#web-handler-cancellation

[tsayin4]

Thanks for the feedback — I agree that the underlying semantics are defined by asyncio, not aiohttp.

The motivation for placing this in the aiohttp client documentation is not to re-document asyncio.create_task(), but to address a specific pattern that commonly leads to issues in aiohttp client code.

In practice, it's common to see background HTTP requests spawned via asyncio.create_task() to decouple request latency from control flow (e.g., prefetching, warm-up calls, telemetry). When this pattern is combined with aiohttp requests, exceptions raised during the request lifecycle (ClientConnectorError, ClientResponseError, timeouts, etc.) can become invisible to application logic unless explicitly handled.

While this behavior is documented at the asyncio level, many aiohttp users encounter it through aiohttp usage patterns, not through generic asyncio examples. The intent here is to add a narrowly scoped warning at the point where aiohttp users are most likely to adopt this pattern.

That said, I'm happy to:

• Narrow the wording to focus strictly on aiohttp client exceptions
• Reduce the section to a brief warning with a reference to asyncio docs
• Close the PR if you feel this is better addressed elsewhere

Please let me know what approach would fit best with the docs structure.

[Dreamsorcerer]

In practice, it's common to see background HTTP requests spawned via asyncio.create_task() to decouple request latency from control flow (e.g., prefetching, warm-up calls, telemetry).

This still feels like it could apply to anything they are using, so I'm not really convinced. Your second example also creates a task and then immediately awaits on it, which entirely defeats the point. .add_done_callback() is also not something I think we should be recommending; I'd instead point users towards aiojobs until a similar thing arrives in asyncio itself.

@webknjaz @bdraco Do you think this is something that should be included in our docs?

[tsayin4]

Thanks for the detailed feedback — this is helpful.

I agree on a couple of points:

• You're right that the semantics themselves are asyncio-level, not aiohttp-specific.
• You're also right that the example that immediately awaits the task is redundant — that defeats the purpose and should be removed.

The intent here isn't to recommend create_task() patterns broadly, but to address a footgun that aiohttp client users frequently run into when doing background HTTP work (telemetry, warm-up calls, best-effort side requests), where aiohttp-specific exceptions (ClientConnectorError, timeouts, response errors) end up being silently lost.

That said, I think your suggestion about aiojobs is a much better direction and makes this genuinely aiohttp-scoped rather than generic asyncio guidance.

I'm happy to revise this PR to:

• Remove the await task example entirely
• Avoid recommending add_done_callback()
• Frame this explicitly as: "If you need background HTTP tasks with proper failure visibility, prefer aiojobs rather than raw create_task()"
• Reduce the content to a short warning + pointer instead of a long section

Something along the lines of:

"Fire-and-forget background HTTP requests using asyncio.create_task() can lead to silent failures. For structured background task management, prefer aiojobs, which integrates with aiohttp and provides explicit exception handling."

Let me know if this direction works—I'm happy to revise accordingly, or if you'd still prefer I close this given the scope concerns, I completely understand.