typeshed
1.0.0
Typeshed には、Python 標準ライブラリと Python ビルトインの外部型アノテーションのほか、これらのプロジェクトの外部の人々によって提供されたサードパーティ パッケージが含まれています。
このデータは、静的分析、型チェック、型推論、オートコンプリートなどに使用できます。
タイプシェッドの使用方法については、以下をお読みください。貢献者向けの情報は CONTRIBUTING.md にあります。プル リクエストを送信する前に必ずお読みください。アノテーションに関する問題は、スタブが対象となっているプロジェクトに報告するのではなく、ここでタイプシェッドに報告してください。
スタブ ファイル、タイプシェッド、および Python の型指定システム全般に関する詳細なドキュメントは、https://typing.readthedocs.io/en/latest/ で見つけることができます。
Typeshed は、Python バージョン 3.8 から 3.13 をサポートします。
型チェッカー (mypy、pyright、pytype、PyCharm など) を開発するのではなく、単に使用している場合は、タイプシェッド リポジトリと対話する必要はまったくありません。 typeshed は型チェッカーにバンドルされています。また、使用しているサードパーティのパッケージとモジュールのタイプ スタブは、PyPI からインストールできます。たとえば、 html5libとrequests使用している場合、次を使用してタイプ スタブをインストールできます。
$ pip install types-html5lib types-requestsこれらの PyPI パッケージは PEP 561 に従っており、タイプシェッド内部機構によって自動的に (最大 1 日 1 回) リリースされます。
型チェッカーは、インストール時にこれらのスタブ パッケージを使用できる必要があります。詳細については、型チェッカーのドキュメントを参照してください。
サードパーティのスタブ パッケージのバージョン番号は、少なくとも 4 つの部分で構成されます。スタブ バージョンの最後の部分を除くすべての部分は、スタブ化されるランタイム パッケージのバージョンに対応します。たとえば、 types-fooパッケージのバージョンが1.2.0.20240309の場合、これにより、 types-fooパッケージにfoo==1.2.*対象としたスタブが含まれ、その指定子に一致するfooの最新バージョンに対してテストされることが保証されます。この例では、バージョン番号の最後の要素 (20240309) は、スタブ パッケージが 2024 年 3 月 9 日にプッシュされたことを示しています。
typeshed では、破壊的な変更を最小限に抑えるよう努めています。ただし、スタブの性質上、バージョンの変更により、コードの型チェックが失敗する可能性がある変更が導入される可能性があります。
使用しているスタブ パッケージのバージョンを指定する方法はいくつかありますが、それぞれに独自のトレードオフがあります。
スタブ化されるパッケージに使用するのと同じ境界を使用します。たとえば、 requests>=2.30.0,<2.32を使用する場合は、 types-requests>=2.30.0,<2.32を使用できます。これにより、スタブが使用しているパッケージと互換性があることが保証されますが、スタブの変更により型チェックが壊れるという小さなリスクが伴います。
この戦略のもう 1 つのリスクは、スタブがスタブ化されるパッケージよりも遅れることが多いことです。重大なバグが修正されるため、スタブ化されているパッケージを特定の最小バージョンに強制することもできますが、対応して更新されたスタブがリリースされていない場合、型チェックの結果が完全に正確ではない可能性があります。
スタブを既知の良好なバージョンにピン留めし、そのピンを時々 (手動で、または dependabot や renovate などのツールを使用して) 更新します。
たとえば、 types-requests==2.31.0.1使用する場合、依存関係をアップグレードしても型チェックが中断されないことを確信できます。ただし、ピンを更新するまでは、型チェックを改善する可能性があるスタブの改善を見逃すことになります。この戦略には、使用しているスタブがスタブ化されるパッケージと互換性がなくなる可能性があるというリスクもあります。
スタブをピンで留めないでください。これは、バージョン ピンを更新する際に必要な作業が最も少なく、スタブ パッケージの新しいバージョンがリリースされるたびに、改良されたスタブの恩恵を自動的に受けられるという利点があります。ただし、スタブがスタブ化されるパッケージと互換性がなくなるリスクが伴います。
たとえば、パッケージの新しいメジャー バージョンがリリースされた場合、スタブ化されているパッケージを更新する前に、ランタイム パッケージの新しいバージョンを反映するようにスタブが更新される可能性があります。
必要に応じて、さまざまな戦略を切り替えることもできます。たとえば、デフォルトで戦略 (1) を使用しますが、簡単に修正できない問題が発生した場合は戦略 (2) に戻ることができます。
_typeshedパッケージtypeshed には、標準ライブラリの一部として_typeshedパッケージが含まれています。このパッケージとそのサブモジュールにはユーティリティ タイプが含まれていますが、実行時には使用できません。このパッケージの使用方法の詳細については、 stdlib/_typeshedディレクトリを参照してください。
特定のライブラリの型スタブが間違っているか不完全であることを示す型チェッカーの動作に遭遇した場合は、ご連絡をお待ちしております。
私たちの主な議論の場は、プロジェクトの GitHub 問題トラッカーです。ここは、上記のいずれか、またはプロジェクトに関する他のほとんどのトピックについてのディスカッションを開始するのに最適な場所です。
Python での入力に関する一般的な質問がある場合、またはタイプシェッド外の型アノテーションやスタブを確認する必要がある場合は、ディスカッション フォーラムにアクセスしてください。あまり形式張らない議論については、gitter.im のタイピング チャット ルームをお試しください。一部の typeshed メンテナはほとんど常に存在します。ぜひお気軽にお立ち寄りください。喜んでお話しさせていただきます。実質的な技術的な議論は問題トラッカーに向けられます。
