O documento discute como criar utilitários de linha de comando em Python de forma elegante. Ele cobre tópicos como códigos de retorno, parsing de argumentos, logging, controle de sinais, arquivos especiais, ferramentas de desenvolvimento, documentação e interfaces de usuário baseadas em texto. O documento enfatiza a importância de se ter uma licença amigável, documentação clara, testes automatizados, integração contínua e uma comunidade ativa para projetos Python de alta qualidade.

1. Utilitários de linha de
comando bonitos em
Python
Rudá Moura
TDC POA 2015

2. 2

3. 3

4. 4

5. Critério Interno
• Projeto tem documentação clara e com exemplos
• Projeto tem um conjunto de testes automatizados
(unittests, nose, etc.)
• Projeto tem uma boa estrutura de diretórios e
arquivos
• Projeto tem um buildsystem (make, setup.py, etc.)
• Projeto instalável dentro de um Virtual Env
5

6. Critério Externo
• Projeto possui uma licença de uso amigável (BSD, MIT, GPL, etc.)
• Projeto está hospedado e possui uma homepage (GitHub, GitLab,
Bitbucket, etc.)
• Projeto possui documentação disponível on-line (readthedocs, github
pages, etc.)
• Projeto possui Integração Contínua (Jenkins, Travis, etc.)
• Projeto disponível no Python Package Index [https://pypi.python.org/pypi]
• Pacotes disponíveis no Debian, BSD Ports, Rudix, etc.
• Projeto possui uma comunidade ativa e amigável
6

7. 7

8. Aspectos de
Programação

9. Códigos de Retorno
(Exit codes)
• Muitos buildsystems (ex.: make) e sistemas de automação (ex.:
fabric) necessitam do código de retorno para saber se podem
continuar com a tarefa.
• 0 = OK, !0 = NOK
• 0 = programa rodou corretamente (EXIT_SUCCESS do C)
• 1 = houve um erro na execução (EXIT_FAILURE do C)
• 2.. = diferenciação de tipos de erros (não há um padrão)
• 64-67 = EX_* (/usr/include/sysexits.h)
• 128+n = saída com sinal n (143 = (128 + 15) SIGTERM)
9

10. Retorno em Python
(seu script deve retornar um)
• return 123 # dentro de __main__()
• sys.exit(123) # em qualquer lugar
• Caso contrário, assume um “retorna 0” OK
(realmente, OK?)
10

11. Parsing de Argumentos
• getopt (desde a antiguidade)
• optparse (py2.3-py.2.7)
• argparse (py2.7-)
11

12. 12

13. 13

14. 14

15. Logging
• O módulo logging é odiado por não ser “Pythonico”
porém o formato de logging e customizações são
necessários em ambientes de produção
• Em cada módulo:
• log = logging.getLogger(__name__)
• log.error(“Can’t start: %s”, msg)
• log.info(), log.warn(), log.debug(), etc.
15

16. 16

17. Controle de Sinais
(KeyboardInterrupt)
• try / except KeyboardInterrupt:…
• Módulo signal:
• signal.signal(signal.SIGTERM, callback)
• def callback(signum, stack)…
17

18. 18

19. Arquivos especiais
• Módulos & Pacotes
• snoopy/
• __init__.py
• Executado quando faço ‘import snoopy’
• __main__.py
• Executado quando faço ‘python -m snoopy’
19

20. Ferramentas
• Python Debugger (pdb)
• import pdb ; pdb.set_trace()
• profiler
• virtualenv, tox (virtualenv-based automation of test activities)
• pylint, pychecker
• GitHub, Bitbucket, Travis, Jenkins, …
• Um ótimo editor: vim, emacs, textmate, notepad++, etc.
• Uma IDE: PyCharm, Eclipse, etc.
20

21. The Python Package Index
(PyPI)
• Central de repositórios de módulos para Python
• Módulo distutils
• Script setup.py
• https://wiki.python.org/moin/Distutils/Tutorial
21

22. 22

23. 23

24. Documentação
• Geralmente se escreve com Markdown ou
reStructuredText (RST)
• Markdown é mais simples de sintaxe e é um
formato bem popular
• RST é mais complexo, porém popular em
projetos Python
• Sphinx (Python Documentation Generator) [http://
sphinx-doc.org]
24

25. 25

26. 26

27. 27

28. Textbased User Interfaces
(TUI)
• ANSI Colors
• colorconsole [https://pypi.python.org/pypi/colorconsole]
• Interfaces Interativas (REPL)
• Módulo cmd (o pdb faz uso dele)
• Curses Interface
• Clint, click, cliff [http://docs.python-guide.org/en/latest/
scenarios/cli/]
28

29. 29

30. 30

31. • Projeto tem uma licença amigável (BSD, MIT, GPL, etc.)
• Projeto tem uma interface coerente e amigável
• Projeto tem documentação clara e com exemplos
• Projeto tem um conjunto de testes, cobertura e IC
• Projeto disponível no PyPI
• Projeto possui uma homepage
• Projeto instalável dentro de um Virtual Env
• Projeto tem uma comunidade legal
• Projeto é mantido regularmente
Resumo
31

32. Fim
• Livro do Luciano Ramalho: “Fluent Python”
• Rudix! Ports e packages para o OSX
• rudix.org
• HIRE ME! Me contrate :)