diff options
| author |   Michał Górny <mgorny@gentoo.org> | 2022-01-27 21:11:58 +0100 |
|---|---|---|
| committer | Michał Górny <mgorny@gentoo.org> | 2022-01-27 21:11:58 +0100 |
| commit | 14070722c8111a273d3c76af27983a414f939ab1 (patch) | |
| tree | 976c7691c0ad9b4d8e9743cdb44af5f058d575bc /guide/expert-multi.html | |
| parent | Update the feed list (diff) | |
| download | python-14070722c8111a273d3c76af27983a414f939ab1.tar.gz python-14070722c8111a273d3c76af27983a414f939ab1.tar.bz2 python-14070722c8111a273d3c76af27983a414f939ab1.zip | |
Import the current version of python-guide
Signed-off-by: Michał Górny <mgorny@gentoo.org>
Diffstat (limited to 'guide/expert-multi.html')
| -rw-r--r-- | guide/expert-multi.html | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/guide/expert-multi.html b/guide/expert-multi.html new file mode 100644 index 0000000..31e75ca --- /dev/null +++ b/guide/expert-multi.html @@ -0,0 +1,642 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Expert python-r1 usage — 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/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Integration with build systems written in Python" href="buildsys.html" /> + <link rel="prev" title="Advanced concepts" href="concept.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="expert-python-r1-usage"> +<h1>Expert python-r1 usage<a class="headerlink" href="#expert-python-r1-usage" title="Permalink to this headline">¶</a></h1> +<p>The APIs described in this chapter are powerful but even harder to use +than those described in <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> chapter. You should not consider +using them unless you have a proper ninja training.</p> +<section id="partially-restricting-python-implementation"> +<span id="index-0"></span><h2>Partially restricting Python implementation<a class="headerlink" href="#partially-restricting-python-implementation" title="Permalink to this headline">¶</a></h2> +<p>There are packages that have been ported to Python 3 only partially. +They may still have some optional dependencies that support Python 2 +only, they may have some components that do not support Python 3 yet. +The opposite is also possible — some of the features being available +only for Python 3.</p> +<p>There are two approaches to this problem. You can either skip features +(ignore USE flags) if the necessary implementation is not enabled, +or you can use <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code> to enforce at least one interpreter +having the requested feature.</p> +<p>Skipping specific tasks can be done via investigating <code class="docutils literal notranslate"><span class="pre">${EPYTHON}</span></code>. +If USE flags are involved, you will probably also need to use +<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> with additional parameters restricting +dependencies to available targets.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy<span class="o">{</span>,3<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"threads(+)"</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"HTTP library for human beings"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://python-requests.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">P</span><span class="p">:</span><span class="nv">0</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="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~arm64 ~sparc ~x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"socks5 +ssl test"</span> + <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=dev-python/certifi-2017.4.17[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/chardet-3.0.2[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/chardet-4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/idna-2.5[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/idna-3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/urllib3-1.26[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> socks5? ( >=dev-python/PySocks-1.5.6[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +<span class="s2"> ssl? (</span> +<span class="s2"> >=dev-python/cryptography-1.3.4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/pyopenssl-0.14[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )</span> +<span class="s2"> "</span> + + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/setuptools[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> test? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> ${RDEPEND}</span> +</span><span class="hll"><span class="s1"> dev-python/pytest[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pytest-httpbin[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pytest-mock[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> >=dev-python/PySocks-1.5.6[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> <span class="s1">'python*'</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )</span> +<span class="s2"> "</span> + + python_test<span class="o">()</span> <span class="o">{</span> + <span class="c1"># tests hang with pypy & pypy3</span> +<span class="hll"> <span class="o">[[</span> <span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span> <span class="o">==</span> pypy* <span class="o">]]</span> <span class="o">&&</span> <span class="k">continue</span> +</span> + epytest + <span class="o">}</span> +</pre></div> +</div> +<p>Enforcing implementations is done via putting <code class="docutils literal notranslate"><span class="pre">||</span></code> block with all +targets providing the feature in <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>. The eclass provides +<code class="docutils literal notranslate"><span class="pre">python_gen_useflags</span></code> function to print valid flag names for specified +implementation list. Please always use this function instead of listing +actual flag names as it handled phasing implementations out gracefully. +<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> should also be called with matching target +list.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"sqlite"</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Toolkit to convert between many translation formats"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/translate/translate"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/translate/translate/releases/download/</span><span class="si">${</span><span class="nv">PV</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="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 arm64 x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"+subtitles"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> subtitles? ( || ( </span><span class="k">$(</span>python_gen_useflags python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span><span class="k">)</span><span class="s2"> ) )"</span> +</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">">=dev-python/six-1.10.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">DEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> !dev-python/pydiff</span> +<span class="s2"> app-text/iso-codes</span> +<span class="s2"> >=dev-python/chardet-3.0.4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/lxml-3.5[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/pycountry-18.5.26[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/python-levenshtein-0.12.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> sys-devel/gettext</span> +<span class="s2"> subtitles? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> media-video/gaupol[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )</span> +<span class="s2"> "</span> +</pre></div> +</div> +<span class="target" id="index-1"></span></section> +<section id="restricting-interpreters-for-python-setup"> +<span id="index-2"></span><h2>Restricting interpreters for python_setup<a class="headerlink" href="#restricting-interpreters-for-python-setup" title="Permalink to this headline">¶</a></h2> +<p>A specific case of the restriction described above is when the build +step supports a subset of Python targets for the runtime part. This +could happen e.g. if package’s Python bindings have been ported +to Python 3 but the test suite or building tooling still requires +Python 2.</p> +<p>To support this use case, <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> can optionally take a list +of implementations. This list must be a subset of <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>, +and only implementation on the list can be used by <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>. +Note that you also need to set matching <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>, as otherwise +the function will fail if the user does not enable any of the supported +targets.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">5</span>,6,7<span class="o">}</span> <span class="o">)</span> + + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Python extension module generator for C and C++ libraries"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.riverbankcomputing.com/software/sip/intro"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://www.riverbankcomputing.com/static/Downloads/</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">PV</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="c1"># Sub-slot based on SIP_API_MAJOR_NR from siplib/sip.h</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/12"</span> + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"|| ( GPL-2 GPL-3 SIP )"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"alpha amd64 arm arm64 ~hppa ia64 ppc ppc64 ~sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> || ( </span><span class="k">$(</span>python_gen_useflags <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"> )"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> sys-devel/bison</span> +<span class="s2"> sys-devel/flex</span> + +<span class="s2"> src_prepare() {</span> +<span class="hll"><span class="s2"> python_setup 'python2*'</span> +</span><span class="s2"> "</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">" build.py prepare || die</span> +<span class="s2"> default</span> +<span class="s2"> }</span> + +<span class="s2"> src_configure() {</span> +<span class="s2"> configuration() {</span> +<span class="s2"> local myconf=(</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">"/configure.py</span> +<span class="s2"> --bindir="</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span>/usr/bin<span class="s2">"</span> +<span class="s2"> --destdir="</span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">"</span> +<span class="s2"> --incdir="</span><span class="k">$(</span>python_get_includedir<span class="k">)</span><span class="s2">"</span> +<span class="s2"> )</span> +<span class="s2"> echo "</span><span class="si">${</span><span class="nv">myconf</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">myconf</span><span class="p">[@]</span><span class="si">}</span><span class="s2">" || die</span> +<span class="s2"> }</span> +<span class="s2"> python_foreach_impl run_in_build_dir configuration</span> +<span class="s2"> }</span> + +<span class="s2"> src_compile() {</span> +<span class="s2"> python_foreach_impl run_in_build_dir default</span> +<span class="s2"> }</span> + +<span class="s2"> src_install() {</span> +<span class="s2"> installation() {</span> +<span class="s2"> emake DESTDIR="</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">" install</span> +<span class="s2"> python_optimize</span> +<span class="s2"> }</span> +<span class="s2"> python_foreach_impl run_in_build_dir installation</span> + +<span class="s2"> einstalldocs</span> +<span class="s2"> }</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> equivalent of <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> parameters is +the <code class="docutils literal notranslate"><span class="pre">DISTUTILS_ALL_SUBPHASE_IMPLS</span></code> variable. Alternatively to global +scope, it can be set in an early phase function (prior to any sub-phase +call).</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">5</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> + pypy + python3_5 python3_6 python3_7 + python2_7 + <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s1">'bzip2(+),ssl(+),threads(+)'</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Portage is the package management and distribution system for Gentoo"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gentoo.org/wiki/Project:Portage"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://gentoo/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.bz2"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~riscv ~s390 ~sh ~sparc ~x86"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"epydoc"</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"epydoc? ( </span><span class="k">$(</span>python_gen_useflags <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"> )"</span> +</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=app-arch/tar-1.27</span> +<span class="s2"> >=sys-apps/sed-4.0.5 sys-devel/patch</span> +<span class="s2"> epydoc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> >=dev-python/epydoc-2.0[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=app-arch/tar-1.27</span> +<span class="s2"> dev-lang/python-exec:2</span> +<span class="s2"> >=sys-apps/sed-4.0.5</span> +<span class="s2"> app-shells/bash:0[readline]</span> +<span class="s2"> >=app-admin/eselect-1.2</span> +<span class="s2"> elibc_glibc? ( >=sys-apps/sandbox-2.2 )</span> +<span class="s2"> kernel_linux? ( sys-apps/util-linux )</span> +<span class="s2"> >=app-misc/pax-utils-0.1.17"</span> + <span class="nv">PDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/rsync-2.6.4</span> +<span class="s2"> userland_GNU? ( >=sys-apps/coreutils-6.4 )"</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> use epydoc <span class="o">&&</span> <span class="nv">DISTUTILS_ALL_SUBPHASE_IMPLS</span><span class="o">=(</span> python2.7 <span class="o">)</span> +</span> <span class="o">}</span> + + python_compile_all<span class="o">()</span> <span class="o">{</span> + <span class="k">if</span> use epydoc<span class="p">;</span> <span class="k">then</span> + esetup.py epydoc + <span class="k">fi</span> + <span class="o">}</span> +</pre></div> +</div> +<p>Note that when the restriction is caused by dependencies rather than +package’s files, the any-r1 API described below is preferable to this.</p> +<span class="target" id="index-3"></span></section> +<section id="disjoint-build-dependencies-any-r1-api"> +<span id="index-4"></span><h2>Disjoint build dependencies (any-r1 API)<a class="headerlink" href="#disjoint-build-dependencies-any-r1-api" title="Permalink to this headline">¶</a></h2> +<p>Some packages have disjoint sets of runtime and pure build-time +dependencies. The former need to be built for all enabled +implementations, the latter only for one of them. The any-r1 API +in <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> is specifically suited for expressing that.</p> +<p>Let’s consider an example package that uses Sphinx with a plugin +to build documentation. Naturally, you’re going to build the documents +only once, not separately for every enabled target.</p> +<section id="using-regular-python-r1-api"> +<h3>Using regular python-r1 API<a class="headerlink" href="#using-regular-python-r1-api" title="Permalink to this headline">¶</a></h3> +<p>If you were using the regular API, you’d have to use +<code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> on the dependencies. The resulting code could look +like the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="s2"> dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )"</span> + +src_compile<span class="o">()</span> <span class="o">{</span> + ... + + <span class="k">if</span> use doc<span class="p">;</span> <span class="k">then</span> + python_setup + emake -C docs html + <span class="k">fi</span> +<span class="o">}</span> +</pre></div> +</div> +<p>If your package is built with support for Python 3.6, 3.7 and 3.8, +then this dependency string will enforce the same targets for Sphinx +and the theme. However, in practice it will only be used through +Python 3.8. Normally, this is not such a big deal.</p> +<p>Now imagine your package supports Python 2.7 as well, while Sphinx +does not anymore. This means that your package will force downgrade +to the old version of <code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> even though it will not +be used via Python 2.7 at all.</p> +</section> +<section id="using-any-r1-api-with-python-r1"> +<h3>Using any-r1 API with python-r1<a class="headerlink" href="#using-any-r1-api-with-python-r1" title="Permalink to this headline">¶</a></h3> +<p>As the name suggests, the any-r1 API resembles the API used +by <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> eclass. The disjoint build-time dependencies +are declared using <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code>, and need to be tested +via <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> function. The presence of the latter +function activates the alternate behavior of <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>. Instead +of selecting one of the enabled targets, it will run it to verify +installed dependencies and use one having all dependencies satisfied.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_compile<span class="o">()</span> <span class="o">{</span> + ... + + <span class="k">if</span> use doc<span class="p">;</span> <span class="k">then</span> +<span class="hll"> python_setup +</span> emake -C docs html + <span class="k">fi</span> + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> may select an implementation that is not even +enabled via <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>. The goal is to try hard to avoid +requiring user to change USE flags on dependencies if possible.</p> +<p>An interesting side effect of that is that the supported targets +in the dependencies can be a subset of the one in package. For example, +we have used this API to add Python 3.8 support to packages before +<code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> supported it — the eclass implicitly forced using +another implementation for Sphinx.</p> +</section> +<section id="different-sets-of-build-time-dependencies"> +<h3>Different sets of build-time dependencies<a class="headerlink" href="#different-sets-of-build-time-dependencies" title="Permalink to this headline">¶</a></h3> +<p>Let’s consider the case when Python is used at build-time for something +else still. In that case, we want <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> to work +unconditionally but enforce dependencies only with <code class="docutils literal notranslate"><span class="pre">doc</span></code> flag enabled.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +<span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> use doc <span class="o">||</span> <span class="k">return</span> <span class="m">0</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_compile<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_setup +</span> + ... + + use doc <span class="o">&&</span> emake -C docs html + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> behaves according to the any-r1 API here. +While it will not enforce doc dependencies with <code class="docutils literal notranslate"><span class="pre">doc</span></code> flag disabled, +it will use <em>any</em> interpreter that is supported and installed, even +if it is not enabled explicitly in <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>.</p> +</section> +<section id="using-any-r1-api-with-distutils-r1"> +<h3>Using any-r1 API with distutils-r1<a class="headerlink" href="#using-any-r1-api-with-distutils-r1" title="Permalink to this headline">¶</a></h3> +<p>The alternate build dependency API also integrates with <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> +eclass. If <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> is declared, the <code class="docutils literal notranslate"><span class="pre">python_*_all()</span></code> +sub-phase functions are called with the interpreter selected according +to any-r1 rules.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> use doc <span class="o">||</span> <span class="k">return</span> <span class="m">0</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + python_compile_all<span class="o">()</span> <span class="o">{</span> + use doc <span class="o">&&</span> emake -C docs html + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> calls <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> unconditionally, +therefore <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> needs to account for that.</p> +<p>Normally you won’t have to use this API for Sphinx though — +<code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code> does precisely that for you.</p> +</section> +</section> +<section id="combining-any-r1-api-with-implementation-restrictions"> +<h2>Combining any-r1 API with implementation restrictions<a class="headerlink" href="#combining-any-r1-api-with-implementation-restrictions" title="Permalink to this headline">¶</a></h2> +<p>Both APIs described above can be combined. This can be used when +build-time scripts support a subset of implementations supported +by the package itself, and by its build-time dependencies. For example, +if the package uses <code class="docutils literal notranslate"><span class="pre">dev-util/scons</span></code> build system with <code class="docutils literal notranslate"><span class="pre">SConstruct</span></code> +files using Python 2 construct.</p> +<p>There are two approaches to achieve that: either the build-time +implementation list needs to be passed to <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>, +or <code class="docutils literal notranslate"><span class="pre">python_check_deps</span></code> needs to explicitly reject unsupported targets. +In both cases, a matching implementation list needs to be passed +to <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_6 <span class="o">)</span> + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GPS daemon and library for USB/serial GPS devices and GPS/mapping clients"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://gpsd.gitlab.io/gpsd/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://nongnu/</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="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/24"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86"</span> + + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/pps-tools-0.0.20120407</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]'</span> -2<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">">=dev-util/scons-2.3.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">myesconsargs</span><span class="o">=(</span> + <span class="nv">prefix</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">/usr"</span> + <span class="nv">libdir</span><span class="o">=</span><span class="s2">"\$prefix/</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">udevdir</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_udevdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">chrpath</span><span class="o">=</span>False + <span class="nv">gpsd_user</span><span class="o">=</span>gpsd + <span class="nv">gpsd_group</span><span class="o">=</span>uucp + <span class="nv">nostrip</span><span class="o">=</span>True + <span class="nv">manbuild</span><span class="o">=</span>False + <span class="k">$(</span>use_scons python<span class="k">)</span> + <span class="o">)</span> + + <span class="c1"># SConstruct uses py2 constructs</span> +<span class="hll"> python_setup -2 +</span> <span class="o">}</span> +</pre></div> +</div> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_6 <span class="o">)</span> + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GPS daemon and library for USB/serial GPS devices and GPS/mapping clients"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://gpsd.gitlab.io/gpsd/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://nongnu/</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="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/24"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86"</span> + + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/pps-tools-0.0.20120407</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]'</span> -2<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> python_is_python3 <span class="o">&&</span> <span class="k">return</span> <span class="m">1</span> +</span><span class="hll"> has_version <span class="s2">">=dev-util/scons-2.3.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">myesconsargs</span><span class="o">=(</span> + <span class="nv">prefix</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">/usr"</span> + <span class="nv">libdir</span><span class="o">=</span><span class="s2">"\$prefix/</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">udevdir</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_udevdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">chrpath</span><span class="o">=</span>False + <span class="nv">gpsd_user</span><span class="o">=</span>gpsd + <span class="nv">gpsd_group</span><span class="o">=</span>uucp + <span class="nv">nostrip</span><span class="o">=</span>True + <span class="nv">manbuild</span><span class="o">=</span>False + <span class="k">$(</span>use_scons python<span class="k">)</span> + <span class="o">)</span> + +<span class="hll"> python_setup +</span> <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="distutils-legacy.html">distutils-r1 legacy concepts</a></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="test.html">Resolving test suite problems</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 current"><a class="current reference internal" href="#">Expert python-r1 usage</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#partially-restricting-python-implementation">Partially restricting Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#restricting-interpreters-for-python-setup">Restricting interpreters for python_setup</a></li> +<li class="toctree-l2"><a class="reference internal" href="#disjoint-build-dependencies-any-r1-api">Disjoint build dependencies (any-r1 API)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#combining-any-r1-api-with-implementation-restrictions">Combining any-r1 API with implementation restrictions</a></li> +</ul> +</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="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="concept.html" title="previous chapter">Advanced concepts</a></li> + <li>Next: <a href="buildsys.html" title="next chapter">Integration with build systems written in Python</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>$('#searchbox').show(0);</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 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/expert-multi.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |