python / python/cpython

List generic arguments for `collections.abc` base classes in documentation

Đang mở
#123,583 3 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

docs topic-typing
Ngôn ngữ chính
Python
Star
77.2k
Fork
35.9k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

Documentation

When #123544 lands, we'll have PEP585-related documentation spread even further than before. Deprecated aliases in typing correctly list the generic arguments, but are otherwise undocumented - all such entries boil down to "deprecated in favour of collections.abc.X".

Several relevant changes were discussed along #123523.

There's no direct way for a user to find generic parameters of collections.abc.Generator - they are listed for typing.Generator and in "annotating generators and coroutines" section in typing docs (the latter linked from collections.abc.Generator, though).

I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.

However, collections.abc is not really a type-hinting module, hence providing those signatures there directly can add too much cognitive load.

As of now, my best suggestion is to introduce "Type parameters" section for each generic alias there, like this:

.. class:: Mapping
           MutableMapping

   ABCs for read-only and mutable :term:`mappings <mapping>`.

   Type arguments:

   * ``Mapping[KT, VT_co](Collection[KT])``
   * ``MutableMapping[KT, VT](Mapping[KT, VT])``

cc @AA-Turner and @AlexWaygood - we started this discussion in the PR above.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. 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.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu bằng việc xem xét tài liệu hiện có của collections.abc, các danh sách đối số generic cho những bí danh typing đã lỗi thời và các cuộc thảo luận liên quan trong #123544 và #123523. Thêm các phần Type parameters nhất quán cho những generic alias liên quan, kèm theo các đối số và mối quan hệ của chúng, đồng thời xác minh rằng người dùng có thể tìm thấy thông tin từ các mục collections.abc.

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ó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.