python / python/cpython

Move `ContextManager` and `AsyncContextManager` type hinting docs from `typing` to `contextlib`

Đang mở
#123,584 0 bình luận 3 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

PEP585 deprecated typing.ContextManager and typing.AsyncContextManager in favour of their contextlib counterparts. However, contextlib documentation lacks any type hinting information and does not even list generic parameters.

Several relevant changes were discussed along #123523.

Currently there's no backlink from contextlib to typing docs, hence users don't have any trivial way to discover type parameters of ContextManager (that's worse than collections.abc.Generator where such a link exists).

Similarly to #123583, I propose to add a "Type hinting" section to both of them in contextlib documentation:

.. class:: AbstractContextManager

   An :term:`abstract base class` for classes that implement
   :meth:`object.__enter__` and :meth:`object.__exit__`. A default
   implementation for :meth:`object.__enter__` is provided which returns
   ``self`` while :meth:`object.__exit__` is an abstract method which by default
   returns ``None``. See also the definition of :ref:`typecontextmanager`.

   :class:`!AbstractContextManager` can be used in type annotations and accepts
   two type parameters: ``AbstractContextManager[T_co, ExitT_co]``. 
   The first type parameter, ``T_co``, represents the type returned by
   the :meth:`~object.__enter__` method. The optional second type parameter, 
   ``ExitT_co``, which defaults to ``bool | None``, represents the type 
   returned by the :meth:`~object.__exit__` method.

   .. versionadded:: 3.6

   .. versionchanged:: 3.13
      Added the optional second type parameter, ``ExitT_co``.

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 với các mục ContextManager và AsyncContextManager hiện có trong tài liệu contextlib, sau đó xem lại cuộc thảo luận liên quan trong #123523 và tài liệu typing được liên kết. Thêm các phần Type hinting được yêu cầu và các liên kết ngược cho các tham số generic, bao quát cả hai kiểu context manager và các đối số kiểu được tài liệu hóa của chú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
52/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.