Skip to content

Cookiecutter template for an idiomatic Python project driven by Makefile

License

Notifications You must be signed in to change notification settings

alexkey/cookiecutter-lux-python

Repository files navigation

cookiecutter-lux-python

Cookiecutter template for a Python package.

The boilerplate Python project that aims to create facility for maintaining of the package easily. It considering tools for building, testing and distribution.

Get Started

This template provides a basic structure for an idiomatic Python package with a convenient Makefile-facility and additional helpers.

Template can be configured using Cookiecutter's CLI or by altering parameters directly in cookiecutter.json.

Requirements

There are a couple of tools for building, packaging, documentation and so on, that must be installed.

  • GNU sed (brew install gnu-sed for macOS),
  • ripgrep (optionally),
  • awk,
  • Docker,
  • Virtualenv,
  • Sphinx (for sphinx-build and sphinx-apidoc).

To check availability of main tools just type make or make doc.

Features

  • To get help about available Makefile targets type:

    make help
    

Creating the virtual environment

  1. Compile Pip requirements from requirements.in to requirements.txt using pip-tools (via Docker):

    make requirements
    
  2. Create the new virtual environment based on requirements.txt and requirements-test.txt:

    make venv
    
  3. Install the package into a virtual environment in so-called "development mode":

    source .venv/bin/activate
    make install
    
    # ...hard working here...
    
    make uninstall
    deactivate
    

Testing the package

Pytest is used as a test tool by default.

  • To run tests type (within a virtual environment):

    make check
    

Building the package from scratch

  • Create a source distribution (tarball with sources):

    make sdist
    ls -al dist/*.tar.gz
    
  • Create a binary (wheel) distribution:

    make dist
    ls -al dist/*.whl
    

Dealing with containers

  • Display system-wide information:

    make docker-info
    
  • Show all images, containers and volumes:

    make docker-stats
    
  • Build the image according to Dockerfile:

    make docker-build
    
  • Run temporary container in an interactive mode:

    make docker-run
    
  • Remove all unused images, built containers and volumes:

    make docker-clean
    

Documenting the project using Sphinx

  1. Build an API documentation:

    make apidoc
    
  2. Build the documentation as a standalone HTML files:

    make html
    open doc/_build/html/index.html
    
  • Clean the project's directory (precompiled and temporary files):

    make clean
    
  • Clean the project's build output (eggs, distributions, builds):

    make distclean
    
  • Delete almost everything (including virtual environment):

    make mostlyclean
    

About

Cookiecutter template for an idiomatic Python project driven by Makefile

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published