`enumerate` and `filter` documentation should explicitly mention that they accept any iterable
Chưa có ai nhận issue này.
- Ngôn ngữ chính
- Python
- Star
- 77.2k
- Fork
- 36k
- Merge trung bình
- 1 ngày 9 giờ
- Pull request đã merge (30 ngày)
- 558
Mô tả
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 byenumerate()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
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Hướng nghiên cứu
Trước tiên, hãy kiểm tra PR được liên kết gh-101771, sau đó xem lại các mục tài liệu cho enumerate và filter cùng cách diễn đạt hiện có của chúng. Được xem là hoàn tất khi cả hai mục đều mô tả rõ ràng việc chấp nhận một iterable và sử dụng nhất quán thuật ngữ được yêu cầu trong bảng thuật ngữ.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- documentation
- Loại issue
- Tài liệu
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 30/100