Python Starter Kit
A deployment-ready Python 3 application template for quick, standards-based project setup.
Introduction
Background: The Python Starter Kit serves as a comprehensive template for Python 3 applications to streamline development processes. It exemplifies an integrated approach to build, release and publish using GitHub's CI/CD automation. By leveraging modern Python tooling, the kit simplifies the process of compiling, tagging, releasing and publishing to the Python Package Index (PyPi). It adheres to PEP 517/518 standards with TOML-based configurations to ensure a modern, declarative programming approach.
Use Cases:
- Streamlining Python project setup and configuration.
- Turn-key code analyses, linting and security scanning.
- Facilitating publishing of Python packages to PyPi.
- Update build and release tooling to modern standards using PEP 517/518 compliant tooling with declarative TOML-based configurations in a
pyproject.toml
file.
Prerequisites
- GitHub account with repository creation rights.
- Familiarity with Python, Docker and GitHub Actions.
- Access to PyPi for package publishing.
Quick Start
Click the link above to access the starter kit and begin setting up your project using Python best practices. Select GitHub's "Use this template" feature to leverage the template repository.
Step-by-Step Guide
Team Consensus: Discuss and agree on continuous integration best practices with your development team. Establish a workflow for building, publishing and releasing software.
Create a Repository:
- Use our repository template for a quick start.
- Alternatively, clone and manually edit our starter kit.
Setup Account Credentials:
- Register to create accounts on Test PyPi and PyPi. You'll use one account for testing and one for deployments of your artifact.
- Generate API tokens on PyPI for your accounts. Name your tokens
PYPI_API_TOKEN
and copy their value for the next step below. - Configure these tokens in your repository's GitHub Secrets.
Choose a Unique Python 3 Module Name: Ensure it's distinct from existing PyPi modules.
Move Code into Place:
- Rename
slim_sample_project
to your module name. - For existing projects, integrate your Python 3 code into the new project structure underneath the module-name directory.
Shortcut
Lines requiring code updates are commented with the keywordMODIFY
.
Documentation requiring updates are marked with the keywordINSERT
.
- Rename
Apply Project Settings:
- Update
pyproject.toml
to update build system dependencies- Edit the
write_to
variable to point to the directory containing your Python 3 code.
- Edit the
- Update
setup.cfg
to specify build system configurations- Edit the metadata keywords to set appropriate keyword values to apply to your project.
- Set
name
to match your unique module name. - Modify
console_scripts
to point at your entry-point:- If your module launches from a command-line, define an executable inside your module:
executable-name = my_package.module:function
. - Set the value as empty if there is no entry-point.
- If your module launches from a command-line, define an executable inside your module:
- Update URLs for your project.
- Replace
NASA-AMMOS/slim-starterkit-python
with the project/repo_name for your cloned project (or refactoring on an existing repo).
- Replace
- Update
author
,author_email
,description
andkeywords
to reflect your project details
- Set
- Edit the metadata keywords to set appropriate keyword values to apply to your project.
- Update
Build Locally: The application will build, install and deploy from a local command line when all configurations are properly set.
- Install local tooling and requirements
- Clean and build and clean again after module builds successfully
Information
To validate deployment, we publish the module to the Test PyPi sandbox by default. To publish on the official PyPi, a minor configuration change is required. All previous steps must be complete and the application must build successfully.
Build on GitHub: A release kicks off a build and release process in GitHub Actions.
- Test publication on Test PyPi
- Update the version number in the
version.py
file. - Kick off a build by releasing your product using the same version.
- When the product builds successfully, proceed to the next section, Release to PyPi. Otherwise, revisit earlier steps and check for errors or other invalid settings.
- Update the version number in the
- Release to PyPi (simple configuration changes point at the release server)
- Update
PYPI_API_TOKEN
to point at PyPi in GitHub Secrets in your newly created repository- In the repository, select the
Settings
tab and navigate toSecurity
:Secrets and variables
-->Actions
. - Recalling the PyPi token previously saved in Setup Account Credentials (step 3 above): Edit the
PYPI_API_TOKEN
inRepository secrets
to the saved PyPi token value for PyPi. (In other words, replace the test token with the regular, non-test PyPi token.)
- In the repository, select the
- Change the
python-publish.yml
configuration to remove Test PyPi coordinates- Remove '
--repository testpypi
' from the one-line publish command to read:twine upload --verbose dist/*.whl dist/*.zip
- Remove '
- Update the version number in the
version.py
file. - Kick off a build by tagging and releasing your product using the same version number.
- Update
- Test publication on Test PyPi
Additional Files
This starter kit produces several deliverables deployed for distribution:
- GitHub
- PyPi
- Fully documented site with project links
- Released Python 3 distributions:
Frequently Asked Questions (FAQ)
Q: What tooling is necessary to use the starter kit?
A: Python 3 version 3.9 or greater must be installed with a working package manager (
pip
). As well, you'll need the latest versions ofpip
,build
,setuptools
,twine
andwheel
.python3 --version # must report Python >3.9.x
pip3 install --upgrade pip
pip3 install --upgrade build setuptools setuptools_scm twine wheelQ: How do I choose a unique module name for PyPi?
A: Research existing modules on PyPi and select a name that is not already in use. Consider using a creative and/or descriptive name relevant to your project.
Credits
Authorship:
Acknowledgements:
- Inspiration and practices from modern Python tooling and GitHub CI/CD workflows.
Feedback and Contributions
We welcome feedback and contributions to improve this guide. Please see our contribution guidelines.