phlo-testing 0.2.0__tar.gz → 0.3.0__tar.gz

{phlo_testing-0.2.0 → phlo_testing-0.3.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-testing
-Version: 0.2.0
+Version: 0.3.0
 Summary: Testing utilities for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT
 Requires-Python: >=3.11
 Description-Content-Type: text/plain
 Requires-Dist: phlo>=0.1.0
+Requires-Dist: phlo-postgres>=0.1.0
 Requires-Dist: duckdb>=0.9.0
 Requires-Dist: pyarrow>=21.0.0
 Requires-Dist: pyiceberg>=0.10.0

{phlo_testing-0.2.0 → phlo_testing-0.3.0}/pyproject.toml

@@ -1,19 +1,14 @@
 [build-system]
-requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools>=45",
+    "wheel",
+]
 
 [project]
-name = "phlo-testing"
-version = "0.2.0"
-description = "Testing utilities for Phlo"
-readme = {text = "Testing utilities for Phlo.", content-type = "text/plain"}
-requires-python = ">=3.11"
-authors = [
-    {name = "Phlo Team", email = "team@phlo.dev"},
-]
-license = {text = "MIT"}
 dependencies = [
     "phlo>=0.1.0",
+    "phlo-postgres>=0.1.0",
     "duckdb>=0.9.0",
     "pyarrow>=21.0.0",
     "pyiceberg>=0.10.0",
@@ -21,25 +16,36 @@ dependencies = [
     "pandera>=0.26.1",
     "dlt>=1.18.2",
 ]
+description = "Testing utilities for Phlo"
+name = "phlo-testing"
+requires-python = ">=3.11"
+version = "0.3.0"
+
+[[project.authors]]
+email = "team@phlo.dev"
+name = "Phlo Team"
+
+[project.license]
+text = "MIT"
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
     "ruff>=0.1.0",
 ]
-dlt = [
-    "phlo-dlt>=0.1.0",
-]
-trino = [
-    "phlo-trino>=0.1.0",
-]
-
-[tool.setuptools]
-package-dir = {"" = "src"}
+dlt = ["phlo-dlt>=0.1.0"]
+trino = ["phlo-trino>=0.1.0"]
 
-[tool.setuptools.packages.find]
-where = ["src"]
+[project.readme]
+content-type = "text/plain"
+text = "Testing utilities for Phlo."
 
 [tool.ruff]
 line-length = 100
 target-version = "py311"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

{phlo_testing-0.2.0 → phlo_testing-0.3.0}/src/phlo_testing/__init__.py

@@ -341,4 +341,4 @@ __all__ = [
 if _FIXTURES_AVAILABLE:
     __all__.extend(_FIXTURE_EXPORTS)
 
-__version__ = "1.0.0"
+__version__ = "0.3.0"

phlo_testing-0.3.0/src/phlo_testing/conftest_template.py

@@ -0,0 +1,95 @@
+"""Conftest template for user projects.
+
+This module provides a ready-to-use conftest.py template that users can copy
+to their tests/ directory to get all phlo_testing fixtures automatically.
+
+The template includes:
+    - All standard phlo_testing fixtures (mock resources, test data, etc.)
+    - Environment reset fixture for test isolation
+    - Project root fixture for path resolution
+
+Usage:
+    >>> from phlo_testing.conftest_template import CONFTEST_TEMPLATE, get_conftest_template
+    >>> from pathlib import Path
+    >>> # Write template to tests/conftest.py
+    >>> Path("tests/conftest.py").write_text(get_conftest_template())
+    >>> # Or use the constant directly
+    >>> print(CONFTEST_TEMPLATE)
+
+The fixtures included in the template:
+    - mock_iceberg_catalog: Fresh MockIcebergCatalog for each test
+    - mock_trino: Fresh MockTrinoResource for each test
+    - mock_asset_context: MockAssetContext with logging capture
+    - sample_partition_date: Standard test partition date
+    - sample_dlt_data: Sample DLT source data
+    - temp_staging_dir: Temporary directory for test files
+    - And more...
+"""
+
+CONFTEST_TEMPLATE = '''"""
+Pytest configuration and shared fixtures.
+
+Place this file in tests/ directory to make fixtures available to all tests.
+"""
+
+import pytest
+from pathlib import Path
+
+# Import fixtures from phlo_testing
+from phlo_testing.fixtures import (
+    mock_iceberg_catalog,
+    mock_trino,
+    mock_asset_context,
+    mock_resources,
+    sample_partition_date,
+    sample_partition_range,
+    sample_dlt_data,
+    sample_dataframe,
+    mock_dlt_source_fixture,
+    temp_staging_dir,
+    test_data_dir,
+    setup_test_catalog,
+    setup_test_trino,
+    load_json_fixture,
+    load_csv_fixture,
+    test_config,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_test_env(monkeypatch):
+    """Reset environment variables before each test.
+
+    Ensures test isolation by setting PHLO_ENV and PHLO_LOG_LEVEL
+    before each test execution.
+
+    Args:
+        monkeypatch: pytest monkeypatch fixture.
+    """
+    monkeypatch.setenv("PHLO_ENV", "test")
+    monkeypatch.setenv("PHLO_LOG_LEVEL", "DEBUG")
+
+
+@pytest.fixture
+def project_root() -> Path:
+    """Return path to project root.
+
+    Returns:
+        Path to the project root directory (where pyproject.toml is located).
+    """
+    return Path(__file__).parent.parent
+'''
+
+
+def get_conftest_template() -> str:
+    """Get the conftest.py template content.
+
+    Returns:
+        String content for conftest.py that can be written to a file.
+
+    Example:
+        >>> template = get_conftest_template()
+        >>> Path("tests/conftest.py").write_text(template)
+
+    """
+    return CONFTEST_TEMPLATE

{phlo_testing-0.2.0 → phlo_testing-0.3.0}/src/phlo_testing/execution.py

@@ -1,5 +1,4 @@
-"""
-Helper to execute assets with mocked dependencies and capture results.
+"""Helper to execute assets with mocked dependencies and capture results.
 
 Provides `test_asset_execution()` for running `@phlo_ingestion` assets in tests
 with mocked Iceberg, Trino, and DLT dependencies.
@@ -12,6 +11,7 @@ Example:
     ... )
     >>> assert result.success
     >>> assert len(result.data) == 1
