478.feature.rst

Overview

This file documents a feature related to the support of PEP 420 implicit namespace packages within a specific testing or package discovery context. It describes an enhancement that allows the `--pyargs` target option, when used in conjunction with the configuration option `consider_namespace_packages` set to `true`, to recognize and handle implicit namespace packages not only for package naming but also for test discovery.

In essence, this feature ensures that when searching for tests or modules to run, the system respects PEP 420-style namespace packages—those without `__init__.py` files—offering improved compatibility and flexibility for modern Python package structures.

Detailed Explanation

Purpose

The feature expands the behavior of the `--pyargs` command-line target option to support implicit namespace packages according to PEP 420, when enabled by the configuration flag `consider_namespace_packages`.

Context

• Previously, the option consider_namespace_packages = true influenced only how package names were interpreted.

• After this enhancement, it also affects the discovery of tests, allowing tests inside implicit namespace packages to be found and executed.

Key Terms

• PEP 420 (Implicit Namespace Packages): A Python enhancement proposal that allows packages to span multiple directories without the need for an __init__.py file.

• --pyargs Target: A command-line argument that allows specifying Python modules or packages by their import path rather than filesystem path.

• consider_namespace_packages Config Option: A boolean configuration setting that toggles the consideration of namespace packages.

Usage Example

Suppose you have a namespace package structure like this:

my_namespace/
    package_a/
        tests/
            test_module.py
    package_b/
        tests/
            test_another.py

Neither `my_namespace` nor `package_a` and `package_b` directories have `__init__.py` files, making them implicit namespace packages per PEP 420.

• Set consider_namespace_packages = true in your configuration.

• Run the test discovery with the --pyargs option targeting my_namespace.

• The system will discover and execute tests located in both package_a and package_b.

Implementation Details

• The implementation likely involves checking the filesystem and import paths for modules and packages without __init__.py files.

• The test discovery algorithm is extended to recognize implicit namespace packages, relying on Python's import system behavior described in PEP 420.

• The feature integrates with the command-line parsing logic for --pyargs, affecting how targets are resolved.

Interaction with Other System Parts

• Configuration Module: Reads consider_namespace_packages setting.

• Command-Line Interface (CLI): Parses and processes the --pyargs option.

• Test Discovery Engine: Uses this feature to find tests within implicit namespace packages.

• Package Naming and Resolution: Extended to handle namespace packages uniformly for both naming and discovery phases.

By unifying package name handling with test discovery, the feature ensures consistency and better support for modern Python packaging standards.

Mermaid Diagram

flowchart TD
    A[Start: CLI receives --pyargs target] --> B{consider_namespace_packages = true?}
    B -- No --> C[Resolve target as regular package/module]
    B -- Yes --> D[Resolve target including implicit namespace packages]
    C --> E[Test discovery with standard package rules]
    D --> F[Test discovery including PEP 420 namespaces]
    E --> G[Run discovered tests]
    F --> G
    G --> H[End]

    style B fill:#f9f,stroke:#333,stroke-width:2px
    style D fill:#bbf,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px

This flowchart describes the decision pathway for resolving `--pyargs` targets with respect to the `consider_namespace_packages` flag and how it influences test discovery.

Summary

The [478.feature.rst](/projects/286/67223) file documents a targeted feature enhancement for Python test discovery tools or package resolution utilities that aligns test discovery behavior with Python's PEP 420 implicit namespace package standards, ensuring more comprehensive and modern package support when the relevant configuration is enabled.