geotiff: re-export #1987 error classes from xrspatial.geotiff

Second-pass review follow-up on PR 2006.

The user-facing ambiguity error hierarchy lived in
`xrspatial.geotiff._errors`. The leading underscore marks the module
as private, so callers writing `except GeoTIFFAmbiguousMetadataError`
were coupled to an implementation-detail import path. The neighbouring
user-facing errors and warnings (`UnsafeURLError`,
`GeoTIFFFallbackWarning`) are re-exported from `xrspatial.geotiff`;
the #1987 family now follows the same convention.

Adds `GeoTIFFAmbiguousMetadataError` plus the seven case subclasses
to `__all__`, updates the frozen-public-API guard test to pin the
new names, and adds a regression test that imports each one from
the public namespace.

No raise-site change; per-case PRs still wire the checks. This is a
public-API surface addition only.

Author: brendancol

xrspatial/geotiff/__init__.py

@@ -55,6 +55,16 @@
     coords_to_transform as _coords_to_transform,
     require_transform_for_georeferenced as _require_transform_for_georeferenced,
 )
+from ._errors import (
+    ConflictingCRSError,
+    ConflictingNodataError,
+    GeoTIFFAmbiguousMetadataError,
+    InvalidCRSCodeError,
+    MixedBandMetadataError,
+    NonUniformCoordsError,
+    RotatedTransformError,
+    UnparseableCRSError,
+)
 from ._geotags import GeoTransform, RASTER_PIXEL_IS_AREA, RASTER_PIXEL_IS_POINT
 from ._reader import UnsafeURLError
 # ``read_to_array`` is internal: it is used by ``open_geotiff`` and the
@@ -108,7 +118,15 @@
 # is intentionally omitted: it is deprecated in favour of ``da.xrs.plot()``
 # and emits a ``DeprecationWarning`` when called.
 __all__ = [
+    'ConflictingCRSError',
+    'ConflictingNodataError',
+    'GeoTIFFAmbiguousMetadataError',
     'GeoTIFFFallbackWarning',
+    'InvalidCRSCodeError',
+    'MixedBandMetadataError',
+    'NonUniformCoordsError',
+    'RotatedTransformError',
+    'UnparseableCRSError',
     'UnsafeURLError',
     'open_geotiff',
     'read_geotiff_gpu',

xrspatial/geotiff/tests/test_ambiguous_metadata_hooks_1987.py

@@ -88,6 +88,35 @@ def test_base_is_value_error_subclass():
     assert issubclass(GeoTIFFAmbiguousMetadataError, ValueError)
 
 
+def test_error_classes_reexported_from_public_namespace():
+    """User-facing ambiguity errors must be importable from ``xrspatial.geotiff``.
+
+    ``UnsafeURLError`` and ``GeoTIFFFallbackWarning`` follow the same
+    convention. Without the re-export, callers would have to dig into
+    the private ``_errors`` module to write ``except`` clauses, which
+    couples them to an implementation-detail import path.
+    """
+    import xrspatial.geotiff as geotiff_pkg
+
+    for name in (
+        "GeoTIFFAmbiguousMetadataError",
+        "InvalidCRSCodeError",
+        "UnparseableCRSError",
+        "RotatedTransformError",
+        "NonUniformCoordsError",
+        "MixedBandMetadataError",
+        "ConflictingCRSError",
+        "ConflictingNodataError",
+    ):
+        assert hasattr(geotiff_pkg, name), (
+            f"{name} not exposed on xrspatial.geotiff")
+        assert name in geotiff_pkg.__all__, (
+            f"{name} not listed in xrspatial.geotiff.__all__")
+    # The re-exported class is the same object as the one in ``_errors``.
+    assert (geotiff_pkg.GeoTIFFAmbiguousMetadataError
+            is GeoTIFFAmbiguousMetadataError)
+
+
 def test_subclass_catch_does_not_catch_siblings():
     """``except UnparseableCRSError`` must not catch ``RotatedTransformError``."""
     with pytest.raises(RotatedTransformError):

xrspatial/geotiff/tests/test_features.py

@@ -2726,6 +2726,17 @@ def test_all_lists_supported_functions(self):
         # public API. If any of these gets removed or renamed, that is a
         # breaking change and should go through a deprecation cycle.
         expected = {
+            # Ambiguous-metadata error hierarchy (#1987). Re-exported in
+            # PR 0 so callers can ``except`` the family or a specific
+            # case without importing from the private ``_errors`` module.
+            'ConflictingCRSError',
+            'ConflictingNodataError',
+            'GeoTIFFAmbiguousMetadataError',
+            'InvalidCRSCodeError',
+            'MixedBandMetadataError',
+            'NonUniformCoordsError',
+            'RotatedTransformError',
+            'UnparseableCRSError',
             'GeoTIFFFallbackWarning',
             'UnsafeURLError',
             'open_geotiff',