+
 """
 
 from __future__ import annotations
@@ -30,17 +30,20 @@ from phlo_testing.mock_trino import MockTrinoResource
 
 @dataclass
 class AssetTestResult:
-    """
-    Result of executing an asset in test mode.
+    """Result of executing an asset in test mode.
+
+    Encapsulates all information about an asset test execution including
+    success status, resulting data, metadata, logs, timing, and errors.
 
     Attributes:
-        success: Whether asset execution succeeded
-        data: Resulting DataFrame (if available)
-        metadata: Metadata from MaterializeResult
-        logs: Captured log messages
-        duration: Execution time in seconds
-        error: Exception if execution failed
-        raw_result: Raw Dagster ExecuteInProcessResult (advanced use)
+        success: Whether asset execution succeeded.
+        data: Resulting DataFrame (if available).
+        metadata: Metadata from MaterializeResult.
+        logs: Captured log messages.
+        duration: Execution time in seconds.
+        error: Exception if execution failed.
+        raw_result: Raw Dagster ExecuteInProcessResult (advanced use).
+
     """
 
     success: bool
@@ -53,10 +56,21 @@ class AssetTestResult:
 
 
 class MockAssetContext:
-    """
-    Mock Dagster context for asset execution.
+    """Mock Dagster context for asset execution.
+
+    Provides mocked resources (Iceberg, Trino, DLT) and logging capabilities
+    for testing assets without requiring a full Dagster environment.
+
+    Attributes:
+        partition_key: Partition identifier (e.g., "2024-01-01").
+        iceberg: MockIcebergCatalog instance for table operations.
+        trino: MockTrinoResource instance for SQL execution.
+
+    Example:
+        >>> context = MockAssetContext(partition_key="2024-01-01")
+        >>> context.log("Processing partition")
+        >>> table_store = context.get_resource("table_store")
 
-    Provides mocked resources (Iceberg, Trino, DLT) and logging.
     """
 
     def __init__(
@@ -65,13 +79,13 @@ class MockAssetContext:
         mock_iceberg: Optional[MockIcebergCatalog] = None,
         mock_trino: Optional[MockTrinoResource] = None,
     ) -> None:
-        """
-        Initialize mock context.
+        """Initialize mock context.
 
         Args:
-            partition_key: Partition identifier (e.g., "2024-01-01")
-            mock_iceberg: MockIcebergCatalog instance (creates new if None)
-            mock_trino: MockTrinoResource instance (creates new if None)
+            partition_key: Partition identifier (e.g., "2024-01-01").
+            mock_iceberg: MockIcebergCatalog instance (creates new if None).
+            mock_trino: MockTrinoResource instance (creates new if None).
+
         """
         self.partition_key = partition_key or "2024-01-01"
         self.iceberg = mock_iceberg or MockIcebergCatalog()
