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 theREADME.md
with all necessary package documentation.mkdocs.yml
: Update thenav
section with all necessary pages and their corresponding Markdown files (see below).docs-mkdocs/CNAME
: Update theCNAME
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