typeshed
1.0.0
Typeshed 包含 Python 標準函式庫和 Python 內建函數的外部型別註釋，以及由這些專案外部人員貢獻的第三方套件。
例如，該資料可用於靜態分析、類型檢查、類型推斷和自動完成。
有關如何使用 typeshed 的信息，請閱讀下文。貢獻者的資訊可以在 CONTRIBUTING.md 中找到。請在提交拉取請求之前閱讀它；不要向存根所在的項目報告註解問題，而是在此處將它們報告給 typeshed。
有關存根文件、typeshed 和 Python 一般類型系統的更多文檔，也可以在 https://typing.readthedocs.io/en/latest/ 中找到。
Typeshed 支援 Python 版本 3.8 至 3.13。
如果您只是使用類型檢查器（mypy、pyright、pytype、PyCharm 等），而不是開發它，則根本不需要與 typeshed 儲存庫進行互動：標準庫部分的副本typeshed 與類型檢查器捆綁在一起。您正在使用的第三方套件和模組的類型存根可以從 PyPI 安裝。例如，如果您使用html5lib和requests ，則可以使用安裝類型存根
$ pip install types-html5lib types-requests這些 PyPI 套件遵循 PEP 561，並透過 typeshed 內部機制自動發布（最多每天一次）。
安裝後類型檢查器應該能夠使用這些存根套件。有關更多詳細信息，請參閱類型檢查器的文檔。
第三方存根包的版本號碼至少由四個部分組成。存根版本的所有部分（除了最後一部分）都對應到被存根的運行時包的版本。例如，如果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 。這確保了存根與您正在使用的套件相容，但由於存根的更改，它會帶來破壞類型檢查的小風險。
此策略的另一個風險是存根通常落後於被存根的包。您可能希望強制將包存根到某個最低版本，因為它修復了一個關鍵錯誤，但如果相應更新的存根尚未發布，您的類型檢查結果可能不完全準確。
將存根固定在已知的良好版本，並不時更新該固定（手動或使用 dependentabot 或 renovate 等工具）。
例如，如果您使用types-requests==2.31.0.1 ，您可以確信升級依賴項不會破壞類型檢查。但是，在更新引腳之前，您將錯過存根中可能會改進類型檢查的改進。此策略還存在以下風險：您正在使用的存根可能與所存根的套件不相容。
不要固定存根。此選項在更新版本引腳時要求您做的工作最少，並且具有以下優點：每當發布新版本的存根套件時，您將自動受益於改進的存根。然而，它存在存根與被存根的包不相容的風險。
例如，如果發布了套件的新主要版本，則在更新要存根的套件之前，存根可能會更新以反映運行時套件的新版本。
您也可以根據需要在不同策略之間切換。例如，您可以預設採用策略 (1)，但當出現無法輕易解決的問題時，您可以回退到策略 (2)。
_typeshed包typeshed 包含一個套件_typeshed作為標準函式庫的一部分。該套件及其子模組包含實用程式類型，但在運行時不可用。有關如何使用此套件的更多信息，請參閱stdlib/_typeshed目錄。
如果您在類型檢查器中遇到表明給定庫的類型存根不正確或不完整的行為，我們希望收到您的來信！
我們的主要討論論壇是該專案的 GitHub 問題追蹤器。這是開始討論上述任何主題或與該項目相關的大多數其他主題的正確位置。
如果您對使用 Python 鍵入有一般性問題，或者您需要在 typeshed 之外查看類型註釋或存根，請訪問我們的討論論壇。對於不太正式的討論，請嘗試 gitter.im 上的打字聊天室。一些 typeshed 維護者幾乎總是在場；請隨時在那裡找到我們，我們很樂意與您聊天。實質技術討論將針對問題追蹤器。
