pypackitup - Python Package Template

Template repository for developing Python packages.


Do you like the Python Package Template? Star the repository on GitHub and please consider helping support its ongoing development:


READ THE DOCS HERE!
Detailed documentation can be found at https://package.wrencode.dev.

Table of Contents


About

The Python Package Template is an example for Python package development.

Dependencies

The Python Package Template does not have any third-party dependencies to run the code. It has several development dependencies, which can be seen in the package pyproject.toml.


Setup

The below list covers all updates needed in the Python Package Template when using it to create a new Python package:

Configuration

  • pyproject.toml: Update all relevant fields as needed for the new package.

Version Control

  • .gitignore: Add any package-specific files that should not be checked in to version control.
  • .github/ISSUE_TEMPLATE/: Make any package-specific changes to the project issue templates.
  • .github/workflows/python-package.yml: Update the supported Python versions and add any necessary CI/CD steps.

Documentation

  • README.md: Update the README.md with all necessary package documentation.
  • mkdocs.yml: Update the nav section with all necessary pages and their corresponding Markdown files (see below).
  • docs-mkdocs/CNAME: Update the CNAME file with the desired mkdocs documentation GitHub Pages custom domain.
  • docs-mkdocs/extra.css: Add any custom CSS for the mkdocs documentation.
  • docs-mkdocs/extra.js: Add any custom JavaScript for the mkdocs documentation.
  • docs-mkdocs/*.md: Add any necessary Markdown (.md) files for pages in the mkdocs documentation.
  • docs-mkdocs/*.svg/*.png/*.jpg/etc.: Add any necessary images for the mkdocs documentation.

Code

  • src/pypackitup/: Rename this directory to match the project directory and follow the PEP naming conventions for the package.
  • src/pypackitup/__init__.py: Update the package __init__.py with available imports.
  • src/pypackitup/*.py: Add package code.
  • tests/: Add tests for package code.

Deployment

(Optional) Check pyproject.toml for latest dependency versions.

 

(Optional) Update virtual machine with the latest dependencies:

uv sync --all-extras --dev

 

Lint code with ruff:

ruff check .

 

Check code security with bandit:

bandit -c pyproject.toml -r .

 

(Optional) Run all pytest tests (see following commands for running subsets of tests):

uv run pytest tests

 

(Optional) Run all pytest tests verbosely:

 uv run pytest -v -s tests

 

(Optional) Run all tests from pytest file:

uv run pytest -v -s tests/test_helloworld.py

 

(Optional) Run specific test from pytest file:

uv run pytest -v -s tests/test_helloworld.py -k test_main

 

(Optional) Test Python support using act for GitHub Actions:

act -j build

Note: If act is unable to locate Docker, make sure that the required /var/run/docker.sock symlink exists. If it does not, you can fix it by running:

sudo ln -s "$HOME/.docker/run/docker.sock" /var/run/docker.sock`

 

(Optional) Build the PyPI package independent of deployment:

make build

 

(Optional) Test packages for PyPI deployment:

make verify_build

 

(Optional) Check MkDocs documentation by serving it at http://localhost:8000/ locally:

make test_docs

 

(Optional) Build the PyPI package and MkDocs documentation independent of deployment:

make docs

Note: Running make test_docs from the previous step recreates the documentation without building the PyPI package.

 

Create a git commit:

git add .
git commit -m 'commit message'

 

Update the git tag with the new version (git tag -a [tag_name/version] -m [message]):

git tag -a v1.0.0 -m 'release message'
git push origin --tags

 

Install twine (if not already installed):

uv add twine

 

(Optional) Test deployment by building the PyPI packages, recreating the documentation, and deploying to Test PyPI:

make test_deploy

 

Deploy the package by building it, recreating the documentation, and deploying the package to PyPI:

make deploy

 

Create a second git commit with updated version number and documentation:

git add .
git commit -m 'update version number and docs'

 

Update package git repository:

git push