python / python/cpython

Clarifying documentation of typing.Set

オープン
#93,579 コメント 4 件 リアクション 1 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

3.10 3.11 3.12 docs topic-typing
主要言語
Python
スター
77.2k
フォーク
36k
PR マージ指標
PR 指標を取得中

説明

Documentation

Edit: I added some more clarification.

Documentation of typing.Set is not entirely clear

The typing module's documentation currently requires two hops when the reader looks up typing.Set.

  1. In the docstring of typing.Set it states "To annotate arguments it is preferred to use an abstract collection type such as AbstractSet." This is referring to typing.AbstractSet
  2. Docstring of typing.AbstractSet says that it is deprecated and refers the reader to collections.abc.Set, which has no docstring of its own (it is grouped together with the docstring of collections.abc.MutableSet.
    I feel we can prevent these two hops i.e. typing.Set --> typing.AbstractSet --> collections.abc.Set and direct the reader to the final destination i.e. typing.Set -> collections.abc.Set.

Suggested change

  1. typing.Set should say something like --

"To annotate arguments it is preferred to use an abstract collection type such as collections.abc.Set.
"To annotate everything else, the use of typing.Set is deprecated since version 3.9: builtins.set now supports []. See PEP 585 and Generic Alias Type"

  1. Docstring of typing.AbstractSet is fine as it is.
  2. collections.abc.Set should say something like --

"Use this to annotate arguments. For all other annotations, use builtins.set, which now supported []. See PEP 585 ...

Other generic alias types like List, Tuple, FrozenSet etc. probably could use a similar change (IF others agree that this is something that needs to changed at all.)

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

typing.Set と collections.abc.Set の docstring から始め、関連するジェネリックエイリアスのドキュメントと PEP 585 の指針を比較してください。完了条件は、ドキュメントが追加の中間ステップなしで読者を typing.Set から collections.abc.Set に誘導し、builtins.set をいつ使用するかを明確に説明していることです。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
documentation
issue の種類
ドキュメント
難易度
2/5
見積もり時間
1〜3時間
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。