Generate New Python Package Project¶

This python generator was designed to be installed via pip and then invoked through the cli.

Installing the cli¶

Cookiecutter Python Package, available as source code on github, is also published

on pypi.org.

Install as PyPi package¶

Installing cookiecutter-python with pip is the way to go, for getting the generate-python cli onto your machine. Here we demonstrate how to do that using a

In virtual environment (recommended)¶

As with any Python Package, it is recommended to install cookiecutter-python inside a python virtual environment. You can use any of virtualenv, venv, pyenv of the tool of your choice. Here we demonstrate, using virtualenv, by running the following commands in a console (aka terminal):

Create a virtual environment

virtualenv env --python=python3

Open a console (aka terminal) and run:

Activate environment

source env/bin/activate

Install cookiecutter-python

pip install cookiecutter-python

Create symbolic link for the (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)!

For user (option 2)¶

One could also opt for a user installation of cookiecutter-python package:

python3 -m pip install --user cookiecutter-python

For all users (option 3)¶

The least recommended way of installing cookiecutter-python package is to directly install in the host machine:

sudo python3 -m pip install cookiecutter-python

Note the need to invoke using sudo, hence not that much recommended.

Check installation¶

Now the generate-python cli should be available!

You can verify by running the following:

generate-python --version

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

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

generate-python

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!

New Python Package Use Cases¶

Ready to enjoy some of your newly generated Python Package Project features available out-of-the-box!?

For instance:

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