Add doc snippet; document exceptions and explain_no_results

doc/changes/DM-33600.api.rst

@@ -0,0 +1,2 @@
+Registry methods now raise exceptions belonging to a class hierarchy rooted at `lsst.daf.butler.registry.RegistryError`.
+See also :ref:`daf_butler_query_error_handling` for details.

doc/changes/README.rst

@@ -20,5 +20,5 @@ An example file name would therefore look like ``DM-30291.misc.rst``.
 
 If the change concerns specifically the registry or a datastore the news fragment can be placed in the relevant subdirectory.
 
-You can test how the content will be integrated into the release notes by running ``towncrier --draft --version=V.vv``.
+You can test how the content will be integrated into the release notes by running ``towncrier build --draft --version=V.vv``.
 ``towncrier`` can be installed from PyPI or conda-forge.

doc/lsst.daf.butler/queries.rst

@@ -410,3 +410,18 @@ Example of use of these two methods:
     # Print ten latest visit records in reverse time order
     for record in registry.queryDimensionRecords("visit").order_by("-timespan.begin").limit(10):
         print(record)
+
+.. _daf_butler_query_error_handling:
+
+Error handling with Registry methods
+------------------------------------
+
+`Registry` methods typically raise exceptions when they detect problems with input parameters. Documentation for these methods describes a set of exception classes and conditions in which exceptions are generated. In most cases, these exceptions belong to one of the special exception classes defined in `lsst.daf.butler.registry` module, e.g. `~lsst.daf.butler.registry.DataIdError`, which have `~lsst.daf.butler.registry.RegistryError` as a common base class. These exception classes are not exposed in `lsst.daf.butler` module interface, to use these classes they need to be imported explicitly, e.g.:
+
+.. code-block:: Python
+
+    from lsst.daf.butler.registry import DataIdError, UserExpressionError
+
+While class documentation should list most commonly produced exception, there may be other exceptions raised by its methods. Code that needs to handle all types of exceptions generated by `Registry` methods should be prepared to handle other types of exceptions as well.
+
+Few of the `Registry` query methods (`~Registry.queryDataIds`, `~Registry.queryDatasets`, and `~Registry.queryDimensionRecords`) return result objects. These objects are iterables of the corresponding record types and typically they represent a non-empty result set. In some cases these methods can return empty results without generating an exception, for example due to a combination of constraints excluding all existing records. Result classes implement ``explain_no_results()`` method which can be used to try to identify the reason for an empty result. It returns a list of strings, each string contains human-readable message describing the reason for an empty result. This method does not always work reliably and can return an empty list even when result is empty. In particular it cannot analyze user expression and identify which part of that expression is responsible for an empty result.