fixturify 0.1.9__py3-none-any.whl

fixturify/__init__.py

@@ -0,0 +1,21 @@
+"""PyTools - A collection of reusable Python utility modules."""
+
+__version__ = "0.1.8"
+
+from fixturify.sql_d import sql, Phase, SqlTestConfig
+from fixturify.read_d import read
+from fixturify.http_d import http, HttpTestConfig
+from fixturify.json_assert import JsonAssert
+from fixturify.object_mapper import ObjectMapper
+
+__all__ = [
+    "__version__",
+    "sql",
+    "Phase",
+    "SqlTestConfig",
+    "read",
+    "http",
+    "HttpTestConfig",
+    "JsonAssert",
+    "ObjectMapper",
+]

fixturify/_utils/__init__.py

@@ -0,0 +1,7 @@
+"""Internal utilities shared across modules."""
+
+from fixturify._utils._constants import ENCODING
+from fixturify._utils._fixture_discovery import find_fixture_by_type, is_pytest_available
+from fixturify._utils._path_resolver import _PathResolver
+
+__all__ = ["ENCODING", "_PathResolver", "find_fixture_by_type", "is_pytest_available"]

fixturify/_utils/_constants.py

@@ -0,0 +1,10 @@
+"""Shared constants for PyTools modules."""
+
+# All file I/O operations must use UTF-8 encoding for cross-platform consistency
+ENCODING = "utf-8"
+
+# Maximum depth for object traversal (prevents infinite recursion).
+# This value is intentionally hardcoded at 100 for simplicity and predictability.
+# Deeply nested structures beyond 100 levels typically indicate circular references
+# or design issues that should be addressed differently.
+MAX_DEPTH = 100

fixturify/_utils/_fixture_discovery.py

@@ -0,0 +1,165 @@
+"""Generic pytest fixture discovery by return type annotation.
+
+This module provides a reusable fixture discovery mechanism that finds
+pytest fixtures based on their return type annotation, not their name.
+"""
+
+from typing import TYPE_CHECKING, Any, List, Optional, Type, TypeVar
+
+if TYPE_CHECKING:
+    from _pytest.fixtures import FixtureRequest
+
+
+T = TypeVar("T")
+
+
+def is_pytest_available() -> bool:
+    """Check if pytest is installed."""
+    try:
+        import pytest  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def find_fixture_by_type(
+    request: "FixtureRequest",
+    config_type: Type[T],
+) -> Optional[T]:
+    """
+    Find a pytest fixture by its return TYPE annotation.
+
+    Scans ALL available fixtures (not just function dependencies) for fixtures
+    that return the specified type. This allows defining config fixtures in
+    conftest.py without needing to add them as test parameters.
+
+    Args:
+        request: Pytest's FixtureRequest object
+        config_type: The type to search for (e.g., SqlTestConfig, HttpTestConfig)
+
+    Returns:
+        Instance of config_type if a matching fixture is found, None otherwise
+    """
+    # First pass: check fixture type annotations to find matching fixtures
+    # This scans ALL available fixtures, not just function dependencies
+    candidate_fixtures = _get_fixture_names_by_type(request, config_type)
+
+    # If we found candidates by annotation, try those
+    if candidate_fixtures:
+        for fixture_name in candidate_fixtures:
+            try:
+                value = request.getfixturevalue(fixture_name)
+                if isinstance(value, config_type):
+                    return value
+            except Exception:
+                # Fixture failed to resolve, try next candidate
+                continue
+        return None
+
+    # Fallback: iterate through function's fixture dependencies
+    # This maintains backward compatibility with unannotated fixtures
+    for fixture_name in request.fixturenames:
+        try:
+            value = request.getfixturevalue(fixture_name)
+            if isinstance(value, config_type):
+                return value
+        except Exception:
+            # Non-candidate fixture failed to resolve, skip it
+            continue
+
+    return None
+
+
+def _get_fixture_names_by_type(
+    request: "FixtureRequest",
+    config_type: Type[T],
+) -> List[str]:
+    """
+    Get fixture names that are annotated as returning the specified type.
+
+    Scans ALL available fixtures in the fixture manager, not just the ones
+    in the function's dependency list.
+
+    Args:
+        request: Pytest's FixtureRequest object
+        config_type: The type to search for
+
+    Returns:
+        List of fixture names with matching return annotation
+    """
+    candidates: List[str] = []
+
+    # Access the fixture manager to get all fixture definitions
+    fixturemanager = getattr(request, "_fixturemanager", None)
+    if fixturemanager is None:
+        return candidates
+
+    # Get the node for fixture resolution (getfixturedefs needs node, not nodeid)
+    node = getattr(request, "node", None)
+    if node is None:
+        return candidates
+
+    # _arg2fixturedefs contains ALL registered fixtures
+    # This is an internal pytest API but is stable
+    arg2fixturedefs = getattr(fixturemanager, "_arg2fixturedefs", None)
+    if arg2fixturedefs is None:
+        # Fallback to just checking fixturenames
+        return _get_from_fixturenames(request, fixturemanager, node, config_type)
+
+    # Scan ALL fixtures for ones that return the target type
+    for fixture_name in arg2fixturedefs.keys():
+        try:
+            # Get fixture definition(s) for this name
+            fixturedefs = fixturemanager.getfixturedefs(fixture_name, node)
+            if not fixturedefs:
+                continue
+
+            # Check the most recent fixture definition
+            fixturedef = fixturedefs[-1]
+            func = fixturedef.func
+
+            # Check return annotation
+            annotations = getattr(func, "__annotations__", {})
+            return_type = annotations.get("return")
+
+            if return_type is config_type:
+                candidates.append(fixture_name)
+        except Exception:
+            # Can't inspect this fixture, skip
+            continue
+
+    return candidates
+
+
+def _get_from_fixturenames(
+    request: "FixtureRequest",
+    fixturemanager: Any,
+    node: Any,
+    config_type: Type[T],
+) -> List[str]:
+    """
+    Fallback: Get fixtures from function's fixturenames only.
+
+    Used when _arg2fixturedefs is not available.
+    """
+    candidates: List[str] = []
+
+    for fixture_name in getattr(request, "fixturenames", []):
+        try:
+            fixturedefs = fixturemanager.getfixturedefs(fixture_name, node)
+            if not fixturedefs:
+                continue
+
+            fixturedef = fixturedefs[-1]
+            func = fixturedef.func
+
+            annotations = getattr(func, "__annotations__", {})
+            return_type = annotations.get("return")
+
+            if return_type is config_type:
+                candidates.append(fixture_name)
+        except Exception:
+            continue
+
+    return candidates

