python / python/cpython

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

Ouverte
#123,584 0 commentaires 3 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

docs topic-typing
Langage dominant
Python
Étoiles
77.2k
Forks
35.9k
Métriques de merge des PR
Métriques de PR en attente

Description

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``.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par les entrées existantes de ContextManager et AsyncContextManager dans la documentation de contextlib, puis examinez la discussion associée dans #123523 ainsi que la documentation de typing liée. Ajoutez les sections de Type hinting demandées et les liens de retour pour les paramètres génériques, en couvrant les deux types de gestionnaires de contexte et leurs arguments de type documentés.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
documentation
Type d'issue
Documentation
Difficulté
2/5
Temps estimé
1-3 heures
Activité
À l'abandon
Clarté
Clairement spécifiée
Accessibilité débutants
52/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.