release-2.9.0.rst

Overview

This file is the release notes documentation for version 2.9.0 of **pytest**, a popular and mature Python testing framework. It provides a detailed summary of new features, changes, and bug fixes introduced in this release compared to the previous version 2.8.7. The document also acknowledges contributors, offers upgrade instructions, and highlights important internal implementation changes.

The primary purpose of this file is to inform users and developers about the enhancements and fixes in pytest 2.9.0, helping them understand new capabilities, behavioral changes, and potential impacts on their testing workflows.

Detailed Content Breakdown

The file does not contain executable code, classes, or functions but is structured as a changelog and release announcement. The main sections include:

General Introduction: Overview of pytest and link to official documentation.
Upgrade Instructions: How to upgrade pytest using pip.
Acknowledgments: List of contributors to the release.
New Features: Description of major new functionalities added.
Changes: Detailed notes on important modifications and internal refactorings.
Bug Fixes: List of resolved issues and improvements.
External References: Links to related documentation and issue trackers.

Key Sections Explained

1. New Features

pytest.mark.skip Mark
Introduces a new marker to unconditionally skip tests.
Usage Example:

import pytest

@pytest.mark.skip(reason="Skipping this test unconditionally")
def test_example():
    assert False  # This test will be skipped

Multiple --doctest-glob Arguments
Allows passing multiple glob patterns for doctest discovery via command line.
New Reporting Options -rp and -rP
Added refined test reporting flags to show summaries and details of passing tests.
pytest.mark.xfail strict Option
Enables marking expected failures as strict, causing unexpected passes (XPASS) to fail the suite.
Parser Enhancements
Parser.addini now supports boolean configuration options.
ALLOW_BYTES Doctest Option
New option to ignore byte string prefixes in doctest outputs.
KeyboardInterrupt Hint
Suggests using --fulltrace on KeyboardInterrupt for better debugging.
Exception Source Location Handling
Catches IndexError to handle dynamically generated test code gracefully.

2. Changes

Merging py.code into pytest._code
Internal refactoring to consolidate code handling into the pytest repository for better maintenance.
Important: This module is private and experimental; users should not import it explicitly.
pytest_enter_pdb API Change
Now optionally receives the pytest configuration object, enhancing debugger integration.
Dropped Python ≤ 2.5 Support
Cleaned up legacy code including obsolete assertion rewriting modules.
Enhanced Comparison Output
Always shows full comparison when running in CI/build environments.
Long Command-Line Options
Support for --last-failed and --failed-first as longer alternatives to --lf and --ff.
Improved Collection Progress Output
Progress messages shown only in terminal environments to avoid clutter in CI logs.

3. Bug Fixes

Fixes enabling -s and -c options to work with distributed testing (xdist).
Support for Python 3.5’s matrix multiplication operator (@) in assertion rewriting.
UTF-8 message formatting fixes.
Updated traceback documentation to reflect all available styles accurately.
Fix for multiple property records in JUnit XML output.

Implementation Details and Algorithms

As a release notes file, this document does not contain executable code or algorithms. However, it references significant internal changes such as:

Codebase Refactoring: The integration of py.code into pytest._code reflects a strategic architectural change aiming to improve maintainability and bug fixing efficiency by co-locating related code.
Enhanced Assertion Rewriting: Support for new Python syntax elements (e.g., matrix multiplication operator) indicates ongoing improvements to the core assertion introspection engine used by pytest.
Improved Reporting and CLI Usability: Additions to command-line flags and reporting options reflect user feedback and aim to improve test output clarity and debugging experience.

Interactions with Other System Components

External Dependencies: Users upgrade pytest via PyPI using pip, ensuring compatibility with Python environments.
Internal Modular Structure: The note about pytest._code indicates tight coupling within pytest’s internal modules for code analysis and test introspection.
Integration with Testing Workflows: New marks (skip, xfail enhancements) and CLI options directly affect how tests are collected, executed, and reported, influencing continuous integration pipelines and developer experience.
Doctest Support: Improvements to doctest options reflect pytest’s support for embedding tests in documentation.

Visual Diagram

Since this file is a changelog/release notes document and does not define classes or functions, a flowchart illustrating the structure of this file and its relationship to pytest’s release process provides the most value.

flowchart TD
    A[Start: pytest 2.9.0 Release Notes] --> B[Introduction & Overview]
    B --> C[Upgrade Instructions]
    C --> D[Acknowledgments]
    D --> E[New Features]
    E --> F[Changes]
    F --> G[Bug Fixes]
    G --> H[External References]
    H --> I[End]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style I fill:#bbf,stroke:#333,stroke-width:2px

This flowchart outlines the sequential structure of the release notes document, aiding readers in navigating the content logically.

Summary

The [release-2.9.0.rst](/projects/286/66986) file serves as an essential communication tool documenting the evolution of pytest in version 2.9.0. It provides users and developers with detailed insights into new capabilities, critical changes, and resolved issues, supporting informed upgrades and usage. Its structure and content reflect the project’s commitment to transparency, quality, and continuous improvement in the Python testing ecosystem.