Coverage for python / lsst / daf / butler / _exceptions.py: 83%
52 statements
« prev ^ index » next coverage.py v7.13.5, created at 2026-04-18 08:43 +0000
1# This file is part of daf_butler.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (http://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This software is dual licensed under the GNU General Public License and also
10# under a 3-clause BSD license. Recipients may choose which of these licenses
11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt,
12# respectively. If you choose the GPL option then the following text applies
13# (but note that there is still no warranty even if you opt for BSD instead):
14#
15# This program is free software: you can redistribute it and/or modify
16# it under the terms of the GNU General Public License as published by
17# the Free Software Foundation, either version 3 of the License, or
18# (at your option) any later version.
19#
20# This program is distributed in the hope that it will be useful,
21# but WITHOUT ANY WARRANTY; without even the implied warranty of
22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23# GNU General Public License for more details.
24#
25# You should have received a copy of the GNU General Public License
26# along with this program. If not, see <http://www.gnu.org/licenses/>.
28"""Specialized Butler exceptions."""
30__all__ = (
31 "ButlerUserError",
32 "CalibrationLookupError",
33 "CollectionCycleError",
34 "CollectionTypeError",
35 "DataIdValueError",
36 "DatasetNotFoundError",
37 "DatasetTypeNotSupportedError",
38 "DimensionNameError",
39 "EmptyQueryResultError",
40 "InconsistentDataIdError",
41 "InvalidQueryError",
42 "MissingCollectionError",
43 "MissingDatasetTypeError",
44 "UnknownComponentError",
45 "ValidationError",
46)
48from ._exceptions_legacy import CollectionError, DataIdError, DatasetTypeError
51class ButlerUserError(Exception):
52 """Base class for Butler exceptions that contain a user-facing error
53 message.
55 Parameters
56 ----------
57 detail : `str`
58 Details about the error that occurred.
59 """
61 # When used with Butler server, exceptions inheriting from
62 # this class will be sent to the client side and re-raised by RemoteButler
63 # there. Be careful that error messages do not contain security-sensitive
64 # information.
65 #
66 # This should only be used for "expected" errors that occur because of
67 # errors in user-supplied data passed to Butler methods. It should not be
68 # used for any issues caused by the Butler configuration file, errors in
69 # the library code itself or the underlying databases.
70 #
71 # When you create a new subclass of this type, add it to the list in
72 # _USER_ERROR_TYPES below.
74 error_type: str
75 """Unique name for this error type, used to identify it when sending
76 information about the error to the client.
77 """
79 def __init__(self, detail: str):
80 return super().__init__(detail)
83class CalibrationLookupError(LookupError, ButlerUserError):
84 """Exception raised for failures to look up a calibration dataset.
86 For a find-first query involving a calibration dataset to work, either the
87 query's result rows need to include a temporal dimension or needs to be
88 constrained temporally, such that each result row corresponds to a unique
89 calibration dataset. This exception can be raised if those dimensions or
90 constraint are missing, or if a temporal dimension timespan overlaps
91 multiple validity ranges (e.g. the recommended bias changes in the middle
92 of an exposure).
93 """
95 error_type = "calibration_lookup"
98class CollectionCycleError(ValueError, ButlerUserError):
99 """Raised when an operation would cause a chained collection to be a child
100 of itself.
101 """
103 error_type = "collection_cycle"
106class CollectionTypeError(CollectionError, ButlerUserError):
107 """Exception raised when type of a collection is incorrect."""
109 error_type = "collection_type"
112class DataIdValueError(DataIdError, ButlerUserError):
113 """Exception raised when a value specified in a data ID does not exist."""
115 error_type = "data_id_value"
118class DatasetNotFoundError(LookupError, ButlerUserError):
119 """The requested dataset could not be found."""
121 error_type = "dataset_not_found"
124class DimensionNameError(KeyError, DataIdError, ButlerUserError):
125 """Exception raised when a dimension specified in a data ID does not exist
126 or required dimension is not provided.
127 """
129 error_type = "dimension_name"
132class DimensionValueError(ValueError, ButlerUserError):
133 """Exception raised for issues with dimension values in a data ID."""
135 error_type = "dimension_value"
138class InconsistentDataIdError(DataIdError, ButlerUserError):
139 """Exception raised when a data ID contains contradictory key-value pairs,
140 according to dimension relationships.
141 """
143 error_type = "inconsistent_data_id"
146class InvalidQueryError(ButlerUserError):
147 """Exception raised when a query is not valid."""
149 error_type = "invalid_query"
152class MissingCollectionError(CollectionError, ButlerUserError):
153 """Exception raised when an operation attempts to use a collection that
154 does not exist.
155 """
157 error_type = "missing_collection"
160class UnimplementedQueryError(NotImplementedError, ButlerUserError):
161 """Exception raised when the query system does not support the query
162 specified by the user.
163 """
165 error_type = "unimplemented_query"
168class MissingDatasetTypeError(DatasetTypeError, KeyError, ButlerUserError):
169 """Exception raised when a dataset type does not exist."""
171 error_type = "missing_dataset_type"
174class UnknownComponentError(KeyError, ButlerUserError):
175 """Exception raised when the requested component of a DatasetType is not
176 known.
177 """
179 error_type = "unknown_component"
182class DatasetTypeNotSupportedError(RuntimeError):
183 """A `DatasetType` is not handled by this routine.
185 This can happen in a `Datastore` when a particular `DatasetType`
186 has no formatters associated with it.
187 """
189 pass
192class ValidationError(RuntimeError):
193 """Some sort of validation error has occurred."""
195 pass
198class EmptyQueryResultError(Exception):
199 """Exception raised when query methods return an empty result and
200 ``explain`` flag is set.
202 Parameters
203 ----------
204 reasons : `list` [`str`]
205 List of possible reasons for an empty query result.
206 """
208 def __init__(self, reasons: list[str]):
209 self.reasons = reasons
211 def __str__(self) -> str:
212 # There may be multiple reasons, format them into multiple lines.
213 return "Possible reasons for empty result:\n" + "\n".join(self.reasons)
216class UnknownButlerUserError(ButlerUserError):
217 """Raised when the server sends an ``error_type`` for which we don't know
218 the corresponding exception type. (This may happen if an old version of
219 the Butler client library connects to a new server).
220 """
222 error_type = "unknown"
225_USER_ERROR_TYPES: tuple[type[ButlerUserError], ...] = (
226 CalibrationLookupError,
227 CollectionCycleError,
228 CollectionTypeError,
229 DimensionNameError,
230 DimensionValueError,
231 DataIdValueError,
232 DatasetNotFoundError,
233 InconsistentDataIdError,
234 InvalidQueryError,
235 MissingCollectionError,
236 MissingDatasetTypeError,
237 UnimplementedQueryError,
238 UnknownButlerUserError,
239 UnknownComponentError,
240)
241_USER_ERROR_MAPPING = {e.error_type: e for e in _USER_ERROR_TYPES}
242assert len(_USER_ERROR_MAPPING) == len(_USER_ERROR_TYPES), (
243 "Subclasses of ButlerUserError must have unique 'error_type' property"
244)
247def create_butler_user_error(error_type: str, message: str) -> ButlerUserError:
248 """Instantiate one of the subclasses of `ButlerUserError` based on its
249 ``error_type`` string.
251 Parameters
252 ----------
253 error_type : `str`
254 The value from the ``error_type`` class attribute on the exception
255 subclass you wish to instantiate.
256 message : `str`
257 Detailed error message passed to the exception constructor.
258 """
259 cls = _USER_ERROR_MAPPING.get(error_type)
260 if cls is None:
261 raise UnknownButlerUserError(f"Unknown exception type '{error_type}': {message}")
262 return cls(message)