python-cookiecutter

This is an opinionated cookiecutter template for a quickly creating command line utilities in python.

It comes with the following features:

• Free software: MIT license
• All the administrative tasks are defined in the invoke and nox scripts
• Anyconfig: Read and validate configuration file
• CircleCI: Continuous Integration for your project
  • Check the formating
  • Build the documentation
  • Lint the code and docstrings
  • Test the code
  • Publish the documentation when tagging your code
  • Upload a package to PyPI when tagging your code
• Click: Create beautiful command line interfaces
  • TAB completion support
• Docker: Containerize the project
• EditorConfig: Maintain consistent coding styles between different editors
• Github templates: Create consistent Issues and Pull Requests
• Github pages: Enable GitHub pages and add a CircleCI job to automatically publish the documentation when tagging the project
• Loguru: Logging made (stupidly) simple
• Mergify: Automatically merge your PRs
• PBR: To easily package your application
• Pytest: Better unit testing
  • coverage: plugin that produces coverage reports
  • mock: plugin that installs a mocker fixture
  • rerunfailures: plugin that re-runs failed tests up to -n times to eliminate flakey failures
  • socket: plugin that disables or restricts socket calls to ensure network calls are prevented.
  • xdist: distributed testing plugin
• Sphinx: Documentation ready for generation and publication
  • aiohttp heme to get a nice look and feel
  • badges support for PyPI, CircleCI and Coveralls.io
  • markdown support in addition to reStructured
  • sphinx click to automatically generate the CLI documentation
• Twine: Easily publish your package on PyPI
• YAPF: Automatic code formatting

Usage

Setup

Install the latest Cookiecutter if you haven't installed it yet:

pip install cookiecutter invoke nox

Generate a Python project:

cookiecutter https://github.com/rgreinho/python-cookiecutter

Congratulations! Now that your project is fully generated, you have access to a lot of features, mostly using Invoke and Nox.

To run the initial setup, run:

inv

Pushing to Github

Create a new repository on Github and add the remote to this repository

git remote add origin https://github.com/<user>/<repo.git>
git push -u origin master
git push --tags

Enabling CircleCI

This cookiecutter comes with a pre-defined configuration for CircleCI. All you have to do is to add the repository of your project to CircleCI.

Formatting the code

To end all holy wars about formatting, you should use a formatter. YAPF makes this task easy for you.

To check whether you code is formatted correctly, run:

inv lint-format

And to reformat the entire project use the following:

inv format

Creating a virtual environment for the project

This is not really necessary as the project will be fully containerized using Docker, but in some cases you might want to setup a local virtual environment for your project.

inv venv

Running all the tests

inv ci

Generating the documentation

The documentation is generated using Sphinx. All your documentation must be put into the docs directory.

To generate the documentation run:

inv docs

Packaging the application

To create a wheel package of the application:

inv dist

setup.cfg

The application is packaged using PBR. The packaging configuration is located in the setup.cfg file. For detailed explanations about the various options, please refer to the official documentation.

The dependencies of the application are located in the requirements.txt file. Modify that file if you need to add or update dependencies. The other dependencies - tests, lint, docs - are located in the setup.cfg file.

Cleaning up

inv clean