python / python/cpython

typing docs: Use soft deprecation

オープン
#132,941 コメント 8 件 リアクション 5 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

docs topic-typing
主要言語
Python
スター
77.2k
フォーク
36k
PR マージ指標
PR 指標を取得中

説明

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

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

リンク先の Python ドキュメントページにある、タイトルが “Deprecation timeline of major features” の typing ドキュメントセクションから始め、既存の項目を、要求されている soft deprecations と比較してください。ドキュメントが一覧にある古い形式を明確に特定し、それらの新しい代替手段を推奨していれば完了です; 作業はすでに関連付けられているため、まずリンク先の PR gh-154480 を確認してください。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
documentation
issue の種類
ドキュメント
難易度
2/5
見積もり時間
1〜3時間
活発さ
停滞
明瞭さ
明確に書かれている
初心者へのやさしさ
30/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。