python / python/cpython

typing docs: Use soft deprecation

Aperta
#132,941 8 commenti 5 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

docs topic-typing
Lingua principale
Python
Stelle
77.2k
Fork
35.9k
Metriche di merge delle PR
Metriche PR in attesa

Descrizione

A while ago we introduced the concept of "soft deprecation" in PEP 387 (https://peps.python.org/pep-0387/#soft-deprecation): for things that we no longer recommend using, but which we aren't planning to remove in the near future.

The typing docs already list four classes of objects that are deprecated without a scheduled removal (https://docs.python.org/3.14/library/typing.html#deprecation-timeline-of-major-features):

  • Pre-PEP-585 generic aliases (e.g. List)
  • Text
  • Hashable and Sized
  • TypeAlias

I'd like to also soft-deprecate the following:

  • Optional (obviated by PEP-604)
  • NoReturn (prefer Never)
  • typing.ForwardRef (deprecated alias for annotationlib.ForwardRef)
  • types.UnionType (deprecated alias for typing.Union)
  • Creating a Union using subscripting (Union[A, B] instead of A | B) (PEP-604)
  • Creating a TypeVar, ParamSpec, or TypeVarTuple using the constructor directly (PEP-695)
  • Directly inheriting from Generic (PEP-695)

None of those will be removable for many years if ever, but I think it's useful to have a clear statement in the docs that the newer syntax is preferred.

Linked PRs
  • gh-154480

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Inizia dalla sezione della documentazione di typing intitolata “Deprecation timeline of major features” nella pagina collegata della documentazione di Python e confronta le voci esistenti con le soft deprecations richieste. Il lavoro è completato quando la documentazione identifica chiaramente le forme precedenti elencate e ne raccomanda le alternative più recenti; esamina prima il PR collegato gh-154480, perché il lavoro è già associato a esso.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
2/5
Tempo stimato
1-3 ore
Stato di attività
Ferma
Chiarezza
Specificata chiaramente
Idoneità per principianti
30/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.