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

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

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: phlo-testing
-Version: 0.2.3
+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.3 → phlo_testing-0.3.0}/pyproject.toml

@@ -8,6 +8,7 @@ requires = [
 [project]
 dependencies = [
     "phlo>=0.1.0",
+    "phlo-postgres>=0.1.0",
     "duckdb>=0.9.0",
     "pyarrow>=21.0.0",
     "pyiceberg>=0.10.0",
@@ -18,7 +19,7 @@ dependencies = [
 description = "Testing utilities for Phlo"
 name = "phlo-testing"
 requires-python = ">=3.11"
-version = "0.2.3"
+version = "0.3.0"
 
 [[project.authors]]
 email = "team@phlo.dev"

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

@@ -341,4 +341,4 @@ __all__ = [
 if _FIXTURES_AVAILABLE:
     __all__.extend(_FIXTURE_EXPORTS)
 
-__version__ = "0.2.3"
+__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.3 → 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

{phlo_testing-0.2.3 → phlo_testing-0.3.0}/src/phlo_testing/fixtures.py

@@ -8,6 +8,7 @@ Example:
     >>> def test_my_asset(mock_iceberg_catalog, sample_partition_date):
     ...     # Use fixtures automatically
     ...     pass
+
 """
 
 from __future__ import annotations
@@ -44,6 +45,7 @@ def mock_iceberg_catalog() -> Iterator[MockIcebergCatalog]:
         ...         "raw.users",
         ...         schema=get_schema(),
         ...     )
+
     """
     catalog = MockIcebergCatalog()
     yield catalog
@@ -61,6 +63,7 @@ def mock_trino() -> Iterator[MockTrinoResource]:
         >>> def test_with_trino(mock_trino):
         ...     cursor = mock_trino.cursor()
         ...     cursor.execute("SELECT 1 as id")
+
     """
     trino = MockTrinoResource()
     yield trino
@@ -78,6 +81,7 @@ def mock_asset_context() -> Iterator[MockAssetContext]:
         >>> def test_with_context(mock_asset_context):
         ...     context.log("test message")
         ...     assert "test message" in context.logs
+
     """
     context = MockAssetContext()
     yield context
@@ -103,6 +107,7 @@ def mock_resources(
         >>> def test_with_resources(mock_resources):
         ...     table_store = mock_resources["table_store"]
         ...     trino = mock_resources["trino"]
+
     """
     return {
         "table_store": mock_iceberg_catalog,
@@ -123,6 +128,7 @@ def sample_partition_date() -> str:
     Example:
         >>> def test_asset(sample_partition_date):
         ...     assert sample_partition_date == "2024-01-15"
+
     """
     return "2024-01-15"
 
@@ -139,6 +145,7 @@ def sample_partition_range() -> tuple[str, str]:
         ...     start, end = sample_partition_range
         ...     # start = "2024-01-01"
         ...     # end = "2024-01-31"
+
     """
     start = "2024-01-01"
     end = "2024-01-31"
@@ -155,6 +162,7 @@ def sample_dlt_data() -> list[dict[str, Any]]:
     Example:
         >>> def test_ingestion(sample_dlt_data):
         ...     source = mock_dlt_source(sample_dlt_data)
+
     """
     return [
         {
@@ -186,6 +194,7 @@ def sample_dataframe() -> pd.DataFrame:
     Example:
         >>> def test_transform(sample_dataframe):
         ...     assert len(sample_dataframe) == 3
+
     """
     return pd.DataFrame(
         {
@@ -206,6 +215,7 @@ def mock_dlt_source_fixture(sample_dlt_data: list[dict]) -> MockDLTResource:
         >>> def test_with_source(mock_dlt_source_fixture):
         ...     for record in mock_dlt_source_fixture:
         ...         # Process record
+
     """
     return mock_dlt_source(sample_dlt_data, resource_name="test_data")
 
@@ -224,6 +234,7 @@ def temp_staging_dir() -> Iterator[Path]:
         >>> def test_with_temp_dir(temp_staging_dir):
         ...     parquet_file = temp_staging_dir / "data.parquet"
         ...     df.to_parquet(parquet_file)
+
     """
     with tempfile.TemporaryDirectory() as tmpdir:
         yield Path(tmpdir)
@@ -239,6 +250,7 @@ def test_data_dir() -> Path:
     Example:
         >>> def test_with_data_dir(test_data_dir):
         ...     data_file = test_data_dir / "users.json"
+
     """
     # Find project root by looking for pyproject.toml
     current = Path(__file__).parent
@@ -267,6 +279,7 @@ def setup_test_catalog(
     Example:
         >>> def test_with_setup_catalog(setup_test_catalog):
         ...     table = setup_test_catalog.load_table("raw.users")
+
     """
     from pyiceberg.schema import Schema
     from pyiceberg.types import DoubleType, IntegerType, NestedField, StringType
@@ -298,6 +311,7 @@ def setup_test_trino(
         >>> def test_with_setup_trino(setup_test_trino):
         ...     cursor = setup_test_trino.cursor()
         ...     cursor.execute("SELECT * FROM test.sample_data")
+
     """
     mock_trino.load_table("test.sample_data", sample_dataframe)
     return mock_trino
@@ -314,6 +328,7 @@ def load_json_fixture(test_data_dir: Path) -> Callable[[str], Any]:
     Example:
         >>> def test_with_json(load_json_fixture):
         ...     data = load_json_fixture("users.json")
+
     """
 
     def _load_json(filename: str) -> Any:
@@ -335,6 +350,7 @@ def load_csv_fixture(test_data_dir: Path) -> Callable[[str], pd.DataFrame]:
     Example:
         >>> def test_with_csv(load_csv_fixture):
         ...     df = load_csv_fixture("users.csv")
+
     """
 
     def _load_csv(filename: str) -> pd.DataFrame:
@@ -360,6 +376,7 @@ def test_config() -> dict[str, Any]:
     Example:
         >>> def test_with_config(test_config, monkeypatch):
         ...     monkeypatch.setenv("PHLO_ENV", "test")
+
     """
     return {
         "environment": "test",
@@ -381,6 +398,7 @@ def session_temp_dir() -> Iterator[Path]:
     Example:
         >>> def test_with_session_dir(session_temp_dir):
         ...     # Shared across all tests in session
+
     """
     with tempfile.TemporaryDirectory() as tmpdir:
         yield Path(tmpdir)
@@ -396,6 +414,7 @@ def session_catalog() -> Iterator[MockIcebergCatalog]:
     Example:
         >>> def test_with_session_catalog(session_catalog):
         ...     # Shared across all tests
+
     """
     catalog = MockIcebergCatalog()
     yield catalog
@@ -420,6 +439,7 @@ def create_partition_dates(start: str, end: str, step_days: int = 1) -> list[str
     Example:
         >>> dates = create_partition_dates("2024-01-01", "2024-01-31", step_days=7)
         >>> # ["2024-01-01", "2024-01-08", "2024-01-15", ...]
+
     """
     start_dt = datetime.fromisoformat(start)
     end_dt = datetime.fromisoformat(end)
@@ -443,5 +463,6 @@ def conftest_template() -> str:
 
     Returns:
         String content for conftest.py
+
     """
     return get_conftest_template()