Python Typing Generator

Propósito & Intenção do Usuário: a ferramenta analisa código-fonte Python e docstrings para gerar hints de tipo precisos. Destina-se a desenvolvedores, mantenedores de bibliotecas, engenheiros de dados e equipes que estão migrando para typing e precisam de contratos de tipo consistentes em grandes bases de código. Use durante refatoração, design de API ou onboarding para padronizar o typing.

Lógica Central & Funcionalidades: funções obrigatórias incluem inferência baseada em AST a partir de definições de funções, parâmetros, tipos de retorno e docstrings; suporte a construções de typing PEP 484 (List, Dict, Optional, Union, Callable); formatos de exportação para anotações inline ou arquivos .pyi independentes; suporte básico a TypeVar e generics; resolução entre módulos para reduzir imports não resolvidos. Funções opcionais: profundidade de inferência configurável, integração com hints existentes e geração de um sumário de tipos. A lógica prioriza anotações explícitas quando presentes; caso contrário infere tipos prováveis e recai em Any ou Optional para casos incertos. Saídas podem ser injetadas no código ou entregues como stubs prontos para patch. Uma rodada de validação verifica a consistência de tipos e sinaliza conflitos.

Entradas & Saídas: Entradas são um fragmento de código Python ou caminho de arquivo, uma seleção de modo (inline vs Stub) e diretrizes opcionais sobre profundidade de inferência. Saídas incluem blocos de código anotados ou arquivos .pyi, formatados de acordo com PEP 8 e padrões de typing. A ferramenta também emite um sumário de tipos, uma lista de tipos inferidos e avisos sobre imports não resolvidos ou construções dinâmicas.

Algoritmos & Cálculos: A ferramenta analisa o AST, coleta definições de símbolos e deduz tipos de parâmetros e retorno a partir de assinaturas e docstrings. Converte tipos de docstrings em construções de typing, resolve imports e propaga tipos inferidos pelos módulos. O output final pode ser edições diretas no código ou declarações de stub separadas. Casos limites incluem atributos dinâmicos, reflexão ou metaprogramação intensa onde o typing é incerto; nesses casos, a ferramenta sinaliza tipagem conservadora e recomenda anotações explícitas.

Indústria/Região & Localização; Suposições & Exclusões: Segue convenções padrão de typing Python (PEP 484) e normas de codificação US/EU; não há necessidade de formatação específica de locale. Assume entrada Python válida, não executa o código e exclui refatoração em tempo real ou análise estática completa além do typing.