pyclbr no Python: inspecione módulos

O módulo pyclbr no Python lê código-fonte e extrai informações sobre classes, funções, métodos e definições aninhadas sem importar o módulo analisado. Ele foi criado para oferecer dados suficientes a navegadores de código, índices de símbolos, geradores de documentação simples e ferramentas de exploração.

A vantagem central é evitar a execução do arquivo. Importar um módulo pode iniciar conexões, ler variáveis de ambiente, registrar plugins ou executar código no nível superior. O pyclbr trabalha diretamente com a fonte, o que o torna mais adequado para examinar código desconhecido. Ainda assim, ele fornece informações limitadas e não substitui uma análise completa com AST.

O que o pyclbr encontra

A interface moderna, readmodule_ex(), retorna um dicionário com descritores de funções e classes declaradas por instruções def, async def e class. Cada descritor inclui nome, arquivo, módulo, linha inicial, pai e filhos.

import pyclbr

simbolos = pyclbr.readmodule_ex("meu_pacote.servico")
for nome, descritor in simbolos.items():
    if nome == "__path__":
        continue
    print(nome, descritor.file, descritor.lineno)

O nome informado segue a notação de importação, não um caminho de arquivo arbitrário.

Forneça caminhos de busca

O argumento path acrescenta diretórios antes de sys.path durante a localização da fonte.

simbolos = pyclbr.readmodule_ex(
    "aplicacao.modulo",
    path=["/workspace/src"],
)

Resolva os caminhos e limite-os a diretórios aprovados. Uma ferramenta web não deve aceitar qualquer raiz do sistema fornecida por usuário.

readmodule e readmodule_ex

readmodule() é a interface histórica e retorna apenas descritores de classes no nível do módulo. readmodule_ex() inclui funções, classes e objetos aninhados, por isso deve ser preferida em código novo.

classes = pyclbr.readmodule("meu_modulo")
completo = pyclbr.readmodule_ex("meu_modulo")

Ferramentas legadas podem depender do formato antigo, mas novos índices ganham mais contexto com a versão estendida.

Descritores de função

Objetos Function possuem file, module, name, lineno, parent, children e is_async.

for nome, item in simbolos.items():
    if isinstance(item, pyclbr.Function):
        print({
            "nome": item.name,
            "linha": item.lineno,
            "assíncrona": item.is_async,
        })

O atributo is_async permite diferenciar funções comuns e corrotinas declaradas com async def.

Descritores de classe

Objetos Class incluem os mesmos atributos e acrescentam super e methods. A lista super pode conter descritores resolvidos ou apenas nomes em texto quando a classe-base não é encontrada.

for item in simbolos.values():
    if isinstance(item, pyclbr.Class):
        bases = [
            base.name if hasattr(base, "name") else base
            for base in item.super
        ]
        print(item.name, bases, item.methods)

Não presuma que toda herança será resolvida. Imports condicionais, aliases e metaprogramação limitam o resultado.

Definições aninhadas

Desde Python 3.7, descritores possuem children e parent. Isso permite representar classes internas, métodos e funções locais.

def visitar(item, nivel=0):
    print("  " * nivel, item.name, item.lineno)
    for filho in item.children.values():
        visitar(filho, nivel + 1)

for item in simbolos.values():
    if hasattr(item, "children"):
        visitar(item)

Use um conjunto de objetos visitados se combinar resultados de vários módulos e houver risco de referências repetidas.

Construa um índice de símbolos

Uma aplicação pode transformar os descritores em JSON para alimentar uma busca de código.

def serializar(item):
    return {
        "module": item.module,
        "name": item.name,
        "file": item.file,
        "line": item.lineno,
        "kind": type(item).__name__,
        "children": [
            serializar(filho)
            for filho in item.children.values()
        ],
    }

Normalize caminhos antes de armazená-los e evite publicar caminhos absolutos do servidor.

Crie links para o editor

Como cada descritor possui arquivo e linha, um navegador pode abrir diretamente a definição. Valide se o arquivo permanece dentro do workspace antes de construir URLs como editor://file:line.

