feat(types): pay down mypy errors (var-annotated + json overloads)

.pre-commit-config.yaml

@@ -26,6 +26,7 @@ exclude: |
     | gget/constants/
     | tests/fixtures/
     | tests/pytest_results.*\.txt
+    | \.github/badges/.*\.json
   )
 repos:
   - repo: https://github.com/biomejs/pre-commit

gget/gget_8cube.py

@@ -2,7 +2,7 @@
 
 import io
 import json as json_package
-from typing import Any
+from typing import Any, Literal, overload
 
 import pandas as pd
 import requests
@@ -54,12 +54,30 @@ def _normalize_gene_list(gene_list: list[str] | tuple[str, ...]) -> list[str]:
 # --------------------------------------------------------------------
 # 1. SPECIFICITY
 # --------------------------------------------------------------------
+@overload
+def specificity(
+    gene_list: list[str] | tuple[str, ...],
+    json: Literal[False] = False,
+    save: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame: ...
+
+
+@overload
+def specificity(
+    gene_list: list[str] | tuple[str, ...],
+    json: Literal[True],
+    save: bool = False,
+    verbose: bool = True,
+) -> list[dict[str, Any]]: ...
+
+
 def specificity(
     gene_list: list[str] | tuple[str, ...],
     json: bool = False,
     save: bool = False,
     verbose: bool = True,
-) -> Any:
+) -> pd.DataFrame | list[dict[str, Any]]:
     """Retrieve gene-level specificity statistics from the 8cubeDB.
 
     (https://eightcubedb.onrender.com/).
@@ -126,14 +144,36 @@ def specificity(
 # --------------------------------------------------------------------
 # 2. PSI BLOCK
 # --------------------------------------------------------------------
+@overload
+def psi_block(
+    gene_list: list[str] | tuple[str, ...],
+    analysis_level: str,
+    analysis_type: str,
+    json: Literal[False] = False,
+    save: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame: ...
+
+
+@overload
+def psi_block(
+    gene_list: list[str] | tuple[str, ...],
+    analysis_level: str,
+    analysis_type: str,
+    json: Literal[True],
+    save: bool = False,
+    verbose: bool = True,
+) -> list[dict[str, Any]]: ...
+
+
 def psi_block(
     gene_list: list[str] | tuple[str, ...],
     analysis_level: str,
     analysis_type: str,
     json: bool = False,
     save: bool = False,
     verbose: bool = True,
-) -> Any:
+) -> pd.DataFrame | list[dict[str, Any]]:
     """Retrieve ψ_block (psi-block) specificity scores from the 8cubeDB.
 
     ψ_block quantifies the specificity of a gene to a particular block
