Merge pull request #904 from mandeepsingh2007/GH903-api-introspection

Add describe_api() method for API introspection (#903)

Author: jonbrenas

malariagen_data/anoph/describe.py

@@ -0,0 +1,115 @@
+import inspect
+from typing import Optional
+
+import pandas as pd
+from numpydoc_decorator import doc  # type: ignore
+
+from .base import AnophelesBase
+
+
+class AnophelesDescribe(AnophelesBase):
+    """Mixin class providing API introspection and discovery functionality."""
+
+    @doc(
+        summary="""
+            List all available public API methods with their descriptions.
+        """,
+        returns="""
+            A dataframe with one row per public method, containing the method
+            name, a short summary description, and its category (data access,
+            analysis, or plotting).
+        """,
+        parameters=dict(
+            category="""
+                Optional filter to show only methods of a given category.
+                Supported values are "data", "analysis", "plot", or None to
+                show all methods.
+            """,
+        ),
+    )
+    def describe_api(
+        self,
+        category: Optional[str] = None,
+    ) -> pd.DataFrame:
+        methods_info = []
+
+        # Walk through all public methods on this instance.
+        for name in sorted(dir(self)):
+            # Skip private/dunder methods.
+            if name.startswith("_"):
+                continue
+
+            attr = getattr(type(self), name, None)
+            if attr is None:
+                continue
+
+            # Only include callable methods and non-property attributes.
+            if isinstance(attr, property):
+                continue
+            if not callable(attr):
+                continue
+
+            # Extract the docstring summary.
+            summary = self._extract_summary(attr)
+
+            # Determine category.
+            method_category = self._categorize_method(name)
+
+            methods_info.append(
+                {
+                    "method": name,
+                    "summary": summary,
+                    "category": method_category,
+                }
+            )
+
+        df = pd.DataFrame(methods_info)
+
+        # Apply category filter if specified.
+        if category is not None:
+            valid_categories = {"data", "analysis", "plot"}
+            if category not in valid_categories:
+                raise ValueError(
+                    f"Invalid category: {category!r}. "
+                    f"Must be one of {valid_categories}."
+                )
+            df = df[df["category"] == category].reset_index(drop=True)
+
+        return df
+
+    @staticmethod
+    def _extract_summary(method) -> str:
+        """Extract the first line of the docstring as a summary."""
+        docstring = inspect.getdoc(method)
+        if not docstring:
+            return ""
+        # Take the first non-empty line as the summary.
+        for line in docstring.strip().splitlines():
+            line = line.strip()
+            if line:
+                return line
+        return ""
+
+    @staticmethod
+    def _categorize_method(name: str) -> str:
+        """Categorize a method based on its name."""
+        if name.startswith("plot_"):
+            return "plot"
+        data_prefixes = (
+            "sample_",
+            "snp_",
+            "hap_",
+            "cnv_",
+            "genome_",
+            "open_",
+            "lookup_",
+            "read_",
+            "general_",
+            "sequence_",
+            "cohorts_",
+            "aim_",
+            "gene_",
+        )
+        if name.startswith(data_prefixes):
+            return "data"
+        return "analysis"

malariagen_data/anopheles.py

@@ -44,6 +44,7 @@
 from .anoph.phenotypes import AnophelesPhenotypeData
 from .mjn import _median_joining_network, _mjn_graph
 from .anoph.hapclust import AnophelesHapClustAnalysis
+from .anoph.describe import AnophelesDescribe
 from .anoph.dipclust import AnophelesDipClustAnalysis
 from .util import (
     CacheMiss,
@@ -95,6 +96,7 @@ class AnophelesDataResource(
     AnophelesSampleMetadata,
     AnophelesGenomeFeaturesData,
     AnophelesGenomeSequenceData,
+    AnophelesDescribe,
     AnophelesBase,
     AnophelesPhenotypeData,
 ):

tests/anoph/test_describe.py

@@ -0,0 +1,127 @@
+import pandas as pd
+import pytest
+from pytest_cases import parametrize_with_cases
+
+from malariagen_data import af1 as _af1
+from malariagen_data import ag3 as _ag3
+from malariagen_data.anoph.describe import AnophelesDescribe
+
+
+@pytest.fixture
+def ag3_sim_api(ag3_sim_fixture):
+    return AnophelesDescribe(
+        url=ag3_sim_fixture.url,
+        public_url=ag3_sim_fixture.url,
+        config_path=_ag3.CONFIG_PATH,
+        major_version_number=_ag3.MAJOR_VERSION_NUMBER,
+        major_version_path=_ag3.MAJOR_VERSION_PATH,
+        pre=True,
+    )
+
+
+@pytest.fixture
+def af1_sim_api(af1_sim_fixture):
+    return AnophelesDescribe(
+        url=af1_sim_fixture.url,
+        public_url=af1_sim_fixture.url,
+        config_path=_af1.CONFIG_PATH,
+        major_version_number=_af1.MAJOR_VERSION_NUMBER,
+        major_version_path=_af1.MAJOR_VERSION_PATH,
+        pre=False,
+    )
+
+
+def case_ag3_sim(ag3_sim_fixture, ag3_sim_api):
+    return ag3_sim_fixture, ag3_sim_api
+
+
+def case_af1_sim(af1_sim_fixture, af1_sim_api):
+    return af1_sim_fixture, af1_sim_api
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_returns_dataframe(fixture, api):
+    """Test that describe_api returns a DataFrame with expected columns."""
+    df = api.describe_api()
+    assert isinstance(df, pd.DataFrame)
+    assert "method" in df.columns
+    assert "summary" in df.columns
+    assert "category" in df.columns
+    assert len(df) > 0
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_no_private_methods(fixture, api):
+    """Test that describe_api does not include private or dunder methods."""
+    df = api.describe_api()
+    for method_name in df["method"]:
+        assert not method_name.startswith(
+            "_"
+        ), f"Private method {method_name!r} should not appear in describe_api output"
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_category_filter(fixture, api):
+    """Test filtering by category."""
+    for category in ("data", "analysis", "plot"):
+        df = api.describe_api(category=category)
+        assert isinstance(df, pd.DataFrame)
+        if len(df) > 0:
+            assert all(df["category"] == category)
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_invalid_category(fixture, api):
+    """Test that an invalid category raises ValueError."""
+    with pytest.raises(ValueError, match="Invalid category"):
+        api.describe_api(category="invalid")
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_known_methods(fixture, api):
+    """Test that some known methods appear in the output."""
+    df = api.describe_api()
+    method_names = set(df["method"])
+    # These methods should exist on AnophelesDescribe (inherited from AnophelesBase).
+    assert "describe_api" in method_names
+    assert "sample_sets" in method_names
+
+
+@parametrize_with_cases("fixture,api", cases=".")
+def test_describe_api_summaries_not_empty(fixture, api):
+    """Test that at least some methods have non-empty summaries."""
+    df = api.describe_api()
+    non_empty = df[df["summary"] != ""]
+    assert len(non_empty) > 0, "Expected at least some methods to have summaries"
+
+
+def test_categorize_method():
+    """Test the static _categorize_method helper."""
+    assert AnophelesDescribe._categorize_method("plot_pca") == "plot"
+    assert AnophelesDescribe._categorize_method("plot_heterozygosity") == "plot"
+    assert AnophelesDescribe._categorize_method("sample_metadata") == "data"
+    assert AnophelesDescribe._categorize_method("snp_calls") == "data"
+    assert AnophelesDescribe._categorize_method("genome_sequence") == "data"
+    assert AnophelesDescribe._categorize_method("lookup_release") == "data"
+    assert AnophelesDescribe._categorize_method("diversity_stats") == "analysis"
+    assert AnophelesDescribe._categorize_method("cohort_diversity_stats") == "analysis"
+
+
+def test_extract_summary():
+    """Test the static _extract_summary helper."""
+
+    def dummy_func():
+        """This is a test summary.
+
+        More details here.
+        """
+        pass
+
+    summary = AnophelesDescribe._extract_summary(dummy_func)
+    assert summary == "This is a test summary."
+
+    def no_doc_func():
+        pass
+
+    summary = AnophelesDescribe._extract_summary(no_doc_func)
+    assert summary == ""