From c49e63569a2f1663f027f8cfc5f321803bb5b205 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 16:46:37 +0000 Subject: [PATCH] Document the Debian/Ubuntu opentracing build failure Installing requirements/test.txt into the system Python on Debian or Ubuntu fails while building opentracing: AttributeError: install_layout opentracing 2.4.0 is the latest release and publishes no wheel, so pip builds it from the sdist through the legacy setup.py path using whatever setuptools is already installed. Debian's packaged python3-setuptools patches its install_lib command to read an install_layout option from the install command it runs against, and that command -- setuptools' vendored _distutils -- does not define it. Nothing in the pin can avoid this: 2.4.0 is the newest release, and the sdist is all upstream publishes. So document it where contributors meet it, next to the install commands in the contributing guide, and leave a pointer in the extras file itself. Verified on Ubuntu 24.04 with the system Python 3.11: the packaged setuptools 68.1.2 fails, and a virtualenv (setuptools 79.0.1), an upgraded setuptools in place (84.0.0), and `pip install --use-pep517` each build it fine. The comment added to requirements/extras/opentracing.txt is stripped by setup.py's own requirements parser, so the `faust[opentracing]` extra still resolves to the pin alone; tests/unit/test_packaging.py passes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Sejq9tYzzeqWeZAgA3EB6s --- docs/contributing.rst | 19 +++++++++++++++++++ requirements/extras/opentracing.txt | 5 +++++ 2 files changed, 24 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index e1bcbcfa7..5cc8cd6a7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -394,6 +394,25 @@ dependencies, so install these: $ pip install -U -r requirements/test.txt $ pip install -U -r requirements/default.txt +.. note:: + + Install these into a virtualenv. On Debian and Ubuntu, installing them + into the system Python can fail while building :pypi:`opentracing` (pulled + in by :file:`requirements/test.txt`) with:: + + AttributeError: install_layout + + :pypi:`opentracing` publishes no wheel, so pip builds it from the sdist + through the legacy :file:`setup.py` path using whatever setuptools is + already installed -- and Debian's packaged ``python3-setuptools`` patches + its ``install_lib`` command to read an ``install_layout`` option that the + ``install`` command it runs against does not define. + + A virtualenv gets an unpatched setuptools and builds it fine. If you must + install into the system Python, either upgrade setuptools in place + (``pip install -U setuptools``) or build that one package in an isolated + environment (``pip install --use-pep517 opentracing``). + After installing the dependencies required, you can now execute the test suite by calling :pypi:`py.test =1.3.0,<=2.4.0