Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado Apto para principiantes
  • ¿Algo no está bien?
#15,190 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #15191 de @Lothnic — cerrado sin fusionar
  • #15192 de @Lothnic — fusionado

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
75/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
python
Área
documentation

Línea de trabajo

La advertencia que falla se genera al construir el docstring de pluggy._manager.PluginManager.list_plugin_distinfo, que incluyen los docs de la API de PytestPluginManager, y se origina en la referencia de src/_pytest/config/__init__.py. Empieza por localizar la lista nitpick_ignore existente en la configuración de Sphinx, bajo el comentario 'Undocumented third parties', y comprueba cómo aparece allí _tracing.TagTracerSub. Añade la entrada pluggy._compat.DistFacade como se propone y luego ejecuta tox -e docs para confirmar que la compilación pasa con -W. Está terminado cuando la compilación de la documentación se completa con éxito con Pluggy 1.7.0 y ninguna otra entrada de nitpick cambia.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

  • 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
Lenguaje dominante
Python
Estrellas
14.6k
Forks
3.5k
Merge medio
1 d 21 h
PR fusionados (30 d)
23

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de pytest-dev/pytest

Todos los issues de pytest-dev/pytest

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.