11.1.0 installs top-level `docs` directory

[mgorny]

❓ I'm submitting a ...

• 🐞 bug report
• 🐣 feature request
• ❓ question about the decisions made in the repository

🐞 Describe the bug. What is the current behavior?
The 11.1.0 wheels include a top-level docs package.

❓ What is the motivation / use case for changing the behavior?
docs package is installed outside the package's namespace.

💡 To Reproduce
Steps to reproduce the behavior:

1. pip install cheroot
2. You get site-packages/docs.

💡 Expected behavior
No docs in site-packages.

📋 Details

$ unzip -l /tmp/cheroot-11.1.0-py3-none-any.whl | grep docs
     6581  11-03-2025 00:32   docs/conf.py
      540  11-03-2025 00:32   docs/devguide.rst
      493  11-03-2025 00:32   docs/history.rst
      620  11-03-2025 00:32   docs/index.rst
     2518  11-03-2025 00:32   docs/spelling_stub_ext.py
      700  11-03-2025 00:32   docs/spelling_wordlist.txt
     2274  11-03-2025 00:32   docs/_templates/python_2_eol.html
      395  11-03-2025 00:32   docs/changelog-fragments.d/.gitignore
     2493  11-03-2025 00:32   docs/changelog-fragments.d/.towncrier-template.rst.j2
     5012  11-03-2025 00:32   docs/changelog-fragments.d/README.rst
     3660  11-03-2025 00:32   docs/contributing/guidelines.rst
     3070  11-03-2025 00:32   docs/contributing/release_guide.rst
       14  11-03-2025 00:32   docs/pkg/.gitignore

📋 Environment

• Cheroot version: 11.1.0
• CherryPy version: n/a
• Python version: all
• OS: all
• Browser: all

📋 Additional context
n/a

[webknjaz]

Wow, that's actually not all. It also includes bin/, not just docs/. I assume this might have something to do with setuptools' auto-discovery mechanism. Thanks for reporting!

Interestingly, the previous release v11.0.0 does not contain extra installable files and they are like 5 weeks apart:

• https://inspector.pypi.io/project/cheroot/11.1.0/packages/40/ce/26b9592293b68783cfb3f2e3922d99f3b2c16b04f73ab3ff9eca2be9b8ac/cheroot-11.1.0-py3-none-any.whl/
• https://inspector.pypi.io/project/cheroot/11.0.0/packages/8f/56/8808b1ae899b7d3976b401fd4e29c3cfc97bc3d46a7973f76393218cca1f/cheroot-11.0.0-py3-none-any.whl/

Looking at the diff between the tags, it shows that neither of the pins for setuptools, setuptools-scm or any other pip constraint for building changed: v11.0.0...v11.1.0#diff-25d9465a97d2f7f35c884be35be8c67a02c4ec095a5bfcff7ef679c76e454e2aR19.

Though, there was a similar problem with the dependencies/ dir and I had to exclude it in the config: d0d9d7f.

I guess it's possible that the PIP_CONSTRAINT integration broke in tox and it no longer applied to the PEP 517 ephemeral build env..

[webknjaz]

In the time-frame between the releases, pip v25.3 shipped a related intentional feature for constraints applied to ephemeral build envs: pypa/pip#13534. According to the description it shouldn't have affected the existing uses of PIP_CONSTRAINT, but who knows.. This is something to investigate.

[mgorny]

I think the safest solution would be to invert it to include, i.e.:

diff --git a/pyproject.toml b/pyproject.toml
index 6ebb4216..fecbb23f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -89,6 +89,6 @@ docs = [
 cheroot = "cheroot.cli:main"
 
 [tool.setuptools.packages.find]
-exclude = ['dependencies']
+include = ['cheroot*']
 
 [tool.setuptools_scm]

[webknjaz]

Yes, I'm going to apply that. Just wanted to figure out how the isolation broke and see if I can prevent it in the future.

[mgorny]

Are you sure it's about isolation? I don't recall any related behavior changes in setuptools for a long time — and to be honest, looking at that code now, I'm surprised it actually didn't happen before. I've seen multiple packages accidentally getting docs installed like that — because of conf.py inside it.

[webknjaz]

@mgorny I'm 99% sure because it's supposed to be pinned to setuptools==69.5.1 in https://github.com/cherrypy/cheroot/blob/f60f9a929ccfeacbef61243edbcd5124a78ec531/dependencies/dist-build-constraints.txt#L19C13-L20C1 and it shold be picked up via https://github.com/cherrypy/cheroot/blob/f60f9a929ccfeacbef61243edbcd5124a78ec531/tox.ini#L137C20-L137C75 (plugged in through

cheroot/tox.ini

Line 395 in f60f9a9

{[dists]setenv}

).

The discovery mechanism is relatively new and I haven't had a chance to update the pin in a while so I expected the behavior to remain unchanged — pinning the build deps is supposed to ensure predictable updates in test/dev envs. setuptools didn't have a release since May so it's probably something in the tooling that let the pinning slip.

[webknjaz]

• The job that built v11.0.0 — https://github.com/cherrypy/cheroot/actions/runs/17894178348/job/50878588668#step:13:27 — has pip 25.2
• The job that built v11.1.0 —https://github.com/cherrypy/cheroot/actions/runs/19020536310/job/54314955772#step:13:27 — has pip 25.3

Also, tox version changed in the outer env:

- Successfully installed cachetools-6.2.0 chardet-5.2.0 colorama-0.4.6 distlib-0.4.0 filelock-3.19.1 packaging-25.0 platformdirs-4.4.0 pluggy-1.6.0 pyproject-api-1.9.1 tox-4.30.2 virtualenv-20.34.0
+ Successfully installed cachetools-6.2.1 chardet-5.2.0 colorama-0.4.6 distlib-0.4.0 filelock-3.20.0 packaging-25.0 platformdirs-4.5.0 pluggy-1.6.0 pyproject-api-1.10.0 tox-4.32.0 virtualenv-20.35.4
                                                                                                                                                                             ^^^^^^

[webknjaz]

Looking at the GHA logs closely, both have

* Installing packages in isolated environment:
  - wheel

Which means that PIP_CONSTRAINT is still functional: setuptools==70.1.0 is the version that vendored wheel. Versions before it would inject the wheel dependency via PEP 517 hooks which is what's visible in the log.

This leaves me even more confused — is it possible that setuptools changed behavior on timer? I know some deprecations are deadline-based but I would be surprised if functional behaviors were as well.

[webknjaz]

Since d0d9d7f was on Oct 13 and the v11.0.0 release was on Sep 21, I conclude that something happened in this date range.