py.py

Overview

`py.py` serves as a compatibility shim for the `pylib` package, which is being deprecated or removed. Its main purpose is to provide seamless backward compatibility for projects or modules that depend on `py.error` and `py.path` submodules.

If `pylib` is installed and available with higher priority, this shim file will be bypassed in favor of the actual `py` package implementation (typically located at `py/__init__.py`). When the shim is active, it redirects import requests for `py.error` and `py.path` to corresponding internal `_pytest._py` modules, ensuring that existing code relying on these modules continues to function without modification.

This approach allows a smooth transition away from `pylib` while maintaining compatibility and avoiding import errors in legacy codebases or during migration.

Detailed Explanation

Module-Level Behavior

• Imports

  • sys: Used to manipulate the module import system.

  • _pytest._py.error as error: Imports the error handling module from the internal _pytest package.

  • _pytest._py.path as path: Imports the path handling module from the internal _pytest package.

• Module Replacement in sys.modules

  The two key lines:

  sys.modules["py.error"] = error
  sys.modules["py.path"] = path
  

  perform dynamic patching of the Python import system such that any subsequent import of py.error or py.path will reference these imported internal modules instead of looking for the original py package submodules.

• __all__ Specification

  Declares the public API for this module as:

  __all__ = ["error", "path"]
  

  meaning only error and path are intended to be accessible when using from py import *.

Usage Examples

This file itself is not intended to be directly imported by developers. Instead, it transparently hooks into the import mechanism.

For example, with this shim in place, the following code:

import py.error
import py.path

try:
    raise py.error.Exception("Error occurred")
except py.error.Exception as e:
    print("Caught py error:", e)

p = py.path.local("/tmp")
print("Local path:", p)

will work correctly by using the `_pytest._py.error` and `_pytest._py.path` implementations, even if the original `pylib` is not installed.

Important Implementation Details

• Shim Strategy

  This file acts purely as a shim or proxy to maintain compatibility. It does not implement any functionality itself but leverages internal _pytest._py modules.

• Module Precedence

  It is important that if the pylib package is installed, this shim file is skipped because the actual py package in py/__init__.py will take precedence due to Python's module resolution order.

• No Classes or Functions

  This file contains no class or function definitions. Its entire logic is at the module level for import redirection.

Interaction with the System

• Dependency on _pytest._py

  This shim depends on the internal _pytest._py.error and _pytest._py.path modules provided by the pytest testing framework.

• Impact on Downstream Code

  Code that imports py.error or py.path will transparently receive the corresponding _pytest implementations, ensuring compatibility without code changes.

• Part of Migration Path

  This file is part of a transition strategy removing the deprecated pylib in favor of internal or alternative implementations.

Mermaid Diagram: Module Structure

flowchart TD
    A[py.py (shim)] --> B[_pytest._py.error]
    A --> C[_pytest._py.path]

    subgraph sys.modules
        direction LR
        D["py.error"] -->|redirects to| B
        E["py.path"] -->|redirects to| C
    end

Summary

• py.py is a shim file redirecting py.error and py.path imports to internal _pytest._py modules.

• It enables compatibility for projects relying on pylib during its deprecation.

• Implements import redirection by patching sys.modules.

• No classes or functions; purely a module-level proxy.

• Used internally in the system and skipped if the real py package is present.

• Supports legacy code and smooth migration.

This design ensures minimal disruption and a clean path forward as the `pylib` package is phased out.