diff options
| -rw-r--r-- | guide/_sources/pypi.rst.txt | 91 | ||||
| -rw-r--r-- | guide/pypi.html | 212 |
2 files changed, 303 insertions, 0 deletions
diff --git a/guide/_sources/pypi.rst.txt b/guide/_sources/pypi.rst.txt new file mode 100644 index 0000000..071c7c4 --- /dev/null +++ b/guide/_sources/pypi.rst.txt @@ -0,0 +1,91 @@ +====================================== +pypi — helper eclass for PyPI archives +====================================== + +.. highlight:: bash + +The ``pypi`` eclass is a small eclass to facilitate fetching sources +from PyPI. It abstracts away the complexity of PyPI URLs, and makes it +easier to adapt ``SRC_URI`` to their future changes. + +Please note that PyPI archives are not always the best choice +for distfiles. In particular, they frequently are missing tests +and other files important to Gentoo packaging. Should that be the case, +other archives should be used. Read the :ref:`source archives` section +for more information. + +Eclass reference: `pypi.eclass(5)`_ + + +Packages with matching name and version +======================================= +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 ``SRC_URI``. The URI +will be equivalent to:: + + SRC_URI=" + https://files.pythonhosted.org/packages/source/${PN::1}/${PN}/${P}.tar.gz + " + +Note that ``SRC_URI`` is not combined between eclasses and ebuilds. +Should you need to fetch additional files, you need to explicitly append +to the variable or the default will be overwritten, e.g.:: + + inherit distutils-r1 pypi + + SRC_URI+=" + https://github.com/pytest-dev/execnet/commit/c0459b92bc4a42b08281e69b8802d24c5d3415d4.patch + -> ${P}-pytest-7.2.patch + " + + +Customizing the generated URL +============================= +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 ``.zip`` sdist format. The ``pypi_sdist_url`` +function can be used to generate URLs in that case. Its usage is:: + + pypi_sdist_url [<project> [<version> [<suffix>]]] + +with package defaulting to ``${PN}``, version to ``${PV}`` and suffix +to ``.tar.gz``. For example, the Gentoo ``dev-python/markups`` package +uses title-case ``Markups`` project name, and so the ebuild uses:: + + inherit distutils-r1 pypi + + SRC_URI="$(pypi_sdist_url "${PN^}")" + + +Fetching wheels +=============== +In very specific cases, it may be necessary to fetch wheels +(i.e. prebuilt Python packages) instead. The ``pypi_wheel_url`` +function is provided to aid this purpose. Its usage is:: + + pypi_wheel_url [<project> [<version> [<python-tag> [<abi-platform-tag>]]]] + +with package defaulting to ``${PN}``, version to ``${PV}``, python-tag +to ``py3`` and abi-platform-tag to ``none-any`` (i.e. indicating a pure +Python package). For example, ``dev-python/ensurepip-setuptools`` +does:: + + inherit pypi + SRC_URI="$(pypi_wheel_url "${PN#ensurepip-}")" + +Note that wheels are ZIP archives suffixed ``.whl``, and they are not +unpacked by the package manager automatically. You either need to +unzip it explicitly or use ``->`` to rename it, e.g. by appending +``.zip`` suffix. Remember to add an explicit dependency +on ``app-arch/unzip`` as well. + +The ``pypi_wheel_filename`` function is provided to aid getting +the wheel filename. It has a matching synopsis:: + + pypi_wheel_filename [<project> [<version> [<python-tag> [<abi-platform-tag>]]]] + + +.. _pypi.eclass(5): + https://devmanual.gentoo.org/eclass-reference/pypi.eclass/index.html diff --git a/guide/pypi.html b/guide/pypi.html new file mode 100644 index 0000000..51cb516 --- /dev/null +++ b/guide/pypi.html @@ -0,0 +1,212 @@ + +<!DOCTYPE html> + +<html lang="en"> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> + + <title>pypi — helper eclass for PyPI archives — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/doctools.js"></script> + <script src="_static/sphinx_highlight.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Common helper functions" href="helper.html" /> + <link rel="prev" title="distutils-r1 legacy concepts" href="distutils-legacy.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="pypi-helper-eclass-for-pypi-archives"> +<h1>pypi — helper eclass for PyPI archives<a class="headerlink" href="#pypi-helper-eclass-for-pypi-archives" title="Permalink to this heading">¶</a></h1> +<p>The <code class="docutils literal notranslate"><span class="pre">pypi</span></code> eclass is a small eclass to facilitate fetching sources +from PyPI. It abstracts away the complexity of PyPI URLs, and makes it +easier to adapt <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code> to their future changes.</p> +<p>Please note that PyPI archives are not always the best choice +for distfiles. In particular, they frequently are missing tests +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="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 +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> +<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> +</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. +Should you need to fetch additional files, you need to explicitly append +to the variable or the default will be overwritten, e.g.:</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="s2"> https://github.com/pytest-dev/execnet/commit/c0459b92bc4a42b08281e69b8802d24c5d3415d4.patch</span> +<span class="s2"> -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">-pytest-7.2.patch</span> +<span class="s2">"</span> +</pre></div> +</div> +</section> +<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> +</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> +<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> +</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> +</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> +<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> +<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> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<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="#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> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="qawarn.html">QA checks and warnings</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="distutils-legacy.html" title="previous chapter">distutils-r1 legacy concepts</a></li> + <li>Next: <a href="helper.html" title="next chapter">Common helper functions</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>document.getElementById('searchbox').style.display = "block"</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 6.1.3</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.13</a> + + | + <a href="_sources/pypi.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |