Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jenstroeger merged 6 commits into from
Apr 8, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b65260a
feat: add a Makefile goal `simple-index` that generates a PEP-503 com…
jenstroeger Jun 2, 2025
8fe1d88
chore: gah, fixt typos
jenstroeger Jun 2, 2025
a6b4a2a
fix: normalize the Simple Repo project name from the package name as …
jenstroeger Jun 4, 2025
85132bb
chore: add hash fragments to package URLs
jenstroeger Jun 5, 2025
9ac4aaf
chore: validate generated index.html files
jenstroeger Jun 5, 2025
a8d52b7
docs: mention in README
jenstroeger Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
jenstroeger marked this conversation as resolved.
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
Expand Down
15 changes: 13 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down
Loading