Repolode
Enviar
Erotemic

Erotemic/xdoctest

Um pacote Python que encontra e executa exemplos de código em docstrings, reescrevendo o módulo builtin doctest com um parser baseado em AST.

Ver no GitHub
Estrelas
221
Forks
18
Issues abertas
29
Último commit
anteontem

O que é?

Xdoctest executa doctests, os exemplos de código escritos dentro de docstrings Python. É uma reescrita do módulo doctest da biblioteca padrão, que substitui o parser baseado em regex por um construído com o módulo ast do Python. Assim, é possível escrever exemplos com o prefixo >>> em todas as linhas e strings multilinha sem prefixos especiais.

Você pode executá-lo pela linha de comando com xdoctest, informando o caminho de um módulo ou pacote, ou pelo pytest, ativando a flag --xdoctest. O runner nativo pode listar os doctests, executar todos ou executar o doctest de uma função específica pelo nome. Também pode executar funções sem argumentos pelo nome. O parser aceita blocos Example no estilo Google e blocos >>> livres.

Por padrão, a verificação de got/want é permissiva: ignora diferenças de espaços em branco, usa correspondência ELLIPSIS e considera o teste aprovado se a saída impressa ou o valor final corresponder. Testes sem uma declaração want só precisam ser executados sem erros, então instruções assert simples funcionam para fazer verificações.

Recursos principais

  • 01Faz o parsing de doctests com o módulo ast do Python, em vez de usar expressões regulares.
  • 02Permite prefixar todas as linhas com >>>, sem precisar distinguir linhas PS1 e PS2.
  • 03Integra-se ao pytest por meio da flag --xdoctest.
  • 04Oferece um runner nativo de linha de comando que pode listar, executar todos ou executar um único doctest.
  • 05Aceita os estilos de parsing de doctest do Google e livre.

Casos de uso

  • Manter exemplos de uso em docstrings executáveis no CI junto com os testes unitários.
  • Verificar se os exemplos da documentação de um pacote Python continuam funcionando após mudanças no código.
  • Escrever entradas rápidas de demonstração em uma docstring durante o desenvolvimento de uma função.

Início rápido

  1. 1

    Instale o xdoctest pelo PyPI

    pip install xdoctest
  2. 2

    Execute todos os doctests do seu pacote ou módulo

    python -m xdoctest /path/to/your/pkg-or-module.py

Antes de usar

  • Requer Python 3.8 ou versão posterior.

Em coleções

Frameworks de teste e ferramentas de automação de testes

Tópicos

#python#doctest#testing#pytest#docstrings#pytest-plugin

Perguntas frequentes

O que é xdoctest?
Um pacote Python que encontra e executa exemplos de código em docstrings, reescrevendo o módulo builtin doctest com um parser baseado em AST. Xdoctest executa doctests, os exemplos de código escritos dentro de docstrings Python. É uma reescrita do módulo doctest da biblioteca padrão, que substitui o parser baseado em regex por um construído com o módulo ast do Python. Assim, é possível escrever exemplos com o prefixo >>> em todas as linhas e strings multilinha sem prefixos especiais.
xdoctest é gratuito? Qual é a licença?
xdoctest é open source sob a licença Apache-2.0. Confira os termos da licença antes de usá-lo em produtos comerciais.
xdoctest ainda é mantido?
Manutenção ativa. O último commit de xdoctest foi em 4 de nov. de 2026.
Para que posso usar xdoctest?
Manter exemplos de uso em docstrings executáveis no CI junto com os testes unitários. Verificar se os exemplos da documentação de um pacote Python continuam funcionando após mudanças no código. Escrever entradas rápidas de demonstração em uma docstring durante o desenvolvimento de uma função.
Como instalar xdoctest?
Instale o xdoctest pelo PyPI: pip install xdoctest Execute todos os doctests do seu pacote ou módulo: python -m xdoctest /path/to/your/pkg-or-module.py
Onde consigo xdoctest?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/Erotemic/xdoctest

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados