Doctest - Documentação executável para Python

1. Globalcode – Open4education Trilha – Python Adam Brandizzi Engenheiro de Software para a Liferay

2. Globalcode – Open4education Desenvolvimento Orientado a Documentação? Utilizando doctest para tornar seu código Python legível

3. Globalcode – Open4education Adam Brandizzi programador de computadores há quase 15 anos trabalha para Liferay apaixonado por Python gosta de fazer apresentações

4. Globalcode – Open4education O que é doctest?

5. Globalcode – Open4education “O módulo doctest busca por trechos de texto que pareçam com sessões iterativas de Python, e então executa estas seções para verificar se elas executam como mostradas.” — docs.python.org

6. Globalcode – Open4education Como funciona? O módulo doctest procura por exemplos de código em arquivos ou docstrings.

7. Globalcode – Open4education Nota: o que são docstrings Docstring Docstring

8. Globalcode – Open4education Como funciona? O módulo doctest procura por exemplos de código em arquivos ou docstrings. Estes exemplos são geralmente chamados de doctests. Cada exemplo tem duas partes: Código a executar Resultado esperado

9. Globalcode – Open4education Como funciona? O código a ser executado é prefixado por >>> na primeira linha (... nas demais). O resultado esperado vem na linha seguinte ao código executado. Basicamente: doctests simulam o terminal

10. Globalcode – Open4education Formato de um exemplo Código a executar Resultado esperado

11. Globalcode – Open4education Um exemplo em uma docstring Doctest Doctest

12. Globalcode – Open4education Como checar doctests É possível executar doctests de várias maneiras A mais simples é invocando o módulo com python -m doctest <arquivo>

13. Globalcode – Open4education Checando doctests com erros

14. Globalcode – Open4education Qual é o propósito de doctest?

15. Globalcode – Open4education Documentação executável Com doctest, você pode garantir que os exemplos de sua documentação estarão atualizados. Imagine arquivos README que se garantem!

16. Globalcode – Open4education Documentação executável Caso de uso: Uma biblioteca em Python 2.7. Bem documentada, mas abandonada por anos. De repente, precisei atualizar para Python 3.6. Como atualizar a documentação disso?

17. Globalcode – Open4education Documentação executável

18. Globalcode – Open4education Documentação executável

19. Globalcode – Open4education Documentação executável Caso de uso: Uma biblioteca em Python 2.7. Bem documentada, mas abandonada por anos. De repente, precisei atualizar para Python 3.6. Como atualizar a documentação disso? Todos os erros encontrados. Bastou rodar python -m doctest readme.rst

20. Globalcode – Open4education Por que doctest não é mais popular?

21. Globalcode – Open4education Os pequenos problemas Doctests são extremamente literais... Detalhes irrelevantes quebram exemplos Não aceitam quebra de linha, espaços extras Dicionários e sets não podem ser impressos deterministicamente ...mas estes problemas têm solução.

22. Globalcode – Open4education Detalhes quebram exemplos

26. Globalcode – Open4education Espaços extras

29. Globalcode – Open4education Imprimindo dicionários

33. Globalcode – Open4education Imprimindo dicionários Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos.

35. Globalcode – Open4education Imprimindo sets Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos. Infelizmente não vale para sets.

36. Globalcode – Open4education Imprimindo sets

38. Globalcode – Open4education Imprimindo sets Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos. Infelizmente não vale para sets. Só no resta um velho truque: Comparar o resultado esperado.

41. Globalcode – Open4education As grandes questões Competindo com frameworks xUnit Bom teste, má documentação Falta uma metodologia

42. Globalcode – Open4education Competindo com xUnit TDD revolucionou o desenvolvimento de software. TDD é baseado em testes unitários. xUnit (unittest, pytest etc.) são ideais para testes unitários. doctest é ideal para contar uma história.

43. Globalcode – Open4education Documentação não é teste Documentação deve ser clara e sucinta. Não se devem cobrir todos os edge cases em uma documentação com doctest.

44. Globalcode – Open4education Documentação não é teste

45. Globalcode – Open4education Documentação não é teste Documentação deve ser clara e sucinta. Não se devem cobrir todos os edge cases em uma documentação com doctest. Assim, doctest não substitui a necessidade de testes automatizados.

47. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá?

48. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá? A resposta, por muito tempo, era: nenhum

49. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá? A resposta, por muito tempo, era: nenhum. Hoje, preferem testes. Por quê? Porque TDD é divertido e estimulante!

50. Globalcode – Open4education Uma metodologia para documentação executável

51. Globalcode – Open4education Uma metodologia E se documentarmos antes de implementarmos?

52. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Novo artefato: Crie o módulo, classe ou assinatura de função. Escreva a docstring. Rode doctest. Implemente o artefato para fazer o doctest passar.

53. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Alterar comportamento: Acrescente doctests à docstring. Rode doctest. Altere o artefato para fazer o doctest passar.

54. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Bonus points: copie a docstring para o README.

55. Globalcode – Open4education Uma metodologia Hora da demonstração

56. Globalcode – Open4education Por que eu faria isso?

57. Globalcode – Open4education Os ganhos de doctest Clareza do código Melhores assinaturas. Menos interdependências. Menores unidades de código. Mais documentação Documentação atualizada (obviamente) Desenvolvedores “plantando sementes” Documentação interna

58. Globalcode – Open4education Clareza de código Melhores assinaturas Se ao explicar a assinatura de uma função, ou os métodos de uma classe, você encontra dificuldade, isto é um sinal de que é possível melhorar esses aspectos. Esta não é uma questão arquitetural, mas é relevante. TDD não ajuda muito aqui necessariamente.

59. Globalcode – Open4education Clareza de código Menos interdependências. TDD facilita extrair grandes blocos de código. Surge dependência entre o código extraído e o antigo. Dependências são geralmente detalhes de implementação, difíceis de explicar. Se você tiver de documentá-las, terá um incentivo para torná-las transparentes.

60. Globalcode – Open4education Clareza de código Menores unidades de código Blocos de código complicados incentivam comentários. Mas comentários podem ficar desatualizados. Uma solução: Mova o bloco para uma função. Escreva uma docstring para a função. Ponha doctests na docstring.

61. Globalcode – Open4education Mais documentação Sementes de documentação Documentação, assim como QA, é uma disciplina. Você vai querer um time dedicado. O desenvolvedor tem conhecimento fundamental.

62. Globalcode – Open4education Mais documentação Sementes de documentação Para programadores, documentar é... chato. Aproximar do código ajuda. Mas não resolve Quem gosta de escrever JavaDoc? Documentação executável é muito mais interessante! Desenvolvedores bem mais motivados a explicar em docstrings. As docstrings são “sementes” para os documentadores expandirem.

63. Globalcode – Open4education Mais documentação Documentação interna Um pedido comum dos recém-contratados: “A gente tem documentação para essa classe?” Geralmente classes internas, resultados de refatoração. Não há documentação. Time de documentação foca nas APIs externas.

64. Globalcode – Open4education Mais documentação Documentação interna Ou o time assume, ou não existe. Docstrings são parte da solução. Doctest aproxima o ato de documentar à experiência do desenvolvedor.

65. Globalcode – Open4education E aí, fez sentido?

66. Globalcode – Open4education Um comentário off-topic Eu trabalho para a Liferay. Estamos patrocinando o TDC e temos uma trilha dedicada! Se você quer saber mais sobre os produtos e processos de uma grande empresa multinacional, passe lá! Também temos muitas vagas abertas em liferay.com/careers.

67. Globalcode – Open4education Obrigado! Se tiverem perguntas, é só fazer! Também podem me contatar por esses canais: linkedin.com/in/brandizzi twitter.com/adambrandizzi adam@brandizzi.com.br adam.brandizzi.com.br

68. Globalcode – Open4education Trilha – Python Adam Brandizzi Engenheiro de Software para a Liferay

69. Globalcode – Open4education Desenvolvimento Orientado a Documentação? Utilizando doctest para tornar seu código Python legível

70. Globalcode – Open4education Adam Brandizzi programador de computadores há quase 15 anos trabalha para Liferay apaixonado por Python gosta de fazer apresentações

71. Globalcode – Open4education O que é doctest?

