Exception Hierarchy

siege_utilities follows a fail-loud-over-silent-swallow policy: when a function cannot deliver its documented output, it raises a typed exception rather than returning None, False, or an empty container that looks like a legitimate “no result.” This distinguishes real failures from expected empty-input paths and prevents silent data corruption in downstream pipelines.

This page catalogs the typed exceptions across the library. Every exception subclasses a standard Python exception (LookupError, ValueError, RuntimeError) so broad existing handlers continue to work.

Design principles

1. Lookup failures are ``LookupError``. Missing chart types, missing client configs, and similar “you asked for X but X doesn’t exist” cases.

2. Parameter / input failures are ``ValueError``. Missing required parameters, invalid values, bad config shapes.

3. Operation failures are ``RuntimeError``. Failed I/O, failed parse, failed API call — anything where the inputs were valid but the work did not complete.

4. Not-found return values are preserved where semantic. list_X() returning [], lookup helpers returning None when the caller should handle absence as normal — these are unchanged. The rewrite only affects sites where absence was masking a transport or parse failure.

5. Every raise chains with ``from e``. Inspect exc.__cause__ to see the underlying error (JSONDecodeError, OSError, HTTPError, etc.).

Reporting

Top-level config export / import

exception siege_utilities.reporting.ReportingConfigError

Bases: RuntimeError

Raised when a reporting configuration export / import cannot complete.

Chart type registry

exception siege_utilities.reporting.chart_types.UnknownChartTypeError

Bases: LookupError

Raised when a chart type name is not in the registry.

exception siege_utilities.reporting.chart_types.ChartParameterError

Bases: ValueError

Raised when required parameters are missing or invalid.

exception siege_utilities.reporting.chart_types.ChartCreationError

Bases: RuntimeError

Raised when the underlying create function fails to produce a Figure.

Client branding

exception siege_utilities.reporting.client_branding.ClientBrandingNotFoundError

Bases: LookupError

Raised when a named client’s branding configuration does not exist.

exception siege_utilities.reporting.client_branding.ClientBrandingError

Bases: RuntimeError

Raised when a client-branding operation fails unexpectedly.

Use the __cause__ attribute (set via raise … from e) to inspect the underlying error (YAMLError, OSError, ValidationError, etc.).

Geographic

Census Bureau geocoder

exception siege_utilities.geo.census_geocoder.CensusGeocodeError

Bases: RuntimeError

Raised when the Census geocoder API call fails unexpectedly.

Distinct from “no match” results (which return a CensusGeocodeResult with matched=False). This exception indicates an API / network / parse failure where the geocoder could not even attempt to match. Use __cause__ to inspect the underlying exception.

Before this change, geocode_single() and geocode_batch() caught all failures (network, API, parse) and returned CensusGeocodeResult(matched=False). Downstream pipelines treated unmatched rows as “address not findable” and dropped them — so API outages silently poisoned entire batches with fake unmatched rows. CensusGeocodeError surfaces the real cause.

Spatial data sources

exception siege_utilities.geo.spatial_data.SpatialDataError

Bases: RuntimeError

Raised when a non-boundary spatial data fetch fails unexpectedly.

Used by GovernmentDataSource and OpenStreetMapDataSource, which load generic portal datasets and OSM Overpass results respectively. Boundary retrieval has its own exception hierarchy in boundary_result.py.

Use the __cause__ attribute (set via raise ... from e) to inspect the underlying exception (HTTPError, JSONDecodeError, etc.).

Used by GovernmentDataSource (CKAN-style portals) and OpenStreetMapDataSource (Overpass API). Distinct from boundary retrieval, which has its own hierarchy below.

Boundary retrieval

exception siege_utilities.geo.boundary_result.BoundaryRetrievalError

Bases: SiegeGeoError

Base exception for all boundary retrieval failures.

Inherits from SiegeGeoError so callers can catch the entire siege_utilities exception family with a single except SiegeError:. Previously this stood alone outside the documented hierarchy and slipped past except SiegeError blocks.

__init__(message, stage, context=None)

Parameters:

• message (str)

• stage (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryInputError

Bases: BoundaryRetrievalError

Invalid input parameters (state FIPS, year, geographic level).

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryDiscoveryError

Bases: BoundaryRetrievalError

Failed to discover available boundary types or construct a URL.

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryUrlValidationError

Bases: BoundaryRetrievalError

Constructed URL is not accessible (HTTP error, timeout, etc.).

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryDownloadError

Bases: BoundaryRetrievalError

Download succeeded but the file is corrupt or not a valid zip.

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryParseError

Bases: BoundaryRetrievalError

Downloaded data could not be parsed as a shapefile/GeoDataFrame.

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

exception siege_utilities.geo.boundary_result.BoundaryConfigurationError

Bases: BoundaryRetrievalError

Boundary type requires parameters that were not provided (e.g., state FIPS, congress number).

__init__(message, context=None)

Parameters:

• message (str)

• context (Dict[str, Any] | None)

Migration guidance

Callers that relied on the pre-rewrite silent-swallow behavior must migrate to try/except around the new exception types.

Before:

result = registry.create_chart("unknown_type")
if result is None:
    log.warning("chart creation failed")
    return None

After:

try:
    result = registry.create_chart("unknown_type")
except UnknownChartTypeError:
    log.warning("unknown chart type")
    return None
except ChartCreationError as e:
    log.error("chart creation failed: %s", e.__cause__)
    raise

Because the exception types subclass standard Python exceptions, you can also use a single broad except LookupError: / except ValueError: / except RuntimeError: if you do not need to distinguish cases. The __cause__ attribute still gives you the original error.

Further reading

• ../../docs/FAILURE_MODES — complete anti-pattern catalog

• ../../docs/ARCHITECTURE — three-layer dependency model