refactor(library): make cache depend on pipeline (#43)

Currently, the pipeline depends on the cache, but it should be the other
way around. We need cache to be able to import pipeline so that we
define the disk logic only once.

While there, CacheEntry -> PipelineCacheEntry for clarity.

Author: bassosimone

library/src/iqb/cache.py

@@ -25,13 +25,7 @@
 from datetime import datetime
 from pathlib import Path
 
-
-def data_dir_or_default(data_dir: str | Path | None) -> Path:
-    """
-    Return data_dir as a Path if not empty. Otherwise return the
-    default value for the data_dir (i.e., `./.iqb` like git).
-    """
-    return Path.cwd() / ".iqb" if data_dir is None else Path(data_dir)
+from . import pipeline
 
 
 class IQBCache:
@@ -45,7 +39,7 @@ def __init__(self, data_dir: str | Path | None = None):
             data_dir: Path to directory containing cached data files.
                 If None, defaults to .iqb/ in current working directory.
         """
-        self.data_dir = data_dir_or_default(data_dir)
+        self.data_dir = pipeline.data_dir_or_default(data_dir)
 
     def get_data(
         self,

library/src/iqb/pipeline.py

@@ -88,7 +88,7 @@
 from google.cloud import bigquery, bigquery_storage_v1
 from google.cloud.bigquery import job, table
 
-from . import cache, queries
+from . import queries
 
 VALID_TEMPLATE_NAMES: Final[set[str]] = {
     "downloads_by_country",
@@ -110,7 +110,7 @@ class ParsedTemplateName:
 
 
 @dataclass(frozen=True)
-class CacheEntry:
+class PipelineCacheEntry:
     """
     Reference to a cache entry containing query results and metadata.
 
@@ -232,7 +232,7 @@ def __init__(self, project_id: str, data_dir: str | Path | None = None):
         """
         self.client = bigquery.Client(project=project_id)
         self.bq_read_clnt = bigquery_storage_v1.BigQueryReadClient()
-        self.data_dir = cache.data_dir_or_default(data_dir)
+        self.data_dir = data_dir_or_default(data_dir)
 
     def _cache_dir_path(
         self,
@@ -252,7 +252,7 @@ def get_cache_entry(
         end_date: str,
         *,
         fetch_if_missing: bool = False,
-    ) -> CacheEntry:
+    ) -> PipelineCacheEntry:
         """
         Get or create a cache entry for the given query.
 
@@ -264,7 +264,7 @@ def get_cache_entry(
                 Default is False (do not fetch automatically).
 
         Returns:
-            CacheEntry with paths to data.parquet and stats.json.
+            PipelineCacheEntry with paths to data.parquet and stats.json.
 
         Raises:
             FileNotFoundError: if cache doesn't exist and fetch_if_missing is False.
@@ -282,7 +282,7 @@ def get_cache_entry(
 
         # 4. check if cache exists
         if data_path.exists() and stats_path.exists():
-            return CacheEntry(data_path=data_path, stats_path=stats_path)
+            return PipelineCacheEntry(data_path=data_path, stats_path=stats_path)
 
         # 5. handle missing cache without auto-fetching
         if not fetch_if_missing:
@@ -298,7 +298,7 @@ def get_cache_entry(
         result.save_stats()
 
         # 7. return information about the cache entry
-        return CacheEntry(data_path=data_path, stats_path=stats_path)
+        return PipelineCacheEntry(data_path=data_path, stats_path=stats_path)
 
     def execute_query_template(
         self,
@@ -360,6 +360,14 @@ def _execute_query_template(
         )
 
 
+def data_dir_or_default(data_dir: str | Path | None) -> Path:
+    """
+    Return data_dir as a Path if not empty. Otherwise return the
+    default value for the data_dir (i.e., `./.iqb` like git).
+    """
+    return Path.cwd() / ".iqb" if data_dir is None else Path(data_dir)
+
+
 def _parse_both_dates(start_date: str, end_date: str) -> tuple[datetime, datetime]:
     """Parses both dates and ensures start_date <= end_date."""
     start_time = _parse_date(start_date)

library/tests/iqb/cache_test.py

@@ -1,34 +1,10 @@
 """Tests for the IQBCache data fetching module."""
 
 from datetime import datetime
-from pathlib import Path
 
 import pytest
 
 from iqb import IQBCache
-from iqb.cache import data_dir_or_default
-
-
-class TestDataDirOrDefault:
-    """Test pure functions without external dependencies."""
-
-    def test_data_dir_or_default_with_none(self):
-        """Test default behavior when data_dir is None."""
-        result = data_dir_or_default(None)
-        expected = Path.cwd() / ".iqb"
-        assert result == expected
-
-    def test_data_dir_or_default_with_string(self, tmp_path):
-        """Test conversion of string path."""
-        test_path = str(tmp_path / "test")
-        result = data_dir_or_default(test_path)
-        assert result == Path(test_path)
-
-    def test_data_dir_or_default_with_path(self, tmp_path):
-        """Test pass-through of Path object."""
-        input_path = tmp_path / "test"
-        result = data_dir_or_default(input_path)
-        assert result == input_path
 
 
 class TestIQBCacheInitialization:

library/tests/iqb/pipeline_test.py

@@ -8,18 +8,41 @@
 import pytest
 
 from iqb.pipeline import (
-    CacheEntry,
     IQBPipeline,
     ParquetFileInfo,
     ParsedTemplateName,
+    PipelineCacheEntry,
     QueryResult,
     _load_query_template,
     _parse_both_dates,
     _parse_date,
     _parse_template_name,
+    data_dir_or_default,
 )
 
 
+class TestDataDirOrDefault:
+    """Test for data_dir_or_default function."""
+
+    def test_data_dir_or_default_with_none(self):
+        """Test default behavior when data_dir is None."""
+        result = data_dir_or_default(None)
+        expected = Path.cwd() / ".iqb"
+        assert result == expected
+
+    def test_data_dir_or_default_with_string(self, tmp_path):
+        """Test conversion of string path."""
+        test_path = str(tmp_path / "test")
+        result = data_dir_or_default(test_path)
+        assert result == Path(test_path)
+
+    def test_data_dir_or_default_with_path(self, tmp_path):
+        """Test pass-through of Path object."""
+        input_path = tmp_path / "test"
+        result = data_dir_or_default(input_path)
+        assert result == input_path
+
+
 class TestHelperFunctions:
     """Test pure functions without external dependencies."""
 
@@ -514,7 +537,7 @@ def test_save_stats_creates_directory(self, tmp_path):
         assert stats_path.exists()
 
 
-class TestIQBPipelineGetCacheEntry:
+class TestIQBPipelineGetPipelineCacheEntry:
     """Test get_cache_entry method."""
 
     @patch("iqb.pipeline.bigquery.Client")
@@ -540,7 +563,7 @@ def test_get_cache_entry_when_exists(self, mock_storage, mock_client, tmp_path):
         # Get cache entry (should not execute query)
         entry = pipeline.get_cache_entry("downloads_by_country", "2024-10-01", "2024-11-01")
 
-        assert isinstance(entry, CacheEntry)
+        assert isinstance(entry, PipelineCacheEntry)
         assert entry.data_path == cache_dir / "data.parquet"
         assert entry.stats_path == cache_dir / "stats.json"
         assert entry.data_path.exists()
@@ -608,7 +631,7 @@ def test_get_cache_entry_fetch_if_missing(self, mock_storage, mock_client, tmp_p
             mock_client_instance.query.assert_called_once()
 
             # Entry should be returned with correct paths
-            assert isinstance(entry, CacheEntry)
+            assert isinstance(entry, PipelineCacheEntry)
             expected_cache_dir = (
                 data_dir
                 / "cache"