python / python/cpython

Clarifying documentation of typing.Set

未关闭
#93,579 4 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

3.10 3.11 3.12 docs topic-typing
主要语言
Python
星标
77.2k
派生
36k
平均合并
1 天 9 小时
30 天内合并 PR
558

描述

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. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

先从 typing.Set 和 collections.abc.Set 的文档字符串入手,然后比较相关的泛型别名文档以及 PEP 585 中的指导。完成的标准是:文档将读者从 typing.Set 直接引导至 collections.abc.Set,不再经过额外的中间步骤,并清楚说明何时使用 builtins.set。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
documentation
Issue 类型
文档
难度
2/5
预计耗时
1-3 小时
活跃度
停滞
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。