bolster.exceptions
==================

.. py:module:: bolster.exceptions

.. autoapi-nested-parse::

   Bolster domain-specific exception hierarchy.

   This module provides the constitutional exception hierarchy for all data source modules.
   All data sources MUST use these domain-specific exceptions instead of generic Exception.



Attributes
----------

.. autoapisummary::

   bolster.exceptions.NISRADataNotFoundError
   bolster.exceptions.NISRAValidationError
   bolster.exceptions.PSNIDataNotFoundError
   bolster.exceptions.PSNIValidationError


Exceptions
----------

.. autoapisummary::

   bolster.exceptions.DataSourceError
   bolster.exceptions.DataNotFoundError
   bolster.exceptions.ValidationError
   bolster.exceptions.ParseError
   bolster.exceptions.NetworkError


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

.. py:exception:: DataSourceError

   Bases: :py:obj:`Exception`


   Base class for all data source errors.

   This is the root exception for all domain-specific errors in Bolster.
   All other exceptions should inherit from this base class.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:exception:: DataNotFoundError(message, url = None, source = None)

   Bases: :py:obj:`DataSourceError`


   Raised when expected data publications or URLs are not found.

   .. rubric:: Examples

   - Publication page returns 404
   - Expected Excel file link missing from page
   - RSS feed returns no entries
   - API endpoint returns empty response

   :param message: Description of what data was not found
   :param url: Optional URL that was being accessed
   :param source: Optional data source identifier

   Initialize DataSourceError with message and optional context.


   .. py:attribute:: url
      :value: None



   .. py:attribute:: source
      :value: None



   .. py:method:: __str__()

      Return str(self).



.. py:exception:: ValidationError(message, data_info = None, validation_type = None)

   Bases: :py:obj:`DataSourceError`


   Raised when data fails integrity validation checks.

   .. rubric:: Examples

   - Required columns missing from DataFrame
   - Data values outside expected ranges
   - Inconsistent data relationships
   - Empty datasets when data expected

   :param message: Description of validation failure
   :param data_info: Optional info about the problematic data
   :param validation_type: Optional type of validation that failed

   Initialize ValidationError with message and optional validation context.


   .. py:attribute:: data_info
      :value: None



   .. py:attribute:: validation_type
      :value: None



   .. py:method:: __str__()

      Return str(self).



.. py:exception:: ParseError(message, file_path = None, parser_type = None)

   Bases: :py:obj:`DataSourceError`


   Raised when file or data parsing fails.

   .. rubric:: Examples

   - Malformed Excel file structure
   - Unexpected CSV format
   - HTML parsing issues
   - JSON decode errors

   :param message: Description of parsing failure
   :param file_path: Optional path to file that failed to parse
   :param parser_type: Optional type of parser (excel, csv, html, json)

   Initialize ParseError with message and optional parsing context.


   .. py:attribute:: file_path
      :value: None



   .. py:attribute:: parser_type
      :value: None



   .. py:method:: __str__()

      Return str(self).



.. py:exception:: NetworkError(message, url = None, status_code = None, retry_count = None)

   Bases: :py:obj:`DataSourceError`


   Raised when network operations fail beyond retry limits.

   .. rubric:: Examples

   - Timeout errors after retries
   - Connection refused
   - DNS resolution failures
   - Server returning persistent errors (500, 503)

   :param message: Description of network failure
   :param url: Optional URL that failed
   :param status_code: Optional HTTP status code
   :param retry_count: Optional number of retries attempted

   Initialize NetworkError with message and optional network context.


   .. py:attribute:: url
      :value: None



   .. py:attribute:: status_code
      :value: None



   .. py:attribute:: retry_count
      :value: None



   .. py:method:: __str__()

      Return str(self).



.. py:data:: NISRADataNotFoundError

.. py:data:: NISRAValidationError

.. py:data:: PSNIDataNotFoundError

.. py:data:: PSNIValidationError