test_local.py

Overview

`test_local.py` is a comprehensive test suite designed to validate the functionality, robustness, and correctness of the `py.path.local` module (commonly imported as `local` from the `py` library). This module provides a high-level, object-oriented interface to filesystem paths and operations, allowing manipulation and querying of files and directories in a platform-independent manner.

The test file exercises a broad range of features including path construction, equality, joining, file and directory operations (creation, removal, copying, moving), filesystem attributes (mtime, size, ownership), pattern matching, import-related utilities, symbolic links, permission handling, and platform-specific behaviors. It also tests interactions with Python's import system and ensures compatibility with newer Python features like the [os.PathLike](/projects/286/67409) protocol.

In essence, this file serves as a quality assurance layer that guarantees the correctness of the `local` path abstraction and its integration in various filesystem scenarios and Python runtime environments.

Detailed Documentation

Modules and Imports

• contextlib, multiprocessing, os, sys, time, warnings: Standard Python libraries for context management, parallel processing, OS-level operations, and timing.

• unittest.mock: Used for mocking system modules and attributes in tests.

• py.error, py.path.local: Core dependencies from the py library providing error definitions and the local path abstraction.

• pytest: Testing framework used to define and run test cases.

Context Manager

ignore_encoding_warning()

A context manager that suppresses [EncodingWarning](/projects/286/67223) on Python 3.10+ during file read/write operations. This is useful for tests that perform encoding-sensitive operations and want to avoid noisy warnings.

**Usage Example:**

with ignore_encoding_warning():
    content = path.join("samplefile").read("r")

Class: CommonFSTests

This class contains a large collection of test methods that verify the core filesystem operations and path manipulations on `local` path instances. The tests are designed to be reusable for different path implementations by passing fixtures such as `path1`.

Key Test Methods & Their Purpose:

• test_constructor_equality(self, path1)
  Validates that constructing a path from another path produces an equal object.

• test_join(self, path1)
  Checks that joining paths works correctly and that the resulting path string matches expected patterns.

• test_add_something(self, path1)
  Tests path concatenation using the + operator and verifies the existence and type of the resulting path.

• test_parts(self, path1)
  Verifies the .parts() method which returns a list of path components.

• test_exists(self, path1)
  Confirms that existence checks and file/directory type checks behave as expected.

• test_listdir(self, path1)
  Tests directory listing with and without filters and pattern matching.

• test_visit_nofilter(self, path1)
  Iterates over directory trees recursively, verifying visit functionality.

• test_copy_file(self, path1) and test_copy_dir(self, path1)
  Verify copying of files and directories, including content integrity.

• test_remove_file(self, path1) and test_remove_dir_recursive_by_default(self, path1)
  Test removal of files and directories, including recursive deletion.

• test_move_file(self, path1) and test_move_dir(self, path1)
  Test moving files and directories and ensure the source no longer exists afterward.

• test_fspath_protocol_match_strpath(self, path1)
  Ensures that __fspath__() method returns the correct string path representation.

• test_make_numbered_dir_multiprocess_safe(self, tmpdir)
  Validates the thread/process safety of the make_numbered_dir utility via multiprocessing.

**Usage:**

`CommonFSTests` is a base test class designed to be inherited or instantiated by specific test classes that provide the `path1` fixture.

Function: setuptestfs(path)

Initializes a sample filesystem structure under the given `path` for testing purposes. It creates files, directories, Python modules, and a pickle file with predefined content. This setup ensures that tests have a consistent and known environment.

**Details:**

• Creates files like "samplefile", "execfile.py", and "samplepickle" with specific contents.

• Creates directories such as "sampledir" and "otherdir" with Python module files inside.

• Writes Python files with code to test import-related features.

**Usage Example:**

setuptestfs(tmpdir)

Fixtures

• path1: A session-scoped pytest fixture that yields a temporary directory with the sample test filesystem initialized by setuptestfs.

• fake_fspath_obj: Provides an object implementing the __fspath__() method to test compatibility with Python's PathLike protocol.

Utility Function: batch_make_numbered_dirs(rootdir, repeats)

Creates multiple numbered directories under `rootdir` using `local.make_numbered_dir`. For each directory, it writes a file containing the directory number and verifies the content. Also removes any `.lock` files to simulate unlocked state.

**Parameters:**

• rootdir: The root directory under which numbered dirs are created.

• repeats: Number of directories to create.

**Returns:**

• True on successful creation and verification.

Class: TestLocalPath(CommonFSTests)

Extends `CommonFSTests` with additional tests specific to the `local` path class. These include:

• Path normalization and equality with different path representations.

