Generate Python Project

Our Python Generator Project was designed to be installable via pip and then invoked through the generate-python entrypoint to the CLI.

Getting the CLI

Cookiecutter Python Package, available as source code on github, with published
Distribution on pypi.org PyPI, and Docker Image on hub.docker.com Registry.

Install in virtual env, and make available globally in your (host) machine.

pipx install cookiecutter-python

Now, the generate-python executable should be available.

Pull the latest Stable image from Docker Hub

docker pull boromir674/generate-python:master
Now, the CLI should be available, via
docker run -it --rm boromir674/generate-python:master

Hint

Not to be confused with the ‘latest’ (channel) image tag advertised by dockerhub, which my no means promises to contain a stable release.

Hint

We promise stable releases on ‘master’ tag, since on git, ‘all tagged production releases are on ‘master’ branch. They are the same to correspond to PyPI Distributions as well.

Install in virtual env

virtualenv env --python=python3
source env/bin/activate

pip install cookiecutter-python

Make available to current user

ln -s env/bin/generate-python ~/.local/bin/generate-python

Now, the generate-python executable should be available (assuming ~/.local/bin is in your PATH).

Check installation

You can verify by running the following:
generate-python --version

Hint

All methods demonstrated for getting the CLI, download the Latest Stable (Release).

Using the CLI

Using the cli is as simple as invoking generate-python from a console.

You can run the following to see all the available parameters you can control:

generate-python --help
docker run -it --rm boromir674/generate-python:master --help

The most common way to generate a new Python Package Project is to run:

generate-python
docker run -it --rm boromir674/generate-python:master

This will prompt you to input some values and create a fresh new Project in the current directory!

Now, simply cd into the generated Project’s directory and enjoy some of the features the generator supplies new projects with!

More on use cases in the next section.

Generated Python Project Use Cases

Ready to enjoy some of your newly generated Python Package Project 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 environment 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 intended.

  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.