Astrapy 2.0.0-preview: Tables and much more (#326)

* WIP on tables, descriptor refactor, dse compose

* database table methods: list/listnames sync+async done

* first table (unit) tests

* covering vector types in table defs

* wip on tolerant parse/coerce of table options

* table crd in place

* table info structures handle unsupported columns

* just introduced scalar-type enum

* check for ok:1 in all database class table/coll CD ops

* table index descriptor classes

* create (regular/vector) index; drop index

* better, shorter, privacy-oriented repr for Full/APIOptions/db classes

* more streamlined and secure hiding of tokens in repr and such

* repr for apicommander

* add support for sourceModel in vector index options

* add items to the cql type enum

* most table vanity methods

* finished table vanity methods; started refactor exceptions

* binary is handled at the payload coded layer

* removed the pointless {ok:1} returns

* remove check_exists and CollectionAlreadyExistsException

* rationalize table test dir; some table DML+testing

* fix timeout s-vs-ms bugs, simplify timeout internal management, unflaky timeout tests

* collection find_one uses API findOne command

* WIP table generics

* wip generics of collection

* tiny edit

* brought typing in all tests; add 1/4 typing-specific test

* add test for typing collections+tables

* rename the default Row and Document types

* started cursor2

* cursor2 rewritten and wired to collection find. distinct todo

* distinct+in cursors for collections + test/ruff

* refine cursor timeouts and replace CursorIsStartedException -> CursorException

* for_each, map (also rename overall_max_time_ms -> overall_timeout_ms)

* test of timeouts in cursor 'reduce' operations

* add typing test for map, etc

* table cursors, table's find and distinct methods

* improve class hierarchy for table column descriptors

* table converters, core logic and most converters

* TableSet class and its usage

* TableMap and its usage

* apitimestamp class, loss/y api optins known to payload conv, support in collections read/write

* TableDuration type and its wiring

* use stdlib ipaddress for 'inet' CQL type

* TableDate class and its use in converters

* TableTime type and its usage

* DataAPITimestamp covers the stringy rfc3339 formats; used in table converters

* DataAPIVector basics

* binary encoding of vectors in collections + api options to control it

* renamed wire-format options

* limit vector bin-enc for collections to insertions

* fix tests with the new tolerant-on-insert policy for types

* guard against empty-keyspace DBs without 'keyspace' and 'keyspaces' fields on devops responses

* add .region property to databases; optimize vector-path in coll pre/post process; adjust dbInfo tests

* move the pre-post-processing logic out of commander, into collections (tables todo)

* renamed option to 'unroll_iterables_to_list' and used in the general collection preproc route

* rename tpostprocessors; nested nan in lists/maps and its test

* table type-driven preprocessing wip (DataAPITimestamp missing + tests)

* most pre/post processing for tables (except using the custom dt option); missing wiring

* full table pre-post-processors, testing and use of options

* sensible repr and str for DataAPIVector

* converter agent for tables, with caching

* unexpected response exceptions renamed; result classes split T/C; full wiring of pre-post-processing for tables

* rename WireFormatOptions->SerdesOptions; better timeout messages that always give the number in ms

* info methods of async classes are async; adjust collections test re: datetime/DataAPITimestamp; made custom types hashable

* WIP on surfacing original timeouts

* wip 2 on surfacing the nominal timeout values

* surfacing the timeouts as the user configured them

* cursors' for_each and to_list error on closed cursors

* adjust tests to fetch_db_info signature; suspend dropIndex (the command is missing somehow)

* cursor to_list and for_each will error if cursor is closed

* equality method on CollectionDescriptor

* mostly reworked exception tree; added InvalidEnvironmentException

* rearrange and rename collection-specific exceptions

* rearranged exception tree

* final arrangement of exceptions all in astrapy.exceptions

* cursor.has_next can start iteration on IDLE cursor

* less unwieldy repr for XInsertManyResult if many items

* cursors don't accept project after map is set

* if/not/exists option and all the create/drop table/index commands ready

* renamed all TableX custom data types to DataAPIX

* drop_table_index now a Database method

* delete_many for tables; fixes and int.tests for distinct; int.tests for delete_many/one

* full options to (table)find_one + testing

* wip on the decimal management in jsonencoding

* full feature for the decimal-first flag in collections + unit tests

* integration testing of the decimal encoding and related options for collections

* unit test of table codec paths for decimal/number support

* remove CollectionNotFoundException; cleaned out a forgotten table drop_index method

* table deletion methods return None; removed associated XResult classes and related exceptions

* alterTable and tests

* revert to common CumulativeOperationException; remove Table{DeleteMany|UpdateMany}Exception and Table{Delete|Update}Result

* rename test modules tableX to dataapiX; factored the 'c' format for duration logic in a separate module

* wip DataAPIDuration format flip

* DataAPIDuration switched to the ISO-8601-with-signum notation

* table's count_documents, estimated_document_count methods + aliases + unit test

* removed outdated 'astrapy_latest_interface.py'

* table update_one method and test

* table insert_many sync + tests

* table insert_many, async + integration tests

* fix Decimal schema-hashing bug; added IT for update_one

* align cursor class names

* more terse repr of collections and tables

* improve error messages for multi-error DataAPIResponseExceptions

* cursors, reverted to .data_source common property for tables/collections

* v2.0 diagrams (abstractions, exceptions)

* DataAPIClient init and spawner methods all accept api_options besides top named params

* database's get_database_admin accepts admin_api_options parameter

* removed unnecessary token coercion in tests

* uniform api_options to all copy/clone/conversion methods

* remove useless token coercion steps

* minor (typing and typos)

* Table.alter() supports typing and returns the newly-typed table

* Table.alter() accepts a dict which it tries to parse into an Operation

* cursors' get_sort_vector behaves as dictated by serdes options for tables/collections

* include_similarity full support

* support for source_model in create collection

* add tests for paginated table fnid; rename SortDocuments to SortMode (with alias)

* switch to the 6-tier timeout options

* duration, use c-format in write path for lossless (for now)

* remove row-named count methods

* schema-based fillers for missing columns in row,

* table's list_indexes and list_index_names methods + test

* remove cursor .keyspace property

* database 'command' method can target no-keyspace; update param names and streamlined logic

* fixed some tests after the api and client minor changes

* all tests (except countDocuments) passing again

* rename max_time_ms to timeout_ms consistently

* refactored the per-method timeout override chains in a zero-respecting manner

* reinstated use of command() in a test

* DataAPITimestamp has friendlier repr

* adjusted the year/sign part of DataAPITimestamp parsing and stringifying

* tiny fix to timestamp parsing (+0000123 allowed, 0000123 no for year)

* adjusted DataAPIDate parsing and to_string to respect sign-of-year constraints as the API

* add test for the timeout overrides including passing zero

* added timeout-override and timeout-zero test for async collection

* tables, int. test restructure+enrich wip

* wip for tuple right typing in ids

* proper type handling in insertedIds (dict+tuple) and its testing

* a mostly complete integration test suite for tables

* DataAPIMap and DataAPISet __eq__ method behaves like regular maps and sets; completed read-then-write-all-types tests

* bugfix: token passthrough in the async_fetch_database_info

* standard table vectorize integration tests

* include sort vector, include similarity; covered by table vectorize tests

* more table IT coverage

* bigfix: equality of DataAPIMap

* I test of table command

* some more find IT for tables

* increase default per-req timeout to 10s

* tables, full IT coverage of find

* full findOne IT for tables

* full integration test coverage of table cursors

* wip3 naming timeouts in errors

* wip1 fine-align timeouts

* wip2  fine-align timeouts

* full alignment to timeout management

* split Create- vs List- TableIndexDefinition and TableIndexDescriptor

* index creation/list final API for tables

* CollectionOptions -> CollectionDefinition class rename

* from_dict -> _from_dict method consistently

* cursors, for_each and to_list start where consumtion stopped

* callback to for_each can stop early by returning False

* added a tiny bit of testing to table cursors with foreach

* added all collection cursor integration tests

* table class docstrings

* made some internal-method param required; remove any check/error on include_sort_vector and include_similarity

* docstring fixes; in part. move tokens out of client (unless admin example docstrings)

* table index creation new signature (for real)

* first quickstart and some more timezonecare in the readme

* table create_index has optional options param

* better readme quickstarts (t/c both)

* table.py docstrings: create_index, create_vector_index, list_index_names, list_indexes, alter (+async)

* table docstring wip: halfway throug find

* minor parameters to table-creation structures made optional; more table docstrings

* more docstrings to table.py

* sync table docstrings tier0 done

* full tier-0 table.py docstring, incl async

* more standardization of table.py docstrings

* TableVectorIndexOptions can be coerced from None; create_vector_index has optional options; minor docs improvement

* more docstring improvement around tables

* final datetime/timezone serdes options, completed

* adjusted tests in the wake of datetime tzinfo rework

* systematc, consistent rewrite of the options to copy and spawn methods for the various abstractions

* fix clipped datetime diagram picture

* conftest param naming update

* minor IT adjustments

* create/get[table/coll] docstrings done, vectorize IT improved

* adapt a vectorize test to DataAPIVector

* wip on createCollection arg unflattening

* create_collection signature rework + fluent interface, completed

* table creation docstring order fix

* column_type may be omitted for vector column type descriptor

* param name change in builder method; better repr for DataAPIMap

* AsyncDatabase: get_table and get_collection methods are not async functions anymore

* environment locked in APIOptions

* TODO cleanup in tests

* api_options: all docstrings; fixed a couple of spawn/api_option parameter names here and there

* datetime serdes example in readme

* a small apioptions example in readme

* minor api-option docstring changes

* docstring for date and vector

* docstring all of the custom data types

* more docstrings

* rename CursorState->FindCursorState; most cursor docstrings

* full cursor docstrings

* simplified drop_table and drop_collection to only accept the string name of the target to drop

* wip typing finds

* add type parameter to find methods for returned items

* more docstring; all collection vector writes abide by binary_encode_vectors setting

* disable (for now) collection vector binary encoding altogether

* all docstrings in table.py and database_info.py

* docstring for collection.py

* all database.py docstrings done

* table descriptors, docstrings ok

* all docstrings done

* primitive->scalar terminology consistently for columns

* rewritten CHANGES file

* mark version as preview; upgrade hcd docker-compose data api image

* comment a stupid flaky test

* another tricky async timeout test gone

* another tricky async timeout test gone 2

* disabled most of the timeout tests with httpsserver

* removed the alias SortMode->SortDocuments

* builder interface renamed to .builder()---.build() pattern

* renamed TableScalarColumnType -> ColumnType

* wip toward proper list/create split for collection def/descr

* split list/create table descriptors for real

Author: hemidactylus

CHANGES

@@ -1,40 +1,160 @@
-v 2.0.0
-=======
-Support for arbitrary 'database' and 'admin' headers throughout the object chain
-Reworked the options system:
+v 2.0.0-preview
+===============
+Introduction of full Tables support.
+Major revision of overall interface including Collection support.
+
+Introduced new astrapy-specific data types for full expressivity (see `serdes_options` below):
+    - `DataAPIVector` data type
+    - `DataAPIDate`, `DataAPITime`, `DataAPITimestamp`, `DataAPIDuration`
+    - `DataAPISet`, `DataAPIMap`
+
+Typing support for Collections (optional):
+    - `get_collection` and `create_collection` get a `document_type` parameter to go with the type hint `Collection[MyType]`
+    - if unspecified fall back to `DefaultCollection = Collection[DefaultDocumentType]` (where `DefaultDocumentType = dict[str, Any]`)
+    - cursors from `find` also allow strict typechecking
+
+Introduced a consistent API Options system:
     - an APIOptions object inherited at each "spawn" operation, with overrides
     - environment-dependent defaults if nothing supplied
-    - "spawn" operations expose top-level aliases for selected settings
-    - per-method overrides. For timeouts, `max_time_ms` becomes an alias for more specific timeout types
-    - collection and database's `info` method gets timeout parameters
-    - (not user-facing) classes in the hierarchy other than DataAPIClient have breaking changes in their constructor (now options-first and keyword-arg-only)
-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
-Removed AstraDBDatabaseAdmin's `from_api_endpoint` static method (reason: unused)
-Rename main branch from 'master' ==> `main`
-Cursors' state described by the `CursorState` enum
-Removal of several deprecated modules/features from previous versions:
+    - `serdes_options` to control data types accepted for writes and to select data types for reads
+    - `serdes_options`: Collections default to using custom types for lossless and full-range expression of database content
+        - `serdes_options.binary_encode_vectors`, to control usage of binary-encoding for writing vectors.
+        - e.g. instead of 'datetime.datetime', instances of `DataAPITimestamp` are returned
+        - Exception: numbers are treated by default as ints and floats. To have them all Decimal, set serdes_option.use_decimals_in_collections to True.
+        - Use the options' serdes_option to opt out and revert to non-custom data types
+        - For datetimes, fine control over naive-datetime tolerance and timezone is introduced. Usage of naive datetime is now OPT-IN.
+    - Support for arbitrary 'database' and 'admin' headers throughout the object chain
+    - Fully reworked timeout options through all abstractions:
+        - `TimeoutOptions` has six classes of timeouts, applying differently to various methods according to the kind of method. Timeouts can be overridden per-method-call
+        - removal of the 'max_time_ms` parameter ==> still a quick migration path is to replace it with `timeout_ms` throughout
+        - timeout of 0 means that timeout is disabled
+
+Reworked and enriched `FindCursor` interface:
+    - Cursors are typed, similarly to Tables and Collections. The `find` method has an optional `document_type` parameter for typechecking.
+    - Cursor classes renamed to `[Async]CollectionCursor`
+    - Base class for all (find) cursors renamed to `FindCursor`
+    - introduced `map` and `to_list` methods
+    - `cursor.state` now has values in `FindCursorState` enum (take `cursor.state.value` for a string)
+    - 'cursor.address' is removed from the API
+    - `cursor.rewind()` returns None, mutates cursor in-place
+    - removed 'cursor.distinct()': use the  corresponding collection(/table) method.
+    - removed cursor '.keyspace' property
+    - removed 'retrieved' for cursors: use `consumed`
+    - added many cursor management methods (see docstrings for details)
+
+Other changes to existing API:
+    - `Database.create_collection`: signature change (now accepts a single "collection definition")
+        - added parameter `definition` to method (a CollectionDefinition, plain dictionary or None)
+        - (support for `source_model` vector index setting within the `definition` parameter)
+        - removed 'dimension', 'metric', 'source_model', 'service', 'indexing', 'default_id_type' (all of them subsumed in `definition`)
+        - removed parameters 'additional_options' and 'timeout_ms' as part of the broader timeout rework
+    - renamed 'CollectionOptions' class to `CollectionDefinition` (return type of `Collection.options()`):
+        - renamed its 'options' attribute into `definition` (although the API payload calls it "options")
+        - removed its 'raw_options' attribute (redundant w.r.t `CollectionDescriptor.raw_descriptor`)
+        - `CollectionDefinition`: implemented fluent interface to build collection definition objects
+    - renamed `CollectionVectorServiceOptions` class to `VectorServiceOptions`
+    - renamed `astrapy.constants.SortDocuments` to `SortMode`
+    - renamed (collection-specific) "Result" classes like this:
+        - 'DeleteResult' ==> `CollectionDeleteResult`
+        - 'InsertOneResult' ==> `CollectionInsertOneResult`
+        - 'InsertManyResult' ==> `CollectionInsertManyResult`
+        - 'UpdateResult' ==> `CollectionUpdateResult`
+    - signature change from `-> {"ok": 1}` to `-> None` for some admin and schema methods:
+        - `AstraDBAdmin`: `drop_database` (+ async)
+        - `AstraDBDatabaseAdmin`, `DataAPIDatabaseAdmin`: `create_keyspace`, `drop_keyspace`, `drop` (+ async)
+        - `Database`, `AsyncDatabase`: `drop_collection`, `drop_table`
+        - `Collection`, `AsyncCollection`: `drop`
+    - renamed parameter 'collection_name' to `collection_or_table_name` and allow for `keyspace=None` in database `command()` method
+    - [Async]Database `drop_collection` method now accepts a keyspace parameter.
+    - `AsyncDatabase` methods `get_collection` and `get_table` are not async functions anymore (remove the await when calling them)
+    - the following "info" methods are made async (= awaitable): `AsyncDatabase.info`, `AsyncDatabase.name`, `AsyncCollection.info`, `AsyncTable.info`, `AsyncDatabase.list_collections`, `AsyncDatabase.list_tables`
+    - Database info structure: changed class name and reworked attributes of `AstraDBAdminDatabaseInfo` (formerly 'AdminDatabaseInfo') and `AstraDBDatabaseInfo` (formerly 'DatabaseInfo')
+    - `[Async]Collection` and `[Async]Database`: `info` method now accepts the relevant timeout parameters
+    - remove 'check_exists' from `[Async]Database.create_collection` method (the client does no checks now)
+    - removed AstraDBDatabaseAdmin's `from_api_endpoint` static method (reason: unused)
+    - remove 'database' parameter to the `to_sync()` and `to_async()` conversion methods for collections
+    - `[Async]Database.drop_collection` method accepts only the string name of the target to drop (no collection objects anymore)
+    - removed the 'CommandCursor'/'AsyncCommandCursor' classes:
+        - `AstraDBAdmin`: `list_databases`, `async_list_databases` methods return regular lists
+        - `[Async]Database`: `list_collections`, `list_tables` methods return regular lists
+    - `[Async]Database`: added a `.region` property
+
+Exceptions hierarchy reworked:
+    - removed 'CursorIsStartedException': now `CursorException` raised for all state-related illegal calls in cursors
+    - removed 'CollectionNotFoundException', replaced by a ValueError in the few cases it's needed
+    - removed `CollectionAlreadyExistsException` class (not used anymore without `check_exists`)
+    - introduced `InvalidEnvironmentException` for operations invalid on some Data API environments.
+    - renamed 'InsertManyException' ==> `CollectionInsertManyException`
+    - renamed 'DeleteManyException' ==> `CollectionDeleteManyException`
+    - renamed 'UpdateManyException' ==> `CollectionUpdateManyException`
+    - renamed 'DevOpsAPIFaultyResponseException' ==> `UnexpectedDevOpsAPIResponseException`
+    - renamed 'DataAPIFaultyResponseException' ==> `UnexpectedDataAPIResponseException`
+    - (improved string representation of DataAPIResponseException cases with multiple error descriptors)
+
+Removal of deprecated modules, objects, patterns and parameters:
     - 'core' (i.e. pre-1.0) library
     - 'collection.bulk_write' and the associated result and exception classes
     - 'vector=', 'vectorize=' and 'vectors=' parameters from collection methods
-    - 'retrieved' (=> `consumed`) and 'collection' (=> `data_source`) for cursors
     - 'set_caller' method of `DataAPIClient`, `AstraDBAdmin`, `DataAPIDatabaseAdmin`, `AstraDBDatabaseAdmin`, `[Async]Database`, `[Async]Collection`
-    - 'caller_name' and 'caller_version' parameters where `callers` is now expected
+    - 'caller_name' and 'caller_version' parameters. A single list-of-pairs `callers` is now expected
     - 'id' and 'region' to DataAPIClient's 'get_database' (and async version). Use `api_endpoint` which is now the one positional parameter.
-    - 'region' parameter of AstraDBDatabaseAdmin.get[_async]_database (was ignored already in the method)
-    - 'max_time_ms' parameter in AstraDBDatabaseAdmin's constructor and its `from_astra_db_admin` method (was already ignored in the body)
-    - The 'max_time_ms' parameter in DataAPIClient's 'get_database' method.
     - Accordingly, the syntax `client[api_endpoint]` also does not accept a database ID anymore.
+    - 'region' parameter of `AstraDBDatabaseAdmin.get[_async]_database` (was ignored already in the method)
     - 'namespace' parameter of several methods of: DataAPIClient, admin objects, Database and Collection (use `keyspace`)
     - 'namespace' property of CollectionInfo, DatabaseInfo, CollectionNotFoundException, CollectionAlreadyExistsException (use `keyspace`)
-    - 'namespace' property of Databases and Collections (switch to `keyspace`)
-    - 'update_db_namespace' parameter to for admin keyspace CRD methods (use `update_db_keyspace`)
-    - 'use_namespace' for Databases (switch to `use_keyspace`)
-    - 'delete_all' method of Collection and AsyncCollection (use `delete_many({})`)
-Removal of unused imports from toplevel __init__.py (ids, constants, cursors)
+    - 'namespace' property of `Database` and `Collection` (switch to `keyspace`)
+    - 'update_db_namespace' parameter for keyspace admin methods (use `update_db_keyspace`)
+    - 'use_namespace' for `Databases` (switch to `use_keyspace`)
+    - 'delete_all' method of `Collection` and `AsyncCollection` (use `delete_many({})`)
+
+API payloads are encoded with full Unicode (not encoded in ASCII anymore) for HTTP requests
+
+- Revision of all "spawning and copying" methods for abstractions. Parameters added/removed/renamed (switch to the corresponding parameters inside the APIOptions instead of the removed keyword parameters):
+    - All the client/admin/database/table/collection classes have an `api_options` parameter in their `with_options/to_[a]sync` method
+    - `DataAPIClient`
+        - `_copy()`, `with_options()`: removed 'callers'
+        - `get_..._database...()`: removed 'api_path', 'api_version'
+        - `get_admin()`: removed 'dev_ops_url', 'dev_ops_api_version'
+    - `AstraDBAdmin`
+        - `(_copy)`: removed 'environment', 'dev_ops_url', 'dev_ops_api_version', 'callers'
+        - `(with_options)`: removed 'callers'
+        - `(create..._database)`: added `token`, `spawn_api_options`
+        - `(get..._database)`: removed 'api_path', 'api_version', 'database_request_timeout_ms', 'database_timeout_ms'; renamed 'database_api_options' => `spawn_api_options`
+        - `(get_database_admin)`: added `token`, `spawn_api_options`
+    - `AstraDBDatabaseAdmin`
+        - `_copy()`: removed 'api_endpoint', 'environment', 'dev_ops_url', 'dev_ops_api_version', 'api_path', 'api_version', 'callers'
+        - `with_options()`: removed 'api_endpoint', 'callers'
+        - `get..._database()`: removed 'api_path', 'api_version', 'database_request_timeout_ms', 'database_timeout_ms'; renamed 'database_api_options' => `spawn_api_options`
+    - `DataAPIDatabaseAdmin`
+        - `_copy()`: removed 'api_endpoint', 'environment', 'api_path', 'api_version', 'callers'
+        - `with_options()`: removed 'api_endpoint', 'callers'
+        - `get..._database()`: removed 'api_path', 'api_version', 'database_request_timeout_ms', 'database_timeout_ms'; renamed 'database_api_options' => `spawn_api_options`
+    - `[Async]Database`
+        - `_copy()`: removed 'api_endpoint', 'callers', 'environment', 'api_path', 'api_version'
+        - `with_options()`: removed 'callers'; added `token`
+        - `to_[a]sync()`: removed 'api_endpoint', 'callers', 'environment', 'api_path', 'api_version', 
+        - `get_collection()`: removed 'collection_request_timeout_ms', 'collection_timeout_ms'; renamed 'collection_api_options' => `spawn_api_options`
+        - `get_table()`: removed 'table_request_timeout_ms', 'table_timeout_ms'; renamed 'table_api_options' => `spawn_api_options`
+        - `create_collection()`: removed 'collection_request_timeout_ms', 'collection_timeout_ms'; renamed 'collection_api_options' => `spawn_api_options`
+        - `create_table()`: removed 'table_request_timeout_ms', 'table_timeout_ms'; renamed 'table_api_options' => `spawn_api_options`
+        - `get_database_admin()`: removed 'dev_ops_url', 'dev_ops_api_version'
+    - `[Async]Collection`
+        - `_copy()`: removed 'request_timeout_ms', 'collection_timeout_ms', 'callers'
+        - `with_options`: removed 'request_timeout_ms', 'collection_timeout_ms', 'name', 'callers'
+        - `to_[a]sync()`: removed 'request_timeout_ms', 'collection_timeout_ms', 'keyspace', 'name', 'callers'
+    - `[Async]Table`
+        - `_copy()`: removed 'database', 'name', 'keyspace', 'request_timeout_ms', 'table_timeout_ms', 'callers'
+        - `with_options`: removed 'name', 'request_timeout_ms', 'table_timeout_ms', 'callers'
+        - `to_[a]sync()`: removed 'database', 'name', 'keyspace', 'request_timeout_ms', 'table_timeout_ms', 'callers'
 
+Internal restructuring/maintenance things:
+    - (not user-facing) classes in the hierarchy other than `DataAPIClient` have breaking changes in their constructor (now options-first and keyword-arg-only)
+    - Token and Embedding API key coercion into `*Provider` now happens at the Options' init layer
+    - `[Async]Collection.find_one` method uses the actual findOne API command
+    - rename main branch from 'master' ==> `main`
+    - major restructuring of the codebase in directories (some internal-only imports changed; reduced the scope of `test_imports`)
+    - removal of unused imports from toplevel `__init__.py` (ids, constants, cursors)
+    - simplified timeout management classes and representations
 
 v. 1.5.2
 ========