• Hash computation on files.

• Removing readonly files and directories.

• Changing directories and context management with as_cwd.

• Handling of tilde expansions (~).

• Case-insensitive behavior on Windows.

• Opening files using __fspath__() compatibility.

• Multi-process safety for numbered directory creation.

Class: TestExecutionOnWindows

Tests Windows-specific behaviors, such as the precedence of `.bat` files over `.exe` in `sysfind`.

Class: TestExecution

Tests execution-related features on non-Windows platforms:

• sysfind behavior with permissions and absolute vs relative paths.

• Running shell commands via sysexec.

• Numbered directory creation with edge cases.

• Error handling and import mismatches.

Class: TestImport

Verifies Python module import functionality from paths, including:

• Importing .py files and packages.

• Handling renamed directories and import mismatches.

• Importing modules with complex names.

• Ensuring sys.path modifications for imports.

• Compatibility with different import mechanisms.

Class: TestImportlibImport

Similar to `TestImport` but uses `importlib` for module importing, testing failure cases and isolation from `sys.modules`.

Additional Tests

• test_pypkgdir: Tests detection of Python package directories.

• test_isimportable: Validates the utility function checking if a string is a valid Python importable name.

• test_samefile: Tests path equality including symlink resolution.

• test_unicode: Ensures proper handling of Unicode paths and filenames.

• test_binary_and_text_methods: Tests reading/writing files in binary and text modes with encoding.

• Platform-specific tests for Windows (TestWINLocalPath) and POSIX (TestPOSIXLocalPath) systems, covering permissions, symbolic links, ownership, and more.

Important Implementation Details and Algorithms

• Path Normalization: The tests ensure that redundant or relative path components (like "../" or multiple slashes) are normalized correctly by the local path object.

• Filesystem Traversal: The .visit() method is extensively tested for different filters (by filename patterns, file/directory type), recursion options (breadth-first vs depth-first), and error handling.

• Import System Integration: The tests cover complex scenarios such as importing modules from dynamically created files, handling import mismatches, and working with namespace packages.

• Multiprocessing Safety: The make_numbered_dir utility, which creates numbered directories avoiding name collisions, is tested under concurrent access using Python's multiprocessing pool to ensure thread/process safety.

• Cross-Platform Compatibility: The test suite accounts for differences between Windows and POSIX filesystems, including case sensitivity, symbolic link behavior, permission bits, and path separators.

Interaction with Other Parts of the System

• Relies on the py.path.local module as the core component under test.

• Integrates with Python's import system and filesystem APIs (os, sys).

• Uses pytest fixtures and markers extensively for setup, teardown, and conditional test execution.

• Interacts with the py.error module for exception handling specific to filesystem errors.

• Some tests depend on the py._process.cmdexec module for command execution (used in sysexec testing).

• Uses the local implementation's internal methods like make_numbered_dir, new(), join(), and visit() to validate functionality.

Visual Diagram: Class Structure and Main Test Classes

classDiagram
    class CommonFSTests {
        +test_constructor_equality(path1)
        +test_join(path1)
        +test_exists(path1)
        +test_listdir(path1)
        +test_visit_nofilter(path1)
        +test_copy_file(path1)
        +test_remove_file(path1)
        +test_move_file(path1)
        +test_fspath_protocol_match_strpath(path1)
        +... (many other test methods)
    }

    class TestLocalPath {
        +test_join_normpath(tmpdir)
        +test_gethash(tmpdir)
        +test_remove_removes_readonly_file(tmpdir)
        +test_chdir(tmpdir)
        +test_make_numbered_dir_multiprocess_safe(tmpdir)
        +... (inherits CommonFSTests)
    }

    class TestExecution {
        +test_sysfind_no_permission_ignored(monkeypatch, tmpdir)
        +test_sysfind_absolute()
        +test_sysexec()
        +test_make_numbered_dir(tmpdir)
        +... (additional execution tests)
    }

    class TestImport {
        +test_pyimport(path1)
        +test_pyimport_renamed_dir_creates_mismatch(tmpdir, monkeypatch)
        +test_pyimport_dir(tmpdir)
        +test_pyimport_and_import(tmpdir)
        +... (import-related tests)
    }

    CommonFSTests <|-- TestLocalPath

Summary

`test_local.py` is a large-scale, detailed test suite ensuring the stability and correctness of the `py.path.local` filesystem path abstraction. It covers a wide spectrum of functionality, from basic path manipulation to complex import mechanisms and platform-specific behaviors. The tests serve both as verification and documentation of expected behaviors, providing confidence in the module's operation across diverse environments and use cases.