Add SpyType protocol to expose spy attributes for type checking

[BlocksecPHD]

Summary

The Spy type definition previously didn't include the extra attributes (spy_return, spy_return_list, spy_return_iter, spy_exception) that are added at runtime by the spy() method. This broke autocomplete and type checking for users.

This PR introduces a new SpyType protocol that:

• Defines the spy-specific attributes with proper type annotations
• Includes common mock assertion methods for full mock interface
• Uses runtime_checkable decorator for isinstance support
• Is exported from pytest_mock module for easy import

The spy() method now returns SpyType instead of MockType, enabling proper type inference and autocomplete in IDEs.

Changes

1. Added SpyType protocol in src/pytest_mock/plugin.py with:

   • spy_return: Any
   • spy_return_list: list[Any]
   • spy_return_iter: Optional[Iterator[Any]]
   • spy_exception: Optional[BaseException]
   • Mock assertion methods (assert_called, assert_called_once, etc.)
   • Mock properties (call_count, call_args, call_args_list, called)

2. Updated spy() method to return SpyType

3. Exported SpyType from src/pytest_mock/__init__.py

4. Added comprehensive tests in tests/test_spy_type_annotations.py

Example Usage

Before (required type: ignore comments):

spy = mocker.spy(Foo, "bar")
result = spy.spy_return  # type: ignore[attr-defined]

After (type checker recognizes attributes):

from pytest_mock import SpyType

spy: SpyType = mocker.spy(Foo, "bar")
result = spy.spy_return  # No type: ignore needed!

Testing

All existing spy tests pass. New test file verifies:

• SpyType is properly exported
• All spy attributes are defined with correct types
• spy() method returns SpyType
• Mock methods are available on SpyType

Fixes #547