fixturify/_utils/_path_resolver.py

@@ -0,0 +1,135 @@
+"""Path resolution utility for relative paths based on caller's file location."""
+
+import inspect
+from pathlib import Path
+from typing import Optional
+
+
+# Patterns to skip when walking the stack (debuggers, frameworks, internals)
+_SKIP_PATH_PATTERNS = (
+    # VS Code debugger
+    "debugpy",
+    "_debugpy",
+    # PyCharm debugger
+    "pydevd",
+    "_pydevd",
+    "_pydev_",
+    "pydev",
+    # Frameworks
+    "site-packages",
+    # Python internals
+    "importlib",
+    "<frozen",
+)
+
+
+class _PathResolver:
+    """Resolves relative paths based on a reference file's location."""
+
+    @staticmethod
+    def resolve(relative_path: str, reference_file: Optional[str] = None) -> Path:
+        """
+        Resolve a relative path based on a reference file's location.
+
+        Args:
+            relative_path: Path like "../fixtures/data.json"
+            reference_file: Absolute path to the reference file (e.g., test file).
+                           If None, uses the caller's file location.
+
+        Returns:
+            Absolute Path object to the resolved file
+
+        Raises:
+            FileNotFoundError: If resolved path doesn't exist
+        """
+        if reference_file is None:
+            # Get caller's file path (skip this function and the immediate caller)
+            reference_file = _PathResolver._get_caller_file(stack_level=2)
+
+        reference_dir = Path(reference_file).parent
+        resolved = (reference_dir / relative_path).resolve()
+
+        if not resolved.exists():
+            raise FileNotFoundError(
+                f"File not found: {resolved} "
+                f"(resolved from '{relative_path}' relative to '{reference_file}')"
+            )
+
+        return resolved
+
+    @staticmethod
+    def resolve_without_check(
+        relative_path: str, reference_file: Optional[str] = None
+    ) -> Path:
+        """
+        Resolve a relative path without checking if the file exists.
+
+        Args:
+            relative_path: Path like "../fixtures/data.json"
+            reference_file: Absolute path to the reference file.
+                           If None, uses the caller's file location.
+
+        Returns:
+            Absolute Path object to the resolved file (may not exist)
+        """
+        if reference_file is None:
+            reference_file = _PathResolver._get_caller_file(stack_level=2)
+
+        reference_dir = Path(reference_file).parent
+        return (reference_dir / relative_path).resolve()
+
+    @staticmethod
+    def _get_caller_file(stack_level: int = 1) -> str:
+        """
+        Get the file path of the caller, skipping internal and debugger frames.
+
+        This method walks the stack and filters out:
+        - pytools internal frames (detected via module name, not file path)
+        - IDE debugger frames (VS Code debugpy, PyCharm pydevd)
+        - Framework frames (site-packages, importlib)
+
+        Using module names for pytools detection makes this independent of
+        installation location (works with editable installs, wheels, etc.)
+
+        Args:
+            stack_level: Number of valid caller frames to skip (1 = immediate caller)
+
+        Returns:
+            Absolute path to the caller's file
+
+        Raises:
+            RuntimeError: If caller's file cannot be determined
+        """
+        frame = inspect.currentframe()
+        try:
+            # Skip this function's frame
+            frame = frame.f_back
+            valid_frames_found = 0
+
+            while frame is not None:
+                filename = inspect.getfile(frame)
+                file_str = str(Path(filename).resolve())
+
+                # Get module name from frame globals (reliable way to identify package)
+                module_name = frame.f_globals.get("__name__", "")
+
+                # Skip pytools internal frames (using module name, not file path)
+                if module_name.startswith("fixturify.") or module_name == "fixturify":
+                    frame = frame.f_back
+                    continue
+
+                # Skip debugger and framework frames (using file path patterns)
+                if any(pattern in file_str for pattern in _SKIP_PATH_PATTERNS):
+                    frame = frame.f_back
+                    continue
+
+                # Found a valid caller frame
+                valid_frames_found += 1
+                if valid_frames_found >= stack_level:
+                    return file_str
+
+                frame = frame.f_back
+
+            raise RuntimeError("Cannot determine caller's file location")
+        finally:
+            del frame

