Skip to main content

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

SLIM Starterkit Python

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

  1. Team Consensus: Discuss and agree on continuous integration best practices with your development team. Establish a workflow for building, publishing and releasing software.

  2. Create a Repository:

  3. 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.
  4. Choose a Unique Python 3 Module Name: Ensure it's distinct from existing PyPi modules.

  5. 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 keyword MODIFY.
      Documentation requiring updates are marked with the keyword INSERT.

  6. Apply Project Settings:

    • Update pyproject.toml to update build system dependencies
    • Update setup.cfg to specify build system configurations
      • Edit the metadata keywords to set appropriate keyword values to apply to your project.
        1. Set name to match your unique module name.
        2. Modify console_scripts to point at your entry-point:
          1. If your module launches from a command-line, define an executable inside your module: executable-name = my_package.module:function.
          2. Set the value as empty if there is no entry-point.
        3. Update URLs for your project.
          1. Replace NASA-AMMOS/slim-starterkit-python with the project/repo_name for your cloned project (or refactoring on an existing repo).
        4. Update author, author_email, description and keywords to reflect your project details
  7. 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.

  8. Build on GitHub: A release kicks off a build and release process in GitHub Actions.


Additional Files

This starter kit produces several deliverables deployed for distribution:


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 of pip, build, setuptools, twine and wheel.

    python3 --version  # must report Python >3.9.x
    pip3 install --upgrade pip
    pip3 install --upgrade build setuptools setuptools_scm twine wheel
  • Q: 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.