typeshed
1.0.0
Typeshed contient des annotations de type externes pour la bibliothèque standard Python et les composants Python intégrés, ainsi que des packages tiers fournis par des personnes externes à ces projets.
Ces données peuvent par exemple être utilisées pour l'analyse statique, la vérification de type, l'inférence de type et l'auto-complétion.
Pour plus d’informations sur l’utilisation de Typeshed, lisez ci-dessous. Les informations destinées aux contributeurs peuvent être trouvées dans CONTRIBUTING.md. Veuillez le lire avant de soumettre des demandes de tirage ; ne signalez pas les problèmes liés aux annotations du projet auquel les stubs sont destinés, mais signalez-les plutôt ici pour être saisis.
Une documentation supplémentaire sur les fichiers stub, le typeshed et le système de typage de Python en général est également disponible sur https://typing.readthedocs.io/en/latest/.
Typeshed prend en charge les versions Python 3.8 à 3.13.
Si vous utilisez simplement un vérificateur de type (mypy, pyright, pytype, PyCharm, ...), au lieu de le développer, vous n'avez pas du tout besoin d'interagir avec le dépôt typeshed : une copie de la bibliothèque standard faisant partie de typeshed est fourni avec des vérificateurs de type. Et les stubs de type pour les packages et modules tiers que vous utilisez peuvent être installés à partir de PyPI. Par exemple, si vous utilisez html5lib et requests , vous pouvez installer les stubs de type en utilisant
$ pip install types-html5lib types-requestsCes packages PyPI suivent le PEP 561 et sont automatiquement publiés (jusqu'à une fois par jour) par la machinerie interne typée.
Les vérificateurs de type devraient pouvoir utiliser ces packages de stub une fois installés. Pour plus de détails, consultez la documentation de votre vérificateur de type.
Les numéros de version des packages de stub tiers se composent d'au moins quatre parties. Toutes les parties de la version stub, à l'exception de la dernière partie, correspondent à la version du package d'exécution en cours de stub. Par exemple, si le package types-foo a la version 1.2.0.20240309 , cela garantit que le package types-foo contient des stubs ciblés sur foo==1.2.* et testés par rapport à la dernière version de foo correspondant à ce spécificateur. Dans cet exemple, le dernier élément du numéro de version (20240309) indique que le package stub a été poussé le 9 mars 2024.
Chez typeshed, nous essayons de réduire au minimum les modifications brutales. Cependant, en raison de la nature des stubs, toute modification de version peut introduire des modifications susceptibles d'empêcher la vérification du type de votre code.
Il existe plusieurs stratégies disponibles pour spécifier la version d'un package de stubs que vous utilisez, chacune avec ses propres compromis :
Utilisez les mêmes limites que celles que vous utilisez pour le package en cours de suppression. Par exemple, si vous utilisez requests>=2.30.0,<2.32 , vous pouvez utiliser types-requests>=2.30.0,<2.32 . Cela garantit que les stubs sont compatibles avec le package que vous utilisez, mais cela comporte un petit risque de rupture de la vérification de type en raison de modifications apportées aux stubs.
Un autre risque de cette stratégie est que les stubs sont souvent en retard par rapport au paquet en cours de stub. Vous souhaiterez peut-être forcer le remplacement du package vers une certaine version minimale, car cela corrige un bogue critique, mais si les stubs mis à jour en conséquence n'ont pas été publiés, les résultats de votre vérification de type peuvent ne pas être entièrement précis.
Épinglez les talons sur une bonne version connue et mettez à jour le code PIN de temps en temps (soit manuellement, soit à l'aide d'un outil tel que dependabot ou renovate).
Par exemple, si vous utilisez types-requests==2.31.0.1 , vous pouvez être sûr que la mise à niveau des dépendances n'interrompra pas la vérification de type. Cependant, vous manquerez des améliorations dans les stubs qui pourraient potentiellement améliorer la vérification de type jusqu'à ce que vous mettiez à jour la broche. Cette stratégie présente également le risque que les stubs que vous utilisez deviennent incompatibles avec le package en cours de stubbing.
N'épinglez pas les talons. C'est l'option qui demande le moins de travail de votre part lorsqu'il s'agit de mettre à jour les broches de version, et présente l'avantage que vous bénéficierez automatiquement de stubs améliorés chaque fois qu'une nouvelle version du package stubs est publiée. Cependant, cela comporte le risque que les talons deviennent incompatibles avec le paquet en cours de création.
Par exemple, si une nouvelle version majeure du package est publiée, il est possible que les stubs soient mis à jour pour refléter la nouvelle version du package d'exécution avant de mettre à jour le package en cours de stub.
Vous pouvez également basculer entre les différentes stratégies selon vos besoins. Par exemple, vous pouvez utiliser par défaut la stratégie (1), mais revenir à la stratégie (2) lorsqu'un problème survient et ne peut pas être facilement résolu.
_typeshed typeshed inclut un package _typeshed dans le cadre de la bibliothèque standard. Ce package et ses sous-modules contiennent des types d'utilitaires, mais ne sont pas disponibles au moment de l'exécution. Pour plus d'informations sur l'utilisation de ce package, consultez le répertoire stdlib/_typeshed .
Si vous avez rencontré un comportement dans le vérificateur de type suggérant que les stubs de type d'une bibliothèque donnée sont incorrects ou incomplets, nous voulons vous entendre !
Notre principal forum de discussion est le système de suivi des problèmes GitHub du projet. C'est le bon endroit pour commencer une discussion sur l'un des sujets ci-dessus ou sur tout autre sujet concernant le projet.
Si vous avez des questions générales sur la saisie avec Python, ou si vous avez besoin d'une révision de vos annotations de type ou de vos stubs en dehors de typeshed, rendez-vous sur notre forum de discussion. Pour une discussion moins formelle, essayez le salon de discussion sur gitter.im. Certains mainteneurs typés sont presque toujours présents ; n'hésitez pas à nous y retrouver et nous serons ravis de discuter. Les discussions techniques de fond seront dirigées vers le système de suivi des problèmes.
