plugin_list.rst

Overview

The `plugin_list.rst` file serves as an autogenerated comprehensive reference document listing available Pytest plugins published on PyPI. Updated regularly via an automated script (`scripts/update-plugin-list.py`), it collates metadata about Pytest plugins, providing a centralized informational resource for discovering and referencing these plugins.

This file does **not** contain executable code or classes but rather a structured, tabular listing of plugins with key attributes such as:

• Plugin name (linked to the PyPI project page)

• Summary description of the plugin

• Date of last release

• Stability status (e.g., Production/Stable, Beta, Alpha)

• Pytest version requirements or other dependencies

Its primary purpose is to assist Pytest users and developers in identifying relevant plugins for their testing needs, emphasizing that this list is informational and uncurated, hence users should evaluate plugins independently before adoption.

Key Features and Functionality

• Automated Generation: The file is produced by a Python update script run on a schedule (usually weekly via GitHub Actions), ensuring up-to-date plugin information.

• PyPI Plugin Discovery: Includes all PyPI projects with names starting with pytest- or pytest_ along with manually selected plugins.

• Filtering: Excludes plugins classified as inactive to keep the list relevant.

• Rich Metadata: Displays plugin status, last release date, and dependency requirements to help users quickly assess plugin suitability.

• Format Adaptation: Uses conditional formatting for different output formats (e.g., a simpler list for PDFs) to improve readability.

• Cross-Referencing: Each plugin name is linked directly to its PyPI project page for easy access.

File Structure and Content

The file is written in reStructuredText (reST) format, suitable for Sphinx documentation generation. Its main content is a large table enumerating the plugins along with their metadata. The file also contains explanatory notes and warnings to set proper expectations regarding the list’s nature and usage.

Sections:

1. Header and Note

   • Mentions the file is autogenerated by the update script.

   • Provides a cross-reference label _plugin-list for linking within the documentation.

   • Title "Pytest Plugin List".

2. Introduction Paragraphs

   • Describes the scope and source of the list.

   • Links to the update script repository for those interested in the generation process.

3. Warning Box

   • Cautions readers that this is not a curated or endorsed list.

   • Advises independent quality assessment.

4. Conditional Formatting Notes

   • Explains different formatting when rendering PDFs to prevent overly wide tables.

5. Plugin Table

   • Columns include:

     • name: Plugin name with PyPI link.

     • summary: Short description.

     • last_release: Date of last release.

     • status: Stability and maturity level.

     • requires: Required pytest or other dependencies.

   • The table lists 1687 plugins as of the snapshot, showcasing a wide ecosystem.

Implementation Details

• Generation Script: The file is generated by the Python script update-plugin-list.py located in the main pytest repository under scripts/. The script performs the following:

  • Queries PyPI for packages with the prefix pytest- or pytest_.

  • Extracts metadata about these packages (name, summary, release dates, classifiers).

  • Filters out inactive or unmaintained plugins.

  • Formats this data into a reStructuredText table.

  • Inserts warning notes and references to the update script itself.

  • Supports conditional formatting directives for different output formats.

• ReStructuredText Markup: The file leverages reST features such as:

  • Cross references for linking (.. _plugin-list:).

  • Admonitions for warnings and notes.

  • Conditional directives (.. only:: not latex) to customize presentation.

  • PyPI package link roles (:pypi:) to create clickable links to PyPI.

Usage Example

This file is intended for inclusion in the Pytest official documentation or any related documentation portal. It can be referenced or linked for users who want an overview of available plugins.

Example inclusion in a Sphinx document:

.. include:: /reference/plugin_list.rst

Users browse this list to identify plugins by name or functionality, and then follow the PyPI links to learn more or install them.

Interaction with Other System Components

• Update Script (update-plugin-list.py): This file is the output product of this script, which is part of the Pytest development repository. The script interacts with PyPI's JSON API to pull plugin data.

• Documentation Build Process: Incorporated into the Pytest Sphinx documentation, this file integrates into the build pipeline to update the online or offline docs.

• Plugin Ecosystem: Acts as a catalog that bridges the Pytest core project and the extensive community-maintained plugin ecosystem.

Visual Diagram

Since this file is a static documentation listing without classes or functions, a **flowchart** illustrating the generation and usage workflow is most appropriate.

flowchart TD
    A[Scheduled GitHub Action] --> B[Run update-plugin-list.py]
    B --> C[Query PyPI for pytest plugins]
    C --> D[Filter active plugins]
    D --> E[Generate plugin_list.rst file]
    E --> F[Include in Pytest docs]
    F --> G[Users browse plugin list]
    G --> H[Users visit PyPI for plugin details]

Explanation:

• The process starts with a scheduled GitHub Action triggering the update script.

• The script queries PyPI, filters plugins, and generates the .rst file.

• The file is included in the Pytest documentation.

• End users utilize this documentation to discover and access plugins.

Summary

• plugin_list.rst is an autogenerated, comprehensive reference listing of Pytest plugins.

• It provides plugin metadata in a structured, searchable format.

• The file is generated by an automated script using PyPI data.

• Serves as an informational resource, not an endorsement or curated list.

• Integrates into Pytest official documentation, facilitating ecosystem visibility.

• The update process flows from scheduled tasks to user consumption, as visualized above.

This documentation should aid maintainers and users in understanding the origin, purpose, and usage of the `plugin_list.rst` file within the Pytest documentation ecosystem.