Bump to 2.1.0 + test improvements + better vectorize docstrings (#372)

* bring udt testing to main testing (data api merged udt to main)

* lift the DESC-TYPES-based udt cql-driven tests on Astra

* use cluster metadata in lieu of 'DESC TYPES', re-enable cql-udt testing in Astra

* reinstate regular testing of findXproviders on Astra which now has full support for apiSupport

* enable udt- and collection-columns- filtering tests for Astra as well

* Positional param to init for AlterTableOperation subclasses; drop and drop vectorize also accept a single-string input

* alter-table operation classes accept plain dicts as values in their 'columns' constructor input

* changesfile

* version bump to 2.1.0

* vectorize in db/collection docstrings

* vectorize in db/table docstrings

* type-check fixed for py 3.9 in table_altering

* make type ok for python 3.8 in table_altering.py

* unit test cover 3.13

* revert adding 3.13 to unit test versions / postponed

* upgrade hcd and data-api in HCD docker compose

* docker/podman adaptation; revert to hcd 1.2.1-early-preview for HCD testing

* style

---------

Co-authored-by: Stefano Lottini <[email protected]>

Author: hemidactylus

CHANGES

@@ -1,5 +1,13 @@
+v 2.1.0
+=======
+Same as 2.1.0rc1
+
 v 2.1.0rc1
 ==========
+AlterTableOperation subclasses:
+    - Added positional passing of parameter constructor
+    - Accept single-string parameter for the drop-column and drop-vectorize cases
+    - Add and AddVectorize constructors accept a 'columns' dict with dict values (now individually coerced)
 Switch default encode_maps_as_lists_in_tables to "DATAAPIMAPS" (no observable changes w.r.t. previous releases)
 Bugfix: fix paykload encoding for empty maps/DataAPIMaps
 User-defined types in tables:
@@ -34,6 +42,8 @@ maintenance: improve integration test coverage for:
     - tables, lexical/BM25-related DML
     - tables, logical filtering (i.e. $and, $or between clauses)
     - multiple vectorize columns in a Table
+maintenance: replaced "DESC TYPES"-based cql-driven UDT testing into cluster-metadata-inspection-based equivalent (supported on Astra)
+maintenance: streamlined several integration tests into targeting Astra as the latest Data API deploy supports the corresponding features
 maintenance: subsumed the specific testing opt-in env. var 'ASTRAPY_TEST_MAP2TUPLES=y' into the catch-all 'cutting-edge main' `ASTRAPY_TEST_LATEST_MAIN=y`
 maintenance: simplified SerdesOptions management in unit testing; some rationalization/refactoring of pre- and post-processing logic for tables in unit tests
 maintenance: switched to uv (from poetry)

README.md

@@ -726,6 +726,11 @@ Depending on the test, different environment variables are needed: refer to
 the templates in `tests/env_templates`. The "basic" credentials (one of the three options)
 are always required, _even for unit testing_.
 
+#### Docker vs. Podman
+
+In case you use a different Docker-compatible container runtime, viz. `podman`, make sure to export
+the environment variable `DOCKER_COMMAND_NAME="podman"` to have the **DockerCompose** tests use it properly.
+
 #### Multiple Python versions
 
 If may be useful to run e.g. unit tests with multiple Python versions. You can have `uv`
@@ -737,7 +742,7 @@ uv venv --python 3.8 .venv-3.8
 uv sync --dev --active
 ```
 
-Then, with the desired virtual env active, you will simply run e.g. `uv run pytest [...]`.
+Then, with the desired virtual env active, you will run e.g. `uv run --active pytest [...]`.
 
 Most make targets will also support running in the named virtual env:
 assuming you activated a certain virtual env, you can run e.g.: `make format VENV=true`.
@@ -806,11 +811,7 @@ certain environment variables, otherwise the associated tests are excluded from
 #### Cutting-edge features on `main`
 
 Prepend tests with a `ASTRAPY_TEST_LATEST_MAIN=y` for features found on `main` that are not released anywhere.
-
-#### testing UDT support
-
-Prepend tests with a `ASTRAPY_TEST_UDT=y` to enable testing of Data API support for user-defined types (UDTs).
-These integration tests are off by default, pending release on all test target environments.
+_(Tip: run a code search first to see what is currently marked as such. Chances are nothing is.)_
 
 ## Appendices
 

astrapy/data/collection.py

@@ -152,7 +152,7 @@ class Collection(Generic[DOC]):
         ...     "https://01234567-....apps.astra.datastax.com",
         ...     token="AstraCS:..."
         ... )
-
+        >>>
         >>> # Create a collection using the fluent syntax for its definition
         >>> from astrapy.constants import VectorMetric
         >>> from astrapy.info import CollectionDefinition
@@ -168,7 +168,7 @@ class Collection(Generic[DOC]):
         ...     "my_events",
         ...     definition=collection_definition,
         ... )
-
+        >>>
         >>>
         >>> # Create a collection with the definition as object
         >>> from astrapy.info import CollectionVectorOptions
@@ -185,7 +185,7 @@ class Collection(Generic[DOC]):
         ...     definition=collection_definition_1,
         ... )
         >>>
-
+        >>>
         >>> # Create a collection with the definition as plain dictionary
         >>> collection_definition_2 = {
         ...     "indexing": {"deny": ["annotations", "logs"]},
@@ -198,12 +198,50 @@ class Collection(Generic[DOC]):
         ...     "my_events",
         ...     definition=collection_definition_2,
         ... )
-
+        >>>
         >>> # Get a reference to an existing collection
         >>> # (no checks are performed on DB)
         >>> my_collection_3a = database.get_collection("my_events")
         >>> my_collection_3b = database.my_events
         >>> my_collection_3c = database["my_events"]
+        >>>
+        >>> # Examples with an embedding service ('vectorize'):
+        >>>
+        >>> # Create a collection with 'vectorize' and on-the-fly authentication (by headers)
+        >>> collection_definition_vz1 = (
+        ...     CollectionDefinition.builder()
+        ...     .set_vector_service(
+        ...         "openai",
+        ...         "text-embedding-3-small",
+        ...     )
+        ...     .build()
+        ... )
+        >>> my_collection_vz1 = database.create_collection(
+        ...     "my_entries",
+        ...     definition=collection_definition_vz1,
+        ...     embedding_api_key="sk-...",
+        ... )
+        >>>
+        >>>
+        >>> # Create a 'vectorize' collection, its secret pre-stored on DB as 'EMB_AUTH_KEY'
+        >>> collection_definition_vz2 = (
+        ...     CollectionDefinition.builder()
+        ...     .set_vector_service(
+        ...         "openai",
+        ...         "text-embedding-3-small",
+        ...         authentication={
+        ...             "providerKey": "EMB_AUTH_KEY",
+        ...         },
+        ...     )
+        ...     .build()
+        ... )
+        >>> my_collection_vz2 = database.create_collection(
+        ...     "my_kms_entries",
+        ...     definition=collection_definition_vz2,
+        ... )
+        >>>
+        >>> # Get a reference to an existing collection and set its 'vectorize' authentication:
+        >>> my_collection_vz1a = database.get_collection("my_entries", embedding_api_key="sk-...")
 
     Note:
         creating an instance of Collection does not trigger actual creation
@@ -3066,7 +3104,7 @@ class AsyncCollection(Generic[DOC]):
         ...     "https://01234567-....apps.astra.datastax.com",
         ...     token="AstraCS:..."
         ... )
-
+        >>>
         >>> # Create a collection using the fluent syntax for its definition
         >>> from astrapy.constants import VectorMetric
         >>> from astrapy.info import CollectionDefinition
@@ -3082,7 +3120,7 @@ class AsyncCollection(Generic[DOC]):
         ...     "my_events",
         ...     definition=collection_definition,
         ... )
-
+        >>>
         >>>
         >>> # Create a collection with the definition as object
         >>> from astrapy.info import CollectionVectorOptions
@@ -3099,7 +3137,7 @@ class AsyncCollection(Generic[DOC]):
         ...     definition=collection_definition_1,
         ... )
         >>>
-
+        >>>
         >>> # Create a collection with the definition as plain dictionary
         >>> collection_definition_2 = {
         ...     "indexing": {"deny": ["annotations", "logs"]},
@@ -3112,12 +3150,50 @@ class AsyncCollection(Generic[DOC]):
         ...     "my_events",
         ...     definition=collection_definition_2,
         ... )
-
+        >>>
         >>> # Get a reference to an existing collection
         >>> # (no checks are performed on DB)
         >>> my_collection_3a = async_database.get_collection("my_events")
         >>> my_collection_3b = async_database.my_events
         >>> my_collection_3c = async_database["my_events"]
+        >>>
+        >>> # Examples with an embedding service ('vectorize'):
+        >>>
+        >>> # Create a collection with 'vectorize' and on-the-fly authentication (by headers)
+        >>> collection_definition_vz1 = (
+        ...     CollectionDefinition.builder()
+        ...     .set_vector_service(
+        ...         "openai",
+        ...         "text-embedding-3-small",
+        ...     )
+        ...     .build()
+        ... )
+        >>> my_collection_vz1 = await async_database.create_collection(
+        ...     "my_entries",
+        ...     definition=collection_definition_vz1,
+        ...     embedding_api_key="sk-...",
+        ... )
+        >>>
+        >>>
+        >>> # Create a 'vectorize' collection, its secret pre-stored on DB as 'EMB_AUTH_KEY'
+        >>> collection_definition_vz2 = (
+        ...     CollectionDefinition.builder()
+        ...     .set_vector_service(
+        ...         "openai",
+        ...         "text-embedding-3-small",
+        ...         authentication={
+        ...             "providerKey": "EMB_AUTH_KEY",
+        ...         },
+        ...     )
+        ...     .build()
+        ... )
+        >>> my_collection_vz2 = await async_database.create_collection(
+        ...     "my_kms_entries",
+        ...     definition=collection_definition_vz2,
+        ... )
+        >>>
+        >>> # Get a reference to an existing collection and set its 'vectorize' authentication:
+        >>> my_collection_vz1a = async_database.get_collection("my_entries", embedding_api_key="sk-...")
 
     Note:
         creating an instance of AsyncCollection does not trigger actual creation