Update Guide to 51dd5f6

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

1 files changed, 9 insertions, 339 deletions

diff --git a/guide/distutils.html b/guide/distutils.html
index fd785f4..5f0b8c6 100644
--- a/guide/distutils.html
+++ b/guide/distutils.html
@@ -14,7 +14,7 @@
     <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="distutils-r1 legacy concepts" href="distutils-legacy.html" />
+    <link rel="next" title="Tests in Python packages" href="test.html" />
     <link rel="prev" title="python-r1 — multi-impl packages" href="multi.html" />
    
   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -311,73 +311,7 @@ backend.</p>
 the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> backend (this applies to pure distutils packages
 as well).  The eclass automatically uses the legacy setuptools backend
 for them.</p>
-</section>
-<section id="deprecated-pep-517-backends">
-<h2>Deprecated PEP 517 backends<a class="headerlink" href="#deprecated-pep-517-backends" title="Permalink to this heading">¶</a></h2>
-<section id="flit-buildapi">
-<h3>flit.buildapi<a class="headerlink" href="#flit-buildapi" title="Permalink to this heading">¶</a></h3>
-<p>Some packages are still found using the historical flit build backend.
-Their <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> files contain a section similar
-to the following:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;flit&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;flit.buildapi&quot;</span>
-</pre></div>
-</div>
-<p>This backend requires installing the complete flit package manager.
-Instead, the package should be fixed upstream to use flit_core
-per <a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#build-system-section">flit build system section documentation</a> instead:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;flit_core&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;flit_core.buildapi&quot;</span>
-</pre></div>
-</div>
-<p>flit_core produces identical artifacts to flit.  At the same time, it
-reduces the build-time dependency footprint and therefore makes isolated
-PEP 517 builds faster.</p>
-</section>
-<section id="poetry-masonry-api">
-<h3>poetry.masonry.api<a class="headerlink" href="#poetry-masonry-api" title="Permalink to this heading">¶</a></h3>
-<p>A similar problem applies to the packages using poetry.  The respective
-<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> files contain:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;poetry&gt;=0.12&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;poetry.masonry.api&quot;</span>
-</pre></div>
-</div>
-<p>Instead, the lightweight poetry-core module should be used per <a class="reference external" href="https://python-poetry.org/docs/pyproject/#poetry-and-pep-517">poetry
-PEP-517 documentation</a>:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;poetry_core&gt;=1.0.0&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;poetry.core.masonry.api&quot;</span>
-</pre></div>
-</div>
-<p>poetry-core produces identical artifacts to poetry.  It has smaller
-dependency footprint and makes isolated builds much faster.</p>
-</section>
-<section id="setuptools-build-meta-legacy">
-<h3>setuptools.build_meta:__legacy__<a class="headerlink" href="#setuptools-build-meta-legacy" title="Permalink to this heading">¶</a></h3>
-<p>Some packages using setuptools specify the following:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;setuptools&gt;=40.8.0&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;wheel&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;setuptools.build_meta:__legacy__&quot;</span>
-</pre></div>
-</div>
-<p>This is incorrect, as the legacy backend is intended to be used only
-as an implicit fallback.  All packages should be using the regular
-backend instead:</p>
-<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span>
-<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">&quot;setuptools&gt;=40.8.0&quot;</span><span class="p">]</span>
-<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;setuptools.build_meta&quot;</span>
-</pre></div>
-</div>
-<p>Please also note that the <code class="docutils literal notranslate"><span class="pre">wheel</span></code> package should <em>not</em> be listed
-as a dependency, as it is an implementation detail and it was always
-implicitly returned by the backend.  Unfortunately, due to prolonged
-documentation error, a very large number of packages still specifies it,
-and other packages tend to copy that mistake.</p>
 <span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span></section>
-</section>
 <section id="setuptools-scm-flit-scm-hatch-vcs-and-snapshots">
 <span id="index-5"></span><h2>setuptools_scm (flit_scm, hatch-vcs) and snapshots<a class="headerlink" href="#setuptools-scm-flit-scm-hatch-vcs-and-snapshots" title="Permalink to this heading">¶</a></h2>
 <p><a class="reference external" href="https://pypi.org/project/setuptools-scm/">setuptools_scm</a> is a package providing additional features for running
