core.lib.pgsexceptions
======================

.. py:module:: core.lib.pgsexceptions

.. autoapi-nested-parse::

   This module defines a custom PGS exception hierarchy.

   This module overrides sys.excepthook. Uncaught exceptions are intercepted,
   and ``sys.exit()`` is called with a custom code. This can be helpful to debug
   problems in other applications, because there are relatively few failure states.

   The hierarchy:

   - BasePGSException

     - MatchError

       - DuplicateMatchError

       - MatchRateError

       - ZeroMatchesError

       - MatchValueError

     - CombineError

       - BuildError

       - ScoreFormatError

       - LiftoverError

     - CatalogError

       - ScoreDownloadError

       - ScoreChecksumError

       - QueryError

       - InvalidAccessionError

     - SamplesheetError

       - GenomesNotFound

       - SamplesheetFormatError



Exceptions
----------

.. autoapisummary::

   core.lib.pgsexceptions.BasePGSException
   core.lib.pgsexceptions.BuildError
   core.lib.pgsexceptions.CatalogError
   core.lib.pgsexceptions.CombineError
   core.lib.pgsexceptions.DuplicateMatchError
   core.lib.pgsexceptions.EffectTypeError
   core.lib.pgsexceptions.GenomesNotFound
   core.lib.pgsexceptions.InvalidAccessionError
   core.lib.pgsexceptions.LiftoverError
   core.lib.pgsexceptions.MatchError
   core.lib.pgsexceptions.MatchRateError
   core.lib.pgsexceptions.MatchValueError
   core.lib.pgsexceptions.QueryError
   core.lib.pgsexceptions.SamplesheetError
   core.lib.pgsexceptions.SamplesheetFormatError
   core.lib.pgsexceptions.ScoreChecksumError
   core.lib.pgsexceptions.ScoreDownloadError
   core.lib.pgsexceptions.ScoreFormatError
   core.lib.pgsexceptions.ZeroMatchesError


Classes
-------

.. autoapisummary::

   core.lib.pgsexceptions.ExceptionExitCodeMap


Functions
---------

.. autoapisummary::

   core.lib.pgsexceptions.handle_uncaught_exception


Module Contents
---------------

.. py:exception:: BasePGSException(message: str)



   The base class from which all PGS errors must inherit.
   The purpose of this class is to simplify finding PGS exceptions and exiting python
   with a matching custom exit code.


.. py:exception:: BuildError(message: str)



   Raised when there's a problem with a scoring file genome build.


.. py:exception:: CatalogError(message: str)



   The base class for errors when querying or downloading from the PGS Catalog


.. py:exception:: CombineError(message: str)



   The base class for errors that are raised when combining scorefiles


.. py:exception:: DuplicateMatchError(message: str)



   Raised when a matched variant has been duplicated, so that a variant with the same ID
   would be split across two rows in an output scoring file.


.. py:exception:: EffectTypeError(message: str)



   Raised when non-supported effect types are present


.. py:exception:: GenomesNotFound(message: str)



   Raised when FileNotFound


.. py:exception:: InvalidAccessionError(message: str)



   Raised when an invalid term is used to query the Catalog


.. py:exception:: LiftoverError(message: str)



   Raised when liftover has failed to convert genomic coordinates well


.. py:exception:: MatchError(message: str)



   The base class for errors that are raised during variant matching


.. py:exception:: MatchRateError(message: str)



   Raised when match rate is below match threshold for one or more scoring files


.. py:exception:: MatchValueError(message: str)



   Raised when a match function receives inappropriate values.

   e.g., Multiple chromosomes detected in variant data but data is split per-chromosome


.. py:exception:: QueryError(message: str)



   Raised when the Catalog API doesn't return a valid response


.. py:exception:: SamplesheetError(message: str)



   The base class for errors related to samplesheet parsing


.. py:exception:: SamplesheetFormatError(message: str)



   Raised when a samplesheet is badly formatted


.. py:exception:: ScoreChecksumError(message: str)



   Raised when a scoring file fails checksum validation


.. py:exception:: ScoreDownloadError(message: str)



   Raised when a scoring file can't be downloaded


.. py:exception:: ScoreFormatError(message: str)



   Raised when there's a problem with a scoring file.


.. py:exception:: ZeroMatchesError(message: str)



   Raised when zero matches are found for one or more scoring files.

   Distinct from MatchRateError because it's very common, and caused by bad input data or parameters.


.. py:class:: ExceptionExitCodeMap

   A read only map to get exit codes for custom exceptions


   .. py:attribute:: code_map


.. py:function:: handle_uncaught_exception(exctype: type[BaseException], value: BaseException, trace: types.TracebackType | None) -> None

   Intercept BasePGSExceptions and trigger sys.exit with a custom code