diff options
Diffstat (limited to 'guide/qawarn.html')
| -rw-r--r-- | guide/qawarn.html | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/guide/qawarn.html b/guide/qawarn.html index 81dba30..5e67ad8 100644 --- a/guide/qawarn.html +++ b/guide/qawarn.html @@ -161,6 +161,94 @@ not to install them in the first place.</p></li> </ol> </section> </section> +<section id="stray-top-level-files-in-site-packages"> +<h2>Stray top-level files in site-packages<a class="headerlink" href="#stray-top-level-files-in-site-packages" title="Permalink to this heading">¶</a></h2> +<p>distutils-r1 checks for the common mistake of installing unexpected +files that are installed top-level into the site-packages directory. +An example error due to that looks like the following:</p> +<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>* The following unexpected files/directories were found top-level +* in the site-packages directory: +* +* /usr/lib/python3.10/site-packages/README.md +* /usr/lib/python3.10/site-packages/LICENSE +* /usr/lib/python3.10/site-packages/CHANGELOG +* +* This is most likely a bug in the build system. More information +* can be found in the Python Guide: +* https://projects.gentoo.org/python/guide/qawarn.html#stray-top-level-files-in-site-packages +</pre></div> +</div> +<p>In general, it is desirable to prepare a fix for the build system +and submit it upstream. However, it is acceptable to remove the files +locally in the ebuild while waiting for a release with the fix.</p> +<p>The subsequent sections describe the common causes and the suggested +fixes.</p> +<section id="example-or-test-packages-installed-by-setuptools"> +<h3>Example or test packages installed by setuptools<a class="headerlink" href="#example-or-test-packages-installed-by-setuptools" title="Permalink to this heading">¶</a></h3> +<p>Many packages using the setuptools build system utilize the convenient +<code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> method to locate the Python sources. In some cases, +this method also wrongly grabs top-level test directories or other files +that were not intended to be installed.</p> +<p>For example, the following invocation will install everything that looks +like a Python package from the source tree:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span> + <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">())</span> +</pre></div> +</div> +<p>The correct fix for this problem is to add an <code class="docutils literal notranslate"><span class="pre">exclude</span></code> parameter +that restricts the installed package list, for example:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span> + <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">[</span><span class="s2">"tests"</span><span class="p">,</span> <span class="s2">"tests.*"</span><span class="p">]))</span> +</pre></div> +</div> +<p>Note that if the top-level <code class="docutils literal notranslate"><span class="pre">tests</span></code> package has any subpackages, both +<code class="docutils literal notranslate"><span class="pre">tests</span></code> and <code class="docutils literal notranslate"><span class="pre">tests.*</span></code> need to be listed.</p> +<p>If <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> is used instead, the excludes are specified as follows:</p> +<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[options.packages.find]</span> +<span class="na">exclude</span><span class="w"> </span><span class="o">=</span> +<span class="w"> </span><span class="na">tests</span> +<span class="w"> </span><span class="na">tests.*</span> +</pre></div> +</div> +<p>If <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> is used:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[tool.setuptools.packages.find]</span> +<span class="n">exclude</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> +<span class="w"> </span><span class="s">"tests"</span><span class="p">,</span> +<span class="w"> </span><span class="s">"tests.*"</span><span class="p">,</span> +<span class="p">]</span> +</pre></div> +</div> +<p>For reference, see <a class="reference external" href="https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#custom-discovery">custom discovery in setuptools documentation</a>.</p> +</section> +<section id="documentation-files-installed-by-poetry"> +<h3>Documentation files installed by Poetry<a class="headerlink" href="#documentation-files-installed-by-poetry" title="Permalink to this heading">¶</a></h3> +<p>It is a relatively common problem that packages using the Poetry build +system are installing documentation files (such as <code class="docutils literal notranslate"><span class="pre">README</span></code>) +to the site-packages directory. This is because of incorrect +<code class="docutils literal notranslate"><span class="pre">include</span></code> use in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>. For example, consider +the following configuration:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="n">include</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> +<span class="w"> </span><span class="s">"CHANGELOG"</span><span class="p">,</span> +<span class="w"> </span><span class="s">"README.md"</span><span class="p">,</span> +<span class="w"> </span><span class="s">"LICENSE"</span> +<span class="p">]</span> +</pre></div> +</div> +<p>The author meant to include these files in the source distribution +packages. However, the <code class="docutils literal notranslate"><span class="pre">include</span></code> key applies to wheels as well, +effectively including them in files installed into <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>.</p> +<p>To fix that, you need to specify file formats explicitly, for every +entry:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="n">include</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span> +<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"CHANGELOG"</span><span class="p">,</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"sdist"</span><span class="w"> </span><span class="p">},</span> +<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"README.md"</span><span class="p">,</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"sdist"</span><span class="w"> </span><span class="p">},</span> +<span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"LICENSE"</span><span class="p">,</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"sdist"</span><span class="w"> </span><span class="p">},</span> +<span class="p">]</span> +</pre></div> +</div> +<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> @@ -203,6 +291,7 @@ not to install them in the first place.</p></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">QA checks and warnings</a><ul> <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> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> |