Para listar módulos disponíveis, combine a abordagem com pkgutil no Python. Para mapear imports usados por um script, consulte modulefinder no Python.

Pacotes e __path__

Quando o nome analisado é um pacote, o resultado inclui a chave __path__ com os caminhos de busca do pacote.

resultado = pyclbr.readmodule_ex("meu_pacote")
print(resultado.get("__path__"))

Trate essa chave separadamente porque ela não contém um descritor de função ou classe.

Por que não importar o módulo

Usar importlib.import_module() e inspect oferece informações de runtime, mas executa o código do módulo. Um plugin malicioso ou simplesmente mal configurado pode produzir efeitos antes mesmo da inspeção.

O pyclbr evita essa execução porque lê a fonte. Isso não significa que todo caminho fornecido seja seguro: a ferramenta ainda abre arquivos e pode consumir recursos ao processar árvores grandes.

Limitações com extensões

O módulo só analisa implementações escritas em Python. Extensões C, módulos embutidos e alguns módulos gerados não têm fonte Python compatível. Nesses casos, a análise pode falhar ou não retornar símbolos.

Use metadados, stubs de tipos ou inspeção controlada em processo separado quando precisar representar extensões.

Limitações de análise estática

Classes criadas dinamicamente, funções atribuídas a variáveis, decoradores que substituem objetos, métodos adicionados por metaclasses e imports dinâmicos podem não aparecer como esperado. pyclbr identifica declarações sintáticas, não o estado final do programa.

Para análise mais profunda, use ast. Para recursos lexicais de editor, veja tokenize no Python.

Compare com codeop

O codeop no Python compila texto interativo e determina se uma entrada está completa. pyclbr resolve um problema diferente: extrair uma árvore limitada de definições de um módulo localizado pelo sistema de imports.

Cache e atualização

Ferramentas de índice devem detectar alterações de arquivo e refazer a leitura. Guarde timestamp, tamanho ou hash junto do resultado. Não confie indefinidamente em descritores antigos, especialmente durante desenvolvimento ativo.

Tratamento de erros

Arquivos ausentes, sintaxe inválida, encoding problemático e imports de bases não resolvidos podem afetar a leitura. Capture exceções por módulo e continue indexando os demais.

def ler_seguro(nome, caminhos):
    try:
        return pyclbr.readmodule_ex(nome, path=caminhos)
    except (ImportError, OSError, SyntaxError) as erro:
        registrar_falha(nome, erro)
        return {}

Evite ocultar todas as exceções sem registro, pois isso produz índices incompletos silenciosamente.

Segurança e limites

• Restrinja raízes de busca.
• Não exponha caminhos absolutos.
• Limite quantidade e tamanho de arquivos.
• Defina timeout no processo de indexação.
• Não siga links simbólicos fora do workspace.
• Execute a ferramenta com permissões mínimas.
• Não confunda ausência de import com sandbox completo.

Testes recomendados

Teste funções síncronas e assíncronas, classes com múltipla herança, métodos, classes internas, funções locais, pacotes, aliases de importação e arquivos com sintaxe inválida. Verifique linhas e caminhos em Linux e Windows.

Inclua módulos com decoradores e metaclasses para documentar quais informações sua ferramenta consegue representar e quais ficam fora do escopo.

Boas práticas

• Prefira readmodule_ex().
• Trate __path__ separadamente.
• Considere bases não resolvidas.
• Normalize e restrinja caminhos.
• Atualize o índice quando a fonte mudar.
• Registre falhas por módulo.
• Use AST quando precisar de detalhes completos.
• Não importe código desconhecido apenas para listar símbolos.

Conclusão

O pyclbr no Python oferece uma forma leve de descobrir funções e classes sem executar o módulo. Ele é adequado para navegadores de código, índices simples e ferramentas que precisam reduzir efeitos colaterais.

Use-o reconhecendo seus limites: apenas código Python, declarações sintáticas e informações parciais. Consulte a documentação oficial do pyclbr e a documentação do módulo ast.