Move `ContextManager` and `AsyncContextManager` type hinting docs from `typing` to `contextlib`
Chưa có ai nhận issue này.
- 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
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
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