Removed all "autoregions" and other guesses in the DB/DBAdmin spawn paths. Also better general exceptions (#337)

* replaced ValueErrors with appropriate exceptions where applicable

* custom domain supported in admin's get_database; removed autoregion/autokeyspace in DBspawners

* Completed removal of impur HTTP calls in any db/dbadmin spawn path

Author: hemidactylus

CHANGES

@@ -1,12 +1,27 @@
 main
 ====
-Support for Astra DB "custom domain" endpoints for database (then: `.id`, `.region`, `.get_database_admin()`, `.info()` and `.name()` aren't available)
-Support for the `indexType` field to describe table indexes (as not mandatory for compatibility)
-DataAPITime: support for "hh:mm" no-seconds format
-DataAPIDuration: improved parse performance by caching regexpes
-DataAPIDuration: support for "P4W"-type strings and for zeroes such as "P", "-PR"
-Collection and Table `insert_many` methods employ returnDocumentResponses under the hood
-maintenance: switch to DSE6.9 for local non-Astra testing
+Spawner methods for databases/admins standardized; they don't issue DevOps API calls.
+    - removed `normalize_region_for_id` utility method, not used anymore.
+    - `AstraDBAdmin.get_[async]_database()`:
+        - does not run DevOps API calls anymore (for missing keyspace/region);
+        - defers defaults to the [Async]Database class consistently;
+        - removed `database_admin_timeout_ms`, `request_timeout_ms`, `timeout_ms` parameters;
+        - `region` now required if `id` passed instead of endpoint.
+    - `AstraDBDatabaseAdmin.get[_async]_database()`:
+        - removed `database_admin_timeout_ms`, `request_timeout_ms`, `timeout_ms` parameters.
+    - `AstraDBDatabaseAdmin.get_database_admin()` standardized and simplified:
+        - does not run DevOps API calls anymore (for missing keyspace/region);
+        - removed `database_admin_timeout_ms`, `request_timeout_ms`, `timeout_ms` parameters;
+        - `region` now required if `id` passed instead of endpoint.
+Support for Astra DB "custom domain" endpoints for database
+    - in which case: `.id`, `.region`, `.get_database_admin()`, `.info()` and `.name()` aren't available.
+Support for the `indexType` field to describe table indexes (for compatibility, said field is not mandatory).
+DataAPITime: support for "hh:mm" no-seconds format.
+DataAPIDuration: improved parse performance by caching regexpes.
+DataAPIDuration: support for "P4W"-type strings and for zeroes such as "P", "-PR".
+Replaced the ValueErrors not directly coming from function calls/constructors with more appropriate exceptions.
+Collection and Table `insert_many` methods employ returnDocumentResponses under the hood.
+maintenance: switch to DSE6.9 for local non-Astra testing.
 
 v 2.0.0rc1
 ==========

astrapy/admin/admin.py

@@ -15,7 +15,6 @@
 from __future__ import annotations
 
 import asyncio
-import json
 import logging
 from concurrent.futures import ThreadPoolExecutor
 from types import TracebackType
@@ -476,7 +475,7 @@ def options(
         if self_descriptors:
             return self_descriptors[0].definition
         else:
-            raise ValueError(
+            raise RuntimeError(
                 f"Collection {self.keyspace}.{self.name} not found.",
             )
 
@@ -552,7 +551,7 @@ def keyspace(self) -> str:
 
         _keyspace = self.database.keyspace
         if _keyspace is None:
-            raise ValueError("The collection's DB is set with keyspace=None")
+            raise RuntimeError("The collection's DB is set with keyspace=None")
         return _keyspace
 
     @property
@@ -3009,7 +3008,7 @@ async def options(
         if self_descriptors:
             return self_descriptors[0].definition
         else:
-            raise ValueError(
+            raise RuntimeError(
                 f"Collection {self.keyspace}.{self.name} not found.",
             )
 
@@ -3088,7 +3087,7 @@ def keyspace(self) -> str:
 
         _keyspace = self.database.keyspace
         if _keyspace is None:
-            raise ValueError("The collection's DB is set with keyspace=None")
+            raise RuntimeError("The collection's DB is set with keyspace=None")
         return _keyspace
 
     @property
@@ -3195,14 +3194,14 @@ async def insert_one(
                     inserted_id=inserted_id,
                 )
             else:
-                raise ValueError(
-                    "Could not complete a insert_one operation. "
-                    f"(gotten '${json.dumps(io_response)}')"
+                raise UnexpectedDataAPIResponseException(
+                    text="Faulty response from insert_one API command.",
+                    raw_response=io_response,
                 )
         else:
-            raise ValueError(
-                "Could not complete a insert_one operation. "
-                f"(gotten '${json.dumps(io_response)}')"
+            raise UnexpectedDataAPIResponseException(
+                text="Faulty response from insert_one API command.",
+                raw_response=io_response,
             )
 
     async def insert_many(

astrapy/data/collection.py

@@ -375,7 +375,7 @@ def _fetch_page(
         timeout_context: _TimeoutContext,
     ) -> tuple[list[TRAW], str | None, dict[str, Any] | None]:
         if self.collection is None:
-            raise ValueError("Query engine has no sync collection.")
+            raise RuntimeError("Query engine has no sync collection.")
         f_payload = {
             "find": {
                 **self.f_r_subpayload,
@@ -419,7 +419,7 @@ async def _async_fetch_page(
         timeout_context: _TimeoutContext,
     ) -> tuple[list[TRAW], str | None, dict[str, Any] | None]:
         if self.async_collection is None:
-            raise ValueError("Query engine has no async collection.")
+            raise RuntimeError("Query engine has no async collection.")
         f_payload = {
             "find": {
                 **self.f_r_subpayload,
@@ -512,7 +512,7 @@ def _fetch_page(
         timeout_context: _TimeoutContext,
     ) -> tuple[list[TRAW], str | None, dict[str, Any] | None]:
         if self.table is None:
-            raise ValueError("Query engine has no sync table.")
+            raise RuntimeError("Query engine has no sync table.")
         f_payload = self.table._converter_agent.preprocess_payload(
             {
                 "find": {
@@ -561,7 +561,7 @@ async def _async_fetch_page(
         timeout_context: _TimeoutContext,
     ) -> tuple[list[TRAW], str | None, dict[str, Any] | None]:
         if self.async_table is None:
-            raise ValueError("Query engine has no async table.")
+            raise RuntimeError("Query engine has no async table.")
         f_payload = self.async_table._converter_agent.preprocess_payload(
             {
                 "find": {
@@ -714,7 +714,7 @@ def _copy(
         skip: int | None | UnsetType = _UNSET,
     ) -> CollectionFindCursor[TRAW, T]:
         if self._query_engine.collection is None:
-            raise ValueError("Query engine has no collection.")
+            raise RuntimeError("Query engine has no collection.")
         return CollectionFindCursor(
             collection=self._query_engine.collection,
             request_timeout_ms=self._request_timeout_ms
@@ -805,7 +805,7 @@ def data_source(self) -> Collection[TRAW]:
         """
 
         if self._query_engine.collection is None:
-            raise ValueError("Query engine has no collection.")
+            raise RuntimeError("Query engine has no collection.")
         return self._query_engine.collection
 
     def clone(self) -> CollectionFindCursor[TRAW, TRAW]:
@@ -839,7 +839,7 @@ def clone(self) -> CollectionFindCursor[TRAW, TRAW]:
         """
 
         if self._query_engine.collection is None:
-            raise ValueError("Query engine has no collection.")
+            raise RuntimeError("Query engine has no collection.")
         return CollectionFindCursor(
             collection=self._query_engine.collection,
             request_timeout_ms=self._request_timeout_ms,
@@ -1060,7 +1060,7 @@ def map(self, mapper: Callable[[T], TNEW]) -> CollectionFindCursor[TRAW, TNEW]:
         """
         self._ensure_idle()
         if self._query_engine.collection is None:
-            raise ValueError("Query engine has no collection.")
+            raise RuntimeError("Query engine has no collection.")
         composite_mapper: Callable[[TRAW], TNEW]
         if self._mapper is not None:
 
@@ -1392,7 +1392,7 @@ def _copy(
         skip: int | None | UnsetType = _UNSET,
     ) -> AsyncCollectionFindCursor[TRAW, T]:
         if self._query_engine.async_collection is None:
-            raise ValueError("Query engine has no async collection.")
+            raise RuntimeError("Query engine has no async collection.")
         return AsyncCollectionFindCursor(
             collection=self._query_engine.async_collection,
             request_timeout_ms=self._request_timeout_ms
@@ -1488,7 +1488,7 @@ def data_source(self) -> AsyncCollection[TRAW]:
         """
 
         if self._query_engine.async_collection is None:
-            raise ValueError("Query engine has no async collection.")
+            raise RuntimeError("Query engine has no async collection.")
         return self._query_engine.async_collection
 
     def clone(self) -> AsyncCollectionFindCursor[TRAW, TRAW]:
@@ -1508,7 +1508,7 @@ def clone(self) -> AsyncCollectionFindCursor[TRAW, TRAW]:
         """
 
         if self._query_engine.async_collection is None:
-            raise ValueError("Query engine has no async collection.")
+            raise RuntimeError("Query engine has no async collection.")
         return AsyncCollectionFindCursor(
             collection=self._query_engine.async_collection,
             request_timeout_ms=self._request_timeout_ms,
@@ -1701,7 +1701,7 @@ def map(self, mapper: Callable[[T], TNEW]) -> AsyncCollectionFindCursor[TRAW, TN
 
         self._ensure_idle()
         if self._query_engine.async_collection is None:
-            raise ValueError("Query engine has no async collection.")
+            raise RuntimeError("Query engine has no async collection.")
         composite_mapper: Callable[[TRAW], TNEW]
         if self._mapper is not None:
 
@@ -1994,7 +1994,7 @@ def _copy(
         skip: int | None | UnsetType = _UNSET,
     ) -> TableFindCursor[TRAW, T]:
         if self._query_engine.table is None:
-            raise ValueError("Query engine has no table.")
+            raise RuntimeError("Query engine has no table.")
         return TableFindCursor(
             table=self._query_engine.table,
             request_timeout_ms=self._request_timeout_ms
@@ -2085,7 +2085,7 @@ def data_source(self) -> Table[TRAW]:
         """
 
         if self._query_engine.table is None:
-            raise ValueError("Query engine has no table.")
+            raise RuntimeError("Query engine has no table.")
         return self._query_engine.table
 
     def clone(self) -> TableFindCursor[TRAW, TRAW]:
@@ -2119,7 +2119,7 @@ def clone(self) -> TableFindCursor[TRAW, TRAW]:
         """
 
         if self._query_engine.table is None:
-            raise ValueError("Query engine has no table.")
+            raise RuntimeError("Query engine has no table.")
         return TableFindCursor(
             table=self._query_engine.table,
             request_timeout_ms=self._request_timeout_ms,
@@ -2338,7 +2338,7 @@ def map(self, mapper: Callable[[T], TNEW]) -> TableFindCursor[TRAW, TNEW]:
 
         self._ensure_idle()
         if self._query_engine.table is None:
-            raise ValueError("Query engine has no table.")
+            raise RuntimeError("Query engine has no table.")
         composite_mapper: Callable[[TRAW], TNEW]
         if self._mapper is not None:
 
@@ -2670,7 +2670,7 @@ def _copy(
         skip: int | None | UnsetType = _UNSET,
     ) -> AsyncTableFindCursor[TRAW, T]:
         if self._query_engine.async_table is None:
-            raise ValueError("Query engine has no async table.")
+            raise RuntimeError("Query engine has no async table.")
         return AsyncTableFindCursor(
             table=self._query_engine.async_table,
             request_timeout_ms=self._request_timeout_ms
@@ -2765,7 +2765,7 @@ def data_source(self) -> AsyncTable[TRAW]:
         """
 
         if self._query_engine.async_table is None:
-            raise ValueError("Query engine has no async table.")
+            raise RuntimeError("Query engine has no async table.")
         return self._query_engine.async_table
 
     def clone(self) -> AsyncTableFindCursor[TRAW, TRAW]:
@@ -2785,7 +2785,7 @@ def clone(self) -> AsyncTableFindCursor[TRAW, TRAW]:
         """
 
         if self._query_engine.async_table is None:
-            raise ValueError("Query engine has no async table.")
+            raise RuntimeError("Query engine has no async table.")
         return AsyncTableFindCursor(
             table=self._query_engine.async_table,
             request_timeout_ms=self._request_timeout_ms,
@@ -2978,7 +2978,7 @@ def map(self, mapper: Callable[[T], TNEW]) -> AsyncTableFindCursor[TRAW, TNEW]:
 
         self._ensure_idle()
         if self._query_engine.async_table is None:
-            raise ValueError("Query engine has no async table.")
+            raise RuntimeError("Query engine has no async table.")
         composite_mapper: Callable[[TRAW], TNEW]
         if self._mapper is not None:
 

astrapy/data/cursor.py

@@ -451,7 +451,7 @@ def definition(
         if self_descriptors:
             return self_descriptors[0].definition
         else:
-            raise ValueError(
+            raise RuntimeError(
                 f"Table {self.keyspace}.{self.name} not found.",
             )
 
@@ -524,7 +524,7 @@ def keyspace(self) -> str:
 
         _keyspace = self.database.keyspace
         if _keyspace is None:
-            raise ValueError("The table's DB is set with keyspace=None")
+            raise RuntimeError("The table's DB is set with keyspace=None")
         return _keyspace
 
     @property
@@ -3162,7 +3162,7 @@ async def definition(
         if self_descriptors:
             return self_descriptors[0].definition
         else:
-            raise ValueError(
+            raise RuntimeError(
                 f"Table {self.keyspace}.{self.name} not found.",
             )
 
@@ -3238,7 +3238,7 @@ def keyspace(self) -> str:
 
         _keyspace = self.database.keyspace
         if _keyspace is None:
-            raise ValueError("The table's DB is set with keyspace=None")
+            raise RuntimeError("The table's DB is set with keyspace=None")
         return _keyspace
 
     @property

astrapy/data/table.py

@@ -129,7 +129,7 @@ def _unix_timestamp_ms_to_timetuple(
         milliseconds=y_remainder_ms
     )
     if ref_dt.year != ref_year:
-        raise ValueError(f"Could not map timestamp ({timestamp_ms} ms) to a date.")
+        raise RuntimeError(f"Could not map timestamp ({timestamp_ms} ms) to a date.")
     month = ref_dt.month
     day = ref_dt.day
     hour = ref_dt.hour

astrapy/utils/date_utils.py

@@ -19,7 +19,6 @@
 import pytest
 
 from astrapy import DataAPIClient, Database
-from astrapy.admin import parse_api_endpoint
 from astrapy.constants import DefaultIdType, VectorMetric
 from astrapy.ids import UUID, ObjectId
 from astrapy.info import (
@@ -422,37 +421,6 @@ def test_tokenless_client_sync(
         )
         assert isinstance(database.list_collection_names(), list)
 
-    @pytest.mark.skipif(not IS_ASTRA_DB, reason="Not supported outside of Astra DB")
-    @pytest.mark.describe(
-        "test of autoregion through DevOps API for get_database(_admin), sync"
-    )
-    def test_autoregion_getdatabase_sync(
-        self,
-        data_api_credentials_kwargs: DataAPICredentials,
-        data_api_credentials_info: DataAPICredentialsInfo,
-    ) -> None:
-        client = DataAPIClient(environment=data_api_credentials_info["environment"])
-        parsed_api_endpoint = parse_api_endpoint(
-            data_api_credentials_kwargs["api_endpoint"]
-        )
-        if parsed_api_endpoint is None:
-            raise ValueError(
-                f"Unparseable API endpoint: {data_api_credentials_kwargs['api_endpoint']}"
-            )
-        adm = client.get_admin(token=data_api_credentials_kwargs["token"])
-        # auto-region through the DebvOps "db info" call
-        assert adm.get_database_admin(
-            parsed_api_endpoint.database_id
-        ) == adm.get_database_admin(data_api_credentials_kwargs["api_endpoint"])
-
-        # auto-region for get_database
-        assert adm.get_database(
-            parsed_api_endpoint.database_id,
-            keyspace="the_ks",
-        ) == adm.get_database(
-            data_api_credentials_kwargs["api_endpoint"], keyspace="the_ks"
-        )
-
     @pytest.mark.skipif(not IS_ASTRA_DB, reason="Not supported outside of Astra DB")
     @pytest.mark.describe(
         "test database-from-admin default keyspace per environment, sync"

tests/base/integration/collections/test_collection_ddl_sync.py

@@ -144,7 +144,7 @@ async def test_collection_options_failures_async(
     ) -> None:
         acol = async_empty_collection._copy()
         acol._name += "_hacked"
-        with pytest.raises(ValueError, match="not found"):
+        with pytest.raises(RuntimeError, match="not found"):
             await acol.options()
 
     @pytest.mark.describe("test of collection count_documents failure modes, async")

tests/base/integration/collections/test_collection_exceptions_async.py

@@ -134,7 +134,7 @@ def test_collection_options_failures_sync(
     ) -> None:
         col = sync_empty_collection._copy()
         col._name += "_hacked"
-        with pytest.raises(ValueError, match="not found"):
+        with pytest.raises(RuntimeError, match="not found"):
             col.options()
 
     @pytest.mark.describe("test of collection count_documents failure modes, sync")