Add :canonical: directives for intersphinx cross-referencing by danielalanbates · Pull Request #12098 · aio-libs/aiohttp

danielalanbates · 2026-02-20T04:26:29Z

Summary

When other projects use autodoc or intersphinx to reference aiohttp objects, they resolve the fully-qualified module path (e.g. aiohttp.client.ClientSession) from the object's __module__ attribute. Since our docs only document the public aliases (e.g. aiohttp.ClientSession via .. currentmodule:: aiohttp), these cross-references fail with warnings like:

WARNING: py:class reference target not found: aiohttp.client.ClientSession

This PR adds :canonical: directive options to all class, function, and exception directives across the reference documentation. The :canonical: option (available since Sphinx 4.0) tells Sphinx to register each object under both its documented name and its actual module path in the intersphinx inventory, enabling cross-referencing via either path.

Files changed

docs/client_reference.rst — 50 canonical directives (ClientSession, connectors, exceptions, etc.)
docs/web_reference.rst — 50 canonical directives (Request, Response, Application, routing, runners, etc.)
docs/web_exceptions.rst — 57 canonical directives (all HTTP exception classes)
docs/tracing_reference.rst — 17 canonical directives (TraceConfig and all trace param classes)
docs/multipart_reference.rst — 4 canonical directives (MultipartReader, MultipartWriter, etc.)
docs/websocket_utilities.rst — 2 canonical directives (WSCloseCode, WSMsgType)
docs/streams.rst — 1 canonical directive (StreamReader)
CHANGES/10468.doc.rst — changelog entry

How it works

For example, ClientSession is defined in aiohttp.client but documented under .. currentmodule:: aiohttp:

.. class:: ClientSession(base_url=None, *, ...)
   :canonical: aiohttp.client.ClientSession

This registers aiohttp.client.ClientSession as an alias in the Sphinx inventory, so intersphinx lookups from other projects will resolve correctly while the docs continue to display the public API path aiohttp.ClientSession.

Test plan

Verify the docs build successfully with make html (no new warnings)
Verify intersphinx inventory contains both public and canonical names
Test cross-referencing from an external project using autodoc

This PR was created with the assistance of Claude Opus 4.6 by Anthropic. Happy to make any adjustments! Reviewed and submitted by a human.

When other projects use autodoc or intersphinx to reference aiohttp objects, they resolve the fully-qualified module path (e.g. aiohttp.client.ClientSession) rather than the public API path (aiohttp.ClientSession). Since our docs only document the public aliases, these references fail to resolve. This adds :canonical: directive options to all class, function, and exception directives in the reference documentation, mapping each documented object to its actual module path. This allows intersphinx to resolve both the public alias and the internal module path. Fixes aio-libs#10468 Co-Authored-By: Claude Opus 4.6 <[email protected]>

codecov · 2026-02-20T04:33:04Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.77%. Comparing base (5efc6c8) to head (3f737ae).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #12098   +/-   ##
=======================================
  Coverage   98.77%   98.77%           
=======================================
  Files         128      128           
  Lines       44892    44892           
  Branches     2383     2383           
=======================================
+ Hits        44342    44343    +1     
+ Misses        390      389    -1     
  Partials      160      160

Flag	Coverage Δ
CI-GHA	`98.63% <ø> (+<0.01%)`	⬆️
OS-Linux	`98.37% <ø> (ø)`
OS-Windows	`96.71% <ø> (ø)`
OS-macOS	`97.61% <ø> (+<0.01%)`	⬆️
Py-3.10.11	`97.16% <ø> (ø)`
Py-3.10.19	`97.64% <ø> (-0.01%)`	⬇️
Py-3.11.14	`97.84% <ø> (-0.01%)`	⬇️
Py-3.11.9	`97.37% <ø> (+<0.01%)`	⬆️
Py-3.12.10	`97.46% <ø> (ø)`
Py-3.12.12	`97.94% <ø> (ø)`
Py-3.13.11	`97.94% <ø> (+<0.01%)`	⬆️
Py-3.13.12	`97.43% <ø> (-0.09%)`	⬇️
Py-3.14.2	`97.90% <ø> (ø)`
Py-3.14.3	`97.39% <ø> (-0.75%)`	⬇️
Py-3.14.3t	`97.24% <ø> (ø)`
Py-pypy3.11.13-7.3.20	`97.38% <ø> (+<0.01%)`	⬆️
VM-macos	`97.61% <ø> (+<0.01%)`	⬆️
VM-ubuntu	`98.37% <ø> (ø)`
VM-windows	`96.71% <ø> (ø)`

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.

codspeed-hq · 2026-02-20T04:33:08Z

Merging this PR will not alter performance

✅ 59 untouched benchmarks

_{Comparing danielalanbates:fix/issue-10468 (3f737ae) with master (e458a83)}

patchback · 2026-02-20T17:00:58Z

Backport to 3.13: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply 345ac4d on top of patchback/backports/3.13/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098

Backporting merged PR #12098 into master

Ensure you have a local repo clone of your fork. Unless you cloned it
from the upstream, this would be your origin remote.
Make sure you have an upstream repo added as a remote too. In these
instructions you'll refer to it by the name upstream. If you don't
have it, here's how you can add it:
```
$ git remote add upstream https://github.com/aio-libs/aiohttp.git
```

Ensure you have the latest copy of upstream and prepare a branch
that will hold the backported code:

$ git fetch upstream
$ git checkout -b patchback/backports/3.13/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098 upstream/3.13

Now, cherry-pick PR Add :canonical: directives for intersphinx cross-referencing #12098 contents into that branch:
```
$ git cherry-pick -x 345ac4df3f41e3975a1daa8788a01ec6ff9483bb
```
If it'll yell at you with something like fatal: Commit 345ac4df3f41e3975a1daa8788a01ec6ff9483bb is a merge but no -m option was given., add -m 1 as follows instead:
```
$ git cherry-pick -m1 -x 345ac4df3f41e3975a1daa8788a01ec6ff9483bb
```
At this point, you'll probably encounter some merge conflicts. You must
resolve them in to preserve the patch from PR Add :canonical: directives for intersphinx cross-referencing #12098 as close to the
original as possible.

Push this branch to your fork on GitHub:

$ git push origin patchback/backports/3.13/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098

Create a PR, ensure that the CI is green. If it's not — update it so that
the tests and any other checks pass. This is it!
Now relax and wait for the maintainers to process your pull request
when they have some cycles to do reviews. Don't worry — they'll tell you if
any improvements are necessary when the time comes!

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

patchback · 2026-02-20T17:01:06Z

Backport to 3.14: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply 345ac4d on top of patchback/backports/3.14/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098

Backporting merged PR #12098 into master

Ensure you have a local repo clone of your fork. Unless you cloned it
from the upstream, this would be your origin remote.
Make sure you have an upstream repo added as a remote too. In these
instructions you'll refer to it by the name upstream. If you don't
have it, here's how you can add it:
```
$ git remote add upstream https://github.com/aio-libs/aiohttp.git
```

Ensure you have the latest copy of upstream and prepare a branch
that will hold the backported code:

$ git fetch upstream
$ git checkout -b patchback/backports/3.14/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098 upstream/3.14

Now, cherry-pick PR Add :canonical: directives for intersphinx cross-referencing #12098 contents into that branch:
```
$ git cherry-pick -x 345ac4df3f41e3975a1daa8788a01ec6ff9483bb
```
If it'll yell at you with something like fatal: Commit 345ac4df3f41e3975a1daa8788a01ec6ff9483bb is a merge but no -m option was given., add -m 1 as follows instead:
```
$ git cherry-pick -m1 -x 345ac4df3f41e3975a1daa8788a01ec6ff9483bb
```
At this point, you'll probably encounter some merge conflicts. You must
resolve them in to preserve the patch from PR Add :canonical: directives for intersphinx cross-referencing #12098 as close to the
original as possible.

Push this branch to your fork on GitHub:

$ git push origin patchback/backports/3.14/345ac4df3f41e3975a1daa8788a01ec6ff9483bb/pr-12098

Create a PR, ensure that the CI is green. If it's not — update it so that
the tests and any other checks pass. This is it!
Now relax and wait for the maintainers to process your pull request
when they have some cycles to do reviews. Don't worry — they'll tell you if
any improvements are necessary when the time comes!

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

Dreamsorcerer · 2026-02-20T17:02:18Z

Thanks. If you could follow those instructions to create backports, that'd be really helpful.

danielalanbates requested review from asvetlov and webknjaz as code owners February 20, 2026 04:26

psf-chronographer bot added the bot:chronographer:provided There is a change note present in this PR label Feb 20, 2026

Dreamsorcerer added backport-3.13 Trigger automatic backporting to the 3.13 release branch by Patchback robot backport-3.14 Trigger automatic backporting to the 3.14 release branch by Patchback robot labels Feb 20, 2026

Update 10468.doc.rst

3f737ae

Dreamsorcerer merged commit 345ac4d into aio-libs:master Feb 20, 2026
43 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add :canonical: directives for intersphinx cross-referencing#12098

Add :canonical: directives for intersphinx cross-referencing#12098
Dreamsorcerer merged 2 commits intoaio-libs:masterfrom
danielalanbates:fix/issue-10468

danielalanbates commented Feb 20, 2026

Uh oh!

codecov bot commented Feb 20, 2026 •

edited

Loading

Uh oh!

codspeed-hq bot commented Feb 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

patchback bot commented Feb 20, 2026 •

edited

Loading

Uh oh!

patchback bot commented Feb 20, 2026 •

edited

Loading

Uh oh!

Dreamsorcerer commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

danielalanbates commented Feb 20, 2026

Summary

Files changed

How it works

Test plan

Uh oh!

codecov bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Uh oh!

patchback bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backport to 3.13: 💔 cherry-picking failed — conflicts found

Backporting merged PR #12098 into master

Uh oh!

patchback bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Backport to 3.14: 💔 cherry-picking failed — conflicts found

Backporting merged PR #12098 into master

Uh oh!

Dreamsorcerer commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Feb 20, 2026 •

edited

Loading

codspeed-hq bot commented Feb 20, 2026 •

edited

Loading

patchback bot commented Feb 20, 2026 •

edited

Loading

patchback bot commented Feb 20, 2026 •

edited

Loading