diff options
Diffstat (limited to 'guide/pypi.html')
| -rw-r--r-- | guide/pypi.html | 91 |
1 files changed, 73 insertions, 18 deletions
diff --git a/guide/pypi.html b/guide/pypi.html index 1b182ab..e306f49 100644 --- a/guide/pypi.html +++ b/guide/pypi.html @@ -136,11 +136,47 @@ In this normalization, the example wheel is named:</p> <p>In the most common case, the upstream package will have exactly the same name as the Gentoo package, and the version numbers will be entirely compatible. In this case, it is sufficient to inherit the eclass, -and it will automatically set a suitable default <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code>. The URI -will be equivalent to:</p> +and it will automatically set a suitable default <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code>. +The result will be roughly equivalent to:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"</span> <span class="s2"> https://files.pythonhosted.org/packages/source/</span><span class="si">${</span><span class="nv">PN</span><span class="p">::</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz</span> <span class="s2">"</span> +<span class="nv">S</span><span class="o">=</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span>/<span class="si">${</span><span class="nv">P</span><span class="si">}</span> +</pre></div> +</div> +<p>with <code class="docutils literal notranslate"><span class="pre">${P}</span></code> actually using the normalized project name and the Gentoo +version being translated to its PyPI equivalent. The version +translation performs the following replacements:</p> +<blockquote> +<div><table class="docutils align-default"> +<thead> +<tr class="row-odd"><th class="head"><p>Gentoo suffix</p></th> +<th class="head"><p>PyPI suffix</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>_alpha</p></td> +<td><p>a</p></td> +</tr> +<tr class="row-odd"><td><p>_beta</p></td> +<td><p>b</p></td> +</tr> +<tr class="row-even"><td><p>_rc</p></td> +<td><p>rc</p></td> +</tr> +<tr class="row-odd"><td><p>_p</p></td> +<td><p>.post</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>If the project in question uses a build system that is not compliant +with <a class="reference external" href="https://peps.python.org/pep-0625/">PEP 625</a> and has uppercase letters or dots in its name, you may +need to set <code class="docutils literal notranslate"><span class="pre">PYPI_NO_NORMALIZE</span></code> to a non-empty value to disable name +normalization, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">PYPI_NO_NORMALIZE</span><span class="o">=</span><span class="m">1</span> + +inherit<span class="w"> </span>distutils-r1<span class="w"> </span>pypi </pre></div> </div> <p>Note that <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code> is not combined between eclasses and ebuilds. @@ -158,42 +194,61 @@ to the variable or the default will be overwritten, e.g.:</p> <section id="customizing-the-generated-url"> <h2>Customizing the generated URL<a class="headerlink" href="#customizing-the-generated-url" title="Permalink to this heading">¶</a></h2> <p>The default value may not be suitable for your package if it uses -a different project name, version numbers that are incompatible with -Gentoo or the legacy <code class="docutils literal notranslate"><span class="pre">.zip</span></code> sdist format. The <code class="docutils literal notranslate"><span class="pre">pypi_sdist_url</span></code> -function can be used to generate URLs in that case. Its usage is:</p> -<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pypi_sdist_url<span class="w"> </span><span class="o">[</span><project><span class="w"> </span><span class="o">[</span><version><span class="w"> </span><span class="o">[</span><suffix><span class="o">]]]</span> +a different project name than the Gentoo package name, a version number +that needs to be translated differently or the legacy <code class="docutils literal notranslate"><span class="pre">.zip</span></code> sdist +format. The <code class="docutils literal notranslate"><span class="pre">pypi_sdist_url</span></code> function can be used to generate URLs +in that case. Its usage is:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pypi_sdist_url<span class="w"> </span><span class="o">[</span>--no-normalize<span class="o">]</span><span class="w"> </span><span class="o">[</span><project><span class="w"> </span><span class="o">[</span><version><span class="w"> </span><span class="o">[</span><suffix><span class="o">]]]</span> +</pre></div> +</div> +<p>with package defaulting to <code class="docutils literal notranslate"><span class="pre">${PN}</span></code>, version to translated <code class="docutils literal notranslate"><span class="pre">${PV}</span></code> +and suffix to <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code>. The generated filename uses <a class="reference external" href="https://peps.python.org/pep-0625/">PEP 625</a> +normalization, unless <code class="docutils literal notranslate"><span class="pre">--no-normalize</span></code> is provided +(<code class="docutils literal notranslate"><span class="pre">PYPI_NO_NORMALIZE</span></code> does not affect explicit function calls). +For example, the Gentoo <code class="docutils literal notranslate"><span class="pre">dev-python/markups</span></code> package uses title-case +<code class="docutils literal notranslate"><span class="pre">Markups</span></code> project name and legacy filename, and so the ebuild needs +to use:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>inherit<span class="w"> </span>distutils-r1<span class="w"> </span>pypi + +<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>pypi_sdist_url<span class="w"> </span>--no-normalize<span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">PN</span><span class="p">^</span><span class="si">}</span><span class="s2">"</span><span class="k">)</span><span class="s2">"</span> +<span class="nv">S</span><span class="o">=</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span>/<span class="si">${</span><span class="nv">P</span><span class="p">^</span><span class="si">}</span> </pre></div> </div> -<p>with package defaulting to <code class="docutils literal notranslate"><span class="pre">${PN}</span></code>, version to <code class="docutils literal notranslate"><span class="pre">${PV}</span></code> and suffix -to <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code>. For example, the Gentoo <code class="docutils literal notranslate"><span class="pre">dev-python/markups</span></code> package -uses title-case <code class="docutils literal notranslate"><span class="pre">Markups</span></code> project name, and so the ebuild uses:</p> +<p>Should the package start using source distributions with normalized +filenames, then only project name would need to be overriden +and the default <code class="docutils literal notranslate"><span class="pre">S</span></code> would be correct (<code class="docutils literal notranslate"><span class="pre">Markups</span></code> and <code class="docutils literal notranslate"><span class="pre">markups</span></code> +normalize the same):</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>inherit<span class="w"> </span>distutils-r1<span class="w"> </span>pypi <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>pypi_sdist_url<span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">PN</span><span class="p">^</span><span class="si">}</span><span class="s2">"</span><span class="k">)</span><span class="s2">"</span> </pre></div> </div> +<p>Note that due to project name normalization, the ebuild would also work +without <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code> override. However, it is recommended to pass +the canonical project name, as normalization is not guaranteed.</p> </section> <section id="fetching-wheels"> <h2>Fetching wheels<a class="headerlink" href="#fetching-wheels" title="Permalink to this heading">¶</a></h2> <p>In very specific cases, it may be necessary to fetch wheels (i.e. prebuilt Python packages) instead. The <code class="docutils literal notranslate"><span class="pre">pypi_wheel_url</span></code> function is provided to aid this purpose. Its usage is:</p> -<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pypi_wheel_url<span class="w"> </span><span class="o">[</span><project><span class="w"> </span><span class="o">[</span><version><span class="w"> </span><span class="o">[</span><python-tag><span class="w"> </span><span class="o">[</span><abi-platform-tag><span class="o">]]]]</span> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pypi_wheel_url<span class="w"> </span><span class="o">[</span>--unpack<span class="o">]</span><span class="w"> </span><span class="o">[</span><project><span class="w"> </span><span class="o">[</span><version><span class="w"> </span><span class="o">[</span><python-tag><span class="w"> </span><span class="o">[</span><abi-platform-tag><span class="o">]]]]</span> </pre></div> </div> -<p>with package defaulting to <code class="docutils literal notranslate"><span class="pre">${PN}</span></code>, version to <code class="docutils literal notranslate"><span class="pre">${PV}</span></code>, python-tag -to <code class="docutils literal notranslate"><span class="pre">py3</span></code> and abi-platform-tag to <code class="docutils literal notranslate"><span class="pre">none-any</span></code> (i.e. indicating a pure -Python package). For example, <code class="docutils literal notranslate"><span class="pre">dev-python/ensurepip-setuptools</span></code> -does:</p> +<p>with package defaulting to <code class="docutils literal notranslate"><span class="pre">${PN}</span></code>, version to translated <code class="docutils literal notranslate"><span class="pre">${PV}</span></code>, +python-tag to <code class="docutils literal notranslate"><span class="pre">py3</span></code> and abi-platform-tag to <code class="docutils literal notranslate"><span class="pre">none-any</span></code> +(i.e. indicating a pure Python package). For example, +<code class="docutils literal notranslate"><span class="pre">dev-python/ensurepip-setuptools</span></code> does:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>inherit<span class="w"> </span>pypi <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>pypi_wheel_url<span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">PN</span><span class="p">#ensurepip-</span><span class="si">}</span><span class="s2">"</span><span class="k">)</span><span class="s2">"</span> </pre></div> </div> <p>Note that wheels are ZIP archives suffixed <code class="docutils literal notranslate"><span class="pre">.whl</span></code>, and they are not -unpacked by the package manager automatically. You either need to -unzip it explicitly or use <code class="docutils literal notranslate"><span class="pre">-></span></code> to rename it, e.g. by appending -<code class="docutils literal notranslate"><span class="pre">.zip</span></code> suffix. Remember to add an explicit dependency -on <code class="docutils literal notranslate"><span class="pre">app-arch/unzip</span></code> as well.</p> +unpacked by the package manager automatically. Should you need them +unpacked, you can pass <code class="docutils literal notranslate"><span class="pre">--unpack</span></code> option to include a <code class="docutils literal notranslate"><span class="pre">-></span></code> operator +that renames the wheel to use <code class="docutils literal notranslate"><span class="pre">.whl.zip</span></code> suffix, causing it to be +unpacked. Remember to add an explicit dependency on <code class="docutils literal notranslate"><span class="pre">app-arch/unzip</span></code> +in that case.</p> <p>The <code class="docutils literal notranslate"><span class="pre">pypi_wheel_filename</span></code> function is provided to aid getting the wheel filename. It has a matching synopsis:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pypi_wheel_filename<span class="w"> </span><span class="o">[</span><project><span class="w"> </span><span class="o">[</span><version><span class="w"> </span><span class="o">[</span><python-tag><span class="w"> </span><span class="o">[</span><abi-platform-tag><span class="o">]]]]</span> |