Update arg in PythonAnalysis facade

Signed-off-by: Rahul Krishna <rkrsn@ibm.com>

Author: rahlk

README.md

@@ -217,9 +217,9 @@ Each language has a dedicated analysis backend implemented under `cldk.analysis.
 > Jedi-only analysis. The CodeQL flag is part of the analysis cache key, so
 > toggling it — or upgrading from a version that defaulted it off — triggers
 > a **one-time** rebuild under a new key (no stale data is served). If you
-> instead point `analysis_backend_path` / `analysis_json_path` inside a
-> project, add those directories to your `.gitignore` — they are large and
-> environment-specific.
+> instead point `cache_dir` (the backend virtualenv / CodeQL database) or
+> `analysis_json_path` inside a project, add those directories to your
+> `.gitignore` — they are large and environment-specific.
 
 #### C
 - **Backend:** `cldk.analysis.c`  

cldk/analysis/python/codeanalyzer/codeanalyzer.py

@@ -66,8 +66,8 @@ class PyCodeanalyzer:
             :mod:`cldk.analysis.python.codeanalyzer.cache`).
         eager_analysis: If True, always re-runs the analyzer even when a
             cached analysis.json is available.
-        analysis_backend_path: Cache directory for the analyzer's virtualenv
-            and CodeQL artifacts. Forwarded to ``AnalysisOptions.cache_dir``.
+        cache_dir: Cache directory for the analyzer's virtualenv and CodeQL
+            artifacts. Forwarded verbatim to ``AnalysisOptions.cache_dir``.
             When omitted, a dependency-hash-keyed location under the CLDK
             cache root is used so the virtualenv survives source edits.
         target_files: Optional single target file (relative to project_dir).
@@ -80,7 +80,7 @@ def __init__(
         analysis_level: str,
         analysis_json_path: Union[str, Path, None],
         eager_analysis: bool,
-        analysis_backend_path: Union[str, Path, None] = None,
+        cache_dir: Union[str, Path, None] = None,
         target_files: List[str] | None = None,
         use_codeql: bool = True,
     ) -> None:
@@ -94,10 +94,10 @@ def __init__(
 
         # Cache locations. Explicit args win; otherwise fall back to the
         # content-addressed CLDK cache (two independently-keyed tiers).
-        if analysis_backend_path:
-            self.analysis_backend_path = Path(analysis_backend_path)
+        if cache_dir:
+            self.cache_dir = Path(cache_dir)
         else:
-            self.analysis_backend_path = default_backend_cache_dir(self.project_dir)
+            self.cache_dir = default_backend_cache_dir(self.project_dir)
         if analysis_json_path:
             self.analysis_json_path = Path(analysis_json_path)
         else:
@@ -106,7 +106,7 @@ def __init__(
             )
         logger.info(
             "CLDK cache — backend: %s | analysis: %s",
-            self.analysis_backend_path,
+            self.cache_dir,
             self.analysis_json_path,
         )
 
@@ -145,7 +145,7 @@ def _load_or_run_analyzer(self) -> PyApplication:
             rebuild_analysis=self.eager_analysis,
             skip_tests=True,
             file_name=target_file,
-            cache_dir=self.analysis_backend_path,
+            cache_dir=self.cache_dir,
             clear_cache=False,
             verbosity=0,
         )

cldk/analysis/python/python_analysis.py

@@ -47,8 +47,10 @@ class PythonAnalysis:
 
     Args:
         project_dir: Directory path of the project (required).
-        analysis_backend_path: Cache directory for the backend's virtualenv
-            and intermediate artifacts.
+        cache_dir: Writable directory where the ``codeanalyzer-python``
+            backend provisions its virtualenv and CodeQL database (forwarded
+            as the backend's ``cache_dir``). If None, a dependency-hash-keyed
+            location under the CLDK cache root is used.
         analysis_json_path: Directory to persist analysis.json. If None, the
             analysis is not persisted across runs.
         analysis_level: Analysis level (symbol-table or call-graph).
@@ -59,7 +61,7 @@ class PythonAnalysis:
     def __init__(
         self,
         project_dir: str | Path,
-        analysis_backend_path: str | None,
+        cache_dir: str | Path | None,
         analysis_json_path: str | Path | None,
         analysis_level: str,
         target_files: List[str] | None,
@@ -73,7 +75,7 @@ def __init__(
         self.project_dir = project_dir
         self.analysis_level = analysis_level
         self.analysis_json_path = analysis_json_path
-        self.analysis_backend_path = analysis_backend_path
+        self.cache_dir = cache_dir
         self.eager_analysis = eager_analysis
         self.target_files = target_files
         self.treesitter_python: TreesitterPython = TreesitterPython()
@@ -82,7 +84,7 @@ def __init__(
             analysis_level=analysis_level,
             analysis_json_path=analysis_json_path,
             eager_analysis=eager_analysis,
-            analysis_backend_path=analysis_backend_path,
+            cache_dir=cache_dir,
             target_files=target_files,
             use_codeql=use_codeql,
         )

cldk/core.py

@@ -61,6 +61,7 @@ def analysis(
         target_files: List[str] | None = None,
         analysis_backend_path: str | None = None,
         analysis_json_path: str | Path = None,
+        cache_dir: str | Path | None = None,
         use_codeql: bool = True,
     ) -> JavaAnalysis | PythonAnalysis | CAnalysis:
         """Initialize a language-specific analysis façade.
@@ -71,8 +72,16 @@ def analysis(
             eager (bool): If True, forces regeneration of analysis databases.
             analysis_level (str): Analysis level. See AnalysisLevel.
             target_files (list[str] | None): Files to constrain analysis (optional).
-            analysis_backend_path (str | None): Path to the analysis backend.
-            analysis_json_path (str | Path | None): Path to persist analysis database.
+            analysis_backend_path (str | None): Java only. Directory containing
+                the ``codeanalyzer-*.jar`` to run. Not valid for Python — pass
+                ``cache_dir`` instead.
+            analysis_json_path (str | Path | None): Path to persist the analysis
+                database / ``analysis.json``.
+            cache_dir (str | Path | None): Python only. Writable directory where
+                the ``codeanalyzer-python`` backend provisions its virtualenv and
+                CodeQL database (forwarded as the backend's ``cache_dir``). When
+                omitted, a dependency-hash-keyed location under the CLDK cache
+                root is used. Ignored for other languages.
             use_codeql (bool): Python only, default True. Augments Jedi-resolved
                 call edges with CodeQL-resolved edges; set False for a faster,
                 Jedi-only analysis. Ignored for other languages.
@@ -81,7 +90,9 @@ def analysis(
             JavaAnalysis | PythonAnalysis | CAnalysis: Initialized analysis façade for the chosen language.
 
         Raises:
-            CldkInitializationException: If both or neither of project_path and source_code are provided.
+            CldkInitializationException: If both or neither of project_path and
+                source_code are provided, or if the Java-only
+                ``analysis_backend_path`` is passed in Python mode.
             NotImplementedError: If the specified language is unsupported.
 
         Examples:
@@ -114,10 +125,15 @@ def analysis(
         elif self.language == "python":
             if source_code is not None:
                 raise CldkInitializationException("source_code mode is not supported for Python; please pass project_path.")
+            if analysis_backend_path is not None:
+                raise CldkInitializationException(
+                    "analysis_backend_path is Java-only (it locates codeanalyzer-*.jar). "
+                    "For Python, use cache_dir for the backend's virtualenv/CodeQL cache."
+                )
             return PythonAnalysis(
                 project_dir=project_path,
                 analysis_level=analysis_level,
-                analysis_backend_path=analysis_backend_path,
+                cache_dir=cache_dir,
                 analysis_json_path=analysis_json_path,
                 target_files=target_files,
                 eager_analysis=eager,

tests/analysis/python/test_python_analysis.py

@@ -60,3 +60,29 @@ def __init__(self, **kwargs):
     captured.clear()
     CLDK(language="python").analysis(project_path=tmp_path)
     assert captured["use_codeql"] is True
+
+
+def test_cache_dir_forwarded_through_facade(monkeypatch, tmp_path):
+    """cache_dir must reach the backend as cache_dir (not analysis_backend_path)."""
+    captured = {}
+
+    class FakeBackend:
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+
+    monkeypatch.setattr(
+        "cldk.analysis.python.python_analysis.PyCodeanalyzer", FakeBackend
+    )
+
+    cache = tmp_path / "mycache"
+    CLDK(language="python").analysis(project_path=tmp_path, cache_dir=cache)
+    assert captured["cache_dir"] == cache
+    assert "analysis_backend_path" not in captured
+
+
+def test_python_rejects_java_only_analysis_backend_path(tmp_path):
+    """analysis_backend_path is Java-only; Python mode must reject it."""
+    with pytest.raises(CldkInitializationException, match="Java-only"):
+        CLDK(language="python").analysis(
+            project_path=tmp_path, analysis_backend_path="/some/jar/dir"
+        )