test_stash.py

Overview

This file contains unit tests for the `Stash` and `StashKey` classes imported from the internal `_pytest.stash` module. The primary purpose is to verify the correctness and expected behavior of the stash mechanism, which provides a typed, dictionary-like storage keyed by `StashKey` instances. The tests cover basic storage and retrieval, type enforcement, error handling, interaction isolation between different stash instances, and prevention of accidental attribute injection.

Detailed Explanation

Tested Classes (Imported)

• Stash: A container class that behaves like a dictionary but keyed using StashKey objects. It supports storing and retrieving typed values associated with unique keys.

• StashKey: A generic key class used to uniquely identify entries in a Stash. It is parameterized by type to support type-safe retrieval.

Function: test_stash()

Purpose

This test function validates the behavior of the `Stash` and `StashKey` classes. It ensures that the stash correctly handles storage, retrieval, deletion, and existence checks of typed values, and that keys and stash instances do not interfere with each other.

Parameters

• None

Returns

• None

Behavior and Usage

1. Initialization and Emptiness Checks

   • Create a new Stash instance.

   • Check that it is initially empty (len(stash) == 0 and not stash).

2. Key Creation

   • Create two keys key1 and key2 for different types: str and int.

3. Basic Functionality: Single Key

   • Confirm key1 is not initially in the stash.

   • Store a string "hello" under key1.

   • Verify presence of key1 and correct retrieval.

   • Overwrite the value for key1 with "world".

   • Confirm the retrieved value reflects the update.

   • Demonstrate that the value type is correct by concatenating a string (type-checked by mypy).

   • Check that stash length is correct and it evaluates as truthy.

4. Key Isolation

   • Confirm key2 is not in the stash.

   • Confirm get returns None for missing key.

   • Accessing or deleting key2 raises KeyError.

   • Store an integer 1 under key2.

   • Confirm value retrieval and type correctness by arithmetic operation.

   • Delete key1 and confirm subsequent deletion or access raises KeyError.

5. setdefault Method

   • Store "existing" under key1.

   • Confirm setdefault returns existing value and does not overwrite.

   • Create a new key key_setdefault with type bytes.

   • Confirm setdefault stores and returns the default value for a new key.

   • Check stash length and truthiness.

6. Attribute Assignment Protection

   • Confirm that assigning arbitrary attributes (like stash.foo) raises AttributeError, preventing accidental extension of the stash object.

7. Multiple Stash Instances

   • Create a second stash stash2.

   • Create a new key key3 of type int.

   • Confirm stash2 does not contain key2 initially.

   • Store values under key2 and key3 in stash2.

   • Confirm values are independent of those in the first stash.

Example Usage

stash = Stash()
key = StashKey[str]()
stash[key] = "test"
print(stash[key])  # Output: test

Important Implementation Details

• Type Safety: StashKey is generic, allowing Stash to enforce type safety on stored values at type-check time (e.g., using mypy).

• Isolation: Each Stash instance maintains its own storage, preventing cross-contamination.

• Error Handling: Accessing or deleting keys not present in the stash raises KeyError, mimicking dictionary behavior.

• No Arbitrary Attributes: The Stash class disallows arbitrary attribute setting, ensuring stash contents are only accessible via keys.

Interaction with the System

• This test file is part of the test suite for the _pytest internal stash mechanism.

• It directly tests _pytest.stash.Stash and _pytest.stash.StashKey classes.

• It uses the pytest framework for assertions and exception handling.

• These tests ensure the reliability of stash usage in other pytest internal features or plugins that might rely on storing and retrieving typed contextual data safely.

Mermaid Class Diagram

classDiagram
    class Stash {
        +__getitem__(key: StashKey[T]) T
        +__setitem__(key: StashKey[T], value: T) None
        +__delitem__(key: StashKey[T]) None
        +__contains__(key: StashKey[T]) bool
        +__len__() int
        +get(key: StashKey[T], default: Optional[T]) T | None
        +setdefault(key: StashKey[T], default: T) T
    }

    class StashKey~T~ {
        <<generic>>
    }

    Stash *-- StashKey : uses >

Summary

The [test_stash.py](/projects/286/67397) file is a focused unit test suite that validates the core functionality of the `Stash` and `StashKey` classes, ensuring their correctness, type safety, isolation, and robustness. This test file helps maintain the integrity of pytest's internal stash feature, which can be critical for plugins and internal state management in the pytest framework.