python / python/cpython

`enumerate` and `filter` documentation should explicitly mention that they accept any iterable

未关闭
#101,027 3 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

docs
主要语言
Python
星标
77.2k
派生
36k
PR 合并指标
PR 指标待抓取

描述

The documentation of enumerate(iterable, start=0) currently reads:

Return an enumerate object. iterable must be a sequence, an iterator, or some other object which supports iteration. The __next__() method of the iterator returned by enumerate() returns a tuple containing a count (from start which defaults to 0) and the values obtained from iterating over iterable.

This wording dates back to 2002 (commit 38f71973) with minimal changes ('the values obtained' was originally 'the corresponding value obtained', which was slightly more accurate in my opinion). An earlier issue about this paragraph can be found at #66914, though the specific issue at hand, the description of iterable's type, was not really discussed there.

While the parameter name indicates that enumerate accepts any iterable as the first argument, I find it strange that the description explicitly lists

a sequence, an iterator, or some other object which supports iteration

instead of/without actually mentioning 'iterable' and referencing the term's definition in the glossary.

My primary suggestion is to replace (the slightly vague, as it could mean iterable or iterator) 'object which supports iteration' with 'iterable' and a link to the glossary. Additionally, since all iterators are iterables, their mention could also be removed.

Suggestion 1 (with or without a link for 'iterator'):

iterable must be a sequence, an iterator, or some other iterable.

Suggestion 2:

iterable must be a sequence or some other iterable.


filter has a similar situation:

iterable may be either a sequence, a container which supports iteration, or an iterator.

'A container which supports iteration' is quite vague and mildly misleading since other parts of the documentation use the term 'container' for lists and similar types. It also uses 'may' instead of 'must'. I would suggest to use the same wording there as for enumerate.

Linked PRs
  • gh-101771

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

先检查关联的 PR gh-101771,然后查看 enumerate 和 filter 的文档条目及其现有措辞。完成的标准是两个条目都明确描述接受 iterable,并且一致使用所要求的术语表术语。

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

评估

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

把新 issue 发到你的邮箱

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