@@ -81,7 +95,12 @@ class MockAssetContext:
         self._logger = self._create_logger()
 
     def _create_logger(self) -> Any:
-        """Create logger that captures to self._logs."""
+        """Create logger that captures to self._logs.
+
+        Returns:
+            Logger instance with capture handler attached.
+
+        """
         name = f"asset_test_{id(self)}"
         logger = get_logger(name)
 
@@ -99,6 +118,7 @@ class MockAssetContext:
 
                 Args:
                     logs_list: Destination list for formatted log messages.
+
                 """
                 super().__init__()
                 self.logs = logs_list
@@ -108,6 +128,7 @@ class MockAssetContext:
 
                 Args:
                     record: Log record emitted by the logger.
+
                 """
                 self.logs.append(self.format(record))
 
@@ -121,12 +142,12 @@ class MockAssetContext:
         return logger
 
     def log(self, message: str, level: str = "INFO") -> None:
-        """
-        Log a message.
+        """Log a message.
 
         Args:
-            message: Message to log
-            level: Log level (DEBUG, INFO, WARNING, ERROR)
+            message: Message to log.
+            level: Log level (DEBUG, INFO, WARNING, ERROR).
+
         """
         resolved_level = level.lower()
         if resolved_level == "warn":
@@ -135,21 +156,26 @@ class MockAssetContext:
 
     @property
     def logs(self) -> list[str]:
-        """Get all captured logs."""
+        """Get all captured logs.
+
+        Returns:
+            List of formatted log messages.
+
+        """
         return self._logs.copy()
 
     def get_resource(self, name: str) -> Any:
-        """
-        Get a mock resource by name.
+        """Get a mock resource by name.
 
         Args:
-            name: Resource name (table_store, trino, etc.)
+            name: Resource name (table_store, trino, etc.).
 
         Returns:
-            Mock resource instance
+            Mock resource instance.
 
         Raises:
-            ValueError: If resource doesn't exist
+            ValueError: If resource doesn't exist.
+
         """
         resources = {
             "table_store": self.iceberg,
@@ -172,26 +198,26 @@ def test_asset_execution(
     materialize_kwargs: Optional[dict[str, Any]] = None,
     _pytest_skip: bool = True,  # Flag to prevent pytest collection
 ) -> AssetTestResult:
-    """
-    Execute an asset with mocked dependencies.
+    """Execute an asset with mocked dependencies.
 
     Runs a `@phlo_ingestion` asset in isolation with mocked Iceberg,
     Trino, and DLT services. Captures results and logs for inspection.
 
     Args:
-        asset_fn: Asset function to test
-        partition: Partition key (e.g., "2024-01-01")
-        mock_data: Mock data to return from DLT source
-        mock_iceberg: Pre-configured MockIcebergCatalog (uses new if None)
-        mock_trino: Pre-configured MockTrinoResource (uses new if None)
-        expected_schema: Pandera schema to validate results
-        materialize_kwargs: Extra kwargs to pass to materialize
+        asset_fn: Asset function to test.
+        partition: Partition key (e.g., "2024-01-01").
+        mock_data: Mock data to return from DLT source.
+        mock_iceberg: Pre-configured MockIcebergCatalog (uses new if None).
+        mock_trino: Pre-configured MockTrinoResource (uses new if None).
+        expected_schema: Pandera schema to validate results.
+        materialize_kwargs: Extra kwargs to pass to materialize.
+        _pytest_skip: Flag to prevent pytest from collecting as test.
 
     Returns:
-        AssetTestResult with execution details
+        AssetTestResult with execution details.
 
     Raises:
-        ValueError: If asset execution fails (and success=False in result)
+        ValueError: If asset execution fails (and success=False in result).
 
     Example:
         >>> @phlo_ingestion(
@@ -207,6 +233,7 @@ def test_asset_execution(
         ... )
         >>> assert result.success
         >>> assert len(result.data) == 1
+
     """
     if mock_data is None:
         mock_data = []
@@ -274,27 +301,27 @@ def test_asset_with_catalog(
     partition: str = "2024-01-01",
     catalog: Optional[MockIcebergCatalog] = None,
 ) -> AssetTestResult:
-    """
-    Execute an asset with access to mock Iceberg catalog.
+    """Execute an asset with access to mock Iceberg catalog.
 
     Useful for testing assets that read from or write to Iceberg tables.
 
     Args:
-        asset_fn: Asset function to test
-        partition: Partition key
-        catalog: Pre-configured MockIcebergCatalog
+        asset_fn: Asset function to test.
+        partition: Partition key.
+        catalog: Pre-configured MockIcebergCatalog.
 
     Returns:
-        AssetTestResult with catalog access
+        AssetTestResult with catalog access.
 
     Example:
         >>> catalog = MockIcebergCatalog()
-        >>> # ... set up tables in catalog ...
+        >>> # Set up tables in catalog
         >>> result = test_asset_with_catalog(
         ...     my_transform_asset,
         ...     partition="2024-01-01",
         ...     catalog=catalog,
         ... )
+
     """
     if catalog is None:
         catalog = MockIcebergCatalog()
@@ -311,26 +338,26 @@ def test_asset_with_trino(
     partition: str = "2024-01-01",
     trino: Optional[MockTrinoResource] = None,
 ) -> AssetTestResult:
-    """
-    Execute an asset with access to mock Trino resource.
+    """Execute an asset with access to mock Trino resource.
 
     Useful for testing quality checks and transform assets.
 
     Args:
-        asset_fn: Asset function to test
-        partition: Partition key
-        trino: Pre-configured MockTrinoResource
+        asset_fn: Asset function to test.
+        partition: Partition key.
+        trino: Pre-configured MockTrinoResource.
 
     Returns:
-        AssetTestResult with Trino access
+        AssetTestResult with Trino access.
 
     Example:
         >>> trino = MockTrinoResource()
-        >>> # ... set up tables ...
+        >>> # Set up tables in Trino
         >>> result = test_asset_with_trino(
         ...     my_quality_check,
         ...     trino=trino,
         ... )
+
     """
     if trino is None:
         trino = MockTrinoResource()
@@ -343,16 +370,21 @@ def test_asset_with_trino(
 
 
 class TestAssetExecutor:
-    """
-    Reusable executor for testing multiple asset runs.
+    """Reusable executor for testing multiple asset runs.
 
     Maintains catalog state across multiple executions for integration testing.
 
+    Attributes:
+        catalog: Shared MockIcebergCatalog instance.
+        trino: Shared MockTrinoResource instance.
+        results: List of all AssetTestResult instances from executions.
+
     Example:
         >>> executor = TestAssetExecutor()
         >>> result1 = executor.execute(asset1, partition="2024-01-01")
         >>> result2 = executor.execute(asset2, partition="2024-01-01")
         >>> # Both use same catalog instance
+
     """
 
     def __init__(
@@ -360,12 +392,12 @@ class TestAssetExecutor:
         catalog: Optional[MockIcebergCatalog] = None,
         trino: Optional[MockTrinoResource] = None,
     ) -> None:
-        """
-        Initialize executor.
+        """Initialize executor.
 
         Args:
-            catalog: Shared MockIcebergCatalog
-            trino: Shared MockTrinoResource
+            catalog: Shared MockIcebergCatalog.
+            trino: Shared MockTrinoResource.
+
         """
         self.catalog = catalog or MockIcebergCatalog()
         self.trino = trino or MockTrinoResource()
@@ -377,16 +409,16 @@ class TestAssetExecutor:
         partition: str = "2024-01-01",
         mock_data: Optional[list[dict[str, Any]]] = None,
     ) -> AssetTestResult:
-        """
-        Execute an asset with shared resources.
+        """Execute an asset with shared resources.
 
         Args:
-            asset_fn: Asset function to test
-            partition: Partition key
-            mock_data: Mock data (not used in executor mode)
+            asset_fn: Asset function to test.
+            partition: Partition key.
+            mock_data: Mock data (not used in executor mode).
 
         Returns:
-            AssetTestResult
+            AssetTestResult with execution details.
+
         """
         result = test_asset_execution(
             asset_fn,
@@ -399,14 +431,14 @@ class TestAssetExecutor:
         return result
 
     def get_results(self, asset_fn: Callable) -> list[AssetTestResult]:
-        """
-        Get results for a specific asset.
+        """Get results for a specific asset.
 
         Args:
-            asset_fn: Asset function to filter by
+            asset_fn: Asset function to filter by.
 
         Returns:
-            List of results for that asset
+            List of results for that asset.
+
         """
         # This is a simplified implementation
         # In practice, you'd track asset names