72. Globalcode – Open4education “O módulo doctest busca por trechos de texto que pareçam com sessões iterativas de Python, e então executa estas seções para verificar se elas executam como mostradas.” — docs.python.org

73. Globalcode – Open4education Como funciona? O módulo doctest procura por exemplos de código em arquivos ou docstrings.

74. Globalcode – Open4education Nota: o que são docstrings Docstring Docstring

75. Globalcode – Open4education Como funciona? O módulo doctest procura por exemplos de código em arquivos ou docstrings. Estes exemplos são geralmente chamados de doctests. Cada exemplo tem duas partes: Código a executar Resultado esperado

76. Globalcode – Open4education Como funciona? O código a ser executado é prefixado por >>> na primeira linha (... nas demais). O resultado esperado vem na linha seguinte ao código executado. Basicamente: doctests simulam o terminal

77. Globalcode – Open4education Formato de um exemplo Código a executar Resultado esperado

78. Globalcode – Open4education Um exemplo em uma docstring Doctest Doctest

79. Globalcode – Open4education Como checar doctests É possível executar doctests de várias maneiras A mais simples é invocando o módulo com python -m doctest <arquivo>

80. Globalcode – Open4education Checando doctests com erros

81. Globalcode – Open4education Qual é o propósito de doctest?

82. Globalcode – Open4education Documentação executável Com doctest, você pode garantir que os exemplos de sua documentação estarão atualizados. Imagine arquivos README que se garantem!

83. Globalcode – Open4education Documentação executável Caso de uso: Uma biblioteca em Python 2.7. Bem documentada, mas abandonada por anos. De repente, precisei atualizar para Python 3.6. Como atualizar a documentação disso?

84. Globalcode – Open4education Documentação executável ● Python 3.4: https://github.com/confeitaria/inelegant/#inelegant-net---quick-and-dirty-network-tricks ● Python 2.7: https://github.com/confeitaria/inelegant/tree/74ee30cbf8b6a2803bfcc255a986d8071e522fd6#inelegant-n et---quick-and-dirty-network-tricks

85. Globalcode – Open4education Documentação executável ● Python 3.4: https://github.com/confeitaria/inelegant/#inelegant-net---quick-and-dirty-network-tricks ● Python 2.7: https://github.com/confeitaria/inelegant/tree/74ee30cbf8b6a2803bfcc255a986d8071e522fd6#inelegant-n et---quick-and-dirty-network-tricks

86. Globalcode – Open4education Documentação executável Caso de uso: Uma biblioteca em Python 2.7. Bem documentada, mas abandonada por anos. De repente, precisei atualizar para Python 3.6. Como atualizar a documentação disso? Todos os erros encontrados. Bastou rodar python -m doctest readme.rst

87. Globalcode – Open4education Por que doctest não é mais popular?

88. Globalcode – Open4education Os pequenos problemas Doctests são extremamente literais... Detalhes irrelevantes quebram exemplos Não aceitam quebra de linha, espaços extras Dicionários e sets não podem ser impressos deterministicamente ...mas estes problemas têm solução.

100. Globalcode – Open4education Imprimindo dicionários Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos.

102. Globalcode – Open4education Imprimindo sets Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos. Infelizmente não vale para sets.

105. Globalcode – Open4education Imprimindo sets Desde Python 3.6, os pares são ordenados do menos recente ao mais recente. Isto é parte da especificação em Python 3.7. Isto afeta como dicionários são impressos. Infelizmente não vale para sets. Só no resta um velho truque: Comparar o resultado esperado.

108. Globalcode – Open4education As grandes questões Competindo com frameworks xUnit Bom teste, má documentação Falta uma metodologia

109. Globalcode – Open4education Competindo com xUnit TDD revolucionou o desenvolvimento de software. TDD é baseado em testes unitários. xUnit (unittest, pytest etc.) são ideais para testes unitários. doctest é ideal para contar uma história.

110. Globalcode – Open4education Documentação não é teste Documentação deve ser clara e sucinta. Não se devem cobrir todos os edge cases em uma documentação com doctest.

112. Globalcode – Open4education Documentação não é teste Documentação deve ser clara e sucinta. Não se devem cobrir todos os edge cases em uma documentação com doctest. Assim, doctest não substitui a necessidade de testes automatizados.

114. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá?

115. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá? A resposta, por muito tempo, era: nenhum

116. Globalcode – Open4education Documentação não é teste Se documentação não substitui testes, qual dos dois o desenvolvedor preferirá? A resposta, por muito tempo, era: nenhum. Hoje, preferem testes. Por quê? Porque TDD é divertido e estimulante!

117. Globalcode – Open4education Uma metodologia para documentação executável

118. Globalcode – Open4education Uma metodologia E se documentarmos antes de implementarmos?

119. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Novo artefato: Crie o módulo, classe ou assinatura de função. Escreva a docstring. Rode doctest. Implemente o artefato para fazer o doctest passar.

120. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Alterar comportamento: Acrescente doctests à docstring. Rode doctest. Altere o artefato para fazer o doctest passar.

121. Globalcode – Open4education Uma metodologia Desenvolvimento Orientado à Documentação Bonus points: copie a docstring para o README.

122. Globalcode – Open4education Uma metodologia Hora da demonstração

123. Globalcode – Open4education Por que eu faria isso?

124. Globalcode – Open4education Os ganhos de doctest Clareza do código Melhores assinaturas. Menos interdependências. Menores unidades de código. Mais documentação Documentação atualizada (obviamente) Desenvolvedores “plantando sementes” Documentação interna

125. Globalcode – Open4education Clareza de código Melhores assinaturas Se ao explicar a assinatura de uma função, ou os métodos de uma classe, você encontra dificuldade, isto é um sinal de que é possível melhorar esses aspectos. Esta não é uma questão arquitetural, mas é relevante. TDD não ajuda muito aqui necessariamente.

126. Globalcode – Open4education Clareza de código Menos interdependências. TDD facilita extrair grandes blocos de código. Surge dependência entre o código extraído e o antigo. Dependências são geralmente detalhes de implementação, difíceis de explicar. Se você tiver de documentá-las, terá um incentivo para torná-las transparentes.

127. Globalcode – Open4education Clareza de código Menores unidades de código Blocos de código complicados incentivam comentários. Mas comentários podem ficar desatualizados. Uma solução: Mova o bloco para uma função. Escreva uma docstring para a função. Ponha doctests na docstring.

128. Globalcode – Open4education Mais documentação Sementes de documentação Documentação, assim como QA, é uma disciplina. Você vai querer um time dedicado. O desenvolvedor tem conhecimento fundamental.

129. Globalcode – Open4education Mais documentação Sementes de documentação Para programadores, documentar é... chato. Aproximar do código ajuda. Mas não resolve Quem gosta de escrever JavaDoc? Documentação executável é muito mais interessante! Desenvolvedores bem mais motivados a explicar em docstrings. As docstrings são “sementes” para os documentadores expandirem.

130. Globalcode – Open4education Mais documentação Documentação interna Um pedido comum dos recém-contratados: “A gente tem documentação para essa classe?” Geralmente classes internas, resultados de refatoração. Não há documentação. Time de documentação foca nas APIs externas.

131. Globalcode – Open4education Mais documentação Documentação interna Ou o time assume, ou não existe. Docstrings são parte da solução. Doctest aproxima o ato de documentar à experiência do desenvolvedor.

132. Globalcode – Open4education E aí, fez sentido?

133. Globalcode – Open4education Um comentário off-topic Eu trabalho para a Liferay. Estamos patrocinando o TDC e temos uma trilha dedicada! Se você quer saber mais sobre os produtos e processos de uma grande empresa multinacional, passe lá! Também temos muitas vagas abertas em liferay.com/careers.

134. Globalcode – Open4education Obrigado! Se tiverem perguntas, é só fazer! Também podem me contatar por esses canais: linkedin.com/in/brandizzi twitter.com/adambrandizzi adam@brandizzi.com.br adam.brandizzi.com.br

Doctest - Documentação executável para Python

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a Doctest - Documentação executável para Python

Semelhante a Doctest - Documentação executável para Python (20)

Mais de Adam Victor Brandizzi

Mais de Adam Victor Brandizzi (8)

Doctest - Documentação executável para Python