typeshed
1.0.0
Typeshed contém anotações de tipo externo para a biblioteca padrão do Python e componentes internos do Python, bem como pacotes de terceiros contribuídos por pessoas externas a esses projetos.
Esses dados podem, por exemplo, ser usados para análise estática, verificação de tipo, inferência de tipo e preenchimento automático.
Para obter informações sobre como usar o typeshed, leia abaixo. Informações para contribuidores podem ser encontradas em CONTRIBUTING.md. Leia-o antes de enviar solicitações pull; não relate problemas com anotações ao projeto para o qual os stubs se destinam, mas em vez disso, relate-os aqui para o typeshed.
Documentação adicional sobre arquivos stub, typeshed e sistema de digitação do Python em geral também pode ser encontrada em https://typing.readthedocs.io/en/latest/.
Typeshed oferece suporte às versões 3.8 a 3.13 do Python.
Se você estiver usando apenas um verificador de tipo (mypy, pyright, pytype, PyCharm, ...), em vez de desenvolvê-lo, você não precisa interagir com o repositório digitado: uma cópia da parte da biblioteca padrão de typeshed vem com verificadores de tipo. E os stubs de tipo para pacotes e módulos de terceiros que você está usando podem ser instalados a partir do PyPI. Por exemplo, se você estiver usando html5lib e requests , poderá instalar os stubs de tipo usando
$ pip install types-html5lib types-requestsEsses pacotes PyPI seguem o PEP 561 e são liberados automaticamente (até uma vez por dia) por máquinas internas digitadas.
Os verificadores de tipo devem ser capazes de usar esses pacotes stub quando instalados. Para obter mais detalhes, consulte a documentação do seu verificador de tipo.
Os números de versão de pacotes stub de terceiros consistem em pelo menos quatro partes. Todas as partes da versão stub, exceto a última parte, correspondem à versão do pacote de tempo de execução que está sendo stubado. Por exemplo, se o pacote types-foo tiver a versão 1.2.0.20240309 , isso garante que o pacote types-foo contenha stubs direcionados a foo==1.2.* e testados na versão mais recente de foo correspondente a esse especificador. Neste exemplo, o elemento final do número da versão (20240309) indica que o pacote stub foi enviado por push em 9 de março de 2024.
No typeshed, tentamos reduzir ao mínimo as alterações significativas. No entanto, devido à natureza dos stubs, qualquer aumento de versão pode introduzir alterações que podem fazer com que seu código falhe na verificação de tipo.
Existem diversas estratégias disponíveis para especificar a versão de um pacote stubs que você está usando, cada uma com suas próprias vantagens:
Use os mesmos limites usados para o pacote que está sendo stubado. Por exemplo, se você usar requests>=2.30.0,<2.32 , poderá usar types-requests>=2.30.0,<2.32 . Isso garante que os stubs sejam compatíveis com o pacote que você está usando, mas traz um pequeno risco de quebra da verificação de tipo devido a alterações nos stubs.
Outro risco dessa estratégia é que os stubs geralmente ficam atrás do pacote que está sendo stubado. Você pode querer forçar o stub do pacote para uma determinada versão mínima porque ele corrige um bug crítico, mas se os stubs atualizados correspondentemente não tiverem sido lançados, os resultados da verificação de tipo podem não ser totalmente precisos.
Fixe os stubs em uma versão válida e atualize o pin de tempos em tempos (manualmente ou usando uma ferramenta como dependabot ou renovate).
Por exemplo, se você usar types-requests==2.31.0.1 , poderá ter certeza de que a atualização das dependências não interromperá a verificação de tipo. No entanto, você perderá melhorias nos stubs que poderiam melhorar a verificação de tipo até atualizar o pin. Essa estratégia também apresenta o risco de que os stubs que você está usando possam se tornar incompatíveis com o pacote que está sendo stubado.
Não prenda os tocos. Esta é a opção que exige menos trabalho de sua parte na hora de atualizar os pins de versão, e tem a vantagem de que você se beneficiará automaticamente de stubs aprimorados sempre que uma nova versão do pacote stubs for lançada. No entanto, existe o risco de os stubs se tornarem incompatíveis com a embalagem que está sendo stubada.
Por exemplo, se uma nova versão principal do pacote for lançada, há uma chance de os stubs serem atualizados para refletir a nova versão do pacote de tempo de execução antes de você atualizar o pacote que está sendo stubado.
Você também pode alternar entre as diferentes estratégias conforme necessário. Por exemplo, você poderia usar a estratégia (1) como padrão, mas voltar à estratégia (2) quando surgir um problema que não possa ser facilmente resolvido.
_typeshed typeshed inclui um pacote _typeshed como parte da biblioteca padrão. Este pacote e seus submódulos contêm tipos de utilitários, mas não estão disponíveis em tempo de execução. Para obter mais informações sobre como usar este pacote, consulte o diretório stdlib/_typeshed .
Se você se deparou com um comportamento no verificador de tipo que sugere que os stubs de tipo de uma determinada biblioteca estão incorretos ou incompletos, queremos ouvir sua opinião!
Nosso principal fórum de discussão é o rastreador de problemas do GitHub do projeto. Este é o lugar certo para iniciar uma discussão sobre qualquer um dos tópicos acima ou sobre qualquer outro tópico relacionado ao projeto.
Se você tiver dúvidas gerais sobre digitação com Python ou precisar de uma revisão de suas anotações de tipo ou stubs fora do typeshed, acesse nosso fórum de discussão. Para discussões menos formais, experimente a sala de bate-papo de digitação em gitter.im. Alguns mantenedores digitados estão quase sempre presentes; sinta-se à vontade para nos encontrar lá e ficaremos felizes em conversar. A discussão técnica substantiva será direcionada ao rastreador de problemas.