fixturify/http_d/__init__.py

@@ -0,0 +1,80 @@
+"""HTTP mock decorator for recording and replaying HTTP interactions.
+
+This module provides a test decorator that automatically records HTTP calls
+on the first run and replays them on subsequent runs, making tests fast
+and deterministic.
+
+Supported HTTP clients:
+- httpx (sync and async)
+- requests
+- urllib3
+- http.client (stdlib)
+- aiohttp (async)
+- httplib2
+- tornado (sync and async)
+- boto3/botocore (AWS SDK)
+- httpcore (low-level, used by httpx)
+
+Example:
+    from fixturify.http_d import http
+
+    @http(path="./fixtures/api_calls.json")
+    def test_api_integration():
+        response = requests.get("https://api.example.com/users")
+        assert response.status_code == 200
+
+    # With config for header control
+    from fixturify.http_d import http, HttpTestConfig
+
+    config = HttpTestConfig(
+        ignore_request_headers=["Authorization"],
+        exclude_request_headers=["Authorization", "X-API-Key"],
+        exclude_response_headers=["Set-Cookie"],
+    )
+
+    @http(path="./fixtures/api.json", config=config)
+    def test_with_auth():
+        response = requests.get(
+            "https://api.example.com/data",
+            headers={"Authorization": "Bearer secret"}
+        )
+        assert response.status_code == 200
+
+    # Or use pytest fixture for auto-discovery
+    @pytest.fixture
+    def http_config() -> HttpTestConfig:
+        return HttpTestConfig(
+            ignore_request_headers=["Authorization"],
+        )
+
+    @http(path="./fixtures/api.json")  # Config auto-discovered from fixture
+    def test_with_fixture_config():
+        ...
+"""
+
+from fixturify.http_d._config import HttpTestConfig
+from fixturify.http_d._decorator import http
+from fixturify.http_d._exceptions import (
+    HttpMockError,
+    NoMatchingRecordingError,
+    RequestMismatchError,
+    UnusedRecordingsError,
+)
+from fixturify.http_d._models import HttpMapping, HttpMappings, HttpRequest, HttpResponse
+
+__all__ = [
+    # Main decorator
+    "http",
+    # Configuration
+    "HttpTestConfig",
+    # Exceptions
+    "HttpMockError",
+    "NoMatchingRecordingError",
+    "RequestMismatchError",
+    "UnusedRecordingsError",
+    # Models (for advanced usage)
+    "HttpRequest",
+    "HttpResponse",
+    "HttpMapping",
+    "HttpMappings",
+]

