feat: add a Makefile goal `simple-index` that generates a PEP-503 compatible Simple Index directory inside the dist by jenstroeger · Pull Request #947 · jenstroeger/python-package-template · GitHub

As discussed with @behnazh this changes makes available a PEP-503 compatible Simple Repository directory inside of our dist/ directory.

We can now use pip and its --extra-index-url argument to install packages, including support for their package hashes. For example to install the binary package (pip’s default):

> pip install --extra-index-url file:///path/to/dist/simple-index/ package
Looking in indexes: https://pypi.org/simple, file:///path/to/dist/simple-index/
Processing /path/to/dist/simple-index/package/package-2.16.0-py3-none-any.whl
Installing collected packages: package
Successfully installed package-2.16.0

or the source package (purge the pip cache first!):

> pip install --extra-index-url file:///path/to/dist/simple-index/ --no-binary package package
Looking in indexes: https://pypi.org/simple, file:///path/to/dist/simple-index/
Processing /path/to/dist/simple-index/package/package-2.16.0.tar.gz
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: package
  Building wheel for package (pyproject.toml) ... done
  Created wheel for package: filename=package-2.16.0-py3-none-any.whl size=13457 sha256=9791036dfa1a658e1e43afaa41404a126f3e01b8f36ccc1f98551bbfe50c1da4
  Stored in directory: /path/to/pip/wheels/03/64/4f/969f1993221587084c494fb7687826621c9273963119358c62
Successfully built package
Installing collected packages: package
Successfully installed package-2.16.0

or from the generated requirements file using package hashes:

> pip install --extra-index-url file:///path/to/dist/simple-index/ --require-hashes --requirement package-2.16.0-requirements.txt 
Looking in indexes: https://pypi.org/simple, file:///path/to/dist/simple-index/
...
Processing /path/to/dist/simple-index/package/package-2.16.0-py3-none-any.whl (from -r package-2.16.0-requirements.txt (line 982))
...

Should we mention/document this in the README, or is the comment in the Makefile enough?

Hmm, should we call the Makefile goal simple-repo (because as per PEP-503 this is a simple repository API) instead of simple-index? But then the pip command line option is called --extra-index-url so the generated folder is an “index” implementing the Simple Repo API. Maybe call the goal extra-index?

🤷🏻‍♂️

@behnazh the generated package/index.html file in the simple index

<!-- https://peps.python.org/pep-0503/ -->
<!DOCTYPE html>
  <html>
    <head><meta name='pypi:repository-version' content='1.3'></head>
    <body>
      <a href='package-2.16.0-py3-none-any.whl'>package-2.16.0-py3-none-any.whl</a>
      <a href='package-2.16.0.tar.gz'>package-2.16.0.tar.gz</a>
    </body>
</html>

does not make use of digest hashes as recommended in the specification:

The URL SHOULD include a hash in the form of a URL fragment with the following syntax: #<hashname>=<hashvalue>, where <hashname> is the lowercase name of the hash function (such as sha256) and <hashvalue> is the hex encoded digest.

We should probably add that and I think that would look something like this:

<a href='package-2.16.0-py3-none-any.whl#sha256=82a57ea6a6ec2cea54501b4798dd4684b3666fde92ba1bb524f37791b1ef810b'>package-2.16.0-py3-none-any.whl</a>
<a href='package-2.16.0.tar.gz#sha256=f75bb93f5b3097a3c8f93c3bc4bc357fc17e1db266fd2de04dab76c236e247c9'>package-2.16.0.tar.gz</a>

Thanks for this PR, it's great.

Should we mention/document this in the README, or is the comment in the Makefile enough?
Yes, that's a good idea.

Can we test this feature somehow in _build.yaml GitHub Action?

Can we test this feature somehow in _build.yaml GitHub Action?

Hmm… you mean to use the simple index 🤔 Probably if we would add a Docker file? Hmm…

Can we test this feature somehow in _build.yaml GitHub Action?

Hmm… you mean to use the simple index 🤔 Probably if we would add a Docker file? Hmm…

I don't think you would need to use a Docker file. You can test it in a separate job perhaps.

@behnazh I think we should/need to document this “feature” in the README too, huh?

…patible Simple Index directory inside the dist

…per PEP 503

jenstroeger requested a review from behnazh as a code owner June 2, 2025 09:28

jenstroeger commented Jun 2, 2025

View reviewed changes

Comment thread Makefile

jenstroeger mentioned this pull request Jun 3, 2025

fix: building the package’s dist files should *always* generate the build’s epoch as well, even when using the individual package goals only #950

Merged

behnazh approved these changes Sep 10, 2025

View reviewed changes

behnazh previously approved these changes Apr 8, 2026

View reviewed changes

jenstroeger added 6 commits April 8, 2026 18:18

feat: add a Makefile goal simple-index that generates a PEP-503 com…

b65260a

…patible Simple Index directory inside the dist

chore: gah, fixt typos

8fe1d88

fix: normalize the Simple Repo project name from the package name as …

a6b4a2a

…per PEP 503

chore: add hash fragments to package URLs

85132bb

chore: validate generated index.html files

9ac4aaf

docs: mention in README

a8d52b7

jenstroeger dismissed behnazh’s stale review via a8d52b7 April 8, 2026 08:41

jenstroeger force-pushed the add-simple-index-to-dist branch from ea85098 to a8d52b7 Compare April 8, 2026 08:41

behnazh approved these changes Apr 8, 2026

View reviewed changes

jenstroeger merged commit 2a8412b into main Apr 8, 2026
17 checks passed

feat: add a Makefile goal `simple-index` that generates a PEP-503 compatible Simple Index directory inside the dist by jenstroeger · Pull Request #947 · jenstroeger/python-package-template · GitHub

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

feat: add a Makefile goal simple-index that generates a PEP-503 compatible Simple Index directory inside the dist#947
jenstroeger merged 6 commits into
mainfrom
add-simple-index-to-dist

jenstroeger commented Jun 2, 2025 •
edited
Loading

Uh oh!

Uh oh!

Uh oh!

jenstroeger commented Jun 4, 2025 •
edited
Loading

Uh oh!

Uh oh!

jenstroeger commented Jun 4, 2025

Uh oh!

behnazh commented Jun 14, 2025

Uh oh!

behnazh commented Jun 14, 2025

Uh oh!

jenstroeger commented Jun 14, 2025

Uh oh!

behnazh commented Sep 10, 2025

Uh oh!

jenstroeger commented Dec 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: add a Makefile goal `simple-index` that generates a PEP-503 compatible Simple Index directory inside the dist by jenstroeger · Pull Request #947 · jenstroeger/python-package-template · GitHub

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

Conversation

jenstroeger commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jenstroeger commented Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jenstroeger commented Jun 4, 2025

Uh oh!

behnazh commented Jun 14, 2025

Uh oh!

behnazh commented Jun 14, 2025

Uh oh!

jenstroeger commented Jun 14, 2025

Uh oh!

behnazh commented Sep 10, 2025

Uh oh!

jenstroeger commented Dec 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jenstroeger commented Jun 2, 2025 •
edited
Loading

jenstroeger commented Jun 4, 2025 •
edited
Loading