List generic arguments for `collections.abc` base classes in documentation
還沒有人認領這個 Issue。
- 主要語言
- Python
- 星號
- 77.2k
- 分支
- 35.9k
- PR 合併指標
- PR 指標待擷取
描述
Documentation
When #123544 lands, we'll have PEP585-related documentation spread even further than before. Deprecated aliases in typing correctly list the generic arguments, but are otherwise undocumented - all such entries boil down to "deprecated in favour of collections.abc.X".
Several relevant changes were discussed along #123523.
There's no direct way for a user to find generic parameters of collections.abc.Generator - they are listed for typing.Generator and in "annotating generators and coroutines" section in typing docs (the latter linked from collections.abc.Generator, though).
I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.
However, collections.abc is not really a type-hinting module, hence providing those signatures there directly can add too much cognitive load.
As of now, my best suggestion is to introduce "Type parameters" section for each generic alias there, like this:
.. class:: Mapping
MutableMapping
ABCs for read-only and mutable :term:`mappings <mapping>`.
Type arguments:
* ``Mapping[KT, VT_co](Collection[KT])``
* ``MutableMapping[KT, VT](Mapping[KT, VT])``
cc @AA-Turner and @AlexWaygood - we started this discussion in the PR above.
貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
研究方向
先檢閱現有的 collections.abc 文件、已棄用 typing 別名的泛型引數列表,以及 #123544 和 #123523 中的相關討論。為相關的泛型別名新增一致的 Type parameters 區段,列出其引數和關係,並確認使用者可以從 collections.abc 項目中找到這些資訊。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- python
- 領域
- documentation
- Issue 類型
- 文件
- 難度
- 3/5
- 預估耗時
- 1-2 天
- 活躍度
- 停滯
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100