Refactor to feature 'idiomatic' first, with full back-compat with 'as…

…trapy' (#251)

Restructured package to feature 'idiomatic' first and foremost, keeping full back-compat with 'astrapy'

.github/workflows/main.yml

@@ -35,4 +35,4 @@ jobs:
 
     - name: Run pytest
       run: |
-        poetry run pytest tests/astrapy
+        poetry run pytest tests/core

astrapy/__init__.py

@@ -45,13 +45,16 @@ def get_version() -> str:
 
 __version__: str = get_version()
 
-# There's a circular-import issue to heal here to bring this to top
-from astrapy.idiomatic import (  # noqa: E402
-    AsyncCollection,
+
+# A circular-import issue requires this to happen at the end of this module:
+from astrapy.database import (  # noqa: E402
     AsyncDatabase,
-    Collection,
     Database,
 )
+from astrapy.collection import (  # noqa: E402
+    AsyncCollection,
+    Collection,
+)
 
 __all__ = [
     "AsyncCollection",

astrapy/idiomatic/__init__.py → astrapy/api/__init__.py

@@ -12,12 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from astrapy.idiomatic.collection import AsyncCollection, Collection
-from astrapy.idiomatic.database import AsyncDatabase, Database
+"""Core "api" subpackage, exported here to preserve import patterns."""
+
+from astrapy.core.api import APIRequestError
+
 
 __all__ = [
-    "AsyncCollection",
-    "AsyncDatabase",
-    "Collection",
-    "Database",
+    "APIRequestError",
 ]

astrapy/idiomatic/collection.py → astrapy/collection.py

@@ -19,29 +19,34 @@
 from concurrent.futures import ThreadPoolExecutor
 from typing import Any, Dict, Iterable, List, Optional, Union, TYPE_CHECKING
 
-from astrapy.db import AstraDBCollection, AsyncAstraDBCollection
-from astrapy.idiomatic.types import (
+from astrapy.core.db import (
+    # AstraDB,
+    AstraDBCollection,
+    # AsyncAstraDB,
+    AsyncAstraDBCollection,
+)
+from astrapy.constants import (
     DocumentType,
     FilterType,
     ProjectionType,
     ReturnDocument,
     SortType,
     normalize_optional_projection,
 )
-from astrapy.idiomatic.database import AsyncDatabase, Database
-from astrapy.idiomatic.results import (
+from astrapy.database import AsyncDatabase, Database
+from astrapy.results import (
     DeleteResult,
     InsertManyResult,
     InsertOneResult,
     UpdateResult,
     BulkWriteResult,
 )
-from astrapy.idiomatic.cursors import AsyncCursor, Cursor
-from astrapy.idiomatic.info import CollectionInfo
+from astrapy.cursors import AsyncCursor, Cursor
+from astrapy.info import CollectionInfo
 
 
 if TYPE_CHECKING:
-    from astrapy.idiomatic.operations import AsyncBaseOperation, BaseOperation
+    from astrapy.operations import AsyncBaseOperation, BaseOperation
 
 
 INSERT_MANY_CONCURRENCY = 20
@@ -96,7 +101,7 @@ def __init__(
         caller_name: Optional[str] = None,
         caller_version: Optional[str] = None,
     ) -> None:
-        self._astra_db_collection = AstraDBCollection(
+        self._astra_db_collection: AstraDBCollection = AstraDBCollection(
             collection_name=name,
             astra_db=database._astra_db,
             namespace=namespace,
@@ -136,7 +141,7 @@ def _copy(
     ) -> Collection:
         return Collection(
             database=database or self.database,
-            name=name or self._astra_db_collection.collection_name,
+            name=name or self.name,
             namespace=namespace or self.namespace,
             caller_name=caller_name or self._astra_db_collection.caller_name,
             caller_version=caller_version or self._astra_db_collection.caller_version,
@@ -203,7 +208,7 @@ def to_async(
 
         return AsyncCollection(
             database=database or self.database.to_async(),
-            name=name or self._astra_db_collection.collection_name,
+            name=name or self.name,
             namespace=namespace or self.namespace,
             caller_name=caller_name or self._astra_db_collection.caller_name,
             caller_version=caller_version or self._astra_db_collection.caller_version,
@@ -292,7 +297,8 @@ def name(self) -> str:
         The name of this collection.
         """
 
-        return self._astra_db_collection.collection_name
+        # type hint added as for some reason the typechecker gets lost
+        return self._astra_db_collection.collection_name  # type: ignore[no-any-return, has-type]
 
     @property
     def full_name(self) -> str:
@@ -1206,7 +1212,7 @@ def bulk_write(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.operations import reduce_bulk_write_results
+        from astrapy.operations import reduce_bulk_write_results
 
         if ordered:
             bulk_write_results = [
@@ -1281,7 +1287,7 @@ def __init__(
         caller_name: Optional[str] = None,
         caller_version: Optional[str] = None,
     ) -> None:
-        self._astra_db_collection = AsyncAstraDBCollection(
+        self._astra_db_collection: AsyncAstraDBCollection = AsyncAstraDBCollection(
             collection_name=name,
             astra_db=database._astra_db,
             namespace=namespace,
@@ -1321,7 +1327,7 @@ def _copy(
     ) -> AsyncCollection:
         return AsyncCollection(
             database=database or self.database,
-            name=name or self._astra_db_collection.collection_name,
+            name=name or self.name,
             namespace=namespace or self.namespace,
             caller_name=caller_name or self._astra_db_collection.caller_name,
             caller_version=caller_version or self._astra_db_collection.caller_version,
@@ -1388,7 +1394,7 @@ def to_sync(
 
         return Collection(
             database=database or self.database.to_sync(),
-            name=name or self._astra_db_collection.collection_name,
+            name=name or self.name,
             namespace=namespace or self.namespace,
             caller_name=caller_name or self._astra_db_collection.caller_name,
             caller_version=caller_version or self._astra_db_collection.caller_version,
@@ -1477,7 +1483,8 @@ def name(self) -> str:
         The name of this collection.
         """
 
-        return self._astra_db_collection.collection_name
+        # type hint added as for some reason the typechecker gets lost
+        return self._astra_db_collection.collection_name  # type: ignore[no-any-return, has-type]
 
     @property
     def full_name(self) -> str:
@@ -2373,7 +2380,7 @@ async def bulk_write(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.operations import reduce_bulk_write_results
+        from astrapy.operations import reduce_bulk_write_results
 
         if ordered:
             bulk_write_results = [

astrapy/api.py → astrapy/core/api.py

@@ -2,8 +2,8 @@
 import httpx
 from typing import Any, Dict, Optional, cast
 
-from astrapy.types import API_RESPONSE
-from astrapy.utils import amake_request, make_request
+from astrapy.core.core_types import API_RESPONSE
+from astrapy.core.utils import amake_request, make_request
 
 logger = logging.getLogger(__name__)
 

astrapy/db.py → astrapy/core/db.py

@@ -42,22 +42,22 @@
 )
 
 from astrapy import __version__
-from astrapy.api import api_request, async_api_request
-from astrapy.defaults import (
+from astrapy.core.api import api_request, async_api_request
+from astrapy.core.defaults import (
     DEFAULT_AUTH_HEADER,
     DEFAULT_JSON_API_PATH,
     DEFAULT_JSON_API_VERSION,
     DEFAULT_KEYSPACE_NAME,
     MAX_INSERT_NUM_DOCUMENTS,
 )
-from astrapy.utils import (
+from astrapy.core.utils import (
     convert_vector_to_floats,
     make_payload,
     http_methods,
     normalize_for_api,
     restore_from_api,
 )
-from astrapy.types import (
+from astrapy.core.core_types import (
     API_DOC,
     API_RESPONSE,
     PaginableRequestMethod,
@@ -119,8 +119,8 @@ def __init__(
 
         # Set the remaining instance attributes
         self.astra_db = astra_db
-        self.caller_name = self.astra_db.caller_name
-        self.caller_version = self.astra_db.caller_version
+        self.caller_name: Optional[str] = self.astra_db.caller_name
+        self.caller_version: Optional[str] = self.astra_db.caller_version
         self.collection_name = collection_name
         self.base_path: str = f"{self.astra_db.base_path}/{self.collection_name}"
 
@@ -1193,8 +1193,8 @@ def __init__(
 
         # Set the remaining instance attributes
         self.astra_db: AsyncAstraDB = astra_db
-        self.caller_name = self.astra_db.caller_name
-        self.caller_version = self.astra_db.caller_version
+        self.caller_name: Optional[str] = self.astra_db.caller_name
+        self.caller_version: Optional[str] = self.astra_db.caller_version
         self.client = astra_db.client
         self.collection_name = collection_name
         self.base_path: str = f"{self.astra_db.base_path}/{self.collection_name}"

astrapy/ops.py → astrapy/core/ops.py

@@ -17,15 +17,15 @@
 from typing import Any, cast, Dict, Optional, TypedDict
 
 import httpx
-from astrapy.api import api_request, raw_api_request
+from astrapy.core.api import api_request, raw_api_request
 
-from astrapy.utils import http_methods
-from astrapy.defaults import (
+from astrapy.core.utils import http_methods
+from astrapy.core.defaults import (
     DEFAULT_DEV_OPS_AUTH_HEADER,
     DEFAULT_DEV_OPS_API_VERSION,
     DEFAULT_DEV_OPS_URL,
 )
-from astrapy.types import API_RESPONSE, OPS_API_RESPONSE
+from astrapy.core.core_types import API_RESPONSE, OPS_API_RESPONSE
 
 
 logger = logging.getLogger(__name__)

astrapy/utils.py → astrapy/core/utils.py

@@ -8,8 +8,8 @@
 import httpx
 
 from astrapy import __version__
-from astrapy.defaults import DEFAULT_AUTH_HEADER, DEFAULT_TIMEOUT
-from astrapy.types import API_RESPONSE
+from astrapy.core.defaults import DEFAULT_AUTH_HEADER, DEFAULT_TIMEOUT
+from astrapy.core.core_types import API_RESPONSE
 
 
 class CustomLogger(logging.Logger):

astrapy/idiomatic/cursors.py → astrapy/cursors.py

@@ -31,15 +31,15 @@
     TYPE_CHECKING,
 )
 
-from astrapy.utils import _normalize_payload_value
-from astrapy.idiomatic.types import (
+from astrapy.core.utils import _normalize_payload_value
+from astrapy.constants import (
     DocumentType,
     ProjectionType,
     normalize_optional_projection,
 )
 
 if TYPE_CHECKING:
-    from astrapy.idiomatic.collection import AsyncCollection, Collection
+    from astrapy.collection import AsyncCollection, Collection
 
 
 BC = TypeVar("BC", bound="BaseCursor")

astrapy/idiomatic/database.py → astrapy/database.py

@@ -18,12 +18,12 @@
 from types import TracebackType
 from typing import Any, Dict, List, Optional, Type, Union, TYPE_CHECKING
 
-from astrapy.db import AstraDB, AsyncAstraDB
-from astrapy.idiomatic.cursors import AsyncCommandCursor, CommandCursor
-from astrapy.idiomatic.info import DatabaseInfo, get_database_info
+from astrapy.core.db import AstraDB, AsyncAstraDB
+from astrapy.cursors import AsyncCommandCursor, CommandCursor
+from astrapy.info import DatabaseInfo, get_database_info
 
 if TYPE_CHECKING:
-    from astrapy.idiomatic.collection import AsyncCollection, Collection
+    from astrapy.collection import AsyncCollection, Collection
 
 
 def _validate_create_collection_options(
@@ -318,7 +318,7 @@ def get_collection(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.collection import Collection
+        from astrapy.collection import Collection
 
         _namespace = namespace or self._astra_db.namespace
         return Collection(self, name, namespace=_namespace)
@@ -431,11 +431,11 @@ def drop_collection(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.collection import Collection
+        from astrapy.collection import Collection
 
         if isinstance(name_or_collection, Collection):
             _namespace = name_or_collection.namespace
-            _name = name_or_collection._astra_db_collection.collection_name
+            _name: str = name_or_collection.name
             dc_response = self._astra_db.copy(namespace=_namespace).delete_collection(
                 _name
             )
@@ -809,7 +809,7 @@ async def get_collection(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.collection import AsyncCollection
+        from astrapy.collection import AsyncCollection
 
         _namespace = namespace or self._astra_db.namespace
         return AsyncCollection(self, name, namespace=_namespace)
@@ -921,11 +921,11 @@ async def drop_collection(
         """
 
         # lazy importing here against circular-import error
-        from astrapy.idiomatic.collection import AsyncCollection
+        from astrapy.collection import AsyncCollection
 
         if isinstance(name_or_collection, AsyncCollection):
             _namespace = name_or_collection.namespace
-            _name = name_or_collection._astra_db_collection.collection_name
+            _name = name_or_collection.name
             dc_response = await self._astra_db.copy(
                 namespace=_namespace
             ).delete_collection(_name)

astrapy/db/__init__.py

@@ -0,0 +1,30 @@
+# Copyright DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Core "db" subpackage, exported here to preserve import patterns."""
+
+from astrapy.core.db import (
+    AstraDBCollection,
+    AsyncAstraDBCollection,
+    AstraDB,
+    AsyncAstraDB,
+)
+
+
+__all__ = [
+    "AstraDBCollection",
+    "AsyncAstraDBCollection",
+    "AstraDB",
+    "AsyncAstraDB",
+]