feat: refactor custom exceptions to exceptions module

Author: bencap

src/api/routers/map.py

@@ -6,29 +6,31 @@
 from fastapi.responses import JSONResponse
 from requests import HTTPError
 
-from dcd_mapping.align import AlignmentError, BlatNotFoundError, build_alignment_result
+from dcd_mapping.align import build_alignment_result
 from dcd_mapping.annotate import (
     _get_computed_reference_sequence,
     _get_mapped_reference_sequence,
     _set_scoreset_layer,
     annotate,
 )
 from dcd_mapping.exceptions import (
+    AlignmentError,
+    BlatNotFoundError,
+    DataLookupError,
     MissingSequenceIdError,
+    ResourceAcquisitionError,
+    ScoresetNotSupportedError,
     UnsupportedReferenceSequenceNameSpaceError,
     UnsupportedReferenceSequencePrefixError,
     VrsMapError,
 )
-from dcd_mapping.lookup import DataLookupError
 from dcd_mapping.mavedb_data import (
-    ScoresetNotSupportedError,
     get_raw_scoreset_metadata,
     get_scoreset_metadata,
     get_scoreset_records,
     patch_target_sequence_type,
     with_mavedb_score_set,
 )
-from dcd_mapping.resource_utils import ResourceAcquisitionError
 from dcd_mapping.schemas import (
     ScoreAnnotation,
     ScoresetMapping,

src/dcd_mapping/align.py

@@ -12,12 +12,15 @@
 from Bio.SearchIO._model import Hit, QueryResult
 from cool_seq_tool.schemas import Strand
 
-from dcd_mapping.lookup import get_chromosome_identifier, get_gene_location
-from dcd_mapping.mavedb_data import LOCAL_STORE_PATH, ScoresetNotSupportedError
-from dcd_mapping.resource_utils import (
+from dcd_mapping.exceptions import (
+    AlignmentError,
+    BlatNotFoundError,
     ResourceAcquisitionError,
-    http_download,
+    ScoresetNotSupportedError,
 )
+from dcd_mapping.lookup import get_chromosome_identifier, get_gene_location
+from dcd_mapping.mavedb_data import LOCAL_STORE_PATH
+from dcd_mapping.resource_utils import http_download
 from dcd_mapping.schemas import (
     AlignmentResult,
     GeneLocation,
@@ -32,14 +35,6 @@
 _logger = logging.getLogger(__name__)
 
 
-class AlignmentError(Exception):
-    """Raise when errors encountered during alignment."""
-
-
-class BlatNotFoundError(AlignmentError):
-    """Raise when BLAT binary appears to be missing."""
-
-
 def _write_query_file(file: Path, lines: list[str]) -> None:
     """Write lines to query file. This method is broken out to enable easy mocking while
     testing.

src/dcd_mapping/cli.py

@@ -6,12 +6,14 @@
 
 import click
 
-from dcd_mapping.align import AlignmentError
-from dcd_mapping.exceptions import VrsMapError
+from dcd_mapping.exceptions import (
+    AlignmentError,
+    ResourceAcquisitionError,
+    TxSelectError,
+    VrsMapError,
+)
 from dcd_mapping.main import map_scoreset_urn
-from dcd_mapping.resource_utils import ResourceAcquisitionError
 from dcd_mapping.schemas import VrsVersion
-from dcd_mapping.transcripts import TxSelectError
 
 _logger = logging.getLogger(__name__)
 

src/dcd_mapping/exceptions.py

@@ -1,6 +1,9 @@
 """Exceptions for DCD Mapping Module"""
 
 
+### Custom Exceptions for VRS Mapping Errors ###
+
+
 class VrsMapError(Exception):
     """Raise in case of generic VRS mapping errors."""
 
@@ -15,3 +18,42 @@ class MissingSequenceIdError(ValueError):
 
 class UnsupportedReferenceSequencePrefixError(ValueError):
     """Raised when a reference sequence prefix is not supported."""
+
+
+### Custom Exceptions for Alignment Errors ###
+
+
+class AlignmentError(ValueError):
+    """Raise when errors encountered during alignment."""
+
+
+class BlatNotFoundError(AlignmentError):
+    """Raise when BLAT binary appears to be missing."""
+
+
+### Custom Exceptions for Data Lookup Errors ###
+
+
+class DataLookupError(Exception):
+    """Raise for misc. issues related to resource acquisition/lookup."""
+
+
+### Custom Exceptions for MaveDB Data Errors ###
+
+
+class ScoresetNotSupportedError(ValueError):
+    """Raise when a score set cannot be mapped because it has characteristics that are not currently supported."""
+
+
+### Custom Exceptions for Resource Acquisition Errors ###
+
+
+class ResourceAcquisitionError(ValueError):
+    """Raise when resource acquisition fails."""
+
+
+### Custom Exceptions for Transcript Selection Errors ###
+
+
+class TxSelectError(ValueError):
+    """Raise for transcript selection failure."""

src/dcd_mapping/lookup.py

@@ -49,6 +49,7 @@
 from gene.query import QueryHandler
 from gene.schemas import MatchType, SourceName
 
+from dcd_mapping.exceptions import DataLookupError
 from dcd_mapping.schemas import (
     GeneLocation,
     ManeDescription,
@@ -93,10 +94,6 @@ def cdot_rest() -> RESTDataProvider:
 # ---------------------------------- Global ---------------------------------- #
 
 
-class DataLookupError(Exception):
-    """Raise for misc. issues related to resource acquisition/lookup."""
-
-
 class CoolSeqToolBuilder:
     """Singleton constructor for ``cool-seq-tool`` instance."""
 
@@ -241,7 +238,9 @@ async def check_uta() -> None:
     query = f"select * from {uta.schema}.meta"  # noqa: S608
     result = await uta.execute_query(query)
     if not result:
-        raise DataLookupError
+        msg = "UTA schema check failed. No results returned."
+        _logger.error(msg)
+        raise DataLookupError(msg)
 
 
 async def get_protein_accession(transcript: str) -> str | None:
@@ -302,9 +301,13 @@ async def get_transcripts(
 def check_gene_normalizer() -> None:
     q = GeneNormalizerBuilder()
     if (not q.db.check_schema_initialized()) or not (q.db.check_tables_populated()):
-        raise DataLookupError
+        msg = "Gene Normalizer database schema check failed. No results returned."
+        _logger.error(msg)
+        raise DataLookupError(msg)
     if q.normalize("BRAF").match_type == MatchType.NO_MATCH:
-        raise DataLookupError
+        msg = "Gene Normalizer returned no normalization results for BRAF. This indicates an underlying issue with the database that should be investigated."
+        _logger.error(msg)
+        raise DataLookupError(msg)
 
 
 def _get_hgnc_symbol(term: str) -> str | None:
@@ -436,7 +439,9 @@ def get_gene_location(target_gene: TargetGene) -> GeneLocation | None:
 def check_seqrepo() -> None:
     sr = get_seqrepo()
     if not sr.sr["NC_000001.11"][780000:780020]:
-        raise DataLookupError
+        msg = "SeqRepo returned no sequence for NC_000001.11 at 780000:780020. This indicates an underlying issue with SeqRepo that should be investigated."
+        _logger.error(msg)
+        raise DataLookupError(msg)
     conn = sr.sr.aliases._db
     try:
         # conn = sr.sr.aliases._db

src/dcd_mapping/main.py

@@ -8,32 +8,34 @@
 import click
 from requests import HTTPError
 
-from dcd_mapping.align import AlignmentError, BlatNotFoundError, build_alignment_result
+from dcd_mapping.align import build_alignment_result
 from dcd_mapping.annotate import (
     annotate,
     save_mapped_output_json,
     write_scoreset_mapping_to_json,
 )
 from dcd_mapping.exceptions import (
+    AlignmentError,
+    BlatNotFoundError,
+    DataLookupError,
     MissingSequenceIdError,
+    ResourceAcquisitionError,
+    ScoresetNotSupportedError,
     UnsupportedReferenceSequenceNameSpaceError,
     UnsupportedReferenceSequencePrefixError,
     VrsMapError,
 )
 from dcd_mapping.lookup import (
-    DataLookupError,
     check_gene_normalizer,
     check_seqrepo,
     check_uta,
 )
 from dcd_mapping.mavedb_data import (
-    ScoresetNotSupportedError,
     get_scoreset_metadata,
     get_scoreset_records,
     patch_target_sequence_type,
     with_mavedb_score_set,
 )
-from dcd_mapping.resource_utils import ResourceAcquisitionError
 from dcd_mapping.schemas import (
     ScoreRow,
     ScoresetMapping,

src/dcd_mapping/mavedb_data.py

@@ -17,11 +17,14 @@
 from fastapi import HTTPException
 from pydantic import ValidationError
 
-from dcd_mapping.lookup import DataLookupError
+from dcd_mapping.exceptions import (
+    DataLookupError,
+    ResourceAcquisitionError,
+    ScoresetNotSupportedError,
+)
 from dcd_mapping.resource_utils import (
     LOCAL_STORE_PATH,
     MAVEDB_BASE_URL,
-    ResourceAcquisitionError,
     authentication_header,
     http_download,
 )
@@ -47,10 +50,6 @@
 _logger = logging.getLogger(__name__)
 
 
-class ScoresetNotSupportedError(Exception):
-    """Raise when a score set cannot be mapped because it has characteristics that are not currently supported."""
-
-
 def get_scoreset_urns() -> set[str]:
     """Fetch all scoreset URNs. Since species is annotated at the scoreset target level,
     we can't yet filter on anything like `homo sapien` -- meaning this is fairly slow.

src/dcd_mapping/resource_utils.py

@@ -18,10 +18,6 @@
     LOCAL_STORE_PATH.mkdir(exist_ok=True, parents=True)
 
 
-class ResourceAcquisitionError(Exception):
-    """Raise when resource acquisition fails."""
-
-
 def authentication_header() -> dict | None:
     """Fetch with api key envvar, if available."""
     return {"X-API-key": MAVEDB_API_KEY} if MAVEDB_API_KEY is not None else None

src/dcd_mapping/transcripts.py

@@ -7,6 +7,7 @@
 from Bio.SeqUtils import seq1
 from cool_seq_tool.schemas import TranscriptPriority
 
+from dcd_mapping.exceptions import TxSelectError
 from dcd_mapping.lookup import (
     get_chromosome_identifier,
     get_gene_symbol,
@@ -29,15 +30,11 @@
     TxSelectResult,
 )
 
-__all__ = ["select_transcript", "TxSelectError"]
+__all__ = ["select_transcript"]
 
 _logger = logging.getLogger(__name__)
 
 
-class TxSelectError(Exception):
-    """Raise for transcript selection failure."""
-
-
 async def _get_compatible_transcripts(
     target_gene: TargetGene, align_result: AlignmentResult
 ) -> list[list[str]]: