Defaultdict docs could be clearer
还没有人认领这个 Issue。
- 主要语言
- Python
- 星标
- 77.2k
- 派生
- 35.9k
- PR 合并指标
- PR 指标待抓取
描述
Documentation
The first three paragraphs of the current defaultdict class docs currently read:
Return a new dictionary-like object. defaultdict is a subclass of the built-in dict class. It overrides one method and adds one writable instance variable. The remaining functionality is the same as for the dict class and is not documented here.
The first argument provides the initial value for the default_factory attribute; it defaults to None. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.
defaultdicts are generic over two types, signifying (respectively) the types of the dictionary’s keys and values.
Nowhere in this do we learn about what the defaultdict does differently from dict. We don't even learn what the default_factory parameter is. In fact, the description of the default_factory attribute is decidedly uninformative as well:
This attribute is used by the missing() method; it is initialized from the first argument to the constructor, if present, or to None, if absent.
Basically, I need to read the documentation of the dunder method __missing__ to learn what imo should be stated somewhere at the top earlier.
Suggestions:
- Have a few beginner-friendly introductory sentences that explain in plain language what defaultdict is / how its behaviour differs from dict.
For example, the first sentence of the namedtuple section is
"Named tuples assign meaning to each position in a tuple and allow for more readable, self-documenting code." The utility / motivation for defaultdict is explained well in the Examples section so that doesn't need to be stated (and it feels hard to state its utility without examples).
- Expand the
default_factoryattribute documentation so it is more standalone. At the very least it should state that it should be a callable? The fact that thedefault_factoryparameter must be a callable (or None) should also be stated up top, since the code otherwise throws a TypeError.
Some previous discussions: #131490, #85787 #53745
Happy to try a PR. :-)
Linked PRs
- gh-157033
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
调研方向
从 issue 中链接的当前 defaultdict 类文档开始,将其介绍段落和 default_factory 属性说明与所要求的改进进行比较。完成的标准是:文档解释 defaultdict 与 dict 的区别,将 default_factory 描述为可调用对象或 None,并提供一份独立的说明,无需读者从 missing() 开始阅读。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- python
- 领域
- documentation
- Issue 类型
- 文档
- 难度
- 2/5
- 预计耗时
- 1-3 小时
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100