@@ -194,14 +234,36 @@ def psi_block(
 # --------------------------------------------------------------------
 # 3. GENE EXPRESSION
 # --------------------------------------------------------------------
+@overload
+def gene_expression(
+    gene_list: list[str] | tuple[str, ...],
+    analysis_level: str,
+    analysis_type: str,
+    json: Literal[False] = False,
+    save: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame: ...
+
+
+@overload
+def gene_expression(
+    gene_list: list[str] | tuple[str, ...],
+    analysis_level: str,
+    analysis_type: str,
+    json: Literal[True],
+    save: bool = False,
+    verbose: bool = True,
+) -> list[dict[str, Any]]: ...
+
+
 def gene_expression(
     gene_list: list[str] | tuple[str, ...],
     analysis_level: str,
     analysis_type: str,
     json: bool = False,
     save: bool = False,
     verbose: bool = True,
-) -> Any:
+) -> pd.DataFrame | list[dict[str, Any]]:
     """Retrieve normalized gene expression values from 8cubeDB.
 
     This endpoint returns mean and variance of normalized expression for the

gget/gget_archs4.py

@@ -2,7 +2,7 @@
 
 import io
 import json as json_package
-from typing import Any
+from typing import Any, Literal, overload
 
 import pandas as pd
 import requests
@@ -17,6 +17,32 @@
 from .gget_info import info  # noqa: E402
 
 
+@overload
+def archs4(
+    gene: str,
+    ensembl: bool = False,
+    which: str = "correlation",
+    gene_count: int = 100,
+    species: str = "human",
+    json: Literal[True] = ...,
+    save: bool = False,
+    verbose: bool = True,
+) -> list[dict[str, Any]] | None: ...
+
+
+@overload
+def archs4(
+    gene: str,
+    ensembl: bool = False,
+    which: str = "correlation",
+    gene_count: int = 100,
+    species: str = "human",
+    json: Literal[False] = False,
+    save: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame | None: ...
+
+
 def archs4(
     gene: str,
     ensembl: bool = False,

gget/gget_bgee.py

@@ -2,7 +2,7 @@
 
 import json as json_
 from importlib.metadata import PackageNotFoundError, version
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 from .utils import dig, http_json, json_list_to_df, set_up_logger
 
@@ -180,13 +180,41 @@ def _bgee_expression(gene_id: str | list[str], json: bool = False, verbose: bool
         return df
 
 
+@overload
+def bgee(
+    gene_id: str | list[str],
+    type: str,
+    json: Literal[True],
+    verbose: bool = ...,
+) -> list[dict[str, Any]]: ...
+
+
+@overload
+def bgee(
+    gene_id: str | list[str],
+    type: str = ...,
+    *,
+    json: Literal[True],
+    verbose: bool = ...,
+) -> list[dict[str, Any]]: ...
+
+
+@overload
+def bgee(
+    gene_id: str | list[str],
+    type: str = ...,
+    json: Literal[False] = False,
+    verbose: bool = ...,
+) -> pd.DataFrame: ...
+
+
 # noinspection PyShadowingBuiltins
 def bgee(
     gene_id: str | list[str],
     type: str = "orthologs",
     json: bool = False,
     verbose: bool = True,
-) -> pd.DataFrame | Any:
+) -> pd.DataFrame | list[dict[str, Any]]:
     """Get orthologs/expression data for a gene from Bgee (https://www.bgee.org/).
 
     Args:

gget/gget_blast.py

@@ -3,7 +3,7 @@
 import json as json_package
 import time
 from io import StringIO
-from typing import Any
+from typing import Any, Literal, overload
 from urllib.parse import urlencode
 
 # Using urllib instead of requests here because requests does not
@@ -25,6 +25,39 @@
 )
 
 
+@overload
+def blast(
+    sequence: str,
+    program: str = "default",
+    database: str = "default",
+    limit: int = 50,
+    expect: float = 10.0,
+    low_comp_filt: bool = False,
+    megablast: bool = True,
+    verbose: bool = True,
+    wrap_text: bool = False,
+    *,
+    json: Literal[True],
+    save: bool = False,
+) -> list[dict[str, Any]] | None: ...
+
+
+@overload
+def blast(
+    sequence: str,
+    program: str = "default",
+    database: str = "default",
+    limit: int = 50,
+    expect: float = 10.0,
+    low_comp_filt: bool = False,
+    megablast: bool = True,
+    verbose: bool = True,
+    wrap_text: bool = False,
+    json: Literal[False] = False,
+    save: bool = False,
+) -> pd.DataFrame | None: ...
+
+
 def blast(
     sequence: str,
     program: str = "default",

gget/gget_blat.py

@@ -3,7 +3,7 @@
 import json as json_package
 import time
 from json.decoder import JSONDecodeError
-from typing import Any
+from typing import Any, Literal, overload
 from urllib import request
 from urllib.error import HTTPError, URLError
 
@@ -18,6 +18,28 @@
 _BLAT_BACKOFF_BASE_SECONDS = 1.5
 
 
+@overload
+def blat(
+    sequence: str,
+    seqtype: str = ...,
+    assembly: str = ...,
+    json: Literal[True] = ...,
+    save: bool = ...,
+    verbose: bool = ...,
+) -> list[dict[str, Any]] | None: ...
+
+
+@overload
+def blat(
+    sequence: str,
+    seqtype: str = ...,
+    assembly: str = ...,
+    json: Literal[False] = ...,
+    save: bool = ...,
+    verbose: bool = ...,
+) -> pd.DataFrame | None: ...
+
+
 def blat(
     sequence: str,
     seqtype: str = "default",
@@ -133,7 +155,7 @@ def blat(
 
     ## Build data frame to resemble BLAT web search results
     # Define dataframe from dictionary
-    df_dict = {}
+    df_dict: dict[str, list[Any]] = {}
 
     for field in results["fields"]:
         df_dict.update({field: []})

gget/gget_cosmic.py

@@ -9,7 +9,7 @@
 import shutil
 import subprocess
 import tarfile
-from typing import Any
+from typing import Any, Literal, overload
 
 import pandas as pd
 
@@ -315,6 +315,53 @@ def match_and_limit(mask, extract_fn):
     return results
 
 
+@overload
+def cosmic(
+    searchterm: str | None,
+    cosmic_tsv_path: str | None = None,
+    limit: int = 100,
+    *,
+    json: Literal[True],
+    download_cosmic: bool = False,
+    cosmic_project: str | None = None,
+    cosmic_version: int | None = None,
+    grch_version: int = 37,
+    email: str | None = None,
+    password: str | None = None,
+    gget_mutate: bool = False,
+    keep_genome_info: bool = False,
+    remove_duplicates: bool = False,
+    seq_id_column: str = "seq_ID",
+    mutation_column: str = "mutation",
+    mut_id_column: str = "mutation_id",
+    out: str | None = None,
+    verbose: bool = True,
+) -> list[dict[str, Any]] | None: ...
+
+
+@overload
+def cosmic(
+    searchterm: str | None,
+    cosmic_tsv_path: str | None = None,
+    limit: int = 100,
+    json: Literal[False] = False,
+    download_cosmic: bool = False,
+    cosmic_project: str | None = None,
+    cosmic_version: int | None = None,
+    grch_version: int = 37,
+    email: str | None = None,
+    password: str | None = None,
+    gget_mutate: bool = False,
+    keep_genome_info: bool = False,
+    remove_duplicates: bool = False,
+    seq_id_column: str = "seq_ID",
+    mutation_column: str = "mutation",
+    mut_id_column: str = "mutation_id",
+    out: str | None = None,
+    verbose: bool = True,
+) -> pd.DataFrame | None: ...
+
+
 def cosmic(
     searchterm: str | None,
     cosmic_tsv_path: str | None = None,
@@ -334,7 +381,7 @@ def cosmic(
     mut_id_column: str = "mutation_id",
     out: str | None = None,
     verbose: bool = True,
-) -> Any:
+) -> pd.DataFrame | list[dict[str, Any]] | None:
     """Search for genes, mutations, etc associated with cancers using the COSMIC database.
 
     (Catalogue Of Somatic Mutations In Cancer) database