naming20.rst

Overview

This documentation file, [naming20.rst](/projects/286/67223), explains the renaming conventions and namespace restructuring introduced in version 2.0 of the pytest testing framework. The primary purpose of this file is to guide users migrating from older versions of the `py` distribution (which included the `py.test` command line tool and Python namespace) to the new, simplified `pytest` module structure.

Historically, older versions exposed testing helpers and collection classes under the `py.test` namespace, which was somewhat nested and less intuitive. Version 2.0 refactors this by exposing the same API objects directly and flatly in the `pytest` namespace, promoting clearer, easier to use naming and import patterns.

This file serves as a concise reference for developers updating their test codebases to align with the new naming standards, ensuring compatibility with pytest 2.0 and later.

Detailed Explanation

Purpose and Functionality

• Namespace Flattening: The older nested namespaces such as py.test.collect.XYZ are replaced by direct references under pytest.XYZ.

• Unified Access Point: Instead of accessing functionality via py.test or deeply nested modules, users now import directly from pytest.

• Backward Compatibility: The old py.test.* import paths remain valid but are deprecated in favor of the new flat structure.

• Encouragement for Global Renaming: Users are advised to update their test code imports globally to the new naming scheme for better maintainability and clarity.

Key Renaming Rules

The file enumerates the following critical renaming mappings:

Usage Examples

Old Style (Pre-2.0)

from py.test import raises
from py.test.collect import Collector
from py.test.cmdline import main

def test_example():
    with raises(ValueError):
        raise ValueError("error")

main()  # Run tests via CLI programmatically

New Style (2.0 and Later)

from pytest import raises
from pytest import Collector
from pytest import main

def test_example():
    with raises(ValueError):
        raise ValueError("error")

main()  # Run tests via CLI programmatically

Implementation Details

• The refactoring aligns with Python’s philosophy of "flat is better than nested," reducing the complexity of import paths.

• Internally, pytest re-exports or relocates classes and functions formerly within py.test.collect and other submodules to the top-level pytest namespace.

• This promotes a simplified API surface, reducing learning curve and potential import errors.

• The compatibility layer preserves old import paths to avoid breaking existing code immediately, allowing a gradual migration.

Interactions with Other System Components

• Test Codebases: Test suites and plugins written for older pytest versions using py.test imports will need to update imports to pytest to fully leverage the new naming conventions.

• CLI Tooling: The command line interface remains accessible via pytest.main(), streamlining programmatic invocation.

• pytest Plugins and Extensions: Plugins that extend or interface with pytest internals should update their import statements accordingly to maintain compatibility.

• Legacy py Distribution: This file references deprecations in the py distribution's namespace usage, highlighting the shift towards pytest as the primary namespace.

Mermaid Diagram: Namespace Structure Transition

The following class diagram illustrates the namespace flattening and renaming of key components from the old `py.test` hierarchy to the new `pytest` flat namespace:

classDiagram
    class PyTest {
        <<namespace>>
        +XYZ
        +collect.XYZ
        +cmdline.main()
    }
    class PyTestCollect {
        <<namespace>>
        +XYZ
    }
    class PyTestCmdline {
        <<namespace>>
        +main()
    }
    class Pytest {
        <<namespace>>
        +XYZ
        +main()
    }
    PyTestCollect --|> PyTest
    PyTestCmdline --|> PyTest
    Pytest ..> PyTest : replaces
    Pytest ..> PyTestCollect : flattens
    Pytest ..> PyTestCmdline : flattens

This diagram depicts:

• The original nested namespaces (py.test, py.test.collect, py.test.cmdline) and their contents.

• The new flattened pytest namespace that consolidates these components.

• The directional arrows show that pytest replaces and flattens the older nested structure.

Summary

[naming20.rst](/projects/286/67223) is a concise guideline document intended for pytest users upgrading to version 2.0. It explains the shift from nested `py.test` namespaces to a simpler, flat `pytest` namespace, providing renaming rules and usage examples. The document encourages users to update imports globally for cleaner, more maintainable test code and ensures continuity via backward compatibility. The namespace flattening aligns with Pythonic design principles, improving the developer experience with pytest.

*End of [naming20.rst](/projects/286/67223) documentation.*