Skip to content

How-to Guides

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

Installation

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

Tag master is latest tested stable. Tag latest is literally latest pushed (no stability guaranteed)

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

Hint

All methods shown above Download Latest Stable Releases, either from pypi or docker

Verify Installation

You can verify by running the following:

generate-python --version

Generator Usage

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 Project Usage

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:

    a. Run the Test Suite against the code:

     ```sh
    tox -e dev
 ```

    b. 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:

     ```sh
 tox -e check && tox -e build
 ```

    c. Deploy the package's distributions in a pypi (index) server:

        1. Deploy to **staging**, using the `test` pypi (index) server at [test.pypi.org](https://test.pypi.org/):

       ```sh
          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](https://pypi.org/):

       ```sh
       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.