Update Guide to ba52293

Signed-off-by: Michał Górny <mgorny@gentoo.org>

1 files changed, 89 insertions, 0 deletions

diff --git a/guide/pypi.html b/guide/pypi.html
index 51cb516..1b182ab 100644
--- a/guide/pypi.html
+++ b/guide/pypi.html
@@ -43,6 +43,94 @@ and other files important to Gentoo packaging.  Should that be the case,
 other archives should be used.  Read the <a class="reference internal" href="distutils.html#source-archives"><span class="std std-ref">Source archives</span></a> section
 for more information.</p>
 <p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/pypi.eclass/index.html">pypi.eclass(5)</a></p>
+<section id="pypi-urls">
+<h2>PyPI URLs<a class="headerlink" href="#pypi-urls" title="Permalink to this heading">¶</a></h2>
+<section id="modern-and-legacy-urls">
+<h3>Modern and legacy URLs<a class="headerlink" href="#modern-and-legacy-urls" title="Permalink to this heading">¶</a></h3>
+<p>The modern form of PyPI URLs include a hash of the distribution file,
+e.g.:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>https://files.pythonhosted.org/packages/20/2e/36e46173a288c1c40853ffdb712c67e0e022df0e1ce50b7b1b50066b74d4/gpep517-13.tar.gz
+</pre></div>
+</div>
+<p>This makes them inconvenient for use in ebuilds, as the hash would have
+to be updated manually on every version bump.  For this reason, Gentoo
+settled on using the legacy form of URLs instead, e.g.:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>https://files.pythonhosted.org/packages/source/g/gpep517/gpep517-13.tar.gz
+</pre></div>
+</div>
+<p>It should be noted that legacy URLs are no longer supported and may stop
+working at an arbitrary time.  Using the eclass is going to make
+the migration to an alternative provider easier than inline URLs.</p>
+<p>The path part of a legacy URL for a source package has the general form
+of:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>/packages/source/<span class="si">${</span><span class="nv">project</span><span class="p">::</span><span class="nv">1</span><span class="si">}</span>/<span class="si">${</span><span class="nv">project</span><span class="si">}</span>/<span class="si">${</span><span class="nv">filename</span><span class="si">}</span>
+</pre></div>
+</div>
+<p>whereas the path for a binary package (wheel) is:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>/packages/<span class="si">${</span><span class="nv">pytag</span><span class="si">}</span>/<span class="si">${</span><span class="nv">project</span><span class="p">::</span><span class="nv">1</span><span class="si">}</span>/<span class="si">${</span><span class="nv">project</span><span class="si">}</span>/<span class="si">${</span><span class="nv">filename</span><span class="si">}</span>
+</pre></div>
+</div>
+<p>In both cases, <code class="docutils literal notranslate"><span class="pre">${project}</span></code> refers to the PyPI project name.
+Technically, PyPI accepts any name that matches the PyPI project name
+after <a class="reference external" href="https://packaging.python.org/en/latest/specifications/name-normalization/">package name normalization</a>.  However, this behavior is not
+guaranteed and using the canonical project name is recommended.</p>
+<p>The filenames and <code class="docutils literal notranslate"><span class="pre">${pytag}</span></code> are described in the subsequent sections.</p>
+</section>
+<section id="source-distribution-filenames">
+<h3>Source distribution filenames<a class="headerlink" href="#source-distribution-filenames" title="Permalink to this heading">¶</a></h3>
+<p>The filename of a source distribution (sdist) has the general form of:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="si">${</span><span class="nv">name</span><span class="si">}</span>-<span class="si">${</span><span class="nv">version</span><span class="si">}</span>.tar.gz
+</pre></div>
+</div>
+<p>where <code class="docutils literal notranslate"><span class="pre">${name}</span></code> is the project name normalized according to <a class="reference external" href="https://peps.python.org/pep-0625/">PEP 625</a>
+and <code class="docutils literal notranslate"><span class="pre">${version}</span></code> is the version following <a class="reference external" href="https://peps.python.org/pep-0440/">PEP 440</a>.  The project
+name normalization transforms all uppercase letters to lowercase,
+and replaces all contiguous runs of <code class="docutils literal notranslate"><span class="pre">._-</span></code> characters with a single
+underscore.</p>
+<p>For example, package <code class="docutils literal notranslate"><span class="pre">Flask-BabelEx</span></code> version <code class="docutils literal notranslate"><span class="pre">1.2.3</span></code> would use
+the following filename:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>flask_babelex-1.2.3.tar.gz
+</pre></div>
+</div>
+<p>However, note that source distributions predating PEP 625 are still
+commonly found, and they use non-normalized project names, e.g.:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>Flask-BabelEx-1.2.3.tar.gz
+</pre></div>
+</div>
+<p>In both instances, the top directory inside the archive has the same
+name as the archive filename, minus <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code> suffix.  Historically,
+<code class="docutils literal notranslate"><span class="pre">.zip</span></code> distributions were used as well.</p>
+</section>
+<section id="binary-distribution-filenames">
+<h3>Binary distribution filenames<a class="headerlink" href="#binary-distribution-filenames" title="Permalink to this heading">¶</a></h3>
+<p>The filename of a binary distribution (wheel) has the general form of:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="si">${</span><span class="nv">name</span><span class="si">}</span>-<span class="si">${</span><span class="nv">version</span><span class="si">}</span>-<span class="si">${</span><span class="nv">pytag</span><span class="si">}</span>-<span class="si">${</span><span class="nv">abitag</span><span class="si">}</span>-<span class="si">${</span><span class="nv">platformtag</span><span class="si">}</span>.whl
+</pre></div>
+</div>
+<p>Similarly to source distributions, <code class="docutils literal notranslate"><span class="pre">${name}</span></code> and <code class="docutils literal notranslate"><span class="pre">${version}</span></code>
+specify the normalized project name and version (normalization follows
+the same rules and is specified in <a class="reference external" href="https://packaging.python.org/en/latest/specifications/binary-distribution-format/">binary distribution format</a>
+specification).</p>
+<p><code class="docutils literal notranslate"><span class="pre">${pytag}</span></code> is the tag specifying Python version that the wheel was
+built for.  This can be <code class="docutils literal notranslate"><span class="pre">py2.py3</span></code> or <code class="docutils literal notranslate"><span class="pre">py3</span></code> for pure Python wheels,
+or e.g. <code class="docutils literal notranslate"><span class="pre">cp39</span></code> for CPython 3.9 wheels.  <code class="docutils literal notranslate"><span class="pre">${abitag}</span></code> specifies
+the appropriate ABI (<code class="docutils literal notranslate"><span class="pre">none</span></code> for pure Python wheels),
+<code class="docutils literal notranslate"><span class="pre">${platformtag}</span></code> the platform (<code class="docutils literal notranslate"><span class="pre">any</span></code> for pure Python wheels).</p>
+<p>For example, the modern wheel for the aforementioned package would be
+named:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>flask_babelex-1.2.3-py3-none-any.whl
+</pre></div>
+</div>
+<p>However, some distributions use older normalization rules specified
+in <a class="reference external" href="https://peps.python.org/pep-0427/">PEP 427</a>.  In this case, runs of characters other than alphanumeric
+characters and dots (<code class="docutils literal notranslate"><span class="pre">[^\w\d.]+</span></code>) are replaced by a single underscore.
+Notably, this means that uppercase letters and dots are left in place.
+In this normalization, the example wheel is named:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>Flask_BabelEx-1.2.3-py3-none-any.whl
+</pre></div>
+</div>
+</section>
+</section>
 <section id="packages-with-matching-name-and-version">
 <h2>Packages with matching name and version<a class="headerlink" href="#packages-with-matching-name-and-version" title="Permalink to this heading">¶</a></h2>
 <p>In the most common case, the upstream package will have exactly the same
@@ -144,6 +232,7 @@ the wheel filename.  It has a matching synopsis:</p>
 <li class="toctree-l1"><a class="reference internal" href="test.html">Tests in Python packages</a></li>
 <li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">pypi — helper eclass for PyPI archives</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#pypi-urls">PyPI URLs</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#packages-with-matching-name-and-version">Packages with matching name and version</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#customizing-the-generated-url">Customizing the generated URL</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#fetching-wheels">Fetching wheels</a></li>