feat!: use consistent function/arg names

README.md

@@ -23,7 +23,7 @@ DGIpy is built around query methods that wrap a GraphQL client and fetch data fr
 
 ```pycon
 >>> from dgipy import get_drug
->>> results = get_gene(["BRAF"])
+>>> results = get_genes(["BRAF"])
 >>> results["name"][0], results["concept_id"][0], results["aliases"][0][:5]
 ('BRAF', 'hgnc:1097', ['B-RAF PROTO-ONCOGENE, SERINE/THREONINE KINASE', 'BRAF1', 'BRAF-1', 'UCSC:UC003VWC.5', 'VEGA:OTTHUMG00000157457'])
 ```

src/dgipy/__init__.py

@@ -2,25 +2,25 @@
 
 from .dgidb import (
     SourceType,
+    get_all_genes,
     get_categories,
     get_clinical_trials,
-    get_drug,
     get_drug_applications,
-    get_gene,
-    get_gene_list,
+    get_drugs,
+    get_genes,
     get_interactions,
-    get_source,
+    get_sources,
 )
 from .graph_app import generate_app
 
 __all__ = [
-    "get_drug",
-    "get_gene",
+    "get_drugs",
+    "get_genes",
     "get_interactions",
     "get_categories",
-    "get_source",
+    "get_sources",
     "SourceType",
-    "get_gene_list",
+    "get_all_genes",
     "get_drug_applications",
     "generate_app",
     "get_clinical_trials",

src/dgipy/dgidb.py

@@ -45,23 +45,20 @@ def _backfill_dicts(col: list[dict]) -> list[dict]:
     return [{key: cell.get(key) for key in keys} for cell in col]
 
 
-def get_drug(
-    terms: list | str,
+def get_drugs(
+    terms: list,
     immunotherapy: bool | None = None,
     antineoplastic: bool | None = None,
     api_url: str | None = None,
 ) -> dict:
     """Perform a record look up in DGIdb for a drug of interest
 
-    :param terms: drug or drugs for record lookup
+    :param terms: drugs for record lookup
     :param immunotherapy: filter option for results that are only immunotherapy
     :param antineoplastic: filter option for results that see antineoplastic use
     :param api_url: API endpoint for GraphQL request
     :return: drug data
     """
-    if isinstance(terms, str):
-        terms = [terms]
-
     params: dict[str, bool | list] = {"names": terms}
     if immunotherapy is not None:
         params["immunotherapy"] = immunotherapy
@@ -104,16 +101,13 @@ def get_drug(
     return output
 
 
-def get_gene(terms: list | str, api_url: str | None = None) -> dict:
-    """Perform a record look up in DGIdb for a gene of interest
+def get_genes(terms: list, api_url: str | None = None) -> dict:
+    """Perform a record look up in DGIdb for genes of interest
 
-    :param terms: gene or genes for record lookup
+    :param terms: genes for record lookup
     :param api_url: API endpoint for GraphQL request
     :return: gene data
     """
-    if isinstance(terms, str):
-        terms = [terms]
-
     api_url = api_url if api_url else API_ENDPOINT_URL
     client = _get_client(api_url)
     result = client.execute(queries.get_genes.query, variable_values={"names": terms})
@@ -134,7 +128,7 @@ def get_gene(terms: list | str, api_url: str | None = None) -> dict:
 
 
 def get_interactions(
-    terms: list | str,
+    terms: list,
     search: str = "genes",
     immunotherapy: bool | None = None,
     antineoplastic: bool | None = None,
@@ -157,8 +151,6 @@ def get_interactions(
     :param api_url: API endpoint for GraphQL request
     :return: interaction results for terms
     """
-    if isinstance(terms, str):
-        terms = [terms]
     params: dict[str, str | int | bool | list[str]] = {"names": terms}
     if immunotherapy is not None:
         params["immunotherapy"] = immunotherapy
@@ -259,16 +251,13 @@ def _get_interactions_by_drugs(
     return output
 
 
-def get_categories(terms: list | str, api_url: str | None = None) -> dict:
+def get_categories(terms: list, api_url: str | None = None) -> dict:
     """Perform a category annotation lookup for genes of interest
 
     :param terms: Genes of interest for annotations
     :param api_url: API endpoint for GraphQL request
     :return: category annotation results for genes
     """
-    if isinstance(terms, str):
-        terms = [terms]
-
     api_url = api_url if api_url else API_ENDPOINT_URL
     client = _get_client(api_url)
     results = client.execute(
@@ -300,7 +289,7 @@ class SourceType(str, Enum):
     POTENTIALLY_DRUGGABLE = "potentially_druggable"
 
 
-def get_source(
+def get_sources(
     source_type: SourceType | None = None, api_url: str | None = None
 ) -> dict:
     """Perform a source lookup for relevant aggregate sources
@@ -336,7 +325,7 @@ def get_source(
     return output
 
 
-def get_gene_list(api_url: str | None = None) -> dict:
+def get_all_genes(api_url: str | None = None) -> dict:
     """Get all gene names present in DGIdb
 
     :param api_url: API endpoint for GraphQL request
@@ -352,7 +341,7 @@ def get_gene_list(api_url: str | None = None) -> dict:
     return genes
 
 
-def get_drug_list(api_url: str | None = None) -> dict:
+def get_all_drugs(api_url: str | None = None) -> dict:
     """Get all drug names present in DGIdb
 
     :param api_url: API endpoint for GraphQL request
@@ -388,16 +377,13 @@ def _get_openfda_data(app_no: str) -> list[tuple]:
     ]
 
 
-def get_drug_applications(terms: list | str, api_url: str | None = None) -> dict:
+def get_drug_applications(terms: list, api_url: str | None = None) -> dict:
     """Perform a look up for ANDA/NDA applications for drug or drugs of interest
 
-    :param terms: drug or drugs of interest
+    :param terms: drugs of interest
     :param api_url: API endpoint for GraphQL request
     :return: all ANDA/NDA applications for drugs of interest
     """
-    if isinstance(terms, str):
-        terms = [terms]
-
     api_url = api_url if api_url else API_ENDPOINT_URL
     client = _get_client(api_url)
     results = client.execute(
@@ -432,19 +418,14 @@ def get_drug_applications(terms: list | str, api_url: str | None = None) -> dict
     return output
 
 
-def get_clinical_trials(
-    terms: str | list,
-) -> dict:
+def get_clinical_trials(terms: list) -> dict:
     """Perform a look up for clinical trials data for drug or drugs of interest
 
-    :param terms: drug or drugs of interest
+    :param terms: drugs of interest
     :return: all clinical trials data for drugs of interest in a DataFrame
     """
     base_url = "https://clinicaltrials.gov/api/v2/studies?format=json"
 
-    if isinstance(terms, str):
-        terms = [terms]
-
     output = {
         "search_term": [],
         "trial_id": [],

src/dgipy/graph_app.py

@@ -16,11 +16,11 @@ def generate_app() -> dash.Dash:
     """
     genes = [
         {"label": gene["name"], "value": gene["name"]}
-        for gene in make_tabular(dgidb.get_gene_list())
+        for gene in make_tabular(dgidb.get_all_genes())
     ]
     drugs = [
         {"label": drug["name"], "value": drug["name"]}
-        for drug in make_tabular(dgidb.get_drug_list())
+        for drug in make_tabular(dgidb.get_all_drugs())
     ]
 
     app = dash.Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])

src/dgipy/vcf.py

@@ -42,7 +42,7 @@ def __init__(self, data: list) -> None:
                 list(self.interactions["drug"].values)
             )
 
-        self.gene_info = dgipy.get_gene(self.gene)
+        self.gene_info = dgipy.get_genes(self.gene)
         self.categories = dgipy.get_categories(self.gene)
 
 

tests/test_dgidb.py

@@ -7,13 +7,13 @@
 
 from dgipy.dgidb import (
     SourceType,
+    get_all_genes,
     get_categories,
-    get_drug,
     get_drug_applications,
-    get_gene,
-    get_gene_list,
+    get_drugs,
+    get_genes,
     get_interactions,
-    get_source,
+    get_sources,
 )
 
 
@@ -27,30 +27,32 @@ def test_get_drugs(fixtures_dir: Path, set_up_graphql_mock: Callable):
     ):
         set_up_graphql_mock(m, json_response)
 
-        results = get_drug(["Imatinib"])
+        results = get_drugs(["Imatinib"])
         assert len(results["name"]), "DataFrame is non-empty"
 
-        results_with_added_fake = get_drug(["imatinib", "not-real"])
+        results_with_added_fake = get_drugs(["imatinib", "not-real"])
         assert len(results_with_added_fake["name"]) == len(
             results["name"]
         ), "Gracefully ignore non-existent search terms"
 
         # handling filters
-        filtered_results = get_drug(["imatinib", "metronidazole"], antineoplastic=True)
+        filtered_results = get_drugs(["imatinib", "metronidazole"], antineoplastic=True)
         assert len(filtered_results["name"]) == 1, "Metronidazole is filtered out"
         assert (
             filtered_results["name"][0] == "IMATINIB"
         ), "Imatinib is retained by the filter"
         assert all(results["antineoplastic"]), "All results are antineoplastics"
 
         set_up_graphql_mock(m, filtered_json_response)
-        filtered_results = get_drug(["imatinib", "metronidazole"], antineoplastic=False)
+        filtered_results = get_drugs(
+            ["imatinib", "metronidazole"], antineoplastic=False
+        )
         assert len(filtered_results["name"]), "DataFrame is non-empty"
         assert "METRONIDAZOLE" in filtered_results["name"]
 
         # empty response
         set_up_graphql_mock(m, StringIO('{"data": {"drugs": {"nodes": []}}}'))
-        empty_results = get_drug("not-real")
+        empty_results = get_drugs("not-real")
         assert len(empty_results["name"]) == 0, "Handles empty response"
 
 
@@ -61,17 +63,17 @@ def test_get_genes(fixtures_dir: Path, set_up_graphql_mock: Callable):
     ):
         set_up_graphql_mock(m, json_response)
 
-        results = get_gene(["ereg"])
+        results = get_genes(["ereg"])
         assert len(results["name"]), "DataFrame is non-empty"
 
-        results_with_added_fake = get_gene(["ereg", "not-real"])
+        results_with_added_fake = get_genes(["ereg", "not-real"])
         assert len(results_with_added_fake["name"]) == len(
             results["name"]
         ), "Gracefully ignore non-existent search terms"
 
         # empty response
         set_up_graphql_mock(m, StringIO('{"data": {"genes": {"nodes": []}}}'))
-        empty_results = get_gene("not-real")
+        empty_results = get_genes("not-real")
         assert len(empty_results["name"]) == 0, "Handles empty response"
 
 
@@ -159,13 +161,13 @@ def test_get_sources(fixtures_dir: Path, set_up_graphql_mock: Callable):
         ).open() as filtered_sources_response,
     ):
         set_up_graphql_mock(m, sources_response)
-        results = get_source()
+        results = get_sources()
         assert (
             len(results["name"]) == 45
         ), f"Incorrect # of sources: {len(results['name'])}"
 
         set_up_graphql_mock(m, filtered_sources_response)
-        results = get_source(SourceType.GENE)
+        results = get_sources(SourceType.GENE)
         sources = results["name"]
         assert len(sources) == 3, f"Incorrect # of sources: {len(sources)}"
         assert set(sources) == {
@@ -185,7 +187,7 @@ def test_get_gene_list(fixtures_dir: Path, set_up_graphql_mock: Callable):
     ):
         set_up_graphql_mock(m, gene_list_response)
 
-        results = get_gene_list()
+        results = get_all_genes()
         assert len(results["name"]) == 9