I’d been carefully following along with this discussion, but didn’t have the time or energy to reply until now due to my cat’s health situation, sorry.
It seems the core implication here is that deliberately not explicitly documenting return types is a common pattern in the modern Python stdlib docs. However, I had trouble finding other examples of this, both from memory and spending a fair bit of time browsing for such—all of the many examples I found had such classes explicitly documented in the module using the standard Sphinx syntax. Could you point out some examples of common functions with similarly undocumented return types that follow this pattern? [1]
Overall, I can understand the theoretical motivation, but to me it seems purity on this point comes at the expense of the practical need for explicit, consistent, structured, and precise API reference documentation. And pragmatically, it is unclear to me what practical harm explicitly documenting the return type and its existing publicly-mentioned attributes (leaving source undocumented, at least for now [2]) would have when it comes to duck-typing compatibility—the only thing additional being “exposed” is the name of the class (which is already relied on regardless by pytest, typeshed/type checkers and other users). In turn, this would only make a difference if:
- The old-named name was completely removed even as an alias, or the new class did not inherit from it, and
- User code was, for whatever reason, relying on
isinstancechecks for that name or inheriting from it, and - Users would not have done so without seeing it explicitly documented in the documentation, as opposed to in typeshed/type checkers, via
dir(warnings),type(warnings.catchwarnings()), etc.
ISTM that this seems a relatively narrow hypothetical scenario to be concerned about, particularly relative to the existing real-world usage (and breakage that would result anyway), the complexity of defining/documenting (and having existing downstream code and type annotations switch to using) a new Protocol/ABC, and the benefits of explicitly documenting the public attributes of the class using the standard, consistent structured mechanisms.
The only generally similar cases that immediately came to mind for me was file-like object and path-like object, but those do indeed have explicit class-based (ABC) definitions (the former under
io, the latter asos.PathLike, in addition to linked glossary entries, as well as a strong, widely-used and practical motivation for defining them as protocols (as they are implemented by many different classes across the stdlib and third party packages, not to mention accepted by countless other APIs). ↩︎properly documenting the public attributes but not
sourcemakes it more explicit, if anything, thatsourceis an undocumented detail ↩︎