@@ -708,274 +642,11 @@ beforehand (much like <code class="docutils literal notranslate"><span class="pr
 </div>
 </section>
 <section id="enabling-tests">
-<span id="index-19"></span><h2>Enabling tests<a class="headerlink" href="#enabling-tests" title="Permalink to this heading">¶</a></h2>
-<p>Since Python performs only minimal build-time (or more precisely,
-import-time) checking of correctness, it is important to run tests
-of Python packages in order to catch any problems early.  This is
-especially important for permitting others to verify support for new
-Python implementations.</p>
-<p>Many Python packages use one of the standard test runners, and work fine
-with the default ways of calling them.  Note that upstreams sometimes
-specify a test runner that’s not strictly necessary — e.g. specify
-<code class="docutils literal notranslate"><span class="pre">dev-python/pytest</span></code> as a dependency while the tests do not use it
-anywhere and work just fine with built-in modules.  The best way
-to determine the test runner to use is to grep the test sources.</p>
-<section id="using-distutils-enable-tests">
-<h3>Using distutils_enable_tests<a class="headerlink" href="#using-distutils-enable-tests" title="Permalink to this heading">¶</a></h3>
-<p>The simplest way of enabling tests is to call <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code>
-in global scope, passing the test runner name as the first argument.
-This function takes care of declaring test phase, setting appropriate
-dependencies and <code class="docutils literal notranslate"><span class="pre">test</span></code> USE flag if necessary.  If called after
-setting <code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code>, it also copies it to test dependencies.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="c1"># Copyright 1999-2020 Gentoo Authors</span>
-<span class="w"> </span><span class="c1"># Distributed under the terms of the GNU General Public License v2</span>
-
-<span class="w"> </span><span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span>
-
-<span class="w"> </span><span class="nv">PYTHON_COMPAT</span><span class="o">=(</span><span class="w"> </span>python2_7<span class="w"> </span>python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span><span class="w"> </span>pypy3<span class="w"> </span><span class="o">)</span>
-<span class="w"> </span>inherit<span class="w"> </span>distutils-r1
-
-<span class="w"> </span><span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">&quot;An easy whitelist-based HTML-sanitizing tool&quot;</span>
-<span class="w"> </span><span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">&quot;https://github.com/mozilla/bleach https://pypi.org/project/bleach/&quot;</span>
-<span class="w"> </span><span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">&quot;mirror://pypi/</span><span class="si">${</span><span class="nv">PN</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&quot;</span>
-
-<span class="w"> </span><span class="nv">LICENSE</span><span class="o">=</span><span class="s2">&quot;Apache-2.0&quot;</span>
-<span class="w"> </span><span class="nv">SLOT</span><span class="o">=</span><span class="s2">&quot;0&quot;</span>
-<span class="w"> </span><span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">&quot;~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sparc ~x86&quot;</span>
-
-<span class="w"> </span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">&quot;</span>
-<span class="s2">     dev-python/six[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2">     dev-python/webencodings[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2"> &quot;</span>
-
-<span class="hll"><span class="w"> </span>distutils_enable_tests<span class="w"> </span>pytest
-</span></pre></div>
-</div>
-<p>The valid values include:</p>
-<ul class="simple">
-<li><p><code class="docutils literal notranslate"><span class="pre">nose</span></code> for <code class="docutils literal notranslate"><span class="pre">dev-python/nose</span></code></p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">pytest</span></code> for <code class="docutils literal notranslate"><span class="pre">dev-python/pytest</span></code></p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">setup.py</span></code> to call <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">test</span></code> (<em>deprecated</em>)</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">unittest</span></code> to use built-in unittest discovery</p></li>
-</ul>
-</section>
-<section id="adding-more-test-dependencies">
-<h3>Adding more test dependencies<a class="headerlink" href="#adding-more-test-dependencies" title="Permalink to this heading">¶</a></h3>
-<p>Additional test dependencies can be specified in <code class="docutils literal notranslate"><span class="pre">test?</span></code> conditional.
-The flag normally does not need to be explicitly declared,
-as <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> does that in the majority of cases.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="c1"># Copyright 1999-2020 Gentoo Authors</span>
-<span class="w"> </span><span class="c1"># Distributed under the terms of the GNU General Public License v2</span>
-
-<span class="w"> </span><span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span>
-
-<span class="w"> </span><span class="nv">PYTHON_COMPAT</span><span class="o">=(</span><span class="w"> </span>python2_7<span class="w"> </span>python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span><span class="w"> </span>pypy3<span class="w"> </span><span class="o">)</span>
-<span class="w"> </span>inherit<span class="w"> </span>distutils-r1
-
-<span class="w"> </span><span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">&quot;Universal encoding detector&quot;</span>
-<span class="w"> </span><span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">&quot;https://github.com/chardet/chardet https://pypi.org/project/chardet/&quot;</span>
-<span class="w"> </span><span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">&quot;https://github.com/chardet/chardet/archive/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -&gt; </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz&quot;</span>
-
-<span class="w"> </span><span class="nv">LICENSE</span><span class="o">=</span><span class="s2">&quot;LGPL-2.1&quot;</span>
-<span class="w"> </span><span class="nv">SLOT</span><span class="o">=</span><span class="s2">&quot;0&quot;</span>
-<span class="w"> </span><span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">&quot;~alpha amd64 arm arm64 hppa ia64 ~m68k ~mips ppc ppc64 s390 ~sh sparc x86 ~x64-cygwin ~amd64-linux ~x86-linux ~x64-macos ~x86-macos ~x64-solaris&quot;</span>
-
-<span class="w"> </span><span class="nv">DEPEND</span><span class="o">=</span><span class="s2">&quot;</span>
-<span class="hll"><span class="s2">     test? ( dev-python/hypothesis[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span>
-</span><span class="s2"> &quot;</span>
-
-<span class="hll"><span class="w"> </span>distutils_enable_tests<span class="w"> </span>pytest
-</span></pre></div>
-</div>
-<p>Note that <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> modifies variables directly
-in the ebuild environment.  This means that if you wish to change their
-values, you need to append to them, i.e. the bottom part of that ebuild
-can be rewritten as:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span>distutils_enable_tests<span class="w"> </span>pytest
-
-<span class="hll"><span class="w"> </span><span class="nv">DEPEND</span><span class="o">+=</span><span class="s2">&quot;</span>
-</span><span class="s2">     test? ( dev-python/hypothesis[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span>
-<span class="s2"> &quot;</span>
-</pre></div>
-</div>
-</section>
-<section id="installing-the-package-before-running-tests">
-<h3>Installing the package before running tests<a class="headerlink" href="#installing-the-package-before-running-tests" title="Permalink to this heading">¶</a></h3>
-<p>In PEP 517 mode, the eclass automatically exposes a venv-style install
-tree to the test phase.  No explicit action in necessary.</p>
-<p>In the legacy mode, <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> has an optional
-<code class="docutils literal notranslate"><span class="pre">--install</span></code> option that can be used to force performing an install
-to a temporary directory.  More information can be found in the legacy
-section.</p>
-</section>
-<section id="undesirable-test-dependencies">
-<h3>Undesirable test dependencies<a class="headerlink" href="#undesirable-test-dependencies" title="Permalink to this heading">¶</a></h3>
-<p>There is a number of packages that are frequently listed as test
-dependencies upstream but have little to no value for Gentoo users.
-It is recommended to skip those test dependencies whenever possible.
-If tests fail to run without them, it is often preferable to strip
-the dependencies and/or configuration values enforcing them.</p>
-<p><em>Coverage testing</em> establishes how much of the package’s code is covered
-by the test suite.  While this is useful statistic upstream, it has
-no value for Gentoo users who just want to install the package.  This
-is often represented by dependencies on <code class="docutils literal notranslate"><span class="pre">dev-python/coverage</span></code>,
-<code class="docutils literal notranslate"><span class="pre">dev-python/pytest-cov</span></code>.  In the latter case, you usually need
-to strip <code class="docutils literal notranslate"><span class="pre">--cov</span></code> parameter from <code class="docutils literal notranslate"><span class="pre">pytest.ini</span></code>.</p>
-<p><em>PEP-8 testing</em> enforces standard coding style across Python programs.
-Issues found by it are relevant to upstream but entirely irrelevant
-to Gentoo users.  If the package uses <code class="docutils literal notranslate"><span class="pre">dev-python/pep8</span></code>,
-<code class="docutils literal notranslate"><span class="pre">dev-python/pycodestyle</span></code>, <code class="docutils literal notranslate"><span class="pre">dev-python/flake8</span></code>, strip that
-dependency.</p>
-<p><code class="docutils literal notranslate"><span class="pre">dev-python/pytest-runner</span></code> is a thin wrapper to run pytest
-from <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.  Do not use it, just call pytest directly.</p>
-<p><code class="docutils literal notranslate"><span class="pre">dev-python/tox</span></code> is a convenient wrapper to run tests for multiple
-Python versions, in a virtualenv.  The eclass already provides the logic
-for the former, and an environment close enough to the latter.  Do not
-use tox in ebuilds.</p>
-</section>
-<section id="customizing-the-test-phase">
-<h3>Customizing the test phase<a class="headerlink" href="#customizing-the-test-phase" title="Permalink to this heading">¶</a></h3>
-<p>If additional pre-/post-test phase actions need to be performed,
-they can be easily injected via overriding <code class="docutils literal notranslate"><span class="pre">src_test()</span></code> and making
-it call <code class="docutils literal notranslate"><span class="pre">distutils-r1_src_test</span></code>:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="c1"># Copyright 1999-2020 Gentoo Authors</span>
-<span class="w"> </span><span class="c1"># Distributed under the terms of the GNU General Public License v2</span>
-
-<span class="w"> </span><span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span>
-
-<span class="w"> </span><span class="nv">PYTHON_COMPAT</span><span class="o">=(</span><span class="w"> </span>python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span><span class="w"> </span><span class="o">)</span>
-<span class="w"> </span>inherit<span class="w"> </span>distutils-r1
-
-<span class="w"> </span><span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">&quot;Extra features for standard library&#39;s cmd module&quot;</span>
-<span class="w"> </span><span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">&quot;https://github.com/python-cmd2/cmd2&quot;</span>
-<span class="w"> </span><span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">&quot;mirror://pypi/</span><span class="si">${</span><span class="nv">PN</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&quot;</span>
-
-<span class="w"> </span><span class="nv">LICENSE</span><span class="o">=</span><span class="s2">&quot;MIT&quot;</span>
-<span class="w"> </span><span class="nv">SLOT</span><span class="o">=</span><span class="s2">&quot;0&quot;</span>
-<span class="w"> </span><span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">&quot;~amd64 ~arm ~arm64 ~ppc64 ~x86 ~amd64-linux ~x86-linux&quot;</span>
-
-<span class="w"> </span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">&quot;</span>
-<span class="s2">     dev-python/attrs[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2">     &gt;=dev-python/colorama-0.3.7[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2">     &gt;=dev-python/pyperclip-1.6[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2">     dev-python/six[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2">     dev-python/wcwidth[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2"> &quot;</span>
-<span class="w"> </span><span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">&quot;</span>
-<span class="s2">     dev-python/setuptools_scm[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span>
-<span class="s2"> &quot;</span>
-
-<span class="w"> </span>distutils_enable_tests<span class="w"> </span>pytest
-
-<span class="hll"><span class="w"> </span>src_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-</span><span class="hll"><span class="w">     </span><span class="c1"># tests rely on very specific text wrapping...</span>
-</span><span class="hll"><span class="w">     </span><span class="nb">local</span><span class="w"> </span>-x<span class="w"> </span><span class="nv">COLUMNS</span><span class="o">=</span><span class="m">80</span>
-</span><span class="hll"><span class="w">     </span>distutils-r1_src_test
-</span><span class="hll"><span class="w"> </span><span class="o">}</span>
-</span></pre></div>
-</div>
-<p>If the actual test command needs to be customized, or a non-standard
-test tool needs to be used, you can define a <code class="docutils literal notranslate"><span class="pre">python_test()</span></code> sub-phase
-function.  This function is called for every enabled Python target
-by the default <code class="docutils literal notranslate"><span class="pre">src_test</span></code> implementation.  This can either be combined
-with <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> call, or used instead of it.  In fact,
-the former function simply defines a <code class="docutils literal notranslate"><span class="pre">python_test()</span></code> function as part
-of its logic.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="c1"># Copyright 1999-2020 Gentoo Authors</span>
-<span class="w"> </span><span class="c1"># Distributed under the terms of the GNU General Public License v2</span>
-
-<span class="w"> </span><span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span>
-
-<span class="w"> </span><span class="nv">PYTHON_COMPAT</span><span class="o">=(</span><span class="w"> </span>python<span class="o">{</span>2_7,3_6,3_7,3_8<span class="o">}</span><span class="w"> </span>pypy3<span class="w"> </span><span class="o">)</span>
-<span class="w"> </span>inherit<span class="w"> </span>distutils-r1
-
-<span class="w"> </span><span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">&quot;Bash tab completion for argparse&quot;</span>
-<span class="w"> </span><span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">&quot;https://pypi.org/project/argcomplete/&quot;</span>
-<span class="w"> </span><span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">&quot;mirror://pypi/</span><span class="si">${</span><span class="nv">PN</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&quot;</span>
-
-<span class="w"> </span><span class="nv">LICENSE</span><span class="o">=</span><span class="s2">&quot;Apache-2.0&quot;</span>
-<span class="w"> </span><span class="nv">SLOT</span><span class="o">=</span><span class="s2">&quot;0&quot;</span>
-<span class="w"> </span><span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">&quot;~amd64 ~arm ~arm64 ~hppa ~x86 ~amd64-linux ~x86-linux ~x64-macos&quot;</span>
-<span class="hll"><span class="w"> </span><span class="nv">IUSE</span><span class="o">=</span><span class="s2">&quot;test&quot;</span>
-</span><span class="hll"><span class="w"> </span><span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">&quot;!test? ( test )&quot;</span>
-</span>
-<span class="w"> </span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">&quot;</span>
-<span class="s2">     </span><span class="k">$(</span>python_gen_cond_dep<span class="w"> </span><span class="s1">&#39;</span>
-<span class="s1">         &lt;dev-python/importlib_metadata-2[${PYTHON_USEDEP}]</span>
-<span class="s1">     &#39;</span><span class="w"> </span>-2<span class="w"> </span>python3_<span class="o">{</span><span class="m">5</span>,6,7<span class="o">}</span><span class="w"> </span>pypy3<span class="k">)</span><span class="s2">&quot;</span>
-<span class="w"> </span><span class="c1"># pip is called as an external tool</span>
-<span class="w"> </span><span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">&quot;</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="hll"><span class="s2">     test? (</span>
-</span><span class="hll"><span class="s2">         app-shells/fish</span>
-</span><span class="hll"><span class="s2">         app-shells/tcsh</span>
-</span><span class="hll"><span class="s2">         dev-python/pexpect[</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="s2">         dev-python/pip</span>
-</span><span class="hll"><span class="s2">     )&quot;</span>
-</span>
-<span class="hll"><span class="w"> </span>python_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-</span><span class="hll"><span class="w">     </span><span class="s2">&quot;</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">&quot;</span><span class="w"> </span>test/test.py<span class="w"> </span>-v<span class="w"> </span><span class="o">||</span><span class="w"> </span>die
-</span><span class="hll"><span class="w"> </span><span class="o">}</span>
-</span></pre></div>
-</div>
-<p>Note that <code class="docutils literal notranslate"><span class="pre">python_test</span></code> is called by <code class="docutils literal notranslate"><span class="pre">distutils-r1_src_test</span></code>,
-so you must make sure to call it if you override <code class="docutils literal notranslate"><span class="pre">src_test</span></code>.</p>
-</section>
-<section id="customizing-the-test-phase-for-pytest">
-<span id="index-20"></span><h3>Customizing the test phase for pytest<a class="headerlink" href="#customizing-the-test-phase-for-pytest" title="Permalink to this heading">¶</a></h3>
-<p>For the relatively frequent case of pytest-based packages needing
-additional customization, a <code class="docutils literal notranslate"><span class="pre">epytest</span></code> helper is provided.  The helper
-runs <code class="docutils literal notranslate"><span class="pre">pytest</span></code> with a standard set of options and automatic handling
-of test failures.</p>
-<p>For example, if upstream uses <code class="docutils literal notranslate"><span class="pre">network</span></code> marker to disable
-network-based tests, you can override the test phase in the following
-way:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>distutils_enable_tests<span class="w"> </span>pytest
-
-python_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>epytest<span class="w"> </span>-m<span class="w"> </span><span class="s1">&#39;not network&#39;</span>
-<span class="o">}</span>
-</pre></div>
-</div>
-</section>
-<section id="running-tests-with-virtualx">
-<span id="index-21"></span><h3>Running tests with virtualx<a class="headerlink" href="#running-tests-with-virtualx" title="Permalink to this heading">¶</a></h3>
-<p>Test suites requiring a display to work correctly can often be appeased
-usng Xvfb.  If the package in question does not start Xvfb directly,
-<code class="docutils literal notranslate"><span class="pre">virtualx.eclass</span></code> can be used to do that.  Whenever possible, it is
-preferable to run a single server in <code class="docutils literal notranslate"><span class="pre">src_test()</span></code> for all passes
-of the test suite, e.g.:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>distutils_enable_tests<span class="w"> </span>pytest
-
-src_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>virtx<span class="w"> </span>distutils-r1_src_test
-<span class="o">}</span>
-</pre></div>
-</div>
-<p>Note that <code class="docutils literal notranslate"><span class="pre">virtx</span></code> implicitly enables nonfatal mode.  This means that
-e.g. <code class="docutils literal notranslate"><span class="pre">epytest</span></code> will no longer terminate the ebuild on failure, and you
-need to use <code class="docutils literal notranslate"><span class="pre">die</span></code> explicitly for it:</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>virtx<span class="w"> </span>distutils-r1_src_test
-<span class="o">}</span>
-
-python_test<span class="o">()</span><span class="w"> </span><span class="o">{</span>
-<span class="w">    </span>epytest<span class="w"> </span>-m<span class="w"> </span><span class="s2">&quot;not network&quot;</span><span class="w"> </span><span class="o">||</span><span class="w"> </span>die<span class="w"> </span><span class="s2">&quot;Tests failed with </span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">&quot;</span>
-<span class="o">}</span>
-</pre></div>
-</div>
-<div class="admonition warning">
-<p class="admonition-title">Warning</p>
-<p>Explicit <code class="docutils literal notranslate"><span class="pre">||</span> <span class="pre">die</span></code> is only necessary when overriding <code class="docutils literal notranslate"><span class="pre">python_test</span></code>
-and running <code class="docutils literal notranslate"><span class="pre">epytest</span></code> inside a <code class="docutils literal notranslate"><span class="pre">nonfatal</span></code>.  The <code class="docutils literal notranslate"><span class="pre">virtx</span></code> command
-runs its arguments via a <code class="docutils literal notranslate"><span class="pre">nonfatal</span></code>.  The default <code class="docutils literal notranslate"><span class="pre">python_test</span></code>
-implementation created by <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> accounts for
-this.  In other contexts, <code class="docutils literal notranslate"><span class="pre">epytest</span></code> will die on its own.</p>
-</div>
-</section>
+<h2>Enabling tests<a class="headerlink" href="#enabling-tests" title="Permalink to this heading">¶</a></h2>
+<p>The support for test suites is now covered in the <a class="reference internal" href="test.html"><span class="doc">Tests in Python packages</span></a> chapter.</p>
 </section>
 <section id="building-documentation-via-sphinx">
-<span id="index-22"></span><h2>Building documentation via Sphinx<a class="headerlink" href="#building-documentation-via-sphinx" title="Permalink to this heading">¶</a></h2>
+<span id="index-19"></span><h2>Building documentation via Sphinx<a class="headerlink" href="#building-documentation-via-sphinx" title="Permalink to this heading">¶</a></h2>
 <p><code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> is commonly used to document Python packages.
 It comes with a number of plugins and themes that make it convenient
 to write and combine large text documents (such as this Guide!),
@@ -1091,10 +762,10 @@ If additional packages need to be installed, the previous variant
 must be used instead.</p>
 <p>The eclass tries to automatically determine whether <code class="docutils literal notranslate"><span class="pre">--no-autodoc</span></code>
 should be used, and issue a warning if it’s missing or incorrect.</p>
-<span class="target" id="index-23"></span></section>
+<span class="target" id="index-20"></span></section>
 </section>
 <section id="packages-with-optional-python-build-system-usage">
-<span id="index-24"></span><h2>Packages with optional Python build system usage<a class="headerlink" href="#packages-with-optional-python-build-system-usage" title="Permalink to this heading">¶</a></h2>
+<span id="index-21"></span><h2>Packages with optional Python build system usage<a class="headerlink" href="#packages-with-optional-python-build-system-usage" title="Permalink to this heading">¶</a></h2>
 <p>The eclass has been written with the assumption that the vast majority
 of its consumers will be using the Python build systems unconditionally.
 For this reason, it sets the ebuild metadata variables (dependencies,
@@ -1203,7 +874,7 @@ follows:</p>
 </div>
 </section>
 <section id="packages-with-rust-extensions-using-cargo">
-<span id="index-25"></span><h2>Packages with Rust extensions (using Cargo)<a class="headerlink" href="#packages-with-rust-extensions-using-cargo" title="Permalink to this heading">¶</a></h2>
+<span id="index-22"></span><h2>Packages with Rust extensions (using Cargo)<a class="headerlink" href="#packages-with-rust-extensions-using-cargo" title="Permalink to this heading">¶</a></h2>
 <p>Some Python build systems include support for writing extensions
 in the Rust programming language.  Two examples of these are setuptools
 using <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools_rust</span></code> plugin and Maturin.  Normally,
@@ -1448,7 +1119,6 @@ python_install<span class="o">()</span><span class="w"> </span><span class="o">{
 <li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#python-single-r1-variant">python-single-r1 variant</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#pep-517-build-systems">PEP 517 build systems</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#deprecated-pep-517-backends">Deprecated PEP 517 backends</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#setuptools-scm-flit-scm-hatch-vcs-and-snapshots">setuptools_scm (flit_scm, hatch-vcs) and snapshots</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#packages-using-cython">Packages using Cython</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#parallel-build-race-conditions">Parallel build race conditions</a></li>
@@ -1462,10 +1132,10 @@ python_install<span class="o">()</span><span class="w"> </span><span class="o">{
 <li class="toctree-l2"><a class="reference internal" href="#installing-packages-without-a-pep-517-build-backend">Installing packages without a PEP 517 build backend</a></li>
 </ul>
 </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"><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"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li>
@@ -1482,7 +1152,7 @@ python_install<span class="o">()</span><span class="w"> </span><span class="o">{
 <ul>
   <li><a href="index.html">Documentation overview</a><ul>
       <li>Previous: <a href="multi.html" title="previous chapter">python-r1 — multi-impl packages</a></li>
-      <li>Next: <a href="distutils-legacy.html" title="next chapter">distutils-r1 legacy concepts</a></li>
+      <li>Next: <a href="test.html" title="next chapter">Tests in Python packages</a></li>
   </ul></li>
 </ul>
 </div>