Pretty-print magic methods. #5702
Description
Motivation
When autodoc generates docs for magic methods like __str__ or __getitem__, it displays the method signatures the same way as for any other method. However, this is not how magic methods are typically used, and the literal names may not be the best way to document them.
Proposal
Instead of displaying the literal names of magic methods, display them as they would be used: for instance, len(self) instead of __len__(). This is what the Python documentation does for builtin types. It's possible to do this manually, as Python has, but it would be both more convenient and more consistent for it to be done by an optional feature or extension.
Selected Examples
| Method | Displayed signature |
|---|---|
__len__ |
len(self) |
__setitem__(key, value) |
self[key] = value |
__contains__(item) |
item in self |
__truediv__(other) |
self / other |
Prior Art
The Python docs do this manually in some places, though they are inconsistent.
A library I'm working on does this with a custom extension. The implementation is rough, but perhaps it may suffice as a proof of concept.