Generate New Python Package Project¶
This python generator was designed to be installed via pip and then invoked through the cli.
Installing the cli¶
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¶
generate-python --version
Using the cli¶
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!
More on use cases in the next section.
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:
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}"
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
Deploy the package’s distributions in a pypi (index) server:
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
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.