deep-mock 0.1.0__tar.gz

deep_mock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deep_mock-0.1.0/PKG-INFO

@@ -0,0 +1,539 @@
+Metadata-Version: 2.4
+Name: deep-mock
+Version: 0.1.0
+Summary: A Python mocking library
+Author-email: Ogi Zmaj Dzedaj <ognjen.bozickovic@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/styoe/deep-mock
+Project-URL: Repository, https://github.com/styoe/deep-mock
+Project-URL: Issues, https://github.com/styoe/deep-mock/issues
+Keywords: mock,testing,unittest,mocking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# deep-mock
+
+A Python mocking library that simplifies patching and handles edge cases that `unittest.mock.patch` cannot solve.
+
+## The Problem
+
+Python's standard `unittest.mock.patch` has limitations:
+
+1. **You must patch at the right location** - If `module_b` imports `func` from `module_a`, you need to patch `module_b.func`, not `module_a.func`. This gets complicated with multiple imports.
+
+2. **Module-level state is not recomputed** - If a module computes values at import time using the function you're mocking, those values remain stale:
+
+```python
+# cache.py
+from database import fetch_user
+
+SYSTEM_USER = fetch_user("system")  # Computed ONCE at import time
+```
+
+Even if you patch `fetch_user`, `SYSTEM_USER` still has the original value.
+
+3. **Indirect dependencies are invisible** - If `module_c` imports from `module_b` which imports from `module_a`, patching `module_a` won't affect `module_c`'s module-level state.
+
+## The Solution
+
+`deep-mock` solves all of these problems:
+
+- **Patch once, apply everywhere** - Patches propagate to all modules that imported the mocked function
+- **Auto-reload modules** - Module-level state is automatically recomputed with mocked values
+- **Handle edge cases** - `import_and_reload_module` for indirect dependencies
+
+## Installation
+
+```bash
+pip install deep-mock
+```
+
+## Quick Start
+
+```python
+from unittest.mock import Mock
+from deep_mock import MockSysModules
+
+mock_fetch = Mock(return_value={"id": "1", "name": "Test User"})
+
+with MockSysModules([
+    ("myapp.database", "fetch_user", mock_fetch),
+]):
+    # All modules that import fetch_user now use the mock
+    # Module-level state is recomputed with the mock
+    from myapp.services import user_service
+    assert user_service.get_user("1")["name"] == "Test User"
+
+# After exiting, everything is restored to original
+```
+
+## Examples
+
+### Example 1: Simple Patching
+
+The most basic use case - mock a function and all its imports are automatically patched.
+
+```python
+from unittest.mock import Mock
+from deep_mock import MockSysModules
+
+# Create your mock
+mock_db_connect = Mock(return_value={"connected": True})
+
+# Use MockSysModules context manager
+with MockSysModules([
+    ("myapp.database", "connect", mock_db_connect),
+]):
+    from myapp.api import handler
+
+    result = handler.process_request()
+
+    # Assert the mock was called
+    mock_db_connect.assert_called_once()
+```
+
+### Example 2: Module-Level State (Direct Dependencies)
+
+When a module computes values at import time, `deep-mock` automatically reloads it.
+
+```python
+# myapp/cache.py
+from myapp.database import fetch_user
+
+# This runs ONCE at import time
+SYSTEM_USER = fetch_user("system")
+
+def get_system_user():
+    return SYSTEM_USER
+```
+
+```python
+# test_cache.py
+from unittest.mock import Mock
+from deep_mock import MockSysModules
+
+def test_system_user_is_mocked():
+    mock_fetch = Mock(return_value={"id": "system", "name": "Mock Admin"})
+
+    with MockSysModules([
+        ("myapp.database", "fetch_user", mock_fetch),
+    ]):
+        from myapp.cache import get_system_user
+
+        # SYSTEM_USER was recomputed with the mock!
+        assert get_system_user()["name"] == "Mock Admin"
+
+    # After exiting, SYSTEM_USER is restored to real value
+```
+
+### Example 3: Indirect Dependencies (Edge Case)
+
+When module C depends on module B which depends on module A, and you mock something in A:
+
+```python
+# myapp/database.py
+def fetch_user(user_id):
+    return {"id": user_id, "name": "Real User"}
+
+# myapp/cache.py
+from myapp.database import fetch_user
+SYSTEM_USER = fetch_user("system")
+
+def get_system_user():
+    return SYSTEM_USER
+
+# myapp/user_service.py
+from myapp.cache import get_system_user
+
+# Indirect dependency - imports from cache, not database
+USER_GREETING = f"Hello, {get_system_user()['name']}!"
+```
+
+```python
+# test_indirect.py
+from unittest.mock import Mock
+from deep_mock import MockSysModules, import_and_reload_module
+
+def test_indirect_dependency():
+    mock_fetch = Mock(return_value={"id": "system", "name": "Mock User"})
+
+    # Import user_service BEFORE mocking
+    from myapp import user_service
+    assert user_service.USER_GREETING == "Hello, Real User!"
+
+    with MockSysModules([
+        ("myapp.database", "fetch_user", mock_fetch),
+    ]):
+        # cache is auto-reloaded (direct dependency)
+        from myapp.cache import get_system_user
+        assert get_system_user()["name"] == "Mock User"
+
+        # user_service is NOT auto-reloaded (indirect dependency)
+        # Its USER_GREETING still has the old value!
+        assert user_service.USER_GREETING == "Hello, Real User!"
+
+        # Use import_and_reload_module to fix this
+        user_service = import_and_reload_module("myapp.user_service")
+        assert user_service.USER_GREETING == "Hello, Mock User!"
+```
+
+### Example 4: Mocking Multiple Functions
+
+```python
+from unittest.mock import Mock
+from deep_mock import MockSysModules
+
+mock_fetch = Mock(return_value={"id": "1", "name": "Test"})
+mock_save = Mock(return_value=True)
+mock_delete = Mock(return_value=True)
+
+with MockSysModules([
+    ("myapp.database", "fetch_user", mock_fetch),
+    ("myapp.database", "save_user", mock_save),
+    ("myapp.database", "delete_user", mock_delete),
+]):
+    # All three functions are mocked everywhere
+    pass
+```
+
+### Example 5: Mocking Classes
+
+```python
+from unittest.mock import Mock
+from deep_mock import MockSysModules
+
+# Create a mock class
+MockDatabaseClient = Mock()
+mock_instance = Mock()
+mock_instance.connect.return_value = {"status": "connected"}
+mock_instance.query.return_value = [{"id": 1}]
+MockDatabaseClient.return_value = mock_instance
+
+with MockSysModules([
+    ("myapp.database", "DatabaseClient", MockDatabaseClient),
+]):
+    from myapp.services import data_service
+
+    result = data_service.get_all_records()
+    MockDatabaseClient.assert_called_once()
+```
+
+## Configuration with conftest.py
+
+Set project-wide defaults in your `conftest.py`:
+
+```python
+# conftest.py
+from deep_mock import DeepMockConfig
+
+def pytest_configure(config):
+    DeepMockConfig.configure(
+        base_dir="src",  # Base directory to scan for imports
+        allowed_dirs=["src/myapp"],  # Only scan these directories
+    )
+```
+
+Now all `MockSysModules` usage will use these defaults:
+
+```python
+# test_something.py
+from deep_mock import MockSysModules
+
+# Uses conftest.py defaults automatically
+with MockSysModules([("myapp.database", "fetch_user", mock)]):
+    pass
+
+# Override for specific test if needed
+with MockSysModules(
+    [("myapp.database", "fetch_user", mock)],
+    base_dir="other_dir",
+):
+    pass
+```
+
+## Debugging Mock Calls
+
+Use the debugging utilities to inspect mock calls:
+
+```python
+from unittest.mock import Mock
+from deep_mock import MockSysModules, print_all_mock_calls, find_calls_in_mock_calls
+
+mock_db = Mock()
+
+with MockSysModules([("myapp.database", "db", mock_db)]):
+    from myapp.services import user_service
+    user_service.create_user({"name": "Alice"})
+    user_service.create_user({"name": "Bob"})
+
+    # Print all calls for debugging
+    print_all_mock_calls(mock_db)
+
+    # Find specific calls
+    save_calls = find_calls_in_mock_calls(
+        mock_db,
+        "save",
+        call_filter=lambda args, kwargs: args[0]["name"] == "Alice"
+    )
+```
+
+## API Reference
+
+### `MockSysModules`
+
+Context manager for mocking with automatic module reloading.
+
+```python
+class MockSysModules:
+    def __init__(
+        self,
+        override_modules: list[tuple[str, str, Any]] | None = None,
+        base_dir: str | None = None,
+        allowed_dirs: list[str] | None = None,
+    ):
+        """
+        Args:
+            override_modules: List of (module_name, attribute_name, mock) tuples.
+                - module_name: Full module path (e.g., "myapp.database")
+                - attribute_name: Name of the function/class to mock (e.g., "fetch_user")
+                - mock: The mock object to replace it with
+
+            base_dir: Base directory to scan for modules that import the mocked
+                attributes. Defaults to DeepMockConfig.base_dir or ".".
+
+            allowed_dirs: List of directories to limit scanning to. If None,
+                scans all directories under base_dir. Defaults to
+                DeepMockConfig.allowed_dirs.
+        """
+```
+
+**Behavior:**
+
+1. **On enter (`__enter__`):**
+   - Patches the specified attributes in the source modules
+   - Finds all loaded modules that imported these attributes
+   - Patches those modules too
+   - Reloads all affected modules so module-level state is recomputed with mocks
+
+2. **On exit (`__exit__`):**
+   - Restores all original attributes
+   - Reloads all affected modules so module-level state is recomputed with real values
+   - Also reloads modules that were imported during the context
+
+---
+
+### `mock_sys_modules`
+
+Function version of `MockSysModules`. Returns a cleanup function.
+
+```python
+def mock_sys_modules(
+    override_modules: list[tuple[str, str, Any]] | None = None,
+    base_dir: str = ".",
+    allowed_dirs: list[str] | None = None,
+) -> Callable[[], None]:
+    """
+    Apply mocks and return a cleanup function.
+
+    Args:
+        override_modules: List of (module_name, attribute_name, mock) tuples.
+        base_dir: Base directory to scan for imports.
+        allowed_dirs: Directories to limit scanning to.
+
+    Returns:
+        A cleanup function that restores original values and reloads modules.
+
+    Example:
+        cleanup = mock_sys_modules([("myapp.db", "fetch", mock)])
+        try:
+            # ... test code ...
+        finally:
+            cleanup()
+    """
+```
+
+---
+
+### `import_and_reload_module`
+
+Import a module, or reload it if already imported. Essential for handling indirect dependencies.
+
+```python
+def import_and_reload_module(module_name: str) -> ModuleType:
+    """
+    Import or reload a module, returning the module object.
+
+    This is necessary for modules with INDIRECT dependencies on mocked functions.
+    These modules import from other modules (not directly from the mocked module),
+    so they are not automatically detected and reloaded by MockSysModules.
+
+    Args:
+        module_name: Full module path (e.g., "myapp.services.user_service")
+
+    Returns:
+        The imported/reloaded module object.
+
+    Example:
+        # user_service imports from cache, which imports from database
+        # When we mock database.fetch_user, user_service is not auto-reloaded
+
+        with MockSysModules([("myapp.database", "fetch_user", mock)]):
+            # Manually reload to recompute module-level state
+            user_service = import_and_reload_module("myapp.services.user_service")
+            assert user_service.CACHED_VALUE == "mocked value"
+    """
+```
+
+**When to use:**
+
+- Module has module-level state computed from an indirect dependency
+- Module was imported before entering `MockSysModules` and has indirect dependencies
+- You need to force a reload at a specific point in your test
+
+---
+
+### `DeepMockConfig`
+
+Global configuration for `deep-mock` defaults. Configure once in `conftest.py`.
+
+```python
+class DeepMockConfig:
+    base_dir: str = "."
+    allowed_dirs: list[str] | None = None
+
+    @classmethod
+    def configure(
+        cls,
+        base_dir: str | None = None,
+        allowed_dirs: list[str] | None = None,
+    ):
+        """
+        Set default values for MockSysModules.
+
+        Args:
+            base_dir: Default base directory for scanning modules.
+            allowed_dirs: Default directories to limit scanning to.
+
+        Example:
+            # In conftest.py
+            def pytest_configure(config):
+                DeepMockConfig.configure(
+                    base_dir="src",
+                    allowed_dirs=["src/myapp", "src/lib"],
+                )
+        """
+
+    @classmethod
+    def reset(cls):
+        """Reset configuration to defaults."""
+```
+
+---
+
+### `find_calls_in_mock_calls`
+
+Filter mock call history by name and optional predicate.
+
+```python
+def find_calls_in_mock_calls(
+    mock,
+    call_name: str,
+    call_filter: Callable[[tuple, dict[str, Any]], bool] | None = None,
+) -> list[tuple[str, tuple, dict]]:
+    """
+    Find specific calls in a mock's call history.
+
+    Args:
+        mock: The mock object to inspect.
+        call_name: Name of the method call to find (e.g., "save", "().query").
+        call_filter: Optional function (args, kwargs) -> bool to filter calls.
+
+    Returns:
+        List of (call_name, args, kwargs) tuples matching the criteria.
+
+    Example:
+        # Find all 'save' calls where the first arg has status='active'
+        calls = find_calls_in_mock_calls(
+            mock_db,
+            "save",
+            call_filter=lambda args, kwargs: args[0]["status"] == "active"
+        )
+        assert len(calls) == 2
+    """
+```
+
+---
+
+### `print_all_mock_calls`
+
+Debug utility to print all calls made to a mock.
+
+```python
+def print_all_mock_calls(mock):
+    """
+    Print all calls made to a mock object for debugging.
+
+    Prints each call with:
+    - Call name (e.g., "", "().method", "().method().chain")
+    - Call args (tuple)
+    - Call kwargs (dict)
+
+    Example output:
+        --------------------------------
+             Printing all mock calls
+        --------------------------------
+        Call name   - type: <class 'str'> ().collection
+        Call args   - type: <class 'tuple'> ('users',)
+        Call kwargs - type: <class 'dict'> {}
+        --------------------------------
+    """
+```
+
+---
+
+### `fake_useless_decorator`
+
+A pass-through decorator for replacing real decorators in tests.
+
+```python
+def fake_useless_decorator(func):
+    """
+    A decorator that does nothing - just returns the function as-is.
+
+    Useful for mocking decorators that have side effects you want to avoid
+    in tests (e.g., caching, authentication, rate limiting).
+
+    Example:
+        with MockSysModules([
+            ("myapp.decorators", "require_auth", fake_useless_decorator),
+            ("myapp.decorators", "cache_result", fake_useless_decorator),
+        ]):
+            # Decorators are now no-ops
+            from myapp.api import handler
+            handler.protected_endpoint()  # No auth check
+    """
+```
+
+## License
+
+MIT