From 78dccd650f42a0752e8b0b6adb5c81347b4a9fe2 Mon Sep 17 00:00:00 2001 From: Rolando Bosch Date: Sun, 6 Sep 2026 03:27:21 -0400 Subject: [PATCH 1/2] Document hashes for manually hosted package indexes --- source/guides/hosting-your-own-index.rst | 25 +++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst index ebcd228ee3..97ba646db9 100644 --- a/source/guides/hosting-your-own-index.rst +++ b/source/guides/hosting-your-own-index.rst @@ -52,6 +52,26 @@ directory with autoindex enabled. For an example using the built in Web server in `Twisted`_, you would simply run ``twistd -n web --path .`` and then instruct users to add the URL to their installer's configuration. +An automatically generated directory listing usually doesn't include artifact +hashes. Without hashes in the repository links, tools may be unable to record +them in lock files. To include a SHA-256 hash, generate an ``index.html`` file +in each project directory and append the hash to each artifact URL as described +by the :ref:`Simple Repository API `: + +.. code-block:: html + + + + Links for foo + +

Links for foo

+ Foo-1.0.tar.gz + + + +Replace ``3571b...`` with the full SHA-256 digest of the artifact. You can use +:ref:`dumb-pypi` to generate a static repository with hashes and other Simple +Repository API metadata from a directory of package artifacts. Existing projects ================= @@ -105,11 +125,6 @@ Existing projects - - also mirroring; manual synchronisation - * - :ref:`dumb-pypi` - - - - - - not a server, but a static file site generator - * - :ref:`httpserver` - - From fb577c1323c661fbbf123d0d97b494ce9fe37101 Mon Sep 17 00:00:00 2001 From: Rolando Bosch Date: Tue, 8 Sep 2026 17:30:26 -0400 Subject: [PATCH 2/2] Clarify manual index hash guidance --- source/guides/hosting-your-own-index.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst index 97ba646db9..fe981bd2a6 100644 --- a/source/guides/hosting-your-own-index.rst +++ b/source/guides/hosting-your-own-index.rst @@ -52,11 +52,12 @@ directory with autoindex enabled. For an example using the built in Web server in `Twisted`_, you would simply run ``twistd -n web --path .`` and then instruct users to add the URL to their installer's configuration. -An automatically generated directory listing usually doesn't include artifact -hashes. Without hashes in the repository links, tools may be unable to record -them in lock files. To include a SHA-256 hash, generate an ``index.html`` file -in each project directory and append the hash to each artifact URL as described -by the :ref:`Simple Repository API `: +A bare, automatically generated directory listing, such as one produced by a +generic autoindex module, may not include artifact hashes. Without hashes in +the repository links, tools may be unable to record them in lock files. To +include a SHA-256 hash, generate an ``index.html`` file in each project +directory and append the hash to each artifact URL as described by the +:ref:`Simple Repository API `: .. code-block:: html @@ -71,7 +72,9 @@ by the :ref:`Simple Repository API `: Replace ``3571b...`` with the full SHA-256 digest of the artifact. You can use :ref:`dumb-pypi` to generate a static repository with hashes and other Simple -Repository API metadata from a directory of package artifacts. +Repository API metadata from a directory of package artifacts. Full repository +implementations should prefer the JSON variant of the Simple Repository API, +which requires a (possibly empty) ``hashes`` mapping for each file. Existing projects =================