feat: add a Makefile goal simple-index that generates a PEP-503 compatible Simple Index directory inside the dist (#947)

jenstroeger · web-flow · commit 2a8412b7d7a5 · 2026-04-08T18:48:59.000+10:00
diff --git a/Makefile b/Makefile
@@ -197,6 +197,19 @@ dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip: docs-md
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt:
 	echo $(SOURCE_DATE_EPOCH) > dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
 
+# Build a PEP-503 compatible Simple Repository directory inside of dist/. For details on
+# the layout of that directory and the normalized project name, see: https://peps.python.org/pep-0503/
+# The directory can then be used to install (hashed) artifacts by using `pip` and
+# its `--extra-index-url` argument: https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url
+PROJECT_NAME := $(shell python -c $$'import re; print(re.sub(r"[-_.]+", "-", "$(PACKAGE_NAME)").lower());')
+.PHONY: simple-index
+simple-index: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz
+	mkdir -p dist/simple-index/$(PROJECT_NAME)
+	echo -e "<!-- https://peps.python.org/pep-0503/ -->\n<!DOCTYPE html><html lang='en'><head><meta name='pypi:repository-version' content='1.3'><title>Simple Index</title></head><body><a href='/$(PACKAGE_NAME)/'>$(PACKAGE_NAME)</a></body></html>" > dist/simple-index/index.html
+	echo -e "<!-- https://peps.python.org/pep-0503/ -->\n<!DOCTYPE html><html lang='en'><head><meta name='pypi:repository-version' content='1.3'><title>Simple Index: $(PROJECT_NAME)</title></head><body><a href='$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl#sha256="$$(python -c "with open('dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl', 'rb') as f: import hashlib; print(hashlib.sha256(f.read()).hexdigest());")"'>$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl</a><a href='$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz#sha256="$$(python -c "with open('dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz', 'rb') as f: import hashlib; print(hashlib.sha256(f.read()).hexdigest());")"'>$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz</a></body></html>" > dist/simple-index/$(PROJECT_NAME)/index.html
+	cp -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/simple-index/$(PROJECT_NAME)/
+	cp -f dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz dist/simple-index/$(PROJECT_NAME)/
+
 # Build the HTML and Markdown documentation from the package's source.
 DOCS_SOURCE := $(shell git ls-files docs/source)
 .PHONY: docs docs-html docs-md
diff --git a/README.md b/README.md
@@ -21,8 +21,9 @@ This repository is intended to be a base template, a cookiecutter for a new Pyth
 [Testing](#testing)  
 [Generating documentation](#generating-documentation)  
 [Synchronizing with this template repo](#synchronizing-with-this-template-repo)  
-[Versioning, publishing and changelog](#versioning-publishing-and-changelog)  
+[Versioning, publishing and distributions](#versioning-publishing-and-distributions)  
 &emsp;[Building from a source distribution package](#building-from-a-source-distribution-package)  
+&emsp;[Using the Simple Index](#using-the-simple-index)  
 [Build integrity using SLSA framework](#build-integrity-using-slsa-framework)  
 [Cleaning up](#cleaning-up)  
 [Frequently asked questions](#frequently-asked-questions)  
@@ -255,7 +256,7 @@ In addition to the default HTML, Sphinx also generates Markdown documentation co
 
 The [sync-with-upstream.yaml](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/sync-with-upstream.yaml) GitHub Acions workflow checks this template repo daily and automatically creates a pull request in the downstream repo if there is a new release. Make sure to set up the GitHub username and email address in this workflow accordingly.
 
-## Versioning, publishing and changelog
+## Versioning, publishing and distributions
 
 To enable automation for [semantic versioning](https://semver.org/), package publishing, and changelog generation it is important to use meaningful [conventional commit messages](https://www.conventionalcommits.org/)! This package template already has a built-in semantic release support enabled which is set up to take care of all three of these aspects — every time changes are pushed to the `release` branch.
 
@@ -299,6 +300,16 @@ SKIP=check-hooks-apply,check-useless-excludes,actionlint make dist
 
 Note that we skip Git hooks that are unnecessary when building from the source distribution. As above, this builds the source package and a binary distribution, and stores both in the  `dist/` folder. And, as expected, setting the `SOURCE_DATE_EPOCH` environment variable to the build epoch value of the original sdist and wheel build results in the bit-exact same binary distribution package!
 
+## Using the Simple Index
+
+Once source and/or binary distribution packages have been built, they can be served using a [PEP 503](https://peps.python.org/pep-0503/) compatible package repository. Simply call
+
+```bash
+make simple-index
+```
+
+to create the package repository in the `dist/` folder, and then use it e.g. with [pip](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url) and its `--extra-index-url` parameter.
+
 ## Build integrity using SLSA framework
 
 The build process in this repository follows the requirements in the [SLSA framework](https://slsa.dev/) to be compliant at level 3. An important aspect of SLSA to improve the supply chain security posture is to generate a verifiable provenance for the build pipeline. Such a provenance can be used to verify the builder and let the consumers check the materials and configurations used while building an artifact. In this repository we use the [generic provenance generator reusable workflow](https://github.com/slsa-framework/slsa-github-generator) to generate a provenance that can attest to the following artifacts in every release:
