cookiecutter-python 0.7.2

Yet another modern Python Package (pypi) with emphasis in CI/CD and automation

Cookiecutter Python Package

Python Package (pypi) Cookiecutter, with emphasis on CI/CD and automation.

Source Code: https://github.com/boromir674/cookiecutter-python-package

Pypi Package: https://pypi.org/project/cookiecutter-python/

CI Pipeline: https://github.com/boromir674/cookiecutter-python-package/actions/

Features

1. Fresh Python Package Project Generation, “packaged” with a Test Suite and a CI Pipeline (see Quickstart)

2. Python Package Template (source code at src/cookiecutter_python/) implemented as a Cookiecutter

3. Tested on python versions 3.6, 2.7, 3.8, 3.9 and 3.10, for both “Linux” and “MacOS” platforms (see Test Workflow on CI)

See the Biskotaki Python Package Project, which was entirely generated using this Python Package Template:

• Source Code hosted on Github at https://github.com/boromir674/biskotaki

• Python Package hosted on pypi.org at https://pypi.org/project/biskotaki/

• CI Pipeline hosted on Github Actions at https://github.com/boromir674/biskotaki/actions

Generated Python Package Features

1. Test Suite using pytest

2. Parallel Execution of Unit Tests, on multiple cpu’s

3. Automation, using tox

   1. Code Coverage measuring

   2. Build Command, using the build python package

   3. Pypi Deploy Command, supporting upload to both pypi.org and test.pypi.org servers

   4. Type Check Command, using mypy

4. CI Pipeline, running on Github Actions

   1. Job Matrix, spanning different platform’s and python version’s

      1. Platfroms: ubuntu-latest, macos-latest

      2. Python Interpreters: 3.6, 3.7, 3.8, 3.9, 3.10

   2. Parallel Job execution, generated from the matrix, that runs the Test Suite

Quickstart

Prerequisites

You need to have Cookiecutter installed. Check the Cookiecutter documentation pages for more on Cookiecutter.

Usage

Open a console/terminal and run:

git clone [e-mail]:boromir674/cookiecutter-python-package.git
cookiecutter cookiecutter-python-package/src/cookiecutter_python

Now, you should have generated a new Project for a Python Package, based on the Template!

Just ‘enter’ (cd into) the newly created directory, ie cd <my-great-python-package>.

Develop your package’s Source Code (business logic) inside src/my_great_python_package dir :)

Develop your package’s Test Suite (ie unit-tests, integration tests) inside tests dir :)

Try yourself!

You are ready to enjoy some of the package’s features available out-of-the-box!

For instance:

1. Leverage the supplied tox environments to automate various Testing and DevOps related activities.

   Assuming you have tox installed (example installation command: python3 -m pip install –user tox) and you have done a cd into the newly generated Project directory, you can do for example:

   1. Run the Test Suite against different combinations of Python versions (ie 3.7, 3.8) and different ways of installing (ie ‘dev’, ‘sdist’, ‘wheel’) the <my_great_python_package> package:

      tox -e "py{3.7, 3.8}-{dev, sdist, wheel}"

   2. Check the code for compliance with best practises of the Python packaging ecosystem (ie PyPI, pip), build sdist and wheel distributions and store them in the dist directory:

      tox -e check && tox -e build

   3. Deploy the package’s distributions in a pypi (index) server:

      1. Deploy to staging, using the test pypi (index) server at test.pypi.org:

         TWINE_USERNAME=username TWINE_PASSWORD=password PACKAGE_DIST_VERSION=1.0.0 tox -e deploy

      2. Deploy to production, using the production pypi (index) server at pypi.org:

         TWINE_USERNAME=username TWINE_PASSWORD=password PACKAGE_DIST_VERSION=1.0.0 PYPI_SERVER=pypi tox -e deploy

         Note

         Setting PYPI_SERVER=pypi indicates to deploy to pypi.org (instead of test.pypi.org).

      Note

      Please modify the TWINE_USERNAME, TWINE_PASSWORD and PACKAGE_DIST_VERSION envronment variables, accordingly.

      TWINE_USERNAME & TWINE_PASSWORD are used to authenticate (user credentials) with the targeted pypi server.

      PACKAGE_DIST_VERSION is used to avoid accidentally uploading distributions of different versions than intented.

2. Leverage the CI Pipeline and its build matrix to run the Test Suite against a combination of different Platforms, different Python interpreter versions and different ways of installing the subject Python Package:

   Trigger the Test Workflow on the CI server, by pushing a git commit to a remote branch (ie master on github).

   Navigate to the CI Pipeline web interface (hosted on Github Actions) and inspect the build results!

   Note

   You might have already pushed, in case you answered yes, in the initialize_git_repo prompt, while generating the Python Package, and in that case, the Test Workflow should have already started running!

   Out-of-the-box, triggering the Test Workflow happens only when pushing to the master or dev branch.

License

• Free software: Affero GNU General Public License v3.0

Notes

Currently, since the actual cookiecutter template does not reside on the root directory of the repository (but rather in src/cookiecutter_python), ‘cloning’ the repository locally is required at first.

This was demonstrated in the quickstart section, as well.

For more complex use cases, you can modify the Template and also leverage all of cookiecutter’s features, according to your needs.