Major codebase restructuring (#322)

* more organized file structure

* care about pdoc

Author: hemidactylus

CHANGES

@@ -1,6 +1,11 @@
 v 2.0.0
 =======
+Major restructuring of the codebase into directories
+    - BaseCursor not exported by astrapy.cursors anymore
+    - some imports (supposedly not used externally) changed slightly
+    - adapted and limited scope of test_imports.py
 Rename main branch from 'master' ==> `main`
+Cursors' state described by the `CursorState` enum
 Removal of several deprecated modules/features from previous versions:
     - 'core' (i.e. pre-1.0) library
     - 'collection.bulk_write' and the associated result and exception classes

README.md

@@ -369,33 +369,34 @@ Client, data and admin abstractions:
 
 ```python
 from astrapy import (
-    DataAPIClient,
-    Database,
-    AsyncDatabase,
-    Collection,
-    AsyncCollection,
     AstraDBAdmin,
     AstraDBDatabaseAdmin,
+    AsyncCollection,
+    AsyncDatabase,
+    Collection,
+    DataAPIClient,
     DataAPIDatabaseAdmin,
+    Database,
 )
 ```
 
 Constants for data-related use:
 
 ```python
 from astrapy.constants import (
+    DefaultIdType,
+    Environment,
     ReturnDocument,
     SortDocuments,
     VectorMetric,
-    DefaultIdType,
-    Environment,
 )
 ```
 
 ObjectIds and UUIDs:
 
 ```python
 from astrapy.ids import (
+    UUID,
     ObjectId,
     uuid1,
     uuid3,
@@ -404,7 +405,6 @@ from astrapy.ids import (
     uuid6,
     uuid7,
     uuid8,
-    UUID,
 )
 ```
 
@@ -453,39 +453,42 @@ Info/metadata classes:
 ```python
 from astrapy.info import (
     AdminDatabaseInfo,
-    DatabaseInfo,
-    CollectionInfo,
-    CollectionVectorServiceOptions,
     CollectionDefaultIDOptions,
-    CollectionVectorOptions,
-    CollectionOptions,
     CollectionDescriptor,
-    EmbeddingProviderParameter,
+    CollectionInfo,
+    CollectionOptions,
+    CollectionVectorOptions,
+    CollectionVectorServiceOptions,
+    DatabaseInfo,
+    EmbeddingProvider,
+    EmbeddingProviderAuthentication,
     EmbeddingProviderModel,
+    EmbeddingProviderParameter,
     EmbeddingProviderToken,
-    EmbeddingProviderAuthentication,
-    EmbeddingProvider,
     FindEmbeddingProvidersResult,
 )
 ```
 
-Admin-related classes and constants:
+Admin-related classes, functions and constants:
 
 ```python
 from astrapy.admin import (
+    DatabaseAdmin,
     ParsedAPIEndpoint,
+    fetch_database_info,
+    parse_api_endpoint,
 )
 ```
 
 Cursors:
 
 ```python
 from astrapy.cursors import (
-    BaseCursor,
-    Cursor,
+    AsyncCommandCursor,
     AsyncCursor,
     CommandCursor,
-    AsyncCommandCursor,
+    Cursor,
+    CursorState,
 )
 ```
 

astrapy/__init__.py

@@ -74,12 +74,6 @@ def get_version() -> str:
 
 
 __pdoc__ = {
-    "api_commander": False,
-    "api_options": False,
-    "defaults": False,
     "ids": False,
-    "meta": False,
-    "request_tools": False,
-    "transform_payload": False,
-    "user_agents": False,
+    "settings": False,
 }

astrapy/admin/__init__.py

@@ -0,0 +1,35 @@
+# 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.
+
+from __future__ import annotations
+
+from astrapy.admin.admin import (
+    AstraDBAdmin,
+    AstraDBDatabaseAdmin,
+    DataAPIDatabaseAdmin,
+    DatabaseAdmin,
+    ParsedAPIEndpoint,
+    fetch_database_info,
+    parse_api_endpoint,
+)
+
+__all__ = [
+    "AstraDBAdmin",
+    "AstraDBDatabaseAdmin",
+    "DataAPIDatabaseAdmin",
+    "DatabaseAdmin",
+    "ParsedAPIEndpoint",
+    "fetch_database_info",
+    "parse_api_endpoint",
+]

astrapy/admin.py renamed to astrapy/admin/admin.py

@@ -22,11 +22,17 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Sequence
 
-from astrapy.api_commander import APICommander
 from astrapy.authentication import coerce_token_provider, redact_secret
 from astrapy.constants import CallerType, Environment
 from astrapy.cursors import CommandCursor
-from astrapy.defaults import (
+from astrapy.exceptions import (
+    DataAPIFaultyResponseException,
+    DevOpsAPIException,
+    MultiCallTimeoutManager,
+    base_timeout_info,
+)
+from astrapy.info import AdminDatabaseInfo, DatabaseInfo, FindEmbeddingProvidersResult
+from astrapy.settings.defaults import (
     API_ENDPOINT_TEMPLATE_ENV_MAP,
     API_PATH_ENV_MAP,
     API_VERSION_ENV_MAP,
@@ -46,14 +52,8 @@
     DEV_OPS_URL_ENV_MAP,
     DEV_OPS_VERSION_ENV_MAP,
 )
-from astrapy.exceptions import (
-    DataAPIFaultyResponseException,
-    DevOpsAPIException,
-    MultiCallTimeoutManager,
-    base_timeout_info,
-)
-from astrapy.info import AdminDatabaseInfo, DatabaseInfo, FindEmbeddingProvidersResult
-from astrapy.request_tools import HttpMethod
+from astrapy.utils.api_commander import APICommander
+from astrapy.utils.request_tools import HttpMethod
 
 if TYPE_CHECKING:
     from astrapy import AsyncDatabase, Database

astrapy/authentication.py

@@ -18,7 +18,7 @@
 from abc import ABC, abstractmethod
 from typing import Any
 
-from astrapy.defaults import (
+from astrapy.settings.defaults import (
     EMBEDDING_HEADER_API_KEY,
     EMBEDDING_HEADER_AWS_ACCESS_ID,
     EMBEDDING_HEADER_AWS_SECRET_ID,

astrapy/client.py

@@ -17,7 +17,7 @@
 import logging
 from typing import TYPE_CHECKING, Any, Sequence
 
-from astrapy.admin import (
+from astrapy.admin.admin import (
     api_endpoint_parsing_error_message,
     generic_api_url_parsing_error_message,
     parse_api_endpoint,