fixturify/http_d/_config.py

@@ -0,0 +1,214 @@
+"""HTTP mock configuration."""
+
+from dataclasses import dataclass, field
+from typing import List, Set
+
+
+# Default headers to ignore during request matching
+DEFAULT_IGNORE_REQUEST_HEADERS: Set[str] = {
+    "user-agent",
+    "date",
+    "accept-encoding",
+    "content-length",
+    "connection",
+    "host",
+}
+
+# AWS signing headers to ignore when aws_mode is enabled
+# These headers are dynamically generated and differ between requests
+DEFAULT_IGNORE_REQUEST_HEADERS_AWS: Set[str] = {
+    "authorization",
+    "x-amz-date",
+    "x-amz-security-token",
+    "x-amz-content-sha256",
+    # SDK tracking headers - change with each request
+    "amz-sdk-invocation-id",
+    "amz-sdk-request",
+    # Checksum headers - can vary between requests
+    "x-amz-checksum-crc32",
+    "x-amz-checksum-crc32c",
+    "x-amz-checksum-sha1",
+    "x-amz-checksum-sha256",
+    "x-amz-sdk-checksum-algorithm",
+    # Expect header used for large uploads
+    "expect",
+}
+
+# Default headers to exclude from recording (not saved to file)
+DEFAULT_EXCLUDE_REQUEST_HEADERS: Set[str] = {
+    "user-agent",
+    "accept-encoding",
+    "connection",
+    "host",
+}
+
+DEFAULT_EXCLUDE_RESPONSE_HEADERS: Set[str] = {
+    "date",
+    "server",
+    "x-request-id",
+    "x-correlation-id",
+    "set-cookie",
+    "transfer-encoding",
+    "content-length",
+}
+
+
+@dataclass
+class HttpTestConfig:
+    """
+    Configuration for HTTP mock decorator.
+
+    Controls how requests are matched during playback and which headers
+    are recorded/compared.
+
+    Attributes:
+        ignore_request_headers: Headers to ignore when matching requests.
+            These headers can differ between actual and recorded requests.
+            Default: User-Agent, Date, Accept-Encoding, Content-Length,
+            Connection, Host.
+
+        ignore_response_headers: Headers to ignore when comparing responses
+            (for future use in response validation).
+
+        exclude_request_headers: Headers to exclude from recordings entirely.
+            These headers won't be saved to the JSON file.
+            Default: User-Agent, Accept-Encoding, Connection, Host.
+
+        exclude_response_headers: Headers to exclude from response recordings.
+            These headers won't be saved to the JSON file.
+            Default: Date, Server, X-Request-ID, X-Correlation-ID,
+            Set-Cookie, Transfer-Encoding, Content-Length.
+
+        exclude_hosts: Hosts to exclude from recording and playback entirely.
+            Requests to these hosts will ALWAYS make real HTTP calls,
+            bypassing recording and playback. Useful for local test servers
+            like FastAPI's TestClient (host: "testserver").
+            Example: ["testserver", "localhost:8000"]
+
+        match_request_body: Whether to include request body in matching.
+            Default: True.
+
+        strict_order: Whether requests must occur in the same order as
+            recorded. Default: False.
+
+        redact_request_body: JSON fields to redact in request bodies during
+            recording. Any matching field values are replaced with "*******".
+            These fields are also ignored during request body comparison in
+            playback. Default: [].
+
+        redact_response_body: JSON fields to redact in response bodies during
+            recording. Any matching field values are replaced with "*******".
+            Default: [].
+
+    Example:
+        # Create config to ignore auth headers
+        config = HttpTestConfig(
+            ignore_request_headers=["Authorization", "X-API-Key"],
+            exclude_request_headers=["Authorization"],  # Don't save to file
+        )
+
+        @http(path="./fixtures/api.json", config=config)
+        def test_api():
+            ...
+
+        # Exclude local test server from mocking
+        config = HttpTestConfig(
+            exclude_hosts=["testserver", "localhost:8000"],
+        )
+
+        @http(path="./fixtures/api.json", config=config)
+        def test_with_fastapi():
+            # Calls to testserver go through normally (real calls)
+            # Calls to other hosts are recorded/played back
+            ...
+
+        # Or use as a pytest fixture for auto-discovery:
+        @pytest.fixture
+        def http_config() -> HttpTestConfig:
+            return HttpTestConfig(
+                ignore_request_headers=["Authorization"],
+            )
+
+        @http(path="./fixtures/api.json")  # Config auto-discovered
+        def test_api():
+            ...
+    """
+
+    # Headers to ignore when matching (can differ between actual and recorded)
+    ignore_request_headers: List[str] = field(default_factory=list)
+    ignore_response_headers: List[str] = field(default_factory=list)
+
+    # Headers to exclude from recording (not saved to file)
+    exclude_request_headers: List[str] = field(default_factory=list)
+    exclude_response_headers: List[str] = field(default_factory=list)
+
+    # Hosts to exclude from recording/playback (always make real calls)
+    exclude_hosts: List[str] = field(default_factory=list)
+
+    # Matching options
+    match_request_body: bool = True
+    strict_order: bool = False
+
+    # Redaction options
+    redact_request_body: List[str] = field(default_factory=list)
+    redact_response_body: List[str] = field(default_factory=list)
+
+    # AWS mode: automatically ignore AWS signing headers
+    aws_mode: bool = False
+
+    def get_ignore_request_headers_set(self) -> Set[str]:
+        """Get full set of headers to ignore during matching."""
+        result = DEFAULT_IGNORE_REQUEST_HEADERS.copy()
+        result.update(h.lower() for h in self.ignore_request_headers)
+        if self.aws_mode:
+            result.update(DEFAULT_IGNORE_REQUEST_HEADERS_AWS)
+        return result
+
+    def get_ignore_response_headers_set(self) -> Set[str]:
+        """Get full set of response headers to ignore during matching."""
+        return {h.lower() for h in self.ignore_response_headers}
+
+    def get_exclude_request_headers_set(self) -> Set[str]:
+        """Get full set of request headers to exclude from recording."""
+        result = DEFAULT_EXCLUDE_REQUEST_HEADERS.copy()
+        result.update(h.lower() for h in self.exclude_request_headers)
+        if self.aws_mode:
+            result.update(DEFAULT_IGNORE_REQUEST_HEADERS_AWS)
+        return result
+
+    def get_exclude_response_headers_set(self) -> Set[str]:
+        """Get full set of response headers to exclude from recording."""
+        result = DEFAULT_EXCLUDE_RESPONSE_HEADERS.copy()
+        result.update(h.lower() for h in self.exclude_response_headers)
+        return result
+
+    def get_exclude_hosts_set(self) -> Set[str]:
+        """Get set of hosts to exclude from recording/playback."""
+        return {h.lower() for h in self.exclude_hosts}
+
+    def is_host_excluded(self, url: str) -> bool:
+        """
+        Check if a URL's host is in the excluded hosts list.
+
+        Args:
+            url: Full URL string (e.g., "http://testserver/api/v1")
+
+        Returns:
+            True if the host should be excluded from recording/playback.
+        """
+        from urllib.parse import urlparse
+
+        exclude_hosts = self.get_exclude_hosts_set()
+        if not exclude_hosts:
+            return False
+
+        parsed = urlparse(url)
+        # Check both host and host:port
+        host = parsed.netloc.lower()
+        hostname = parsed.hostname.lower() if parsed.hostname else ""
+
+        return host in exclude_hosts or hostname in exclude_hosts
+
+
+# Default config instance
+DEFAULT_CONFIG = HttpTestConfig()