Update Guide to 51dd5f6

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

1 files changed, 68 insertions, 1 deletions

diff --git a/guide/qawarn.html b/guide/qawarn.html
index 5e67ad8..d57f1d0 100644
--- a/guide/qawarn.html
+++ b/guide/qawarn.html
@@ -249,6 +249,72 @@ entry:</p>
 <p>For reference, see <a class="reference external" href="https://python-poetry.org/docs/pyproject/#include-and-exclude">include and exclude in Poetry documentation</a>.</p>
 </section>
 </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>
+</section>
+</section>
 </section>
 
 
@@ -278,10 +344,10 @@ entry:</p>
 <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"><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>
@@ -292,6 +358,7 @@ entry:</p>
 <li class="toctree-l2"><a class="reference internal" href="#improved-qa-warning-reporting-in-portage">Improved QA warning reporting in Portage</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#compiled-bytecode-related-warnings">Compiled bytecode-related warnings</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#stray-top-level-files-in-site-packages">Stray top-level files in site-packages</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#deprecated-pep-517-backends">Deprecated PEP 517 backends</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li>