Python Package Generator¶
What’s included?¶
Generator CLI to scaffold a modern Python Project, with cross-platform support; Linux, MacOS, Windows
Option for Python Package “variant”, supporting module, module+cli, and pytest-plugin
Template (source at src/cookiecutter_python/) of over 24 files (see Quickstart), to generate Project featuring:
Fully featured CI/CD Pipeline, running on Github Actions, defined in .github/
Documentation Pages, with sphinx or mkdocs, hosted on readthedocs server, located in docs dir
Test Suite, using pytest, located in tests dir
Pypi Deploy Command, supporting upload to both pypi.org and test.pypi.org servers
Type Check Command, using mypy
Build Command, using the build python package
What to expect?¶
You can to be up and running with a new Python Package, and run workflows on Github Actions, such as:
Link: https://github.com/boromir674/biskotaki/actions/runs/4157571651
CI Pipeline, running on Github Actions, defined in .github/
Job Matrix, spanning different platform’s and python version’s
Platforms: ubuntu-latest, macos-latest
Python Interpreters: 3.6, 3.7, 3.8, 3.9, 3.10
Parallel Job execution, generated from the matrix, that runs the Test Suite
Artifact store of Source and Wheel Distributions, factoring Platform and Python Version
Auto Generated Sample Package Biskotaki¶
Check the Biskotaki Python Package Project, for a taste of the project structure and capabilities this Template can generate!
It it entirely generated using this Python Package Template:
Quickstart¶
To install the latest Generator in your environment, run:
pip install cookiecutter-python
The generate-python CLI should become available in your environment.
Next, create a file, let’s call it gen-config.yml, with the following content:
default_context:
project_name: Demo Generated Project
project_type: module+cli
full_name: John Doe
email: john.doe@something.org
github_username: john-doe
project_short_description: 'Demo Generated Project Description'
initialize_git_repo: no
interpreters: {"supported-interpreters": ["3.8", "3.9", "3.10", "3.11"]}
To generate a Python Package Project, run:
mkdir gen-demo-dir
cd gen-demo-dir
generate-python --config-file ../gen-config.yml --no-input
Now, you should have generated a new Project for a Python Package, based on the Template!
The Project should be located in the newly created demo-generated-project directory.
To leverage all out-of-the-box development operations (ie scripts), install tox:
python3 -m pip install --user 'tox<4'
To verify tox available in your environment, run: tox --version
Please, do a cd into the newly created directory, ie cd <my-great-python-package>.
To run the Test Suite, cd into the newly created Project folder, and run:
tox -e dev
All Tests should pass, and you should see a coverage report!
To run Type Checking against the Source Code, run:
tox -e type
All Type Checks should pass!
To setup a Git Repository, run:
git init
git add .
git checkout -b main
git commit -m "Initial commit"
To setup a Remote Repository, run for example:
git remote add origin <remote-repository-url>
git push -u origin main
To trigger the CI/CD Pipeline, run:
git push
Navigate to your github.com/username/your-repo/actions page, to see the CI Pipeline running!
Read the Documentation’s Use Cases section for more on how to leverage your generated Python Package features.
Next Steps¶
To prepare for an Open Source Project Development Lifecycle, you should visit the following websites:
PyPI, test.pypi.org, Dockerhub, and Read the Docs, for setting up Release and Documentation Pipelines
github.com/your-account to configure Actions, through the web UI
Codecov, Codacy, and Codeclimate, for setting up Automated Code Quality, with CI Pipelines
https://www.bestpractices.dev/ for registering your Project for OpenSSF Best Practices Badge
Happy Developing!