typed-pytest

Problem

from unittest.mock import MagicMock
from typing import cast
class UserService:
 def get_user(self, user_id: int) -> dict:
 return {"id": user_id, "name": "John"}
# Problem 1: MagicMock loses original type hints
mock_service = MagicMock(spec=UserService)
mock_service.get_user(1) # No autocomplete for get_user parameters
# Problem 2: cast() loses mock method hints
service = cast(UserService, mock_service)
service.get_user.assert_called_once() # assert_called_once has no type hint!

Solution

from typed_pytest_stubs import typed_mock, UserService
mock = typed_mock(UserService)
mock.get_usr # ❌ Caught by type checker: "get_usr" is not a known member
mock.get_user.assert_called_once_with(1) # ✅ Type-checked!

from typed_pytest import TypedMock, typed_mock
mock_service: TypedMock[UserService] = typed_mock(UserService)
# Mock methods have type hints
mock_service.get_user.assert_called_once_with(1) # Type-checked!
mock_service.get_user.return_value = {"id": 1} # Type-checked!

Installation

# Using uv
uv add typed-pytest
# Using pip
pip install typed-pytest

Requirements

Quick Start

from typed_pytest import typed_mock, TypedMock, TypedMocker
# Method 1: Direct mock creation
def test_user_service():
 mock_service: TypedMock[UserService] = typed_mock(UserService)
 mock_service.get_user.return_value = {"id": 1, "name": "Test"}
 result = mock_service.get_user(1)
 assert result == {"id": 1, "name": "Test"}
 mock_service.get_user.assert_called_once_with(1)
# Method 2: Using pytest fixture
def test_with_fixture(typed_mocker: TypedMocker):
 mock_service = typed_mocker.mock(UserService)
 mock_service.get_user.return_value = {"id": 1}
 mock_service.get_user(1)
 mock_service.get_user.assert_called_once_with(1)

Stub Generator

Important: Environment Requirements

# ✅ Correct: Run in project environment (has access to your dependencies)
uv add typed-pytest --dev
uv run typed-pytest-generator
# ❌ Wrong: uvx runs in isolated environment (no access to your dependencies)
uvx typed-pytest-generator # Will fail if your classes import sqlalchemy, etc.

Basic Usage

# Generate stubs for your classes
typed-pytest-generator -t myapp.services.UserService myapp.repos.ProductRepository
# Specify custom output directory
typed-pytest-generator -t myapp.services.UserService -o my_stubs
# Include private methods (starting with _)
typed-pytest-generator -t myapp.services.UserService --include-private
# Verbose output
typed-pytest-generator -t myapp.services.UserService -v

Generated Files

typed_pytest_stubs/
├── __init__.py # Re-exports all stub classes
└── _runtime.py # Runtime class definitions with method signatures

Using Generated Stubs

# Import typed_mock from stubs package for full auto-completion
from typed_pytest_stubs import typed_mock, UserService
def test_user_service():
 # typed_mock returns UserService_TypedMock with full IDE support
 mock = typed_mock(UserService)
 mock.get_user # ✅ Auto-complete for method names
 mock.get_user.return_value # ✅ Auto-complete for mock properties
 mock.get_user.assert_called_once_with(1) # ✅ Type-checked!
 mock.get_user.return_value = {"id": 1, "name": "Test"}
 result = mock.get_user(1)

Backend Selection

# Use default inspect backend (fast)
typed-pytest-generator -t myapp.services.UserService
# Use stubgen backend for better type information
typed-pytest-generator --backend stubgen -t myapp.services.UserService
# Short form
typed-pytest-generator -b stubgen -t myapp.services.UserService

class UserService_TypedMock:
 @property
 def get_user(self) -> MockedMethod[[int], typing.Any]: ...

class UserService_TypedMock:
 @property
 def get_user(self) -> MockedMethod[[int], dict[str, Any]]: ...

Configuration

pyproject.toml Configuration

[tool.typed-pytest-generator]
# List of fully qualified class names to generate stubs for
# Supports wildcard patterns:
# - "module.*" matches all classes in the module (non-recursive)
# - "module.**" matches all classes in the package recursively (includes submodules)
targets = [
 "myapp.services.*", # All classes in myapp.services module
 "myapp.repositories.**", # All classes in repositories and all submodules
 "myapp.models.User", # Specific class
]
# Output directory for generated stubs (default: "typed_pytest_stubs")
output-dir = "typed_pytest_stubs"
# Include private methods starting with _ (default: false)
include-private = false
# Exclude specific classes from stub generation
exclude-targets = [
 "myapp.internal.PrivateHelper",
 "myapp.legacy.DeprecatedService",
]
# Backend for type extraction (default: "inspect")
# - "inspect": Fast, uses Python's inspect module
# - "stubgen": Slower, uses mypy's stubgen for accurate return types
backend = "inspect"

# Uses configuration from pyproject.toml (auto-discovered)
typed-pytest-generator
# With verbose output
typed-pytest-generator -v

CLI Options

# Override targets from config
typed-pytest-generator -t myapp.services.NewService
# Override output directory
typed-pytest-generator -o custom_stubs
# Add exclusions (merged with config exclusions)
typed-pytest-generator -e myapp.services.SkipThis
# Use a specific config file
typed-pytest-generator -c /path/to/pyproject.toml
# Use wildcard to match all classes in a module (non-recursive)
typed-pytest-generator -t "myapp.services.*"
# Use recursive wildcard to match all classes in a package and submodules
typed-pytest-generator -t "myapp.repositories.**"
# Combine options
typed-pytest-generator -t "myapp.repositories.**" -e myapp.repositories.Internal -o stubs -v

IDE and Type Checker Setup

# Generated stub files
typed_pytest_stubs/

[tool.pyright]
include = ["src", "tests", "typed_pytest_stubs"]

Type Checker Configuration for Generated Stubs

[tool.pyrefly]
project-includes = ["src", "tests"]
# Add project root so typed_pytest_stubs can be found
search-path = ["."]

[tool.ty.environment]
# Add project root so typed_pytest_stubs can be found
extra-paths = ["."]

Recommended Workflow

Development

# Clone repository
git clone https://github.com/tmdgusya/typed-pytest.git
cd typed-pytest
# Install dependencies
uv sync --all-extras
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src/typed_pytest --cov-report=term-missing
# Type check
uv run mypy src/
uv run pyright src/
# Lint
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Documentation

License