sixcodes / python-boilerplate

Boilerplate(cookiecutter) files for your new (or existing!) python project

Python Boilerplate Cookiecutter

Como usar?

Primeiramente garanta que você tem o cookiecutter instalado no seu PATH.

sudo pip install cookiecutter

e então crie o seu projeto.

cookiecutter https://github.com/sixcodes/python-boilerplate.git

Após executar o comando acima, você receberá um questionario para responder de acordo com os dados do seu projeto.

As opções estão descritas no arquivo cookiecutter.json.

Ao executar essas serão os inputs necessários ou apenas enter para aceitar o valor default.

> cookiecutter https://github.com/sixcodes/python-boilerplate.git
project_name [e.g. 'six-toolbox']: sixcodes
package_name [sixcodes]:
package_version [0.0.1]:
short_description [Great python package]:
author [Jesue Junior]: Test boilerplate
author_email [[email protected]]:
author_username [sixcodes]:
url [https://github.com/sixcodes/sixcodes]:

A estrutura do seu projetode pastas e arquivos com esse template será:

sixcodes
|-- CODE_OF_CONDUCT.md
|-- LICENSE
|-- Pipfile
|-- Pipfile.lock
|-- README.md
|-- docs-src
|   |-- Makefile
|   |-- _static
|   |-- conf.py
|   `-- index.rst
|-- mypy.ini
|-- pyproject.toml
|-- setup.py
|-- sixcodes
|   |-- __init__.py
|   `-- config.py
`-- tests
    |-- test_config.py
    `-- test_true.py

7 directories, 38 files

O que esse boilerplate entrega

Github Actions Workflows

O projeto criado já tras alguns workflows do Github Actions:

• pull-request: Workflow que roda a cada pull-request aberto. Roda os testes a checagens de lint, format, etc.

• release: A cada tag criada com o padrão X.Y.Z gera uma publicação no Pypi.

  Para essa publicação você precisa adicionar um secret ao projeto com nome PYPI_TOKEN. Mais detalhes na documentação do Pypi:

Pré-configuração para documentação com Sphinx

A configuração do Sphinx já está pronta. O código-fonte da documentação fica em docs-src/ e a documentação gerada fica em docs/, já pronta para ser servida pelo Github Pages.

Para gerar sua documentação rode: pipenv run make-docs

Como ajudar?

TODO

python-boilerplate's Issues

Adicionar setup.cfg

Aqui podemos ignorar alguns erros de lint que o black já resolve ou que não queremos nos preocupar.

# setup.cfg
[pycodestyle]
# ignore
#  - line-length (black já corrige)
#  - line break before binary operator
ignore = E501, W503

Modificar a config do codecov para mostrar os checks separados por flags

No #9 enviamos os reports com flags específicas. Aqui vamos configurar o codecov para criar novos Merge checks baseado nessas flags.

Adicionar .gitattributes para arquivos auto-gerados

Adicionar .gitattributes para que arquivos auto-gerados aparecam "collapsed" por padrão os PRs.

O primeiro arquivo já incluído será o Pipfile.lock

Adicionar setup.py

Adicionar um setup.py simples para podermos fazer pipenv install -e .

Adicionar config do sphinx

Adicionar as configurações do sphinx, para que o projeto possa já nascer com documentação.

Adicoinar erro E203 à lista de ignores do setup.cfg

Esse erro acontece pois o black formata essa linha:

 task_id_no_namespace = task_id[task_id.index("_") + 1 :]

colocando um espaço entre o 1 e o :, mas a regra E203 diz que esse espaço não deve existir.

Como a formatção final é do black, temos que ignorar essa regra,

Adicionar um workflow simples do Github Actions

Vamos por enquando deixar os dois (circle e Actions) mas podemos escolher um depois.

• Adicionar paths-ignore para o workflow de pull request para não rodar nada se as modificações forem apenas em documentação (docs/** e docs-src/**).

Tem um exemplo aqui: https://github.com/b2wdigital/async-worker/pull/232

Atualizar codecov para 2.0.15

Com versão 1.0.0 em um projeto novo usando py3.7, apesar do upload ser feito com sucesso, o build é marcado com failed pois o codecov cli lança uma exception.

{"uploaded": true, "url": "https://codecov.io/github/b2wads/maas/commit/a8f7f569169b1ca1dd9b2233fd356f9c658d6f28", "queued": true, "meta": {"status": 200}, "message": "Coverage reports upload successfully", "id": "7d0337dc-9d87-45ca-8b62-50a70cf7fc58", "version": "1.0.0"}
Traceback (most recent call last):
  File "/home/circleci/.local/share/virtualenvs/project-zxI9dQ-Q/bin/codecov", line 10, in <module>
    sys.exit(cli())
  File "/home/circleci/.local/share/virtualenvs/project-zxI9dQ-Q/lib/python3.7/site-packages/codecov/__init__.py", line 179, in cli
    if int(data['coverage']) >= min_coverage:
KeyError: 'coverage'
Exited with code 1

Atualizar para a versão 2.0.15 resolveu o problema.

Criar um projeto aceitando todos os valores default, cria a pasta `"e.g. 'six-toolbox'"` como pasta raiz

Usando a master atual (dc3c556) e rodando o cookiecutter dessa forma:

cookiecutter -o /tmp/teste-proj https://github.com/sixcodes/python-boilerplate.git

Gera a seguinte estrutura dentro de /tmp/teste-project:

$ find /tmp/teste-proj -type d
/tmp/teste-proj
/tmp/teste-proj/e.g. 'six-toolbox'
/tmp/teste-proj/e.g. 'six-toolbox'/.github
/tmp/teste-proj/e.g. 'six-toolbox'/.github/workflows
/tmp/teste-proj/e.g. 'six-toolbox'/docs-src
/tmp/teste-proj/e.g. 'six-toolbox'/docs-src/_static
/tmp/teste-proj/e.g. 'six-toolbox'/e.g. 'six-toolbox'
/tmp/teste-proj/e.g. 'six-toolbox'/tests
/tmp/teste-proj/e.g. 'six-toolbox'/docs
/tmp/teste-proj/e.g. 'six-toolbox'/docs/.doctrees
/tmp/teste-proj/e.g. 'six-toolbox'/docs/_sources
/tmp/teste-proj/e.g. 'six-toolbox'/docs/_static

Penso que a pasta e.g 'six-tollbox' não deveria ter sido criada e os arquivos e pasta deveriam estar diretamente dentro de /tmp/teste-proj, que foi o diretório escolhido como raiz para o novo projeto.

Criando a pasta /tmp/teste-proj previamente e rodando o cookiecutter dentro dela tem o mesmo efeito.

@jesuejunior

Mudar o formato do comentário que o codecov faz no PR

As issues #9 e #10 passaram a fazer o upload de múltiplos reports cada um com sua flag. Atualmente o codecov sempre faz o Merge desses reports isso torna o report global menos relevante, já que a cobertura de unittest será afetada pela cobertura de typehint.

Dessa forma vamos configurar o codecov para quando comentar no PR não mostrar mais os números globais e sim apenas a porcentagem de cada flag. Nesse caso temos duas flags: unittest e typehint.

Vou postar aqui um exemplo de como o comentário era e como vai ficar.

Adicionar report de coverage de typehint

É possível enviar ao codecov um report de cobertura de typehint. Vamos adicionar isso aí circleci.

Adicionar .coveragerc para ignorar __main__.py

Pode ter, incialmente, esse conteúdo.

[report]
omit =
    **/__main__.py

Remover .travis.yml

Vamos deixar o CI com o CircleCI

Adicionar plugin sphinx_issues

Esse plugin permite usar construções como :pr:`123` para já linkar com o PR do projeto.

Documentar que é preciso mudar o docs-src/conf.py para colocar lá o nome do projeto no gituhb.

https://github.com/sloria/sphinx-issues

Fazer upload de cobertura pro codeclimate

Workflow do Guthub Actions deve fazer upload pro codeclimate.

https://codeclimate.com/

Refs #24

Ajustar o config do circle para ser parametrizável

Um exemplo: https://github.com/b2wads/nodejs-boilerplate/pull/49

Temos apenas um build e quando declaramos oworkflow é que preenchemos os parametros desse build.

Mover config.py para myproj/conf.py

Na prática, todo o código fica dentro e uma única pasta, geralmente com o nome do pacote principal.

Temo que mover o config.py (que está na raiz) para dentro da pasta de exemplo myproj. Dessa forma a estrutra vai fcar mais aderente ao boilerplate.

@jesuejunior

Gerar o coverage.xml no pipenv run test

Está faltando o --cov-report=xml para que o coverage seja gerado.

Isso já vai ajudar também no #25 .

Completar o .coveragerc com mais opçoẽs

Sugestão:

[run]
omit =
	*/__main__.py

[report]
# Regexes for lines to exclude from consideration
exclude_lines =
    # Have to re-enable the standard pragma
    pragma: no cover

    # Don't complain about missing debug-only code:
    def __repr__
    if self\.debug

    # Don't complain if tests don't hit defensive assertion code:
    raise AssertionError
    raise NotImplementedError

Atualizar a configuração do release draft ser dinâmico

No YAML do release draft ficou com hardcode apntando para o projeto pai. Precisamos deixar flexivel.