python-cookiecutter

This is a 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 Makefile
• Anyconfig: Read and validate configuration file
• CircleCI: Continuous Integration for your project
• 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
• Mergify: Automatically merge your PRs
• PBR: To easily package your application
• Pytest: Better unit testing
• Sphinx: Documentation ready for generation and publication
• Tox: Easily setup tests for Python.
• YAPF: Automatic code formatting

Usage

Setup

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

pip install -U cookiecutter

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 the Makefile.

To run the initial setup, run:

make

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:

make format check

And to reformat the entire project use the following:

make 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.

make venv

Running all the tests

make 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:

make docs

Packaging the application

To create a wheel package of the application:

make 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

make clean docker-clean