Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Docs build fails with Pluggy 1.7.0 on an unresolved private DistFacade reference

Aperta Adatta ai principianti
  • Qualcosa non va?
#15,190 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Lothnic ci sta già lavorando.

Dal 16/10/2026.

  • #15191 di @Lothnic — chiusa senza merge
  • #15192 di @Lothnic — aperta

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
75/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

L'avviso che fa fallire la build viene generato durante la creazione della docstring di pluggy._manager.PluginManager.list_plugin_distinfo, che la documentazione API di PytestPluginManager include, e ha origine dal riferimento in src/_pytest/config/__init__.py. Inizia trovando l'elenco nitpick_ignore esistente nella configurazione di Sphinx, sotto il commento 'Undocumented third parties', e verifica come _tracing.TagTracerSub vi compare. Aggiungi la voce pluggy._compat.DistFacade come proposto, poi esegui tox -e docs per confermare che la build passi con -W. Il lavoro è completato quando la build della documentazione riesce con Pluggy 1.7.0 e nessun'altra voce di nitpick cambia.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

  • Detailed description of the problem
  • Environment package list
  • pytest and operating system versions
  • Minimal reproduction

Description

Following the contributor documentation's tox -e docs command fails on current
pytest main when the docs environment resolves Pluggy 1.7.0. Sphinx reports an
unresolved reference from an inherited Pluggy method docstring, and -W turns
the warning into a build failure.

Reproduction

Starting from pytest commit c9c19f8e62c12834ad83193a1869cc82fe9c700e, with the
contributor environment and tox installed:

tox -e docs

The docs environment used:

  • Python 3.14.6
  • pytest 9.2.0.dev382+gc9c19f8e6
  • Pluggy 1.7.0
  • Sphinx 9.1.0
  • sphinxcontrib-trio 1.2.0
  • Linux x86_64, glibc 2.43

Output:

src/_pytest/config/__init__.py:docstring of pluggy._manager.PluginManager.list_plugin_distinfo:5:
WARNING: py:class reference target not found: pluggy._compat.DistFacade [ref.class]

build finished with problems, 1 warning (with warnings treated as errors).
docs: FAIL code 1

A clean Sphinx rebuild with -E -a reproduces the same warning, excluding an
old doctree cache as the cause.

Expected behavior

The documented contributor docs build succeeds with the supported dependency
versions. The docs requirements allow pluggy>=1.5.0, which includes 1.7.0.

Cause and proposed scope

The PytestPluginManager API documentation includes inherited members.
Pluggy 1.7.0's PluginManager.list_plugin_distinfo docstring now links
pluggy._compat.DistFacade, a private compatibility wrapper with no matching
documentation target. Its unresolved reference fails pytest's strict build.

Adding this exact private class to the existing nitpick_ignore entries for
undocumented third-party types fixes the build:

     # Undocumented third parties
     ("py:class", "_tracing.TagTracerSub"),
+    ("py:class", "pluggy._compat.DistFacade"),
     ("py:class", "warnings.WarningMessage"),

This retains strict reference checking for every other target and does not pin
or downgrade Pluggy.

Verification

  • Original tox -e docs: fails with the warning above.
  • Clean original build with Pluggy 1.7.0: fails with the same warning.
  • Patched tox -e docs: passes with Pluggy 1.7.0 and Sphinx 9.1.0.
  • The unmodified Python 3.14 baseline suite: 4,695 passed, 48 skipped,
    17 xfailed and 4 xpassed.

For comparison, changing only Pluggy to 1.6.0 removes the DistFacade warning
but produces two other private Pluggy-type reference warnings; that version is
not claimed as a successful build or a workaround.

AI assistance was used for reproduction, investigation and preparation of this report.

Docs environment package versions after validation

The local documentation configuration patch was applied when this list was captured.

Package                        Version
------------------------------ ---------------------------------
accessible-pygments            0.0.5
alabaster                      1.0.0
babel                          2.18.0
beautifulsoup4                 4.15.0
certifi                        2026.7.22
charset-normalizer             3.5.2
click                          8.5.0
docutils                       0.22.4
furo                           2025.12.19
idna                           3.20
imagesize                      2.0.1
iniconfig                      2.3.1
jinja2                         3.1.6
markupsafe                     3.0.4
packaging                      26.3
pluggy                         1.7.0
pygments                       2.21.0
pygments-pytest                2.5.0
pytest                         9.2.0.dev382+gc9c19f8e6.d20261016
requests                       2.34.2
roman-numerals                 4.1.0
snowballstemmer                3.1.1
soupsieve                      3.0.3
sphinx                         9.1.0
sphinx-basic-ng                1.0.0b2
sphinx-inline-tabs             2025.12.21.14
sphinx-issues                  6.0.0
sphinx-removed-in              0.2.3
sphinxcontrib-applehelp        2.0.0
sphinxcontrib-devhelp          2.0.0
sphinxcontrib-htmlhelp         2.1.0
sphinxcontrib-jsmath           1.0.1
sphinxcontrib-qthelp           2.0.0
sphinxcontrib-serializinghtml  2.0.0
sphinxcontrib-svg2pdfconverter 2.1.0
sphinxcontrib-towncrier        0.5.0a0
sphinxcontrib-trio             1.2.0
towncrier                      26.9.0
typing-extensions              4.16.0
urllib3                        2.8.0
Lingua principale
Python
Stelle
14.6k
Fork
3.5k
Merge medio
3g 18h
PR unite (30g)
27

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di pytest-dev/pytest

Tutte le issue di pytest-dev/pytest

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.