From b0ec27c278ffb59a86d2c515c7ea83c9f1cd5a9d Mon Sep 17 00:00:00 2001 From: Eric Pinzur Date: Tue, 11 Mar 2025 16:51:34 -0500 Subject: [PATCH 1/3] added code generation example --- data/astrapy.jsonl | 1081 +++++++++++++++++ docs/examples/code-generation.ipynb | 817 +++++++++++++ docs/examples/index.md | 18 +- docs/examples/lazy-graph-rag.ipynb | 7 + .../graph-rag-example-helpers/pyproject.toml | 2 + .../datasets/astrapy/__init__.py | 9 + .../datasets/astrapy/fetch.py | 40 + .../examples/__init__.py | 0 .../examples/code_generation/__init__.py | 7 + .../examples/code_generation/converter.py | 450 +++++++ .../examples/code_generation/format.py | 103 ++ .../src/graph_rag_example_helpers/utils.py | 3 + packages/graph-retriever/pyproject.toml | 1 + .../langchain-graph-retriever/pyproject.toml | 1 + uv.lock | 13 +- 15 files changed, 2546 insertions(+), 6 deletions(-) create mode 100644 data/astrapy.jsonl create mode 100644 docs/examples/code-generation.ipynb create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/__init__.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py create mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py diff --git a/data/astrapy.jsonl b/data/astrapy.jsonl new file mode 100644 index 00000000..11ed2a1d --- /dev/null +++ b/data/astrapy.jsonl @@ -0,0 +1,1081 @@ +{"id": "astrapy", "text": "", "metadata": {"kind": "module", "name": "astrapy", "path": "astrapy", "imports": {"annotations": "__future__.annotations", "importlib": "importlib", "os": "os", "toml": "toml", "astrapy": "astrapy", "AstraDBAdmin": "astrapy.admin.AstraDBAdmin", "AstraDBDatabaseAdmin": "astrapy.admin.AstraDBDatabaseAdmin", "DataAPIDatabaseAdmin": "astrapy.admin.DataAPIDatabaseAdmin", "DataAPIClient": "astrapy.client.DataAPIClient", "AsyncCollection": "astrapy.collection.AsyncCollection", "Collection": "astrapy.collection.Collection", "AsyncDatabase": "astrapy.database.AsyncDatabase", "Database": "astrapy.database.Database"}, "exports": ["DataAPIClient", "Collection", "AsyncCollection", "AsyncDatabase", "__version__", "AstraDBAdmin", "DataAPIDatabaseAdmin", "Database", "AstraDBDatabaseAdmin"], "properties": {"is_init_module": true, "is_package": true, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.get_version", "text": "", "metadata": {"kind": "function", "name": "get_version", "path": "astrapy.get_version", "returns": [{"type": "str"}]}} +{"id": "astrapy.api_options", "text": "", "metadata": {"kind": "module", "name": "api_options", "path": "astrapy.api_options", "imports": {"annotations": "__future__.annotations", "dataclass": "dataclasses.dataclass", "field": "dataclasses.field", "TypeVar": "typing.TypeVar", "EmbeddingAPIKeyHeaderProvider": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "EmbeddingHeadersProvider": "astrapy.authentication.EmbeddingHeadersProvider"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.api_options.AO", "text": "", "metadata": {"kind": "attribute", "name": "AO", "path": "astrapy.api_options.AO", "value": "AO = TypeVar('AO', bound='BaseAPIOptions')"}} +{"id": "astrapy.api_options.BaseAPIOptions", "text": "A description of the options about how to interact with the Data API.", "metadata": {"kind": "class", "name": "BaseAPIOptions", "path": "astrapy.api_options.BaseAPIOptions", "parameters": [{"name": "max_time_ms", "default": "None", "type": "int | None"}], "attributes": [{"name": "max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense."}]}} +{"id": "astrapy.api_options.BaseAPIOptions.max_time_ms", "text": "", "metadata": {"kind": "attribute", "name": "max_time_ms", "path": "astrapy.api_options.BaseAPIOptions.max_time_ms", "value": "max_time_ms: int | None = None"}} +{"id": "astrapy.api_options.BaseAPIOptions.with_default", "text": "Return a new instance created by completing this instance with a default\nAPI options object.\n\nIn other words, `optA.with_default(optB)` will take fields from optA\nwhen possible and draw defaults from optB when optA has them set to anything\nevaluating to False. (This relies on the __bool__ definition of the values,\nsuch as that of the EmbeddingHeadersTokenProvider instances)", "metadata": {"kind": "function", "name": "with_default", "path": "astrapy.api_options.BaseAPIOptions.with_default", "parameters": [{"name": "default", "type": "BaseAPIOptions | None", "description": "an API options instance to draw defaults from.", "default": null}], "returns": [{"type": "AO", "description": "a new instance of this class obtained by merging this one and the default."}], "gathered_types": ["AO", "BaseAPIOptions"]}} +{"id": "astrapy.api_options.BaseAPIOptions.with_override", "text": "Return a new instance created by overriding the members of this instance\nwith those taken from a supplied \"override\" API options object.\n\nIn other words, `optA.with_default(optB)` will take fields from optB\nwhen possible and fall back to optA when optB has them set to anything\nevaluating to False. (This relies on the __bool__ definition of the values,\nsuch as that of the EmbeddingHeadersTokenProvider instances)", "metadata": {"kind": "function", "name": "with_override", "path": "astrapy.api_options.BaseAPIOptions.with_override", "parameters": [{"name": "override", "type": "BaseAPIOptions | None", "description": "an API options instance to preferentially draw fields from.", "default": null}], "returns": [{"type": "AO", "description": "a new instance of this class obtained by merging the override and this one."}], "gathered_types": ["AO", "BaseAPIOptions"]}} +{"id": "astrapy.api_options.CollectionAPIOptions", "text": "A description of the options about how to interact with the Data API\nregarding a collection.\nDevelopers should not instantiate this class directly.", "metadata": {"kind": "class", "name": "CollectionAPIOptions", "path": "astrapy.api_options.CollectionAPIOptions", "parameters": [{"name": "max_time_ms", "default": "None", "type": "int | None"}, {"name": "embedding_api_key", "default": "lambda: EmbeddingAPIKeyHeaderProvider(None)()", "type": "EmbeddingHeadersProvider"}], "bases": ["BaseAPIOptions"], "attributes": [{"name": "max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense."}, {"name": "embedding_api_key", "type": "EmbeddingHeadersProvider", "description": "an `astrapy.authentication.EmbeddingHeadersProvider`\nobject, encoding embedding-related API keys that will be passed\nas headers when interacting with the collection (on each Data API request).\nThe default value is `EmbeddingAPIKeyHeaderProvider(None)`, i.e.\nno embedding-specific headers, whereas if the collection is configured\nwith an embedding service other choices for this parameter can be\nmeaningfully supplied. is configured for the collection,"}], "gathered_types": ["astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "astrapy.authentication.EmbeddingHeadersProvider", "BaseAPIOptions"]}} +{"id": "astrapy.api_options.CollectionAPIOptions.embedding_api_key", "text": "", "metadata": {"kind": "attribute", "name": "embedding_api_key", "path": "astrapy.api_options.CollectionAPIOptions.embedding_api_key", "value": "embedding_api_key: EmbeddingHeadersProvider = field(default_factory=lambda: EmbeddingAPIKeyHeaderProvider(None))", "gathered_types": ["astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "astrapy.authentication.EmbeddingHeadersProvider"]}} +{"id": "astrapy.results", "text": "", "metadata": {"kind": "module", "name": "results", "path": "astrapy.results", "imports": {"annotations": "__future__.annotations", "ABC": "abc.ABC", "abstractmethod": "abc.abstractmethod", "dataclass": "dataclasses.dataclass", "Any": "typing.Any"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.results.OperationResult", "text": "Class that represents the generic result of a single mutation operation.", "metadata": {"kind": "class", "name": "OperationResult", "path": "astrapy.results.OperationResult", "parameters": [{"name": "raw_results", "type": "list[dict[str, Any]]"}], "bases": ["ABC"], "attributes": [{"name": "raw_results", "type": "list[dict[str, Any]]", "description": "response/responses from the Data API call.\nDepending on the exact delete method being used, this\nlist of raw responses can contain exactly one or a number of items."}], "gathered_types": ["ABC"], "implemented_by": ["astrapy.results.DeleteResult", "astrapy.results.InsertManyResult", "astrapy.results.UpdateResult", "astrapy.results.InsertOneResult"]}} +{"id": "astrapy.results.OperationResult.raw_results", "text": "", "metadata": {"kind": "attribute", "name": "raw_results", "path": "astrapy.results.OperationResult.raw_results", "value": "raw_results: list[dict[str, Any]]"}} +{"id": "astrapy.results.OperationResult.to_bulk_write_result", "text": "", "metadata": {"kind": "function", "name": "to_bulk_write_result", "path": "astrapy.results.OperationResult.to_bulk_write_result", "parameters": [{"name": "index_in_bulk_write", "type": "int"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.results.DeleteResult", "text": "Class that represents the result of delete operations.", "metadata": {"kind": "class", "name": "DeleteResult", "path": "astrapy.results.DeleteResult", "parameters": [{"name": "raw_results", "type": "list[dict[str, Any]]"}, {"name": "deleted_count", "type": "int"}], "bases": ["astrapy.results.OperationResult"], "attributes": [{"name": "deleted_count", "type": "int", "description": "number of deleted documents"}, {"name": "raw_results", "type": "list[dict[str, Any]]", "description": "response/responses from the Data API call.\nDepending on the exact delete method being used, this\nlist of raw responses can contain exactly one or a number of items."}], "gathered_types": ["astrapy.results.OperationResult"]}} +{"id": "astrapy.results.DeleteResult.deleted_count", "text": "", "metadata": {"kind": "attribute", "name": "deleted_count", "path": "astrapy.results.DeleteResult.deleted_count", "value": "deleted_count: int"}} +{"id": "astrapy.results.DeleteResult.to_bulk_write_result", "text": "", "metadata": {"kind": "function", "name": "to_bulk_write_result", "path": "astrapy.results.DeleteResult.to_bulk_write_result", "parameters": [{"name": "index_in_bulk_write", "type": "int"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.results.InsertOneResult", "text": "Class that represents the result of insert_one operations.", "metadata": {"kind": "class", "name": "InsertOneResult", "path": "astrapy.results.InsertOneResult", "parameters": [{"name": "raw_results", "type": "list[dict[str, Any]]"}, {"name": "inserted_id", "type": "Any"}], "bases": ["astrapy.results.OperationResult"], "attributes": [{"name": "raw_results", "type": "list[dict[str, Any]]", "description": "one-item list with the response from the Data API call"}, {"name": "inserted_id", "type": "Any", "description": "the ID of the inserted document"}], "gathered_types": ["astrapy.results.OperationResult"]}} +{"id": "astrapy.results.InsertOneResult.inserted_id", "text": "", "metadata": {"kind": "attribute", "name": "inserted_id", "path": "astrapy.results.InsertOneResult.inserted_id", "value": "inserted_id: Any"}} +{"id": "astrapy.results.InsertOneResult.to_bulk_write_result", "text": "", "metadata": {"kind": "function", "name": "to_bulk_write_result", "path": "astrapy.results.InsertOneResult.to_bulk_write_result", "parameters": [{"name": "index_in_bulk_write", "type": "int"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.results.InsertManyResult", "text": "Class that represents the result of insert_many operations.", "metadata": {"kind": "class", "name": "InsertManyResult", "path": "astrapy.results.InsertManyResult", "parameters": [{"name": "raw_results", "type": "list[dict[str, Any]]"}, {"name": "inserted_ids", "type": "list[Any]"}], "bases": ["astrapy.results.OperationResult"], "attributes": [{"name": "raw_results", "type": "list[dict[str, Any]]", "description": "responses from the Data API calls"}, {"name": "inserted_ids", "type": "list[Any]", "description": "list of the IDs of the inserted documents"}], "gathered_types": ["astrapy.results.OperationResult"]}} +{"id": "astrapy.results.InsertManyResult.inserted_ids", "text": "", "metadata": {"kind": "attribute", "name": "inserted_ids", "path": "astrapy.results.InsertManyResult.inserted_ids", "value": "inserted_ids: list[Any]"}} +{"id": "astrapy.results.InsertManyResult.to_bulk_write_result", "text": "", "metadata": {"kind": "function", "name": "to_bulk_write_result", "path": "astrapy.results.InsertManyResult.to_bulk_write_result", "parameters": [{"name": "index_in_bulk_write", "type": "int"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.results.UpdateResult", "text": "Class that represents the result of any update operation.", "metadata": {"kind": "class", "name": "UpdateResult", "path": "astrapy.results.UpdateResult", "parameters": [{"name": "raw_results", "type": "list[dict[str, Any]]"}, {"name": "update_info", "type": "dict[str, Any]"}], "bases": ["astrapy.results.OperationResult"], "attributes": [{"name": "raw_results", "type": "list[dict[str, Any]]", "description": "responses from the Data API calls"}, {"name": "update_info", "type": "dict[str, Any]", "description": "a dictionary reporting about the update"}], "note": "the \"update_info\" field has the following fields: \"n\" (int),\n\"updatedExisting\" (bool), \"ok\" (float), \"nModified\" (int)\nand optionally \"upserted\" containing the ID of an upserted document.", "gathered_types": ["astrapy.results.OperationResult"]}} +{"id": "astrapy.results.UpdateResult.update_info", "text": "", "metadata": {"kind": "attribute", "name": "update_info", "path": "astrapy.results.UpdateResult.update_info", "value": "update_info: dict[str, Any]"}} +{"id": "astrapy.results.UpdateResult.to_bulk_write_result", "text": "", "metadata": {"kind": "function", "name": "to_bulk_write_result", "path": "astrapy.results.UpdateResult.to_bulk_write_result", "parameters": [{"name": "index_in_bulk_write", "type": "int"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.results.BulkWriteResult", "text": "Class that represents the result of a bulk write operations.\n\nIndices in the maps below refer to the position of each write operation\nin the list of operations passed to the bulk_write command.\n\nThe numeric counts refer to the whole of the bulk write.", "metadata": {"kind": "class", "name": "BulkWriteResult", "path": "astrapy.results.BulkWriteResult", "parameters": [{"name": "bulk_api_results", "type": "dict[int, list[dict[str, Any]]]"}, {"name": "deleted_count", "type": "int"}, {"name": "inserted_count", "type": "int"}, {"name": "matched_count", "type": "int"}, {"name": "modified_count", "type": "int"}, {"name": "upserted_count", "type": "int"}, {"name": "upserted_ids", "type": "dict[int, Any]"}], "attributes": [{"name": "bulk_api_results", "type": "dict[int, list[dict[str, Any]]]", "description": "a map from indices to the corresponding raw responses"}, {"name": "deleted_count", "type": "int", "description": "number of deleted documents"}, {"name": "inserted_count", "type": "int", "description": "number of inserted documents"}, {"name": "matched_count", "type": "int", "description": "number of matched documents"}, {"name": "modified_count", "type": "int", "description": "number of modified documents"}, {"name": "upserted_count", "type": "int", "description": "number of upserted documents"}, {"name": "upserted_ids", "type": "dict[int, Any]", "description": "a (sparse) map from indices to ID of the upserted document"}]}} +{"id": "astrapy.results.BulkWriteResult.bulk_api_results", "text": "", "metadata": {"kind": "attribute", "name": "bulk_api_results", "path": "astrapy.results.BulkWriteResult.bulk_api_results", "value": "bulk_api_results: dict[int, list[dict[str, Any]]]"}} +{"id": "astrapy.results.BulkWriteResult.deleted_count", "text": "", "metadata": {"kind": "attribute", "name": "deleted_count", "path": "astrapy.results.BulkWriteResult.deleted_count", "value": "deleted_count: int"}} +{"id": "astrapy.results.BulkWriteResult.inserted_count", "text": "", "metadata": {"kind": "attribute", "name": "inserted_count", "path": "astrapy.results.BulkWriteResult.inserted_count", "value": "inserted_count: int"}} +{"id": "astrapy.results.BulkWriteResult.matched_count", "text": "", "metadata": {"kind": "attribute", "name": "matched_count", "path": "astrapy.results.BulkWriteResult.matched_count", "value": "matched_count: int"}} +{"id": "astrapy.results.BulkWriteResult.modified_count", "text": "", "metadata": {"kind": "attribute", "name": "modified_count", "path": "astrapy.results.BulkWriteResult.modified_count", "value": "modified_count: int"}} +{"id": "astrapy.results.BulkWriteResult.upserted_count", "text": "", "metadata": {"kind": "attribute", "name": "upserted_count", "path": "astrapy.results.BulkWriteResult.upserted_count", "value": "upserted_count: int"}} +{"id": "astrapy.results.BulkWriteResult.upserted_ids", "text": "", "metadata": {"kind": "attribute", "name": "upserted_ids", "path": "astrapy.results.BulkWriteResult.upserted_ids", "value": "upserted_ids: dict[int, Any]"}} +{"id": "astrapy.results.BulkWriteResult.zero", "text": "Return an empty BulkWriteResult, for use in no-ops and list reductions.", "metadata": {"kind": "function", "name": "zero", "path": "astrapy.results.BulkWriteResult.zero", "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.database", "text": "", "metadata": {"kind": "module", "name": "database", "path": "astrapy.database", "imports": {"annotations": "__future__.annotations", "logging": "logging", "warnings": "warnings", "TracebackType": "types.TracebackType", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Sequence": "typing.Sequence", "deprecation": "deprecation", "__version__": "astrapy.__version__", "fetch_database_info": "astrapy.admin.fetch_database_info", "parse_api_endpoint": "astrapy.admin.parse_api_endpoint", "APICommander": "astrapy.api_commander.APICommander", "CollectionAPIOptions": "astrapy.api_options.CollectionAPIOptions", "coerce_embedding_headers_provider": "astrapy.authentication.coerce_embedding_headers_provider", "coerce_token_provider": "astrapy.authentication.coerce_token_provider", "redact_secret": "astrapy.authentication.redact_secret", "CallerType": "astrapy.constants.CallerType", "Environment": "astrapy.constants.Environment", "AsyncCommandCursor": "astrapy.cursors.AsyncCommandCursor", "CommandCursor": "astrapy.cursors.CommandCursor", "API_PATH_ENV_MAP": "astrapy.defaults.API_PATH_ENV_MAP", "API_VERSION_ENV_MAP": "astrapy.defaults.API_VERSION_ENV_MAP", "DEFAULT_ASTRA_DB_KEYSPACE": "astrapy.defaults.DEFAULT_ASTRA_DB_KEYSPACE", "DEFAULT_DATA_API_AUTH_HEADER": "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "NAMESPACE_DEPRECATION_NOTICE_METHOD": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_METHOD", "SET_CALLER_DEPRECATION_NOTICE": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "CollectionAlreadyExistsException": "astrapy.exceptions.CollectionAlreadyExistsException", "DataAPIFaultyResponseException": "astrapy.exceptions.DataAPIFaultyResponseException", "DevOpsAPIException": "astrapy.exceptions.DevOpsAPIException", "MultiCallTimeoutManager": "astrapy.exceptions.MultiCallTimeoutManager", "base_timeout_info": "astrapy.exceptions.base_timeout_info", "CollectionDescriptor": "astrapy.info.CollectionDescriptor", "CollectionVectorServiceOptions": "astrapy.info.CollectionVectorServiceOptions", "DatabaseInfo": "astrapy.info.DatabaseInfo", "check_caller_parameters": "astrapy.meta.check_caller_parameters", "check_namespace_keyspace": "astrapy.meta.check_namespace_keyspace", "DatabaseAdmin": "astrapy.admin.DatabaseAdmin", "EmbeddingHeadersProvider": "astrapy.authentication.EmbeddingHeadersProvider", "TokenProvider": "astrapy.authentication.TokenProvider", "AsyncCollection": "astrapy.collection.AsyncCollection", "Collection": "astrapy.collection.Collection"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.database.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.database.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.database.Database", "text": "A Data API database. This is the object for doing database-level\nDML, such as creating/deleting collections, and for obtaining Collection\nobjects themselves. This class has a synchronous interface.\n\nThe usual way of obtaining one Database is through the `get_database`\nmethod of a `DataAPIClient`.\n\nOn Astra DB, a Database comes with an \"API Endpoint\", which implies\na Database object instance reaches a specific region (relevant point in\ncase of multi-region databases).", "metadata": {"kind": "class", "name": "Database", "path": "astrapy.database.Database", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the full \"API Endpoint\" string used to reach the Data API.\nExample: \"https://-.apps.astra.datastax.com\"", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: \"AstraCS:xyz...\"\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, on Astra DB the name \"default_keyspace\" is set,\nwhile on other environments the keyspace is left unspecified: in this case,\nmost operations are unavailable until a keyspace is set (through an explicit\n`use_keyspace` invocation or equivalent).", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a string representing the target Data API environment.\nIt can be left unspecified for the default value of `Environment.PROD`;\nother values include `Environment.OTHER`, `Environment.DSE`.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default (sensibly chosen based on the environment).", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient\n>>> my_client = astrapy.DataAPIClient(\"AstraCS:...\")\n>>> my_db = my_client.get_database(\n... \"https://01234567-....apps.astra.datastax.com\"\n... )", "note": "creating an instance of Database does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.database.Database.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.database.Database.environment", "value": "environment = environment or Environment.PROD.lower()", "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.database.Database.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.database.Database.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.database.Database.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.database.Database.api_endpoint", "value": "api_endpoint = api_endpoint.strip('/')"}} +{"id": "astrapy.database.Database.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.database.Database.api_path", "value": "api_path = _api_path", "gathered_types": ["_api_path"]}} +{"id": "astrapy.database.Database.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.database.Database.api_version", "value": "api_version = _api_version", "gathered_types": ["_api_version"]}} +{"id": "astrapy.database.Database.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.database.Database.callers", "value": "callers = callers_param"}} +{"id": "astrapy.database.Database.with_options", "text": "Create a clone of this database with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.database.Database.with_options", "parameters": [{"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, the name \"default_keyspace\" is set.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "a new `Database` instance."}], "example": ">>> my_db_2 = my_db.with_options(\n... keyspace=\"the_other_keyspace\",\n... callers=[(\"the_caller\", \"0.1.0\")],\n... )", "gathered_types": ["astrapy.database.Database", "astrapy.constants.CallerType"]}} +{"id": "astrapy.database.Database.to_async", "text": "Create an AsyncDatabase from this one. Save for the arguments\nexplicitly provided as overrides, everything else is kept identical\nto this database in the copy.", "metadata": {"kind": "function", "name": "to_async", "path": "astrapy.database.Database.to_async", "parameters": [{"name": "api_endpoint", "type": "str | None", "description": "the full \"API Endpoint\" string used to reach the Data API.\nExample: \"https://-.apps.astra.datastax.com\"", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: \"AstraCS:xyz...\"\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, the name \"default_keyspace\" is set.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a string representing the target Data API environment.\nValues are, for example, `Environment.PROD`, `Environment.OTHER`,\nor `Environment.DSE`.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "returns": [{"type": "AsyncDatabase", "description": "the new copy, an `AsyncDatabase` instance."}], "example": ">>> my_async_db = my_db.to_async()\n>>> asyncio.run(my_async_db.list_collection_names())", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.database.Database.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe Data API calls are performed (the \"caller\").", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.database.Database.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe Data API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_db.set_caller(caller_name=\"the_caller\", caller_version=\"0.1.0\")"}} +{"id": "astrapy.database.Database.use_namespace", "text": "Switch to a new working namespace for this database.\nThis method changes (mutates) the Database instance.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"use_keyspace\" method.**\n\nNote that this method does not create the namespace, which should exist\nalready (created for instance with a `DatabaseAdmin.create_namespace` call).", "metadata": {"kind": "function", "name": "use_namespace", "path": "astrapy.database.Database.use_namespace", "parameters": [{"name": "namespace", "type": "str", "description": "the new namespace to use as the database working namespace.", "default": null}], "returns": [{"type": "None", "description": "None."}], "example": ">>> my_db.list_collection_names()\n['coll_1', 'coll_2']\n>>> my_db.use_namespace(\"an_empty_namespace\")\n>>> my_db.list_collection_names()\n[]"}} +{"id": "astrapy.database.Database.use_keyspace", "text": "Switch to a new working keyspace for this database.\nThis method changes (mutates) the Database instance.\n\nNote that this method does not create the keyspace, which should exist\nalready (created for instance with a `DatabaseAdmin.create_keyspace` call).", "metadata": {"kind": "function", "name": "use_keyspace", "path": "astrapy.database.Database.use_keyspace", "parameters": [{"name": "keyspace", "type": "str", "description": "the new keyspace to use as the database working keyspace.", "default": null}], "returns": [{"type": "None", "description": "None."}], "example": ">>> my_db.list_collection_names()\n['coll_1', 'coll_2']\n>>> my_db.use_keyspace(\"an_empty_keyspace\")\n>>> my_db.list_collection_names()\n[]"}} +{"id": "astrapy.database.Database.info", "text": "Additional information on the database as a DatabaseInfo instance.\n\nSome of the returned properties are dynamic throughout the lifetime\nof the database (such as raw_info[\"keyspaces\"]). For this reason,\neach invocation of this method triggers a new request to the DevOps API.", "metadata": {"kind": "function", "name": "info", "path": "astrapy.database.Database.info", "returns": [{"type": "DatabaseInfo"}], "example": ">>> my_db.info().region\n'eu-west-1'\n\n>>> my_db.info().raw_info['datacenters'][0]['dateCreated']\n'2023-01-30T12:34:56Z'", "note": "see the DatabaseInfo documentation for a caveat about the difference\nbetween the `region` and the `raw_info[\"region\"]` attributes.", "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.database.Database.id", "text": "The ID of this database.", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.database.Database.id", "value": "id: str", "example": ">>> my_db.id\n'01234567-89ab-cdef-0123-456789abcdef'"}} +{"id": "astrapy.database.Database.name", "text": "The name of this database. Note that this bears no unicity guarantees.\n\nCalling this method the first time involves a request\nto the DevOps API (the resulting database name is then cached).\nSee the `info()` method for more details.", "metadata": {"kind": "function", "name": "name", "path": "astrapy.database.Database.name", "returns": [{"type": "str"}], "example": ">>> my_db.name()\n'the_application_database'"}} +{"id": "astrapy.database.Database.namespace", "text": "The namespace this database uses as target for all commands when\nno method-call-specific namespace is specified.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.database.Database.namespace", "value": "namespace: str | None", "returns": [{"type": "str | None", "description": "the working namespace (a string), or None if not set."}], "example": ">>> my_db.namespace\n'the_keyspace'"}} +{"id": "astrapy.database.Database.keyspace", "text": "The keyspace this database uses as target for all commands when\nno method-call-specific keyspace is specified.", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.database.Database.keyspace", "value": "keyspace: str | None", "returns": [{"type": "str | None", "description": "the working keyspace (a string), or None if not set."}], "example": ">>> my_db.keyspace\n'the_keyspace'"}} +{"id": "astrapy.database.Database.get_collection", "text": "Spawn a `Collection` object instance representing a collection\non this database.\n\nCreating a `Collection` instance does not have any effect on the\nactual state of the database: in other words, for the created\n`Collection` instance to be used meaningfully, the collection\nmust exist already (for instance, it should have been created\npreviously by calling the `create_collection` method).", "metadata": {"kind": "function", "name": "get_collection", "path": "astrapy.database.Database.get_collection", "parameters": [{"name": "name", "type": "str", "description": "the name of the collection.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace containing the collection. If no keyspace\nis specified, the general setting for this database is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based\nauthentication, specialized subclasses of\n`astrapy.authentication.EmbeddingHeadersProvider` should be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration\nof each operation on the collection. Individual timeouts can be\nprovided to each collection method call and will take precedence, with\nthis value being an overall default.\nNote that for some methods involving multiple API calls (such as `find`,\n`delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}], "returns": [{"type": "Collection", "description": "a `Collection` instance, representing the desired collection\n(but without any form of validation)."}], "example": ">>> my_col = my_db.get_collection(\"my_collection\")\n>>> my_col.count_documents({}, upper_bound=100)\n41", "note": "The attribute and indexing syntax forms achieve the same effect\nas this method. In other words, the following are equivalent:\n my_db.get_collection(\"coll_name\")\n my_db.coll_name\n my_db[\"coll_name\"]", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider"]}} +{"id": "astrapy.database.Database.create_collection", "text": "Creates a collection on the database and return the Collection\ninstance that represents it.\n\nThis is a blocking operation: the method returns when the collection\nis ready to be used. As opposed to the `get_collection` instance,\nthis method triggers causes the collection to be actually created on DB.", "metadata": {"kind": "function", "name": "create_collection", "path": "astrapy.database.Database.create_collection", "parameters": [{"name": "name", "type": "str", "description": "the name of the collection.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace where the collection is to be created.\nIf not specified, the general setting for this database is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "dimension", "type": "int | None", "description": "for vector collections, the dimension of the vectors\n(i.e. the number of their components).", "value": "None", "default": "None"}, {"name": "metric", "type": "str | None", "description": "the similarity metric used for vector searches.\nAllowed values are `VectorMetric.DOT_PRODUCT`, `VectorMetric.EUCLIDEAN`\nor `VectorMetric.COSINE` (default).", "value": "None", "default": "None"}, {"name": "service", "type": "CollectionVectorServiceOptions | dict[str, Any] | None", "description": "a dictionary describing a service for\nembedding computation, e.g. `{\"provider\": \"ab\", \"modelName\": \"xy\"}`.\nAlternatively, a CollectionVectorServiceOptions object to the same effect.", "value": "None", "default": "None"}, {"name": "indexing", "type": "dict[str, Any] | None", "description": "optional specification of the indexing options for\nthe collection, in the form of a dictionary such as\n {\"deny\": [...]}\nor\n {\"allow\": [...]}", "value": "None", "default": "None"}, {"name": "default_id_type", "type": "str | None", "description": "this sets what type of IDs the API server will\ngenerate when inserting documents that do not specify their\n`_id` field explicitly. Can be set to any of the values\n`DefaultIdType.UUID`, `DefaultIdType.OBJECTID`,\n`DefaultIdType.UUIDV6`, `DefaultIdType.UUIDV7`,\n`DefaultIdType.DEFAULT`.", "value": "None", "default": "None"}, {"name": "additional_options", "type": "dict[str, Any] | None", "description": "any further set of key-value pairs that will\nbe added to the \"options\" part of the payload when sending\nthe Data API command to create a collection.", "value": "None", "default": "None"}, {"name": "check_exists", "type": "bool | None", "description": "whether to run an existence check for the collection\nname before attempting to create the collection:\nIf check_exists is True, an error is raised when creating\nan existing collection.\nIf it is False, the creation is attempted. In this case, for\npreexisting collections, the command will succeed or fail\ndepending on whether the options match or not.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}], "returns": [{"type": "Collection", "description": "a (synchronous) `Collection` instance, representing the"}, {"type": "Collection", "description": "newly-created collection."}], "example": ">>> new_col = my_db.create_collection(\"my_v_col\", dimension=3)\n>>> new_col.insert_one({\"name\": \"the_row\", \"$vector\": [0.4, 0.5, 0.7]})\nInsertOneResult(raw_results=..., inserted_id='e22dd65e-...-...-...')", "note": "A collection is considered a vector collection if at least one of\n`dimension` or `service` are provided and not null. In that case,\nand only in that case, is `metric` an accepted parameter.\nNote, moreover, that if passing both these parameters, then\nthe dimension must be compatible with the chosen service.", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider", "astrapy.info.CollectionVectorServiceOptions"]}} +{"id": "astrapy.database.Database.drop_collection", "text": "Drop a collection from the database, along with all documents therein.", "metadata": {"kind": "function", "name": "drop_collection", "path": "astrapy.database.Database.drop_collection", "parameters": [{"name": "name_or_collection", "type": "str | Collection", "description": "either the name of a collection or\na `Collection` instance.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary in the form {\"ok\": 1} if the command succeeds."}], "example": ">>> my_db.list_collection_names()\n['a_collection', 'my_v_col', 'another_col']\n>>> my_db.drop_collection(\"my_v_col\")\n{'ok': 1}\n>>> my_db.list_collection_names()\n['a_collection', 'another_col']", "note": "when providing a collection name, it is assumed that the collection\nis to be found in the keyspace that was set at database instance level."}} +{"id": "astrapy.database.Database.list_collections", "text": "List all collections in a given keyspace for this database.", "metadata": {"kind": "function", "name": "list_collections", "path": "astrapy.database.Database.list_collections", "parameters": [{"name": "keyspace", "type": "str | None", "description": "the keyspace to be inspected. If not specified,\nthe general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "CommandCursor[CollectionDescriptor]", "description": "a `CommandCursor` to iterate over CollectionDescriptor instances,"}, {"type": "CommandCursor[CollectionDescriptor]", "description": "each corresponding to a collection."}], "example": ">>> ccur = my_db.list_collections()\n>>> ccur\n\n>>> list(ccur)\n[CollectionDescriptor(name='my_v_col', options=CollectionOptions())]\n>>> for coll_dict in my_db.list_collections():\n... print(coll_dict)\n...\nCollectionDescriptor(name='my_v_col', options=CollectionOptions())", "gathered_types": ["astrapy.info.CollectionDescriptor", "astrapy.cursors.CommandCursor"]}} +{"id": "astrapy.database.Database.list_collection_names", "text": "List the names of all collections in a given keyspace of this database.", "metadata": {"kind": "function", "name": "list_collection_names", "path": "astrapy.database.Database.list_collection_names", "parameters": [{"name": "keyspace", "type": "str | None", "description": "the keyspace to be inspected. If not specified,\nthe general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "a list of the collection names as strings, in no particular order."}], "example": ">>> my_db.list_collection_names()\n['a_collection', 'another_col']"}} +{"id": "astrapy.database.Database.command", "text": "Send a POST request to the Data API for this database with\nan arbitrary, caller-provided payload.", "metadata": {"kind": "function", "name": "command", "path": "astrapy.database.Database.command", "parameters": [{"name": "body", "type": "dict[str, Any]", "description": "a JSON-serializable dictionary, the payload of the request.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace to use. Requests always target a keyspace:\nif not specified, the general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "collection_name", "type": "str | None", "description": "if provided, the collection name is appended at the end\nof the endpoint. In this way, this method allows collection-level\narbitrary POST requests as well.", "value": "None", "default": "None"}, {"name": "raise_api_errors", "type": "bool", "description": "if True, responses with a nonempty 'errors' field\nresult in an astrapy exception being raised.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary with the response of the HTTP request."}], "example": ">>> my_db.command({\"findCollections\": {}})\n{'status': {'collections': ['my_coll']}}\n>>> my_db.command({\"countDocuments\": {}}, collection_name=\"my_coll\")\n{'status': {'count': 123}}"}} +{"id": "astrapy.database.Database.get_database_admin", "text": "Return a DatabaseAdmin object corresponding to this database, for\nuse in admin tasks such as managing keyspaces.\n\nThis method, depending on the environment where the database resides,\nreturns an appropriate subclass of DatabaseAdmin.", "metadata": {"kind": "function", "name": "get_database_admin", "path": "astrapy.database.Database.get_database_admin", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission on the database to\nperform the desired tasks. If omitted (as it can generally be done),\nthe token of this Database is used.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.\nNote that this parameter is allowed only for Astra DB environments.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.\nNote that this parameter is allowed only for Astra DB environments.", "value": "None", "default": "None"}], "returns": [{"type": "DatabaseAdmin", "description": "A DatabaseAdmin instance targeting this database. More precisely,"}, {"type": "DatabaseAdmin", "description": "for Astra DB an instance of `AstraDBDatabaseAdmin` is returned;"}, {"type": "DatabaseAdmin", "description": "for other environments, an instance of `DataAPIDatabaseAdmin` is returned."}], "example": ">>> my_db_admin = my_db.get_database_admin()\n>>> if \"new_keyspace\" not in my_db_admin.list_keyspaces():\n... my_db_admin.create_keyspace(\"new_keyspace\")\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'new_keyspace']", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.admin.DatabaseAdmin"]}} +{"id": "astrapy.database.AsyncDatabase", "text": "A Data API database. This is the object for doing database-level\nDML, such as creating/deleting collections, and for obtaining Collection\nobjects themselves. This class has an asynchronous interface.\n\nThe usual way of obtaining one AsyncDatabase is through the `get_async_database`\nmethod of a `DataAPIClient`.\n\nOn Astra DB, an AsyncDatabase comes with an \"API Endpoint\", which implies\nan AsyncDatabase object instance reaches a specific region (relevant point in\ncase of multi-region databases).", "metadata": {"kind": "class", "name": "AsyncDatabase", "path": "astrapy.database.AsyncDatabase", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the full \"API Endpoint\" string used to reach the Data API.\nExample: \"https://-.apps.astra.datastax.com\"", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: \"AstraCS:xyz...\"\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, on Astra DB the name \"default_keyspace\" is set,\nwhile on other environments the keyspace is left unspecified: in this case,\nmost operations are unavailable until a keyspace is set (through an explicit\n`use_keyspace` invocation or equivalent).", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a string representing the target Data API environment.\nIt can be left unspecified for the default value of `Environment.PROD`;\nother values include `Environment.OTHER`, `Environment.DSE`.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default (sensibly chosen based on the environment).", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient\n>>> my_client = astrapy.DataAPIClient(\"AstraCS:...\")\n>>> my_db = my_client.get_async_database(\n... \"https://01234567-....apps.astra.datastax.com\"\n... )", "note": "creating an instance of AsyncDatabase does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.database.AsyncDatabase.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.database.AsyncDatabase.environment", "value": "environment = environment or Environment.PROD.lower()", "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.database.AsyncDatabase.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.database.AsyncDatabase.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.database.AsyncDatabase.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.database.AsyncDatabase.api_endpoint", "value": "api_endpoint = api_endpoint.strip('/')"}} +{"id": "astrapy.database.AsyncDatabase.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.database.AsyncDatabase.api_path", "value": "api_path = _api_path", "gathered_types": ["_api_path"]}} +{"id": "astrapy.database.AsyncDatabase.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.database.AsyncDatabase.api_version", "value": "api_version = _api_version", "gathered_types": ["_api_version"]}} +{"id": "astrapy.database.AsyncDatabase.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.database.AsyncDatabase.callers", "value": "callers = callers_param"}} +{"id": "astrapy.database.AsyncDatabase.with_options", "text": "Create a clone of this database with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.database.AsyncDatabase.with_options", "parameters": [{"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, the name \"default_keyspace\" is set.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncDatabase", "description": "a new `AsyncDatabase` instance."}], "example": ">>> my_async_db_2 = my_async_db.with_options(\n... keyspace=\"the_other_keyspace\",\n... callers=[(\"the_caller\", \"0.1.0\")],\n... )", "gathered_types": ["astrapy.constants.CallerType", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.database.AsyncDatabase.to_sync", "text": "Create a (synchronous) Database from this one. Save for the arguments\nexplicitly provided as overrides, everything else is kept identical\nto this database in the copy.", "metadata": {"kind": "function", "name": "to_sync", "path": "astrapy.database.AsyncDatabase.to_sync", "parameters": [{"name": "api_endpoint", "type": "str | None", "description": "the full \"API Endpoint\" string used to reach the Data API.\nExample: \"https://-.apps.astra.datastax.com\"", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: \"AstraCS:xyz...\"\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace all method calls will target, unless\none is explicitly specified in the call. If no keyspace is supplied\nwhen creating a Database, the name \"default_keyspace\" is set.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a string representing the target Data API environment.\nValues are, for example, `Environment.PROD`, `Environment.OTHER`,\nor `Environment.DSE`.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "the new copy, a `Database` instance."}], "example": ">>> my_sync_db = my_async_db.to_sync()\n>>> my_sync_db.list_collection_names()\n['a_collection', 'another_collection']", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database", "astrapy.constants.CallerType"]}} +{"id": "astrapy.database.AsyncDatabase.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe Data API calls are performed (the \"caller\").", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.database.AsyncDatabase.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe Data API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_db.set_caller(caller_name=\"the_caller\", caller_version=\"0.1.0\")"}} +{"id": "astrapy.database.AsyncDatabase.use_namespace", "text": "Switch to a new working namespace for this database.\nThis method changes (mutates) the AsyncDatabase instance.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"use_keyspace\" method.**\n\nNote that this method does not create the namespace, which should exist\nalready (created for instance with a `DatabaseAdmin.async_create_namespace` call).", "metadata": {"kind": "function", "name": "use_namespace", "path": "astrapy.database.AsyncDatabase.use_namespace", "parameters": [{"name": "namespace", "type": "str", "description": "the new namespace to use as the database working namespace.", "default": null}], "returns": [{"type": "None", "description": "None."}], "example": ">>> asyncio.run(my_async_db.list_collection_names())\n['coll_1', 'coll_2']\n>>> my_async_db.use_namespace(\"an_empty_namespace\")\n>>> asyncio.run(my_async_db.list_collection_names())\n[]"}} +{"id": "astrapy.database.AsyncDatabase.use_keyspace", "text": "Switch to a new working keyspace for this database.\nThis method changes (mutates) the AsyncDatabase instance.\n\nNote that this method does not create the keyspace, which should exist\nalready (created for instance with a `DatabaseAdmin.async_create_keyspace` call).", "metadata": {"kind": "function", "name": "use_keyspace", "path": "astrapy.database.AsyncDatabase.use_keyspace", "parameters": [{"name": "keyspace", "type": "str", "description": "the new keyspace to use as the database working keyspace.", "default": null}], "returns": [{"type": "None", "description": "None."}], "example": ">>> asyncio.run(my_async_db.list_collection_names())\n['coll_1', 'coll_2']\n>>> my_async_db.use_keyspace(\"an_empty_keyspace\")\n>>> asyncio.run(my_async_db.list_collection_names())\n[]"}} +{"id": "astrapy.database.AsyncDatabase.info", "text": "Additional information on the database as a DatabaseInfo instance.\n\nSome of the returned properties are dynamic throughout the lifetime\nof the database (such as raw_info[\"keyspaces\"]). For this reason,\neach invocation of this method triggers a new request to the DevOps API.", "metadata": {"kind": "function", "name": "info", "path": "astrapy.database.AsyncDatabase.info", "returns": [{"type": "DatabaseInfo"}], "example": ">>> my_async_db.info().region\n'eu-west-1'\n\n>>> my_async_db.info().raw_info['datacenters'][0]['dateCreated']\n'2023-01-30T12:34:56Z'", "note": "see the DatabaseInfo documentation for a caveat about the difference\nbetween the `region` and the `raw_info[\"region\"]` attributes.", "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.database.AsyncDatabase.id", "text": "The ID of this database.", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.database.AsyncDatabase.id", "value": "id: str", "example": ">>> my_async_db.id\n'01234567-89ab-cdef-0123-456789abcdef'"}} +{"id": "astrapy.database.AsyncDatabase.name", "text": "The name of this database. Note that this bears no unicity guarantees.\n\nCalling this method the first time involves a request\nto the DevOps API (the resulting database name is then cached).\nSee the `info()` method for more details.", "metadata": {"kind": "function", "name": "name", "path": "astrapy.database.AsyncDatabase.name", "returns": [{"type": "str"}], "example": ">>> my_async_db.name()\n'the_application_database'"}} +{"id": "astrapy.database.AsyncDatabase.namespace", "text": "The namespace this database uses as target for all commands when\nno method-call-specific namespace is specified.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.database.AsyncDatabase.namespace", "value": "namespace: str | None", "returns": [{"type": "str | None", "description": "the working namespace (a string), or None if not set."}], "example": ">>> my_async_db.namespace\n'the_keyspace'"}} +{"id": "astrapy.database.AsyncDatabase.keyspace", "text": "The keyspace this database uses as target for all commands when\nno method-call-specific keyspace is specified.", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.database.AsyncDatabase.keyspace", "value": "keyspace: str | None", "returns": [{"type": "str | None", "description": "the working keyspace (a string), or None if not set."}], "example": ">>> my_async_db.keyspace\n'the_keyspace'"}} +{"id": "astrapy.database.AsyncDatabase.get_collection", "text": "Spawn an `AsyncCollection` object instance representing a collection\non this database.\n\nCreating an `AsyncCollection` instance does not have any effect on the\nactual state of the database: in other words, for the created\n`AsyncCollection` instance to be used meaningfully, the collection\nmust exist already (for instance, it should have been created\npreviously by calling the `create_collection` method).", "metadata": {"kind": "function", "name": "get_collection", "path": "astrapy.database.AsyncDatabase.get_collection", "parameters": [{"name": "name", "type": "str", "description": "the name of the collection.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace containing the collection. If no keyspace\nis specified, the setting for this database is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based\nauthentication, specialized subclasses of\n`astrapy.authentication.EmbeddingHeadersProvider` should be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration\nof each operation on the collection. Individual timeouts can be\nprovided to each collection method call and will take precedence, with\nthis value being an overall default.\nNote that for some methods involving multiple API calls (such as `find`,\n`delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCollection", "description": "an `AsyncCollection` instance, representing the desired collection\n(but without any form of validation)."}], "example": ">>> async def count_docs(adb: AsyncDatabase, c_name: str) -> int:\n... async_col = await adb.get_collection(c_name)\n... return await async_col.count_documents({}, upper_bound=100)\n...\n>>> asyncio.run(count_docs(my_async_db, \"my_collection\"))\n45", "note": "as this method, returning an AsyncCollection, albeit\nin a synchronous way. In other words, the following are equivalent:\n await my_async_db.get_collection(\"coll_name\")\n my_async_db.coll_name\n my_async_db[\"coll_name\"]", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.database.AsyncDatabase.create_collection", "text": "Creates a collection on the database and return the AsyncCollection\ninstance that represents it.\n\nThis is a blocking operation: the method returns when the collection\nis ready to be used. As opposed to the `get_collection` instance,\nthis method triggers causes the collection to be actually created on DB.", "metadata": {"kind": "function", "name": "create_collection", "path": "astrapy.database.AsyncDatabase.create_collection", "parameters": [{"name": "name", "type": "str", "description": "the name of the collection.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace where the collection is to be created.\nIf not specified, the general setting for this database is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "dimension", "type": "int | None", "description": "for vector collections, the dimension of the vectors\n(i.e. the number of their components).", "value": "None", "default": "None"}, {"name": "metric", "type": "str | None", "description": "the similarity metric used for vector searches.\nAllowed values are `VectorMetric.DOT_PRODUCT`, `VectorMetric.EUCLIDEAN`\nor `VectorMetric.COSINE` (default).", "value": "None", "default": "None"}, {"name": "service", "type": "CollectionVectorServiceOptions | dict[str, Any] | None", "description": "a dictionary describing a service for\nembedding computation, e.g. `{\"provider\": \"ab\", \"modelName\": \"xy\"}`.\nAlternatively, a CollectionVectorServiceOptions object to the same effect.", "value": "None", "default": "None"}, {"name": "indexing", "type": "dict[str, Any] | None", "description": "optional specification of the indexing options for\nthe collection, in the form of a dictionary such as\n {\"deny\": [...]}\nor\n {\"allow\": [...]}", "value": "None", "default": "None"}, {"name": "default_id_type", "type": "str | None", "description": "this sets what type of IDs the API server will\ngenerate when inserting documents that do not specify their\n`_id` field explicitly. Can be set to any of the values\n`DefaultIdType.UUID`, `DefaultIdType.OBJECTID`,\n`DefaultIdType.UUIDV6`, `DefaultIdType.UUIDV7`,\n`DefaultIdType.DEFAULT`.", "value": "None", "default": "None"}, {"name": "additional_options", "type": "dict[str, Any] | None", "description": "any further set of key-value pairs that will\nbe added to the \"options\" part of the payload when sending\nthe Data API command to create a collection.", "value": "None", "default": "None"}, {"name": "check_exists", "type": "bool | None", "description": "whether to run an existence check for the collection\nname before attempting to create the collection:\nIf check_exists is True, an error is raised when creating\nan existing collection.\nIf it is False, the creation is attempted. In this case, for\npreexisting collections, the command will succeed or fail\ndepending on whether the options match or not.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCollection", "description": "an `AsyncCollection` instance, representing the newly-created collection."}], "example": ">>> async def create_and_insert(adb: AsyncDatabase) -> Dict[str, Any]:\n... new_a_col = await adb.create_collection(\"my_v_col\", dimension=3)\n... return await new_a_col.insert_one(\n... {\"name\": \"the_row\", \"$vector\": [0.4, 0.5, 0.7]},\n... )\n...\n>>> asyncio.run(create_and_insert(my_async_db))\nInsertOneResult(raw_results=..., inserted_id='08f05ecf-...-...-...')", "note": "A collection is considered a vector collection if at least one of\n`dimension` or `service` are provided and not null. In that case,\nand only in that case, is `metric` an accepted parameter.\nNote, moreover, that if passing both these parameters, then\nthe dimension must be compatible with the chosen service.", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider", "astrapy.info.CollectionVectorServiceOptions", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.database.AsyncDatabase.drop_collection", "text": "Drop a collection from the database, along with all documents therein.", "metadata": {"kind": "function", "name": "drop_collection", "path": "astrapy.database.AsyncDatabase.drop_collection", "parameters": [{"name": "name_or_collection", "type": "str | AsyncCollection", "description": "either the name of a collection or\nan `AsyncCollection` instance.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary in the form {\"ok\": 1} if the command succeeds."}], "example": ">>> asyncio.run(my_async_db.list_collection_names())\n['a_collection', 'my_v_col', 'another_col']\n>>> asyncio.run(my_async_db.drop_collection(\"my_v_col\"))\n{'ok': 1}\n>>> asyncio.run(my_async_db.list_collection_names())\n['a_collection', 'another_col']", "note": "when providing a collection name, it is assumed that the collection\nis to be found in the keyspace that was set at database instance level.", "gathered_types": ["astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.database.AsyncDatabase.list_collections", "text": "List all collections in a given keyspace for this database.", "metadata": {"kind": "function", "name": "list_collections", "path": "astrapy.database.AsyncDatabase.list_collections", "parameters": [{"name": "keyspace", "type": "str | None", "description": "the keyspace to be inspected. If not specified,\nthe general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCommandCursor[CollectionDescriptor]", "description": "an `AsyncCommandCursor` to iterate over CollectionDescriptor instances,"}, {"type": "AsyncCommandCursor[CollectionDescriptor]", "description": "each corresponding to a collection."}], "example": ">>> async def a_list_colls(adb: AsyncDatabase) -> None:\n... a_ccur = adb.list_collections()\n... print(\"* a_ccur:\", a_ccur)\n... print(\"* list:\", [coll async for coll in a_ccur])\n... async for coll in adb.list_collections():\n... print(\"* coll:\", coll)\n...\n>>> asyncio.run(a_list_colls(my_async_db))\n* a_ccur: \n* list: [CollectionDescriptor(name='my_v_col', options=CollectionOptions())]\n* coll: CollectionDescriptor(name='my_v_col', options=CollectionOptions())", "gathered_types": ["astrapy.info.CollectionDescriptor", "astrapy.cursors.AsyncCommandCursor"]}} +{"id": "astrapy.database.AsyncDatabase.list_collection_names", "text": "List the names of all collections in a given keyspace of this database.", "metadata": {"kind": "function", "name": "list_collection_names", "path": "astrapy.database.AsyncDatabase.list_collection_names", "parameters": [{"name": "keyspace", "type": "str | None", "description": "the keyspace to be inspected. If not specified,\nthe general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "a list of the collection names as strings, in no particular order."}], "example": ">>> asyncio.run(my_async_db.list_collection_names())\n['a_collection', 'another_col']"}} +{"id": "astrapy.database.AsyncDatabase.command", "text": "Send a POST request to the Data API for this database with\nan arbitrary, caller-provided payload.", "metadata": {"kind": "function", "name": "command", "path": "astrapy.database.AsyncDatabase.command", "parameters": [{"name": "body", "type": "dict[str, Any]", "description": "a JSON-serializable dictionary, the payload of the request.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the keyspace to use. Requests always target a keyspace:\nif not specified, the general setting for this database is assumed.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "collection_name", "type": "str | None", "description": "if provided, the collection name is appended at the end\nof the endpoint. In this way, this method allows collection-level\narbitrary POST requests as well.", "value": "None", "default": "None"}, {"name": "raise_api_errors", "type": "bool", "description": "if True, responses with a nonempty 'errors' field\nresult in an astrapy exception being raised.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary with the response of the HTTP request."}], "example": ">>> asyncio.run(my_async_db.command({\"findCollections\": {}}))\n{'status': {'collections': ['my_coll']}}\n>>> asyncio.run(my_async_db.command(\n... {\"countDocuments\": {}},\n... collection_name=\"my_coll\",\n... )\n{'status': {'count': 123}}"}} +{"id": "astrapy.database.AsyncDatabase.get_database_admin", "text": "Return a DatabaseAdmin object corresponding to this database, for\nuse in admin tasks such as managing keyspaces.\n\nThis method, depending on the environment where the database resides,\nreturns an appropriate subclass of DatabaseAdmin.", "metadata": {"kind": "function", "name": "get_database_admin", "path": "astrapy.database.AsyncDatabase.get_database_admin", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission on the database to\nperform the desired tasks. If omitted (as it can generally be done),\nthe token of this Database is used.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.\nNote that this parameter is allowed only for Astra DB environments.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.\nNote that this parameter is allowed only for Astra DB environments.", "value": "None", "default": "None"}], "returns": [{"type": "DatabaseAdmin", "description": "A DatabaseAdmin instance targeting this database. More precisely,"}, {"type": "DatabaseAdmin", "description": "for Astra DB an instance of `AstraDBDatabaseAdmin` is returned;"}, {"type": "DatabaseAdmin", "description": "for other environments, an instance of `DataAPIDatabaseAdmin` is returned."}], "example": ">>> my_db_admin = my_async_db.get_database_admin()\n>>> if \"new_keyspace\" not in my_db_admin.list_keyspaces():\n... my_db_admin.create_keyspace(\"new_keyspace\")\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'new_keyspace']", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.admin.DatabaseAdmin"]}} +{"id": "astrapy.client", "text": "", "metadata": {"kind": "module", "name": "client", "path": "astrapy.client", "imports": {"annotations": "__future__.annotations", "logging": "logging", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Sequence": "typing.Sequence", "deprecation": "deprecation", "__version__": "astrapy.__version__", "api_endpoint_parsing_error_message": "astrapy.admin.api_endpoint_parsing_error_message", "build_api_endpoint": "astrapy.admin.build_api_endpoint", "check_id_endpoint_parg_kwargs": "astrapy.admin.check_id_endpoint_parg_kwargs", "generic_api_url_parsing_error_message": "astrapy.admin.generic_api_url_parsing_error_message", "normalize_region_for_id": "astrapy.admin.normalize_region_for_id", "parse_api_endpoint": "astrapy.admin.parse_api_endpoint", "parse_generic_api_url": "astrapy.admin.parse_generic_api_url", "coerce_token_provider": "astrapy.authentication.coerce_token_provider", "redact_secret": "astrapy.authentication.redact_secret", "CallerType": "astrapy.constants.CallerType", "Environment": "astrapy.constants.Environment", "SET_CALLER_DEPRECATION_NOTICE": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "check_caller_parameters": "astrapy.meta.check_caller_parameters", "check_deprecated_id_region": "astrapy.meta.check_deprecated_id_region", "check_namespace_keyspace": "astrapy.meta.check_namespace_keyspace", "AsyncDatabase": "astrapy.AsyncDatabase", "Database": "astrapy.Database", "AstraDBAdmin": "astrapy.admin.AstraDBAdmin", "TokenProvider": "astrapy.authentication.TokenProvider"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.client.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.client.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.client.DataAPIClient", "text": "A client for using the Data API. This is the main entry point and sits\nat the top of the conceptual \"client -> database -> collection\" hierarchy.\n\nA client is created first, optionally passing it a suitable Access Token.\nStarting from the client, then:\n - databases (Database and AsyncDatabase) are created for working with data\n - AstraDBAdmin objects can be created for admin-level work", "metadata": {"kind": "class", "name": "DataAPIClient", "path": "astrapy.client.DataAPIClient", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a string representing the target Data API environment.\nIt can be left unspecified for the default value of `Environment.PROD`;\nother values include `Environment.OTHER`, `Environment.DSE`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API and DevOps API calls are performed.\nThese end up in the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API and\nDevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient\n>>> my_client = DataAPIClient(\"AstraCS:...\")\n>>> my_db0 = my_client.get_database(\n... \"https://01234567-....apps.astra.datastax.com\"\n... )\n>>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n>>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.1, 0.3]})\n>>> my_db1 = my_client.get_database(\"01234567-...\")\n>>> my_db2 = my_client.get_database(\"01234567-...\", region=\"us-east1\")\n>>> my_adm0 = my_client.get_admin()\n>>> my_adm1 = my_client.get_admin(token=more_powerful_token_override)\n>>> database_list = my_adm0.list_databases()", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.client.DataAPIClient.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.client.DataAPIClient.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.client.DataAPIClient.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.client.DataAPIClient.environment", "value": "environment = environment or Environment.PROD.lower()", "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.client.DataAPIClient.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.client.DataAPIClient.callers", "value": "callers = callers_param"}} +{"id": "astrapy.client.DataAPIClient.with_options", "text": "Create a clone of this DataAPIClient with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.client.DataAPIClient.with_options", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API and DevOps API calls are performed.\nThese end up in the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API and\nDevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "DataAPIClient", "description": "a new DataAPIClient instance."}], "example": ">>> another_client = my_client.with_options(\n... callers=[(\"caller_identity\", \"1.2.0\")],\n... )", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.client.DataAPIClient", "astrapy.constants.CallerType"]}} +{"id": "astrapy.client.DataAPIClient.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe API calls will be performed (the \"caller\").\n\nNew objects spawned from this client afterwards will inherit the new settings.", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.client.DataAPIClient.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe API API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_client.set_caller(caller_name=\"the_caller\", caller_version=\"0.1.0\")"}} +{"id": "astrapy.client.DataAPIClient.get_database", "text": "Get a Database object from this client, for doing data-related work.", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.client.DataAPIClient.get_database", "parameters": [{"name": "api_endpoint_or_id", "type": "str | None", "description": "positional parameter that can stand for both\n`api_endpoint` and `id`. Passing them together is an error.", "value": "None", "default": "None"}, {"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.\nActual admin work can be achieved by using the AstraDBAdmin object.", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of the client token.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "if provided, it is passed to the Database; otherwise\nthe Database class will apply an environment-specific default.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "id", "type": "str | None", "description": "the target database ID. This is alternative to using the API Endpoint.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "the region to use for connecting to the database. The\ndatabase must be located in that region. This parameter can be used\nonly if the database is specified by its ID (instead of API Endpoint).\nIf this parameter is not passed, and cannot be inferred\nfrom the API endpoint, an additional DevOps API request is made\nto determine the default region and use it subsequently.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "a Database object with which to work on Data API collections."}], "example": ">>> my_db0 = my_client.get_database(\"01234567-...\")\n>>> my_db1 = my_client.get_database(\n... \"https://01234567-...us-west1.apps.astra.datastax.com\",\n... )\n>>> my_db2 = my_client.get_database(\"01234567-...\", token=\"AstraCS:...\")\n>>> my_db3 = my_client.get_database(\"01234567-...\", region=\"us-west1\")\n>>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n>>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.3, 0.4]})", "note": "This method does not perform any admin-level operation through\nthe DevOps API. For actual creation of a database, see the\n`create_database` method of class AstraDBAdmin.", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.client.DataAPIClient.get_async_database", "text": "Get an AsyncDatabase object from this client, for doing data-related work.", "metadata": {"kind": "function", "name": "get_async_database", "path": "astrapy.client.DataAPIClient.get_async_database", "parameters": [{"name": "api_endpoint_or_id", "type": "str | None", "description": "positional parameter that can stand for both\n`api_endpoint` and `id`. Passing them together is an error.", "value": "None", "default": "None"}, {"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.\nActual admin work can be achieved by using the AstraDBAdmin object.", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of the client token.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "if provided, it is passed to the Database; otherwise\nthe Database class will apply an environment-specific default.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "id", "type": "str | None", "description": "the target database ID. This is alternative to using the API Endpoint.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "the region to use for connecting to the database. The\ndatabase must be located in that region. This parameter can be used\nonly if the database is specified by its ID (instead of API Endpoint).\nIf this parameter is not passed, and cannot be inferred\nfrom the API endpoint, an additional DevOps API request is made\nto determine the default region and use it subsequently.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "returns": [{"type": "AsyncDatabase", "description": "a Database object with which to work on Data API collections."}], "example": ">>> async def create_use_db(cl: DataAPIClient, api_ep: str) -> None:\n... async_db = cl.get_async_database(api_ep)\n... my_a_coll = await async_db.create_collection(\"movies\", dimension=2)\n... await my_a_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.3, 0.4]})\n...\n>>> asyncio.run(\n... create_use_db(\n... my_client,\n... \"https://01234567-...us-west1.apps.astra.datastax.com\",\n... )\n... )", "note": "This method does not perform any admin-level operation through\nthe DevOps API. For actual creation of a database, see the\n`create_database` method of class AstraDBAdmin.", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.client.DataAPIClient.get_database_by_api_endpoint", "text": "Get a Database object from this client, for doing data-related work.\nThe Database is specified by an API Endpoint instead of the ID and a region.\n\nNote that using this method is generally equivalent to passing\nan API Endpoint as parameter to the `get_database` method (see).", "metadata": {"kind": "function", "name": "get_database_by_api_endpoint", "path": "astrapy.client.DataAPIClient.get_database_by_api_endpoint", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the full \"API Endpoint\" string used to reach the Data API.\nExample: \"https://DATABASE_ID-REGION.apps.astra.datastax.com\"", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of the client token.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "if provided, it is passed to the Database; otherwise\nthe Database class will apply an environment-specific default.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "a Database object with which to work on Data API collections."}], "example": ">>> my_db0 = my_client.get_database_by_api_endpoint(\"01234567-...\")\n>>> my_db1 = my_client.get_database_by_api_endpoint(\n... \"https://01234567-....apps.astra.datastax.com\",\n... token=\"AstraCS:...\",\n... )\n>>> my_db2 = my_client.get_database_by_api_endpoint(\n... \"https://01234567-....apps.astra.datastax.com\",\n... keyspace=\"the_other_keyspace\",\n... )\n>>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n>>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.5, 0.6]})", "note": "This method does not perform any admin-level operation through\nthe DevOps API. For actual creation of a database, see the\n`create_database` method of class AstraDBAdmin.", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.client.DataAPIClient.get_async_database_by_api_endpoint", "text": "Get an AsyncDatabase object from this client, for doing data-related work.\nThe Database is specified by an API Endpoint instead of the ID and a region.\n\nNote that using this method is generally equivalent to passing\nan API Endpoint as parameter to the `get_async_database` method (see).\n\nThis method has identical behavior and signature as the sync\ncounterpart `get_database_by_api_endpoint`: please see that one\nfor more details.", "metadata": {"kind": "function", "name": "get_async_database_by_api_endpoint", "path": "astrapy.client.DataAPIClient.get_async_database_by_api_endpoint", "parameters": [{"name": "api_endpoint", "type": "str"}, {"name": "token", "default": "None", "type": "str | TokenProvider | None"}, {"name": "keyspace", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}], "returns": [{"type": "AsyncDatabase"}], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.client.DataAPIClient.get_admin", "text": "Get an AstraDBAdmin instance corresponding to this client, for\nadmin work such as managing databases.", "metadata": {"kind": "function", "name": "get_admin", "path": "astrapy.client.DataAPIClient.get_admin", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Astra DB Admin instead of the\nclient token. This may be useful when switching to a more powerful,\nadmin-capable permission set.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBAdmin", "description": "An AstraDBAdmin instance, wich which to perform management at the"}, {"type": "AstraDBAdmin", "description": "database level."}], "example": ">>> my_adm0 = my_client.get_admin()\n>>> my_adm1 = my_client.get_admin(token=more_powerful_token_override)\n>>> database_list = my_adm0.list_databases()\n>>> my_db_admin = my_adm0.create_database(\n... \"the_other_database\",\n... cloud_provider=\"AWS\",\n... region=\"eu-west-1\",\n... )\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'that_other_one']", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.admin.AstraDBAdmin"]}} +{"id": "astrapy.cursors", "text": "", "metadata": {"kind": "module", "name": "cursors", "path": "astrapy.cursors", "imports": {"annotations": "__future__.annotations", "hashlib": "hashlib", "json": "json", "logging": "logging", "time": "time", "warnings": "warnings", "AsyncIterator": "collections.abc.AsyncIterator", "Enum": "enum.Enum", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Callable": "typing.Callable", "Generic": "typing.Generic", "Iterable": "typing.Iterable", "Iterator": "typing.Iterator", "Optional": "typing.Optional", "Tuple": "typing.Tuple", "TypeVar": "typing.TypeVar", "deprecation": "deprecation", "DocumentType": "astrapy.constants.DocumentType", "ProjectionType": "astrapy.constants.ProjectionType", "normalize_optional_projection": "astrapy.constants.normalize_optional_projection", "CursorIsStartedException": "astrapy.exceptions.CursorIsStartedException", "DataAPIFaultyResponseException": "astrapy.exceptions.DataAPIFaultyResponseException", "DataAPITimeoutException": "astrapy.exceptions.DataAPITimeoutException", "normalize_payload_value": "astrapy.transform_payload.normalize_payload_value", "AsyncCollection": "astrapy.collection.AsyncCollection", "Collection": "astrapy.collection.Collection"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.cursors.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.cursors.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.cursors.BC", "text": "", "metadata": {"kind": "attribute", "name": "BC", "path": "astrapy.cursors.BC", "value": "BC = TypeVar('BC', bound='BaseCursor')"}} +{"id": "astrapy.cursors.T", "text": "", "metadata": {"kind": "attribute", "name": "T", "path": "astrapy.cursors.T", "value": "T = TypeVar('T')"}} +{"id": "astrapy.cursors.IndexPairType", "text": "", "metadata": {"kind": "attribute", "name": "IndexPairType", "path": "astrapy.cursors.IndexPairType", "value": "IndexPairType = Tuple[str, Optional[int]]"}} +{"id": "astrapy.cursors.CursorState", "text": "", "metadata": {"kind": "class", "name": "CursorState", "path": "astrapy.cursors.CursorState", "bases": ["Enum"], "gathered_types": ["Enum"]}} +{"id": "astrapy.cursors.CursorState.IDLE", "text": "", "metadata": {"kind": "attribute", "name": "IDLE", "path": "astrapy.cursors.CursorState.IDLE", "value": "IDLE = 'idle'"}} +{"id": "astrapy.cursors.CursorState.STARTED", "text": "", "metadata": {"kind": "attribute", "name": "STARTED", "path": "astrapy.cursors.CursorState.STARTED", "value": "STARTED = 'started'"}} +{"id": "astrapy.cursors.CursorState.CLOSED", "text": "", "metadata": {"kind": "attribute", "name": "CLOSED", "path": "astrapy.cursors.CursorState.CLOSED", "value": "CLOSED = 'closed'"}} +{"id": "astrapy.cursors._LookAheadIterator.iterator", "text": "", "metadata": {"kind": "attribute", "name": "iterator", "path": "astrapy.cursors._LookAheadIterator.iterator", "value": "iterator = iterator"}} +{"id": "astrapy.cursors._LookAheadIterator.preread_item", "text": "", "metadata": {"kind": "attribute", "name": "preread_item", "path": "astrapy.cursors._LookAheadIterator.preread_item", "value": "preread_item: DocumentType | None = None", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.cursors._LookAheadIterator.has_preread", "text": "", "metadata": {"kind": "attribute", "name": "has_preread", "path": "astrapy.cursors._LookAheadIterator.has_preread", "value": "has_preread = False"}} +{"id": "astrapy.cursors._LookAheadIterator.preread_exhausted", "text": "", "metadata": {"kind": "attribute", "name": "preread_exhausted", "path": "astrapy.cursors._LookAheadIterator.preread_exhausted", "value": "preread_exhausted = False"}} +{"id": "astrapy.cursors._LookAheadIterator.preread", "text": "", "metadata": {"kind": "function", "name": "preread", "path": "astrapy.cursors._LookAheadIterator.preread", "returns": [{"type": "None"}]}} +{"id": "astrapy.cursors._AsyncLookAheadIterator.async_iterator", "text": "", "metadata": {"kind": "attribute", "name": "async_iterator", "path": "astrapy.cursors._AsyncLookAheadIterator.async_iterator", "value": "async_iterator = async_iterator"}} +{"id": "astrapy.cursors._AsyncLookAheadIterator.preread_item", "text": "", "metadata": {"kind": "attribute", "name": "preread_item", "path": "astrapy.cursors._AsyncLookAheadIterator.preread_item", "value": "preread_item: DocumentType | None = None", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.cursors._AsyncLookAheadIterator.has_preread", "text": "", "metadata": {"kind": "attribute", "name": "has_preread", "path": "astrapy.cursors._AsyncLookAheadIterator.has_preread", "value": "has_preread = False"}} +{"id": "astrapy.cursors._AsyncLookAheadIterator.preread_exhausted", "text": "", "metadata": {"kind": "attribute", "name": "preread_exhausted", "path": "astrapy.cursors._AsyncLookAheadIterator.preread_exhausted", "value": "preread_exhausted = False"}} +{"id": "astrapy.cursors._AsyncLookAheadIterator.preread", "text": "", "metadata": {"kind": "function", "name": "preread", "path": "astrapy.cursors._AsyncLookAheadIterator.preread", "returns": [{"type": "None"}]}} +{"id": "astrapy.cursors.BaseCursor", "text": "Represents a generic Cursor over query results, regardless of whether\nsynchronous or asynchronous. It cannot be instantiated.\n\nSee classes Cursor and AsyncCursor for more information.", "metadata": {"kind": "class", "name": "BaseCursor", "path": "astrapy.cursors.BaseCursor", "parameters": [{"name": "collection", "type": "Collection | AsyncCollection"}, {"name": "filter", "type": "dict[str, Any] | None"}, {"name": "projection", "type": "ProjectionType | None"}, {"name": "max_time_ms", "type": "int | None"}, {"name": "overall_max_time_ms", "type": "int | None"}], "gathered_types": ["astrapy.constants.ProjectionType", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.cursors.BaseCursor.state", "text": "The current state of this cursor, which can be one of\nthe astrapy.cursors.CursorState enum.", "metadata": {"kind": "attribute", "name": "state", "path": "astrapy.cursors.BaseCursor.state", "value": "state: str"}} +{"id": "astrapy.cursors.BaseCursor.address", "text": "The API endpoint used by this cursor when issuing\nrequests to the database.", "metadata": {"kind": "attribute", "name": "address", "path": "astrapy.cursors.BaseCursor.address", "value": "address: str"}} +{"id": "astrapy.cursors.BaseCursor.alive", "text": "Whether the cursor has the potential to yield more data.", "metadata": {"kind": "attribute", "name": "alive", "path": "astrapy.cursors.BaseCursor.alive", "value": "alive: bool"}} +{"id": "astrapy.cursors.BaseCursor.clone", "text": "Clone the cursor into a new, fresh one.", "metadata": {"kind": "function", "name": "clone", "path": "astrapy.cursors.BaseCursor.clone", "returns": [{"type": "BC", "description": "a copy of this cursor, reset to its pristine state,"}, {"type": "BC", "description": "i.e. fully un-consumed."}], "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.close", "text": "Stop/kill the cursor, regardless of its status.", "metadata": {"kind": "function", "name": "close", "path": "astrapy.cursors.BaseCursor.close", "returns": [{"type": "None"}]}} +{"id": "astrapy.cursors.BaseCursor.cursor_id", "text": "An integer uniquely identifying this cursor.", "metadata": {"kind": "attribute", "name": "cursor_id", "path": "astrapy.cursors.BaseCursor.cursor_id", "value": "cursor_id: int"}} +{"id": "astrapy.cursors.BaseCursor.limit", "text": "Set a new `limit` value for this cursor.", "metadata": {"kind": "function", "name": "limit", "path": "astrapy.cursors.BaseCursor.limit", "parameters": [{"name": "limit", "type": "int | None", "description": "the new value to set", "default": null}], "returns": [{"type": "BC", "description": "this cursor itself."}], "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.include_similarity", "text": "Set a new `include_similarity` value for this cursor.", "metadata": {"kind": "function", "name": "include_similarity", "path": "astrapy.cursors.BaseCursor.include_similarity", "parameters": [{"name": "include_similarity", "type": "bool | None", "description": "the new value to set", "default": null}], "returns": [{"type": "BC", "description": "this cursor itself."}], "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.include_sort_vector", "text": "Set a new `include_sort_vector` value for this cursor.", "metadata": {"kind": "function", "name": "include_sort_vector", "path": "astrapy.cursors.BaseCursor.include_sort_vector", "parameters": [{"name": "include_sort_vector", "type": "bool | None", "description": "the new value to set", "default": null}], "returns": [{"type": "BC", "description": "this cursor itself."}], "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.retrieved", "text": "The number of documents consumed so far (by the code consuming the cursor).", "metadata": {"kind": "attribute", "name": "retrieved", "path": "astrapy.cursors.BaseCursor.retrieved", "value": "retrieved: int"}} +{"id": "astrapy.cursors.BaseCursor.consumed", "text": "The number of documents consumed so far (by the code consuming the cursor).", "metadata": {"kind": "attribute", "name": "consumed", "path": "astrapy.cursors.BaseCursor.consumed", "value": "consumed: int"}} +{"id": "astrapy.cursors.BaseCursor.rewind", "text": "Reset the cursor to its pristine state, i.e. fully unconsumed.", "metadata": {"kind": "function", "name": "rewind", "path": "astrapy.cursors.BaseCursor.rewind", "returns": [{"type": "BC", "description": "this cursor itself."}], "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.skip", "text": "Set a new `skip` value for this cursor.", "metadata": {"kind": "function", "name": "skip", "path": "astrapy.cursors.BaseCursor.skip", "parameters": [{"name": "skip", "type": "int | None", "description": "the new value to set", "default": null}], "returns": [{"type": "BC", "description": "this cursor itself."}], "note": "This parameter can be used only in conjunction with an explicit\n`sort` criterion of the ascending/descending type (i.e. it cannot\nbe used when not sorting, nor with vector-based ANN search).", "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.BaseCursor.sort", "text": "Set a new `sort` value for this cursor.", "metadata": {"kind": "function", "name": "sort", "path": "astrapy.cursors.BaseCursor.sort", "parameters": [{"name": "sort", "type": "dict[str, Any] | None", "description": "the new sorting prescription to set", "default": null}], "returns": [{"type": "BC", "description": "this cursor itself."}], "note": "Some combinations of arguments impose an implicit upper bound on the\nnumber of documents that are returned by the Data API. More specifically:\n(a) Vector ANN searches cannot return more than a number of documents\nthat at the time of writing is set to 1000 items.\n(b) When using a sort criterion of the ascending/descending type,\nthe Data API will return a smaller number of documents, set to 20\nat the time of writing, and stop there. The returned documents are\nthe top results across the whole collection according to the requested\ncriterion.\nThese provisions should be kept in mind even when subsequently running\na command such as `.distinct()` on a cursor.", "gathered_types": ["BC"]}} +{"id": "astrapy.cursors.Cursor", "text": "Represents a (synchronous) cursor over documents in a collection.\nA cursor is iterated over, e.g. with a for loop, and keeps track of\nits progress.\n\nGenerally cursors are not supposed to be instantiated directly,\nrather they are obtained by invoking the `find` method on a collection.", "metadata": {"kind": "class", "name": "Cursor", "path": "astrapy.cursors.Cursor", "parameters": [{"name": "collection", "type": "Collection"}, {"name": "filter", "type": "dict[str, Any] | None"}, {"name": "projection", "type": "ProjectionType | None"}, {"name": "max_time_ms", "type": "int | None"}, {"name": "overall_max_time_ms", "type": "int | None"}], "bases": ["BaseCursor"], "attributes": [{"name": "collection", "type": "Collection", "description": "the collection to find documents in\nfilter: a predicate expressed as a dictionary according to the\n Data API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$le\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$le\": 100}}]}\n See the Data API documentation for the full set of operators.\nprojection: used to select a subset of fields in the document being\n returned. The projection can be: an iterable over the field names\n to return; a dictionary {field_name: True} to positively select\n certain fields; or a dictionary {field_name: False} if one wants\n to discard some fields from the response.\n The default is to return the whole documents.\nmax_time_ms: a timeout, in milliseconds, for each single one\n of the underlying HTTP requests used to fetch documents as the\n cursor is iterated over."}], "note": "When not specifying sorting criteria at all (by vector or otherwise),\nthe cursor can scroll through an arbitrary number of documents as\nthe Data API and the client periodically exchange new chunks of documents.\nIt should be noted that the behavior of the cursor in the case documents\nhave been added/removed after the cursor was started depends on database\ninternals and it is not guaranteed, nor excluded, that such \"real-time\"\nchanges in the data would be picked up by the cursor.", "gathered_types": ["astrapy.constants.ProjectionType", "BaseCursor"]}} +{"id": "astrapy.cursors.Cursor.get_sort_vector", "text": "Return the vector used in this ANN search, if applicable.\nIf this is not an ANN search, or it was invoked without the\n`include_sort_vector` parameter, return None.\n\nInvoking this method on a pristine cursor will trigger an API call\nto get the first page of results.", "metadata": {"kind": "function", "name": "get_sort_vector", "path": "astrapy.cursors.Cursor.get_sort_vector", "returns": [{"type": "list[float] | None"}]}} +{"id": "astrapy.cursors.Cursor.collection", "text": "The (synchronous) collection this cursor is targeting.", "metadata": {"kind": "attribute", "name": "collection", "path": "astrapy.cursors.Cursor.collection", "value": "collection: Collection"}} +{"id": "astrapy.cursors.Cursor.data_source", "text": "The (synchronous) collection this cursor is targeting.", "metadata": {"kind": "attribute", "name": "data_source", "path": "astrapy.cursors.Cursor.data_source", "value": "data_source: Collection"}} +{"id": "astrapy.cursors.Cursor.distinct", "text": "Compute a list of unique values for a specific field across all\ndocuments the cursor iterates through.\n\nInvoking this method has no effect on the cursor state, i.e.\nthe position of the cursor is unchanged.", "metadata": {"kind": "function", "name": "distinct", "path": "astrapy.cursors.Cursor.distinct", "parameters": [{"name": "key", "type": "str", "description": "the name of the field whose value is inspected across documents.\nKeys can use dot-notation to descend to deeper document levels.\nExample of acceptable `key` values:\n \"field\"\n \"field.subfield\"\n \"field.3\"\n \"field.3.subfield\"\nif lists are encountered and no numeric index is specified,\nall items in the list are visited.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.", "value": "None", "default": "None"}], "returns": [{"type": "list[Any]"}], "note": "this operation works at client-side by scrolling through all\ndocuments matching the cursor parameters (such as `filter`).\nPlease be aware of this fact, especially for a very large\namount of documents, for this may have implications on latency,\nnetwork traffic and possibly billing."}} +{"id": "astrapy.cursors.AsyncCursor", "text": "Represents a (asynchronous) cursor over documents in a collection.\nAn asynchronous cursor is iterated over, e.g. with a for loop,\nand keeps track of its progress.\n\nGenerally cursors are not supposed to be instantiated directly,\nrather they are obtained by invoking the `find` method on a collection.", "metadata": {"kind": "class", "name": "AsyncCursor", "path": "astrapy.cursors.AsyncCursor", "parameters": [{"name": "collection", "type": "AsyncCollection"}, {"name": "filter", "type": "dict[str, Any] | None"}, {"name": "projection", "type": "ProjectionType | None"}, {"name": "max_time_ms", "type": "int | None"}, {"name": "overall_max_time_ms", "type": "int | None"}], "bases": ["BaseCursor"], "attributes": [{"name": "collection", "type": "AsyncCollection", "description": "the collection to find documents in\nfilter: a predicate expressed as a dictionary according to the\n Data API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$le\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$le\": 100}}]}\n See the Data API documentation for the full set of operators.\nprojection: used to select a subset of fields in the document being\n returned. The projection can be: an iterable over the field names\n to return; a dictionary {field_name: True} to positively select\n certain fields; or a dictionary {field_name: False} if one wants\n to discard some fields from the response.\n The default is to return the whole documents.\nmax_time_ms: a timeout, in milliseconds, for each single one\n of the underlying HTTP requests used to fetch documents as the\n cursor is iterated over."}], "note": "When not specifying sorting criteria at all (by vector or otherwise),\nthe cursor can scroll through an arbitrary number of documents as\nthe Data API and the client periodically exchange new chunks of documents.\nIt should be noted that the behavior of the cursor in the case documents\nhave been added/removed after the cursor was started depends on database\ninternals and it is not guaranteed, nor excluded, that such \"real-time\"\nchanges in the data would be picked up by the cursor.", "gathered_types": ["astrapy.constants.ProjectionType", "astrapy.collection.AsyncCollection", "BaseCursor"]}} +{"id": "astrapy.cursors.AsyncCursor.get_sort_vector", "text": "Return the vector used in this ANN search, if applicable.\nIf this is not an ANN search, or it was invoked without the\n`include_sort_vector` parameter, return None.\n\nInvoking this method on a pristine cursor will trigger an API call\nto get the first page of results.", "metadata": {"kind": "function", "name": "get_sort_vector", "path": "astrapy.cursors.AsyncCursor.get_sort_vector", "returns": [{"type": "list[float] | None"}]}} +{"id": "astrapy.cursors.AsyncCursor.collection", "text": "The (asynchronous) collection this cursor is targeting.", "metadata": {"kind": "attribute", "name": "collection", "path": "astrapy.cursors.AsyncCursor.collection", "value": "collection: AsyncCollection", "gathered_types": ["astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.cursors.AsyncCursor.data_source", "text": "The (asynchronous) collection this cursor is targeting.", "metadata": {"kind": "attribute", "name": "data_source", "path": "astrapy.cursors.AsyncCursor.data_source", "value": "data_source: AsyncCollection", "gathered_types": ["astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.cursors.AsyncCursor.distinct", "text": "Compute a list of unique values for a specific field across all\ndocuments the cursor iterates through.\n\nInvoking this method has no effect on the cursor state, i.e.\nthe position of the cursor is unchanged.", "metadata": {"kind": "function", "name": "distinct", "path": "astrapy.cursors.AsyncCursor.distinct", "parameters": [{"name": "key", "type": "str", "description": "the name of the field whose value is inspected across documents.\nKeys can use dot-notation to descend to deeper document levels.\nExample of acceptable `key` values:\n \"field\"\n \"field.subfield\"\n \"field.3\"\n \"field.3.subfield\"\nif lists are encountered and no numeric index is specified,\nall items in the list are visited.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.", "value": "None", "default": "None"}], "returns": [{"type": "list[Any]"}], "note": "this operation works at client-side by scrolling through all\ndocuments matching the cursor parameters (such as `filter`).\nPlease be aware of this fact, especially for a very large\namount of documents, for this may have implications on latency,\nnetwork traffic and possibly billing."}} +{"id": "astrapy.cursors.CommandCursor", "text": "A (synchronous) cursor over the results of a Data API command\n(as opposed to a cursor over data as one would get with a `find` method).\n\nCommand cursors are iterated over, e.g. with a for loop.\n\nGenerally command cursors are not supposed to be instantiated directly,\nrather they are obtained by invoking methods on a collection/database\n(such as the database `list_collections` method).", "metadata": {"kind": "class", "name": "CommandCursor", "path": "astrapy.cursors.CommandCursor", "parameters": [{"name": "address", "type": "str"}, {"name": "items", "type": "list[T]"}], "bases": ["Generic[T]"]}} +{"id": "astrapy.cursors.CommandCursor.items", "text": "", "metadata": {"kind": "attribute", "name": "items", "path": "astrapy.cursors.CommandCursor.items", "value": "items = items"}} +{"id": "astrapy.cursors.CommandCursor.iterable", "text": "", "metadata": {"kind": "attribute", "name": "iterable", "path": "astrapy.cursors.CommandCursor.iterable", "value": "iterable = items.__iter__()", "gathered_types": ["__iter__"]}} +{"id": "astrapy.cursors.CommandCursor.state", "text": "The current state of this cursor, which can be:\n - \"alive\": the cursor has still the potential to return items.\n - \"exhausted\": the cursor has finished and won't return documents", "metadata": {"kind": "attribute", "name": "state", "path": "astrapy.cursors.CommandCursor.state", "value": "state: str"}} +{"id": "astrapy.cursors.CommandCursor.address", "text": "The API endpoint used by this cursor when issuing\nrequests to the database.", "metadata": {"kind": "attribute", "name": "address", "path": "astrapy.cursors.CommandCursor.address", "value": "address: str"}} +{"id": "astrapy.cursors.CommandCursor.alive", "text": "Whether the cursor has the potential to yield more data.", "metadata": {"kind": "attribute", "name": "alive", "path": "astrapy.cursors.CommandCursor.alive", "value": "alive: bool"}} +{"id": "astrapy.cursors.CommandCursor.cursor_id", "text": "An integer uniquely identifying this cursor.", "metadata": {"kind": "attribute", "name": "cursor_id", "path": "astrapy.cursors.CommandCursor.cursor_id", "value": "cursor_id: int"}} +{"id": "astrapy.cursors.CommandCursor.close", "text": "Stop/kill the cursor, regardless of its status.", "metadata": {"kind": "function", "name": "close", "path": "astrapy.cursors.CommandCursor.close", "returns": [{"type": "None"}]}} +{"id": "astrapy.cursors.AsyncCommandCursor", "text": "A (asynchronous) cursor over the results of a Data API command\n(as opposed to a cursor over data as one would get with a `find` method).\n\nAsynchronous command cursors are iterated over, e.g. with an async for loop.\n\nGenerally command cursors are not supposed to be instantiated directly,\nrather they are obtained by invoking methods on a collection/database\n(such as the database `list_collections` method).", "metadata": {"kind": "class", "name": "AsyncCommandCursor", "path": "astrapy.cursors.AsyncCommandCursor", "parameters": [{"name": "address", "type": "str"}, {"name": "items", "type": "list[T]"}], "bases": ["Generic[T]"]}} +{"id": "astrapy.cursors.AsyncCommandCursor.items", "text": "", "metadata": {"kind": "attribute", "name": "items", "path": "astrapy.cursors.AsyncCommandCursor.items", "value": "items = items"}} +{"id": "astrapy.cursors.AsyncCommandCursor.iterable", "text": "", "metadata": {"kind": "attribute", "name": "iterable", "path": "astrapy.cursors.AsyncCommandCursor.iterable", "value": "iterable = items.__iter__()", "gathered_types": ["__iter__"]}} +{"id": "astrapy.cursors.AsyncCommandCursor.state", "text": "The current state of this cursor, which can be:\n - \"alive\": the cursor has still the potential to return items.\n - \"exhausted\": the cursor has finished and won't return documents", "metadata": {"kind": "attribute", "name": "state", "path": "astrapy.cursors.AsyncCommandCursor.state", "value": "state: str"}} +{"id": "astrapy.cursors.AsyncCommandCursor.address", "text": "The API endpoint used by this cursor when issuing\nrequests to the database.", "metadata": {"kind": "attribute", "name": "address", "path": "astrapy.cursors.AsyncCommandCursor.address", "value": "address: str"}} +{"id": "astrapy.cursors.AsyncCommandCursor.alive", "text": "Whether the cursor has the potential to yield more data.", "metadata": {"kind": "attribute", "name": "alive", "path": "astrapy.cursors.AsyncCommandCursor.alive", "value": "alive: bool"}} +{"id": "astrapy.cursors.AsyncCommandCursor.cursor_id", "text": "An integer uniquely identifying this cursor.", "metadata": {"kind": "attribute", "name": "cursor_id", "path": "astrapy.cursors.AsyncCommandCursor.cursor_id", "value": "cursor_id: int"}} +{"id": "astrapy.cursors.AsyncCommandCursor.close", "text": "Stop/kill the cursor, regardless of its status.", "metadata": {"kind": "function", "name": "close", "path": "astrapy.cursors.AsyncCommandCursor.close", "returns": [{"type": "None"}]}} +{"id": "astrapy.constants", "text": "", "metadata": {"kind": "module", "name": "constants", "path": "astrapy.constants", "imports": {"annotations": "__future__.annotations", "Any": "typing.Any", "Dict": "typing.Dict", "Iterable": "typing.Iterable", "Tuple": "typing.Tuple", "Union": "typing.Union", "DATA_API_ENVIRONMENT_CASSANDRA": "astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA", "DATA_API_ENVIRONMENT_DEV": "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "DATA_API_ENVIRONMENT_DSE": "astrapy.defaults.DATA_API_ENVIRONMENT_DSE", "DATA_API_ENVIRONMENT_HCD": "astrapy.defaults.DATA_API_ENVIRONMENT_HCD", "DATA_API_ENVIRONMENT_OTHER": "astrapy.defaults.DATA_API_ENVIRONMENT_OTHER", "DATA_API_ENVIRONMENT_PROD": "astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "DATA_API_ENVIRONMENT_TEST": "astrapy.defaults.DATA_API_ENVIRONMENT_TEST"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.constants.DocumentType", "text": "", "metadata": {"kind": "attribute", "name": "DocumentType", "path": "astrapy.constants.DocumentType", "value": "DocumentType = Dict[str, Any]"}} +{"id": "astrapy.constants.ProjectionType", "text": "", "metadata": {"kind": "attribute", "name": "ProjectionType", "path": "astrapy.constants.ProjectionType", "value": "ProjectionType = Union[Iterable[str], Dict[str, Union[bool, Dict[str, Union[int, Iterable[int]]]]]]"}} +{"id": "astrapy.constants.SortType", "text": "", "metadata": {"kind": "attribute", "name": "SortType", "path": "astrapy.constants.SortType", "value": "SortType = Dict[str, Any]"}} +{"id": "astrapy.constants.FilterType", "text": "", "metadata": {"kind": "attribute", "name": "FilterType", "path": "astrapy.constants.FilterType", "value": "FilterType = Dict[str, Any]"}} +{"id": "astrapy.constants.VectorType", "text": "", "metadata": {"kind": "attribute", "name": "VectorType", "path": "astrapy.constants.VectorType", "value": "VectorType = Iterable[float]"}} +{"id": "astrapy.constants.CallerType", "text": "", "metadata": {"kind": "attribute", "name": "CallerType", "path": "astrapy.constants.CallerType", "value": "CallerType = Tuple[Union[str, None], Union[str, None]]"}} +{"id": "astrapy.constants.normalize_optional_projection", "text": "", "metadata": {"kind": "function", "name": "normalize_optional_projection", "path": "astrapy.constants.normalize_optional_projection", "parameters": [{"name": "projection", "type": "ProjectionType | None"}], "returns": [{"type": "dict[str, bool | dict[str, int | Iterable[int]]] | None"}], "gathered_types": ["astrapy.constants.ProjectionType"]}} +{"id": "astrapy.constants.ReturnDocument", "text": "Admitted values for the `return_document` parameter in\n`find_one_and_replace` and `find_one_and_update` collection\nmethods.", "metadata": {"kind": "class", "name": "ReturnDocument", "path": "astrapy.constants.ReturnDocument"}} +{"id": "astrapy.constants.ReturnDocument.BEFORE", "text": "", "metadata": {"kind": "attribute", "name": "BEFORE", "path": "astrapy.constants.ReturnDocument.BEFORE", "value": "BEFORE = 'before'"}} +{"id": "astrapy.constants.ReturnDocument.AFTER", "text": "", "metadata": {"kind": "attribute", "name": "AFTER", "path": "astrapy.constants.ReturnDocument.AFTER", "value": "AFTER = 'after'"}} +{"id": "astrapy.constants.SortDocuments", "text": "Admitted values for the `sort` parameter in the find collection methods,\ne.g. `sort={\"field\": SortDocuments.ASCENDING}`.", "metadata": {"kind": "class", "name": "SortDocuments", "path": "astrapy.constants.SortDocuments"}} +{"id": "astrapy.constants.SortDocuments.ASCENDING", "text": "", "metadata": {"kind": "attribute", "name": "ASCENDING", "path": "astrapy.constants.SortDocuments.ASCENDING", "value": "ASCENDING = 1"}} +{"id": "astrapy.constants.SortDocuments.DESCENDING", "text": "", "metadata": {"kind": "attribute", "name": "DESCENDING", "path": "astrapy.constants.SortDocuments.DESCENDING", "value": "DESCENDING = -1"}} +{"id": "astrapy.constants.VectorMetric", "text": "Admitted values for the \"metric\" parameter when creating vector collections\nthrough the database `create_collection` method.", "metadata": {"kind": "class", "name": "VectorMetric", "path": "astrapy.constants.VectorMetric"}} +{"id": "astrapy.constants.VectorMetric.DOT_PRODUCT", "text": "", "metadata": {"kind": "attribute", "name": "DOT_PRODUCT", "path": "astrapy.constants.VectorMetric.DOT_PRODUCT", "value": "DOT_PRODUCT = 'dot_product'"}} +{"id": "astrapy.constants.VectorMetric.EUCLIDEAN", "text": "", "metadata": {"kind": "attribute", "name": "EUCLIDEAN", "path": "astrapy.constants.VectorMetric.EUCLIDEAN", "value": "EUCLIDEAN = 'euclidean'"}} +{"id": "astrapy.constants.VectorMetric.COSINE", "text": "", "metadata": {"kind": "attribute", "name": "COSINE", "path": "astrapy.constants.VectorMetric.COSINE", "value": "COSINE = 'cosine'"}} +{"id": "astrapy.constants.DefaultIdType", "text": "Admitted values for the \"default_id_type\" parameter when creating collections\nthrough the database `create_collection` method.", "metadata": {"kind": "class", "name": "DefaultIdType", "path": "astrapy.constants.DefaultIdType"}} +{"id": "astrapy.constants.DefaultIdType.UUID", "text": "", "metadata": {"kind": "attribute", "name": "UUID", "path": "astrapy.constants.DefaultIdType.UUID", "value": "UUID = 'uuid'"}} +{"id": "astrapy.constants.DefaultIdType.OBJECTID", "text": "", "metadata": {"kind": "attribute", "name": "OBJECTID", "path": "astrapy.constants.DefaultIdType.OBJECTID", "value": "OBJECTID = 'objectId'"}} +{"id": "astrapy.constants.DefaultIdType.UUIDV6", "text": "", "metadata": {"kind": "attribute", "name": "UUIDV6", "path": "astrapy.constants.DefaultIdType.UUIDV6", "value": "UUIDV6 = 'uuidv6'"}} +{"id": "astrapy.constants.DefaultIdType.UUIDV7", "text": "", "metadata": {"kind": "attribute", "name": "UUIDV7", "path": "astrapy.constants.DefaultIdType.UUIDV7", "value": "UUIDV7 = 'uuidv7'"}} +{"id": "astrapy.constants.DefaultIdType.DEFAULT", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT", "path": "astrapy.constants.DefaultIdType.DEFAULT", "value": "DEFAULT = 'uuid'"}} +{"id": "astrapy.constants.Environment", "text": "Admitted values for `environment` property,\ndenoting the targeted API deployment type.", "metadata": {"kind": "class", "name": "Environment", "path": "astrapy.constants.Environment"}} +{"id": "astrapy.constants.Environment.PROD", "text": "", "metadata": {"kind": "attribute", "name": "PROD", "path": "astrapy.constants.Environment.PROD", "value": "PROD = DATA_API_ENVIRONMENT_PROD", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_PROD"]}} +{"id": "astrapy.constants.Environment.DEV", "text": "", "metadata": {"kind": "attribute", "name": "DEV", "path": "astrapy.constants.Environment.DEV", "value": "DEV = DATA_API_ENVIRONMENT_DEV", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_DEV"]}} +{"id": "astrapy.constants.Environment.TEST", "text": "", "metadata": {"kind": "attribute", "name": "TEST", "path": "astrapy.constants.Environment.TEST", "value": "TEST = DATA_API_ENVIRONMENT_TEST", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_TEST"]}} +{"id": "astrapy.constants.Environment.DSE", "text": "", "metadata": {"kind": "attribute", "name": "DSE", "path": "astrapy.constants.Environment.DSE", "value": "DSE = DATA_API_ENVIRONMENT_DSE", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_DSE"]}} +{"id": "astrapy.constants.Environment.HCD", "text": "", "metadata": {"kind": "attribute", "name": "HCD", "path": "astrapy.constants.Environment.HCD", "value": "HCD = DATA_API_ENVIRONMENT_HCD", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_HCD"]}} +{"id": "astrapy.constants.Environment.CASSANDRA", "text": "", "metadata": {"kind": "attribute", "name": "CASSANDRA", "path": "astrapy.constants.Environment.CASSANDRA", "value": "CASSANDRA = DATA_API_ENVIRONMENT_CASSANDRA", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA"]}} +{"id": "astrapy.constants.Environment.OTHER", "text": "", "metadata": {"kind": "attribute", "name": "OTHER", "path": "astrapy.constants.Environment.OTHER", "value": "OTHER = DATA_API_ENVIRONMENT_OTHER", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_OTHER"]}} +{"id": "astrapy.constants.Environment.values", "text": "", "metadata": {"kind": "attribute", "name": "values", "path": "astrapy.constants.Environment.values", "value": "values = {PROD, DEV, TEST, DSE, HCD, CASSANDRA, OTHER}", "gathered_types": ["PROD", "OTHER", "DSE", "DEV", "HCD", "TEST", "CASSANDRA"]}} +{"id": "astrapy.constants.Environment.astra_db_values", "text": "", "metadata": {"kind": "attribute", "name": "astra_db_values", "path": "astrapy.constants.Environment.astra_db_values", "value": "astra_db_values = {PROD, DEV, TEST}", "gathered_types": ["PROD", "TEST", "DEV"]}} +{"id": "astrapy.operations", "text": "", "metadata": {"kind": "module", "name": "operations", "path": "astrapy.operations", "imports": {"annotations": "__future__.annotations", "ABC": "abc.ABC", "abstractmethod": "abc.abstractmethod", "dataclass": "dataclasses.dataclass", "reduce": "functools.reduce", "Any": "typing.Any", "Iterable": "typing.Iterable", "AsyncCollection": "astrapy.collection.AsyncCollection", "Collection": "astrapy.collection.Collection", "DocumentType": "astrapy.constants.DocumentType", "SortType": "astrapy.constants.SortType", "VectorType": "astrapy.constants.VectorType", "check_deprecated_vector_ize": "astrapy.meta.check_deprecated_vector_ize", "BulkWriteResult": "astrapy.results.BulkWriteResult", "DeleteResult": "astrapy.results.DeleteResult", "InsertManyResult": "astrapy.results.InsertManyResult", "InsertOneResult": "astrapy.results.InsertOneResult", "UpdateResult": "astrapy.results.UpdateResult"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.operations.reduce_bulk_write_results", "text": "Reduce a list of bulk write results into a single one.", "metadata": {"kind": "function", "name": "reduce_bulk_write_results", "path": "astrapy.operations.reduce_bulk_write_results", "parameters": [{"name": "results", "type": "list[BulkWriteResult]", "description": "a list of BulkWriteResult instances.", "default": null}], "returns": [{"type": "BulkWriteResult", "description": "A new BulkWRiteResult object which summarized the whole input list."}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.BaseOperation", "text": "Base class for all operations amenable to be used\nin bulk writes on (sync) collections.", "metadata": {"kind": "class", "name": "BaseOperation", "path": "astrapy.operations.BaseOperation", "bases": ["ABC"], "gathered_types": ["ABC"], "implemented_by": ["astrapy.operations.ReplaceOne", "astrapy.operations.UpdateMany", "astrapy.operations.DeleteMany", "astrapy.operations.UpdateOne", "astrapy.operations.InsertOne", "astrapy.operations.DeleteOne", "astrapy.operations.InsertMany"]}} +{"id": "astrapy.operations.BaseOperation.execute", "text": "", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.BaseOperation.execute", "parameters": [{"name": "collection", "type": "Collection"}, {"name": "index_in_bulk_write", "type": "int"}, {"name": "bulk_write_timeout_ms", "type": "int | None"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.InsertOne", "text": "Represents an `insert_one` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "InsertOne", "path": "astrapy.operations.InsertOne", "parameters": [{"name": "document", "type": "DocumentType"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "document", "type": "DocumentType", "description": "the document to insert."}, {"name": "vector", "type": "VectorType | None", "description": "an optional suitable vector to enrich the document at insertion.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the document instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the documents instead."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.InsertOne.document", "text": "", "metadata": {"kind": "attribute", "name": "document", "path": "astrapy.operations.InsertOne.document", "value": "document: DocumentType = document", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.InsertOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.InsertOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.InsertOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.InsertOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.InsertOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.InsertOne.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.InsertMany", "text": "Represents an `insert_many` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "InsertMany", "path": "astrapy.operations.InsertMany", "parameters": [{"name": "documents", "type": "Iterable[DocumentType]"}, {"name": "vectors", "default": "None", "type": "Iterable[VectorType | None] | None"}, {"name": "vectorize", "default": "None", "type": "Iterable[str | None] | None"}, {"name": "ordered", "default": "True", "type": "bool"}, {"name": "chunk_size", "default": "None", "type": "int | None"}, {"name": "concurrency", "default": "None", "type": "int | None"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "documents", "type": "Iterable[DocumentType]", "description": "the list document to insert."}, {"name": "vectors", "type": "Iterable[VectorType | None] | None", "description": "an optional list of vectors to enrich the documents at insertion.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the documents instead."}, {"name": "vectorize", "type": "Iterable[str | None] | None", "description": "an optional list of texts achieving the same effect as `vectors`\nexcept through an embedding service, if one is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the documents instead."}, {"name": "ordered", "type": "bool", "description": "whether the inserts should be done in sequence."}, {"name": "chunk_size", "type": "int | None", "description": "how many documents to include in a single API request.\nExceeding the server maximum allowed value results in an error.\nLeave it unspecified (recommended) to use the system default."}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent requests to the API at\na given time. It cannot be more than one for ordered insertions."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.InsertMany.documents", "text": "", "metadata": {"kind": "attribute", "name": "documents", "path": "astrapy.operations.InsertMany.documents", "value": "documents: Iterable[DocumentType] = documents", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.InsertMany.vectors", "text": "", "metadata": {"kind": "attribute", "name": "vectors", "path": "astrapy.operations.InsertMany.vectors", "value": "vectors: Iterable[VectorType | None] | None = vectors", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.InsertMany.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.InsertMany.vectorize", "value": "vectorize: Iterable[str | None] | None = vectorize"}} +{"id": "astrapy.operations.InsertMany.ordered", "text": "", "metadata": {"kind": "attribute", "name": "ordered", "path": "astrapy.operations.InsertMany.ordered", "value": "ordered: bool = ordered"}} +{"id": "astrapy.operations.InsertMany.chunk_size", "text": "", "metadata": {"kind": "attribute", "name": "chunk_size", "path": "astrapy.operations.InsertMany.chunk_size", "value": "chunk_size: int | None = chunk_size"}} +{"id": "astrapy.operations.InsertMany.concurrency", "text": "", "metadata": {"kind": "attribute", "name": "concurrency", "path": "astrapy.operations.InsertMany.concurrency", "value": "concurrency: int | None = concurrency"}} +{"id": "astrapy.operations.InsertMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.InsertMany.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.UpdateOne", "text": "Represents an `update_one` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "UpdateOne", "path": "astrapy.operations.UpdateOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "update", "type": "dict[str, Any]"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "update", "type": "dict[str, Any]", "description": "an update prescription to apply to the document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.SortType", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.UpdateOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.UpdateOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.UpdateOne.update", "text": "", "metadata": {"kind": "attribute", "name": "update", "path": "astrapy.operations.UpdateOne.update", "value": "update: dict[str, Any] = update"}} +{"id": "astrapy.operations.UpdateOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.UpdateOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.UpdateOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.UpdateOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.UpdateOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.UpdateOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.UpdateOne.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.UpdateOne.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.UpdateOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.UpdateOne.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.UpdateMany", "text": "Represents an `update_many` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "UpdateMany", "path": "astrapy.operations.UpdateMany", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "update", "type": "dict[str, Any]"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select target documents."}, {"name": "update", "type": "dict[str, Any]", "description": "an update prescription to apply to the documents."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.UpdateMany.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.UpdateMany.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.UpdateMany.update", "text": "", "metadata": {"kind": "attribute", "name": "update", "path": "astrapy.operations.UpdateMany.update", "value": "update: dict[str, Any] = update"}} +{"id": "astrapy.operations.UpdateMany.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.UpdateMany.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.UpdateMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.UpdateMany.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.ReplaceOne", "text": "Represents a `replace_one` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "ReplaceOne", "path": "astrapy.operations.ReplaceOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "replacement", "type": "DocumentType"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "replacement", "type": "DocumentType", "description": "the replacement document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.constants.SortType", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.ReplaceOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.ReplaceOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.ReplaceOne.replacement", "text": "", "metadata": {"kind": "attribute", "name": "replacement", "path": "astrapy.operations.ReplaceOne.replacement", "value": "replacement: DocumentType = replacement", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.ReplaceOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.ReplaceOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.ReplaceOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.ReplaceOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.ReplaceOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.ReplaceOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.ReplaceOne.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.ReplaceOne.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.ReplaceOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.ReplaceOne.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.DeleteOne", "text": "Represents a `delete_one` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "DeleteOne", "path": "astrapy.operations.DeleteOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.SortType", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.DeleteOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.DeleteOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.DeleteOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.DeleteOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.DeleteOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.DeleteOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.DeleteOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.DeleteOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.DeleteOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.DeleteOne.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.DeleteMany", "text": "Represents a `delete_many` operation on a (sync) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "DeleteMany", "path": "astrapy.operations.DeleteMany", "parameters": [{"name": "filter", "type": "dict[str, Any]"}], "bases": ["astrapy.operations.BaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select target documents."}], "gathered_types": ["astrapy.operations.BaseOperation"]}} +{"id": "astrapy.operations.DeleteMany.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.DeleteMany.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.DeleteMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.DeleteMany.execute", "parameters": [{"name": "collection", "type": "Collection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.operations.AsyncBaseOperation", "text": "Base class for all operations amenable to be used\nin bulk writes on (async) collections.", "metadata": {"kind": "class", "name": "AsyncBaseOperation", "path": "astrapy.operations.AsyncBaseOperation", "bases": ["ABC"], "gathered_types": ["ABC"], "implemented_by": ["astrapy.operations.AsyncInsertMany", "astrapy.operations.AsyncDeleteMany", "astrapy.operations.AsyncInsertOne", "astrapy.operations.AsyncUpdateMany", "astrapy.operations.AsyncReplaceOne", "astrapy.operations.AsyncDeleteOne", "astrapy.operations.AsyncUpdateOne"]}} +{"id": "astrapy.operations.AsyncBaseOperation.execute", "text": "", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncBaseOperation.execute", "parameters": [{"name": "collection", "type": "AsyncCollection"}, {"name": "index_in_bulk_write", "type": "int"}, {"name": "bulk_write_timeout_ms", "type": "int | None"}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncInsertOne", "text": "Represents an `insert_one` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncInsertOne", "path": "astrapy.operations.AsyncInsertOne", "parameters": [{"name": "document", "type": "DocumentType"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "document", "type": "DocumentType", "description": "the document to insert."}, {"name": "vector", "type": "VectorType | None", "description": "an optional suitable vector to enrich the document at insertion.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the document instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the document instead."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncInsertOne.document", "text": "", "metadata": {"kind": "attribute", "name": "document", "path": "astrapy.operations.AsyncInsertOne.document", "value": "document: DocumentType = document", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.AsyncInsertOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.AsyncInsertOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.AsyncInsertOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.AsyncInsertOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.AsyncInsertOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncInsertOne.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncInsertMany", "text": "Represents an `insert_many` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncInsertMany", "path": "astrapy.operations.AsyncInsertMany", "parameters": [{"name": "documents", "type": "Iterable[DocumentType]"}, {"name": "vectors", "default": "None", "type": "Iterable[VectorType | None] | None"}, {"name": "vectorize", "default": "None", "type": "Iterable[str | None] | None"}, {"name": "ordered", "default": "True", "type": "bool"}, {"name": "chunk_size", "default": "None", "type": "int | None"}, {"name": "concurrency", "default": "None", "type": "int | None"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "documents", "type": "Iterable[DocumentType]", "description": "the list document to insert."}, {"name": "vectors", "type": "Iterable[VectorType | None] | None", "description": "an optional list of vectors to enrich the documents at insertion.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the documents instead."}, {"name": "vectorize", "type": "Iterable[str | None] | None", "description": "an optional list of texts achieving the same effect as `vectors`\nexcept through an embedding service, if one is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the documents instead."}, {"name": "ordered", "type": "bool", "description": "whether the inserts should be done in sequence."}, {"name": "chunk_size", "type": "int | None", "description": "how many documents to include in a single API request.\nExceeding the server maximum allowed value results in an error.\nLeave it unspecified (recommended) to use the system default."}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent requests to the API at\na given time. It cannot be more than one for ordered insertions."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncInsertMany.documents", "text": "", "metadata": {"kind": "attribute", "name": "documents", "path": "astrapy.operations.AsyncInsertMany.documents", "value": "documents: Iterable[DocumentType] = documents", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.AsyncInsertMany.vectors", "text": "", "metadata": {"kind": "attribute", "name": "vectors", "path": "astrapy.operations.AsyncInsertMany.vectors", "value": "vectors: Iterable[VectorType | None] | None = vectors", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.AsyncInsertMany.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.AsyncInsertMany.vectorize", "value": "vectorize: Iterable[str | None] | None = vectorize"}} +{"id": "astrapy.operations.AsyncInsertMany.ordered", "text": "", "metadata": {"kind": "attribute", "name": "ordered", "path": "astrapy.operations.AsyncInsertMany.ordered", "value": "ordered: bool = ordered"}} +{"id": "astrapy.operations.AsyncInsertMany.chunk_size", "text": "", "metadata": {"kind": "attribute", "name": "chunk_size", "path": "astrapy.operations.AsyncInsertMany.chunk_size", "value": "chunk_size: int | None = chunk_size"}} +{"id": "astrapy.operations.AsyncInsertMany.concurrency", "text": "", "metadata": {"kind": "attribute", "name": "concurrency", "path": "astrapy.operations.AsyncInsertMany.concurrency", "value": "concurrency: int | None = concurrency"}} +{"id": "astrapy.operations.AsyncInsertMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncInsertMany.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncUpdateOne", "text": "Represents an `update_one` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncUpdateOne", "path": "astrapy.operations.AsyncUpdateOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "update", "type": "dict[str, Any]"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "update", "type": "dict[str, Any]", "description": "an update prescription to apply to the document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.SortType", "astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncUpdateOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.AsyncUpdateOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.AsyncUpdateOne.update", "text": "", "metadata": {"kind": "attribute", "name": "update", "path": "astrapy.operations.AsyncUpdateOne.update", "value": "update: dict[str, Any] = update"}} +{"id": "astrapy.operations.AsyncUpdateOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.AsyncUpdateOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.AsyncUpdateOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.AsyncUpdateOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.AsyncUpdateOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.AsyncUpdateOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.AsyncUpdateOne.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.AsyncUpdateOne.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.AsyncUpdateOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncUpdateOne.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncUpdateMany", "text": "Represents an `update_many` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncUpdateMany", "path": "astrapy.operations.AsyncUpdateMany", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "update", "type": "dict[str, Any]"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select target documents."}, {"name": "update", "type": "dict[str, Any]", "description": "an update prescription to apply to the documents."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncUpdateMany.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.AsyncUpdateMany.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.AsyncUpdateMany.update", "text": "", "metadata": {"kind": "attribute", "name": "update", "path": "astrapy.operations.AsyncUpdateMany.update", "value": "update: dict[str, Any] = update"}} +{"id": "astrapy.operations.AsyncUpdateMany.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.AsyncUpdateMany.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.AsyncUpdateMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncUpdateMany.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncReplaceOne", "text": "Represents a `replace_one` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncReplaceOne", "path": "astrapy.operations.AsyncReplaceOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "replacement", "type": "DocumentType"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}, {"name": "upsert", "default": "False", "type": "bool"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "replacement", "type": "DocumentType", "description": "the replacement document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}, {"name": "upsert", "type": "bool", "description": "controls what to do when no documents are found."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.constants.SortType", "astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncReplaceOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.AsyncReplaceOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.AsyncReplaceOne.replacement", "text": "", "metadata": {"kind": "attribute", "name": "replacement", "path": "astrapy.operations.AsyncReplaceOne.replacement", "value": "replacement: DocumentType = replacement", "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.operations.AsyncReplaceOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.AsyncReplaceOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.AsyncReplaceOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.AsyncReplaceOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.AsyncReplaceOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.AsyncReplaceOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.AsyncReplaceOne.upsert", "text": "", "metadata": {"kind": "attribute", "name": "upsert", "path": "astrapy.operations.AsyncReplaceOne.upsert", "value": "upsert: bool = upsert"}} +{"id": "astrapy.operations.AsyncReplaceOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncReplaceOne.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncDeleteOne", "text": "Represents a `delete_one` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncDeleteOne", "path": "astrapy.operations.AsyncDeleteOne", "parameters": [{"name": "filter", "type": "dict[str, Any]"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select a target document."}, {"name": "vector", "type": "VectorType | None", "description": "a vector of numbers to use for ANN (vector-search) sorting.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead."}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, with the same result as the\n`vector` attribute, through an embedding service, assuming one is\nconfigured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead."}, {"name": "sort", "type": "SortType | None", "description": "controls ordering of results, hence which document is affected."}], "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.SortType", "astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncDeleteOne.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.AsyncDeleteOne.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.AsyncDeleteOne.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.operations.AsyncDeleteOne.vector", "value": "vector: VectorType | None = vector", "gathered_types": ["astrapy.constants.VectorType"]}} +{"id": "astrapy.operations.AsyncDeleteOne.vectorize", "text": "", "metadata": {"kind": "attribute", "name": "vectorize", "path": "astrapy.operations.AsyncDeleteOne.vectorize", "value": "vectorize: str | None = vectorize"}} +{"id": "astrapy.operations.AsyncDeleteOne.sort", "text": "", "metadata": {"kind": "attribute", "name": "sort", "path": "astrapy.operations.AsyncDeleteOne.sort", "value": "sort: SortType | None = sort", "gathered_types": ["astrapy.constants.SortType"]}} +{"id": "astrapy.operations.AsyncDeleteOne.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncDeleteOne.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.operations.AsyncDeleteMany", "text": "Represents a `delete_many` operation on a (async) collection.\nSee the documentation on the collection method for more information.", "metadata": {"kind": "class", "name": "AsyncDeleteMany", "path": "astrapy.operations.AsyncDeleteMany", "parameters": [{"name": "filter", "type": "dict[str, Any]"}], "bases": ["astrapy.operations.AsyncBaseOperation"], "attributes": [{"name": "filter", "type": "dict[str, Any]", "description": "a filter condition to select target documents."}], "gathered_types": ["astrapy.operations.AsyncBaseOperation"]}} +{"id": "astrapy.operations.AsyncDeleteMany.filter", "text": "", "metadata": {"kind": "attribute", "name": "filter", "path": "astrapy.operations.AsyncDeleteMany.filter", "value": "filter: dict[str, Any] = filter"}} +{"id": "astrapy.operations.AsyncDeleteMany.execute", "text": "Execute this operation against a collection as part of a bulk write.", "metadata": {"kind": "function", "name": "execute", "path": "astrapy.operations.AsyncDeleteMany.execute", "parameters": [{"name": "collection", "type": "AsyncCollection", "description": "the collection this write targets.", "default": null}, {"name": "insert_in_bulk_write", "description": "the index in the list of bulkoperations", "default": null}], "returns": [{"type": "BulkWriteResult"}], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.collection.AsyncCollection"]}} +{"id": "astrapy.admin", "text": "", "metadata": {"kind": "module", "name": "admin", "path": "astrapy.admin", "imports": {"annotations": "__future__.annotations", "asyncio": "asyncio", "logging": "logging", "re": "re", "time": "time", "warnings": "warnings", "ABC": "abc.ABC", "abstractmethod": "abc.abstractmethod", "dataclass": "dataclasses.dataclass", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Sequence": "typing.Sequence", "deprecation": "deprecation", "__version__": "astrapy.__version__", "APICommander": "astrapy.api_commander.APICommander", "coerce_token_provider": "astrapy.authentication.coerce_token_provider", "redact_secret": "astrapy.authentication.redact_secret", "CallerType": "astrapy.constants.CallerType", "Environment": "astrapy.constants.Environment", "CommandCursor": "astrapy.cursors.CommandCursor", "API_ENDPOINT_TEMPLATE_ENV_MAP": "astrapy.defaults.API_ENDPOINT_TEMPLATE_ENV_MAP", "API_PATH_ENV_MAP": "astrapy.defaults.API_PATH_ENV_MAP", "API_VERSION_ENV_MAP": "astrapy.defaults.API_VERSION_ENV_MAP", "DEFAULT_DATA_API_AUTH_HEADER": "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "DEFAULT_DEV_OPS_AUTH_HEADER": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "DEFAULT_DEV_OPS_AUTH_PREFIX": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_PREFIX", "DEV_OPS_DATABASE_POLL_INTERVAL_S": "astrapy.defaults.DEV_OPS_DATABASE_POLL_INTERVAL_S", "DEV_OPS_DATABASE_STATUS_ACTIVE": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_ACTIVE", "DEV_OPS_DATABASE_STATUS_INITIALIZING": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_INITIALIZING", "DEV_OPS_DATABASE_STATUS_MAINTENANCE": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_MAINTENANCE", "DEV_OPS_DATABASE_STATUS_PENDING": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_PENDING", "DEV_OPS_DATABASE_STATUS_TERMINATING": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_TERMINATING", "DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE": "astrapy.defaults.DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE", "DEV_OPS_KEYSPACE_POLL_INTERVAL_S": "astrapy.defaults.DEV_OPS_KEYSPACE_POLL_INTERVAL_S", "DEV_OPS_RESPONSE_HTTP_ACCEPTED": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_ACCEPTED", "DEV_OPS_RESPONSE_HTTP_CREATED": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_CREATED", "DEV_OPS_URL_ENV_MAP": "astrapy.defaults.DEV_OPS_URL_ENV_MAP", "DEV_OPS_VERSION_ENV_MAP": "astrapy.defaults.DEV_OPS_VERSION_ENV_MAP", "NAMESPACE_DEPRECATION_NOTICE_METHOD": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_METHOD", "SET_CALLER_DEPRECATION_NOTICE": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "DataAPIFaultyResponseException": "astrapy.exceptions.DataAPIFaultyResponseException", "DevOpsAPIException": "astrapy.exceptions.DevOpsAPIException", "MultiCallTimeoutManager": "astrapy.exceptions.MultiCallTimeoutManager", "base_timeout_info": "astrapy.exceptions.base_timeout_info", "AdminDatabaseInfo": "astrapy.info.AdminDatabaseInfo", "DatabaseInfo": "astrapy.info.DatabaseInfo", "FindEmbeddingProvidersResult": "astrapy.info.FindEmbeddingProvidersResult", "check_caller_parameters": "astrapy.meta.check_caller_parameters", "check_namespace_keyspace": "astrapy.meta.check_namespace_keyspace", "check_update_db_namespace_keyspace": "astrapy.meta.check_update_db_namespace_keyspace", "HttpMethod": "astrapy.request_tools.HttpMethod", "AsyncDatabase": "astrapy.AsyncDatabase", "Database": "astrapy.Database", "TokenProvider": "astrapy.authentication.TokenProvider"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.admin.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.admin.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.admin.database_id_matcher", "text": "", "metadata": {"kind": "attribute", "name": "database_id_matcher", "path": "astrapy.admin.database_id_matcher", "value": "database_id_matcher = re.compile('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')"}} +{"id": "astrapy.admin.api_endpoint_parser", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint_parser", "path": "astrapy.admin.api_endpoint_parser", "value": "api_endpoint_parser = re.compile('https://([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})-([a-z0-9\\\\-]+).apps.astra[\\\\-]{0,1}(dev|test)?.datastax.com')"}} +{"id": "astrapy.admin.api_endpoint_description", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint_description", "path": "astrapy.admin.api_endpoint_description", "value": "api_endpoint_description = 'https://-.apps.astra.datastax.com'"}} +{"id": "astrapy.admin.generic_api_url_matcher", "text": "", "metadata": {"kind": "attribute", "name": "generic_api_url_matcher", "path": "astrapy.admin.generic_api_url_matcher", "value": "generic_api_url_matcher = re.compile('^https?:\\\\/\\\\/[a-zA-Z0-9\\\\-.]+(\\\\:[0-9]{1,6}){0,1}$')"}} +{"id": "astrapy.admin.generic_api_url_descriptor", "text": "", "metadata": {"kind": "attribute", "name": "generic_api_url_descriptor", "path": "astrapy.admin.generic_api_url_descriptor", "value": "generic_api_url_descriptor = 'http[s]://[:port]'"}} +{"id": "astrapy.admin.ParsedAPIEndpoint", "text": "The results of successfully parsing an Astra DB API endpoint, for internal\nby database metadata-related functions.", "metadata": {"kind": "class", "name": "ParsedAPIEndpoint", "path": "astrapy.admin.ParsedAPIEndpoint", "parameters": [{"name": "database_id", "type": "str"}, {"name": "region", "type": "str"}, {"name": "environment", "type": "str"}], "attributes": [{"name": "database_id", "type": "str", "description": "e. g. \"01234567-89ab-cdef-0123-456789abcdef\"."}, {"name": "region", "type": "str", "description": "a region ID, such as \"us-west1\"."}, {"name": "environment", "type": "str", "description": "a label, whose value is one of Environment.PROD,\nEnvironment.DEV or Environment.TEST."}]}} +{"id": "astrapy.admin.ParsedAPIEndpoint.database_id", "text": "", "metadata": {"kind": "attribute", "name": "database_id", "path": "astrapy.admin.ParsedAPIEndpoint.database_id", "value": "database_id: str"}} +{"id": "astrapy.admin.ParsedAPIEndpoint.region", "text": "", "metadata": {"kind": "attribute", "name": "region", "path": "astrapy.admin.ParsedAPIEndpoint.region", "value": "region: str"}} +{"id": "astrapy.admin.ParsedAPIEndpoint.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.admin.ParsedAPIEndpoint.environment", "value": "environment: str"}} +{"id": "astrapy.admin.parse_api_endpoint", "text": "Parse an API Endpoint into a ParsedAPIEndpoint structure.", "metadata": {"kind": "function", "name": "parse_api_endpoint", "path": "astrapy.admin.parse_api_endpoint", "parameters": [{"name": "api_endpoint", "type": "str", "description": "a full API endpoint for the Data API.", "default": null}], "returns": [{"type": "ParsedAPIEndpoint | None", "description": "The parsed ParsedAPIEndpoint. If parsing fails, return None."}], "gathered_types": ["ParsedAPIEndpoint"]}} +{"id": "astrapy.admin.api_endpoint_parsing_error_message", "text": "Format an error message with a suggestion for the expected url format.", "metadata": {"kind": "function", "name": "api_endpoint_parsing_error_message", "path": "astrapy.admin.api_endpoint_parsing_error_message", "parameters": [{"name": "failing_url", "type": "str"}], "returns": [{"type": "str"}]}} +{"id": "astrapy.admin.parse_generic_api_url", "text": "Validate a generic API Endpoint string,\nsuch as `http://10.1.1.1:123` or `https://my.domain`.", "metadata": {"kind": "function", "name": "parse_generic_api_url", "path": "astrapy.admin.parse_generic_api_url", "parameters": [{"name": "api_endpoint", "type": "str", "description": "a string supposedly expressing a valid API Endpoint", "default": null}], "returns": [{"type": "str | None", "description": "a normalized (stripped) version of the endpoint if valid. If invalid,"}, {"type": "str | None", "description": "return None."}]}} +{"id": "astrapy.admin.generic_api_url_parsing_error_message", "text": "Format an error message with a suggestion for the expected url format.", "metadata": {"kind": "function", "name": "generic_api_url_parsing_error_message", "path": "astrapy.admin.generic_api_url_parsing_error_message", "parameters": [{"name": "failing_url", "type": "str"}], "returns": [{"type": "str"}]}} +{"id": "astrapy.admin.build_api_endpoint", "text": "Build the API Endpoint full strings from database parameters.", "metadata": {"kind": "function", "name": "build_api_endpoint", "path": "astrapy.admin.build_api_endpoint", "parameters": [{"name": "environment", "type": "str", "description": "a label, whose value can be Environment.PROD\nor another of Environment.* for which this operation makes sense.", "default": null}, {"name": "database_id", "type": "str", "description": "e. g. \"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "region", "type": "str", "description": "a region ID, such as \"us-west1\".", "default": null}], "returns": [{"type": "str", "description": "the endpoint string, such as \"https://01234567-...-eu-west1.apps.datastax.com\""}]}} +{"id": "astrapy.admin.check_id_endpoint_parg_kwargs", "text": "Utility function helping with the transition to endpoint-first constructors,\nwith ID being the other possibility.\n\nIt is called with the positional argument, the api_endpoint and id kwargs: it\nthen verifies legitimacy and returns a normalized (endpoint, id) \"either\" value.\n\nNote: this uses the ID regexp to recognize IDs. Crucially, no endpoint regexp\nhere, since even non-Astra endpoints must be properly processed by this validator.", "metadata": {"kind": "function", "name": "check_id_endpoint_parg_kwargs", "path": "astrapy.admin.check_id_endpoint_parg_kwargs", "parameters": [{"name": "p_arg", "type": "str | None"}, {"name": "api_endpoint", "type": "str | None"}, {"name": "id", "type": "str | None"}], "returns": [{"type": "tuple[str | None, str | None]"}]}} +{"id": "astrapy.admin.fetch_raw_database_info_from_id_token", "text": "Fetch database information through the DevOps API and return it in\nfull, exactly like the API gives it back.", "metadata": {"kind": "function", "name": "fetch_raw_database_info_from_id_token", "path": "astrapy.admin.fetch_raw_database_info_from_id_token", "parameters": [{"name": "id", "type": "str", "description": "e. g. \"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "token", "type": "str | None", "description": "a valid token to access the database information.", "default": null}, {"name": "environment", "type": "str", "description": "a string representing the target Data API environment.\nIt can be left unspecified for the default value of `Environment.PROD`.\nOnly Astra DB environments can be meaningfully supplied.", "value": "Environment.PROD", "default": "Environment.PROD"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for waiting on a response.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "The full response from the DevOps API about the database."}], "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.admin.async_fetch_raw_database_info_from_id_token", "text": "Fetch database information through the DevOps API and return it in\nfull, exactly like the API gives it back.\nAsync version of the function, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_fetch_raw_database_info_from_id_token", "path": "astrapy.admin.async_fetch_raw_database_info_from_id_token", "parameters": [{"name": "id", "type": "str", "description": "e. g. \"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "token", "type": "str | None", "description": "a valid token to access the database information.", "default": null}, {"name": "environment", "type": "str", "description": "a string representing the target Data API environment.\nIt can be left unspecified for the default value of `Environment.PROD`.\nOnly Astra DB environments can be meaningfully supplied.", "value": "Environment.PROD", "default": "Environment.PROD"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for waiting on a response.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "The full response from the DevOps API about the database."}], "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.admin.fetch_database_info", "text": "Fetch database information through the DevOps API.", "metadata": {"kind": "function", "name": "fetch_database_info", "path": "astrapy.admin.fetch_database_info", "parameters": [{"name": "api_endpoint", "type": "str", "description": "a full API endpoint for the Data API.", "default": null}, {"name": "token", "type": "str | None", "description": "a valid token to access the database information.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the desired keyspace that will be used in the result.\nIf not specified, the resulting database info will show it as None.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for waiting on a response.", "value": "None", "default": "None"}], "returns": [{"type": "DatabaseInfo | None", "description": "A DatabaseInfo object."}, {"type": "DatabaseInfo | None", "description": "If the API endpoint fails to be parsed, None is returned."}, {"type": "DatabaseInfo | None", "description": "For valid-looking endpoints, if something goes wrong an exception is raised."}], "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.admin.async_fetch_database_info", "text": "Fetch database information through the DevOps API.\nAsync version of the function, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_fetch_database_info", "path": "astrapy.admin.async_fetch_database_info", "parameters": [{"name": "api_endpoint", "type": "str", "description": "a full API endpoint for the Data API.", "default": null}, {"name": "token", "type": "str | None", "description": "a valid token to access the database information.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "the desired keyspace that will be used in the result.\nIf not specified, the resulting database info will show it as None.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for waiting on a response.", "value": "None", "default": "None"}], "returns": [{"type": "DatabaseInfo | None", "description": "A DatabaseInfo object."}, {"type": "DatabaseInfo | None", "description": "If the API endpoint fails to be parsed, None is returned."}, {"type": "DatabaseInfo | None", "description": "For valid-looking endpoints, if something goes wrong an exception is raised."}], "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.admin.normalize_region_for_id", "text": "", "metadata": {"kind": "function", "name": "normalize_region_for_id", "path": "astrapy.admin.normalize_region_for_id", "parameters": [{"name": "database_id", "type": "str"}, {"name": "token_str", "type": "str | None"}, {"name": "environment", "type": "str"}, {"name": "region_param", "type": "str | None"}, {"name": "max_time_ms", "type": "int | None"}], "returns": [{"type": "str"}]}} +{"id": "astrapy.admin.AstraDBAdmin", "text": "An \"admin\" object, able to perform administrative tasks at the databases\nlevel, such as creating, listing or dropping databases.", "metadata": {"kind": "class", "name": "AstraDBAdmin", "path": "astrapy.admin.AstraDBAdmin", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission to perform admin tasks.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a label, whose value is one of Environment.PROD (default),\nEnvironment.DEV or Environment.TEST.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which DevOps API calls are performed. These end up in\nthe request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the DevOps API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient\n>>> my_client = DataAPIClient(\"AstraCS:...\")\n>>> my_astra_db_admin = my_client.get_admin()\n>>> database_list = my_astra_db_admin.list_databases()\n>>> len(database_list)\n3\n>>> database_list[2].id\n'01234567-...'\n>>> my_db_admin = my_astra_db_admin.get_database_admin(\"01234567-...\")\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'staging_keyspace']", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.admin.AstraDBAdmin.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.admin.AstraDBAdmin.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.admin.AstraDBAdmin.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.admin.AstraDBAdmin.environment", "value": "environment = environment or Environment.PROD.lower()", "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.admin.AstraDBAdmin.dev_ops_url", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_url", "path": "astrapy.admin.AstraDBAdmin.dev_ops_url", "value": "dev_ops_url = DEV_OPS_URL_ENV_MAP[self.environment]", "gathered_types": ["astrapy.defaults.DEV_OPS_URL_ENV_MAP"]}} +{"id": "astrapy.admin.AstraDBAdmin.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.admin.AstraDBAdmin.callers", "value": "callers = callers_param"}} +{"id": "astrapy.admin.AstraDBAdmin.with_options", "text": "Create a clone of this AstraDBAdmin with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.admin.AstraDBAdmin.with_options", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which DevOps API calls are performed. These end up in\nthe request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the DevOps API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBAdmin", "description": "a new AstraDBAdmin instance."}], "example": ">>> another_astra_db_admin = my_astra_db_admin.with_options(\n... callers=[(\"caller_identity\", \"1.2.0\")],\n... )", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.admin.AstraDBAdmin", "astrapy.constants.CallerType"]}} +{"id": "astrapy.admin.AstraDBAdmin.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe DevOps API calls will be performed (the \"caller\").\n\nNew objects spawned from this client afterwards will inherit the new settings.", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.admin.AstraDBAdmin.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe DevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_astra_db_admin.set_caller(\n... callers=[(\"the_caller\", \"0.1.0\")],\n... )"}} +{"id": "astrapy.admin.AstraDBAdmin.list_databases", "text": "Get the list of databases, as obtained with a request to the DevOps API.", "metadata": {"kind": "function", "name": "list_databases", "path": "astrapy.admin.AstraDBAdmin.list_databases", "parameters": [{"name": "include", "type": "str | None", "description": "a filter on what databases are to be returned. As per\nDevOps API, defaults to \"nonterminated\". Pass \"all\" to include\nthe already terminated databases.", "value": "None", "default": "None"}, {"name": "provider", "type": "str | None", "description": "a filter on the cloud provider for the databases.\nAs per DevOps API, defaults to \"ALL\". Pass e.g. \"AWS\" to\nrestrict the results.", "value": "None", "default": "None"}, {"name": "page_size", "type": "int | None", "description": "number of results per page from the DevOps API. Optional.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the API request.", "value": "None", "default": "None"}], "returns": [{"type": "CommandCursor[AdminDatabaseInfo]", "description": "A CommandCursor to iterate over the detected databases,"}, {"type": "CommandCursor[AdminDatabaseInfo]", "description": "represented as AdminDatabaseInfo objects."}], "example": ">>> database_cursor = my_astra_db_admin.list_databases()\n>>> database_list = list(database_cursor)\n>>> len(database_list)\n3\n>>> database_list[2].id\n'01234567-...'\n>>> database_list[2].status\n'ACTIVE'\n>>> database_list[2].info.region\n'eu-west-1'", "gathered_types": ["astrapy.info.AdminDatabaseInfo", "astrapy.cursors.CommandCursor"]}} +{"id": "astrapy.admin.AstraDBAdmin.async_list_databases", "text": "Get the list of databases, as obtained with a request to the DevOps API.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_list_databases", "path": "astrapy.admin.AstraDBAdmin.async_list_databases", "parameters": [{"name": "include", "type": "str | None", "description": "a filter on what databases are to be returned. As per\nDevOps API, defaults to \"nonterminated\". Pass \"all\" to include\nthe already terminated databases.", "value": "None", "default": "None"}, {"name": "provider", "type": "str | None", "description": "a filter on the cloud provider for the databases.\nAs per DevOps API, defaults to \"ALL\". Pass e.g. \"AWS\" to\nrestrict the results.", "value": "None", "default": "None"}, {"name": "page_size", "type": "int | None", "description": "number of results per page from the DevOps API. Optional.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the API request.", "value": "None", "default": "None"}], "returns": [{"type": "CommandCursor[AdminDatabaseInfo]", "description": "A CommandCursor to iterate over the detected databases,"}, {"type": "CommandCursor[AdminDatabaseInfo]", "description": "represented as AdminDatabaseInfo objects."}, {"type": "CommandCursor[AdminDatabaseInfo]", "description": "Note that the return type is not an awaitable, rather"}, {"type": "CommandCursor[AdminDatabaseInfo]", "description": "a regular iterable, e.g. for use in ordinary \"for\" loops."}], "example": ">>> async def check_if_db_exists(db_id: str) -> bool:\n... db_cursor = await my_astra_db_admin.async_list_databases()\n... db_list = list(dd_cursor)\n... return db_id in db_list\n...\n>>> asyncio.run(check_if_db_exists(\"xyz\"))\nTrue\n>>> asyncio.run(check_if_db_exists(\"01234567-...\"))\nFalse", "gathered_types": ["astrapy.info.AdminDatabaseInfo", "astrapy.cursors.CommandCursor"]}} +{"id": "astrapy.admin.AstraDBAdmin.database_info", "text": "Get the full information on a given database, through a request to the DevOps API.", "metadata": {"kind": "function", "name": "database_info", "path": "astrapy.admin.AstraDBAdmin.database_info", "parameters": [{"name": "id", "type": "str", "description": "the ID of the target database, e. g.\n\"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the API request.", "value": "None", "default": "None"}], "returns": [{"type": "AdminDatabaseInfo", "description": "An AdminDatabaseInfo object."}], "example": ">>> details_of_my_db = my_astra_db_admin.database_info(\"01234567-...\")\n>>> details_of_my_db.id\n'01234567-...'\n>>> details_of_my_db.status\n'ACTIVE'\n>>> details_of_my_db.info.region\n'eu-west-1'", "gathered_types": ["astrapy.info.AdminDatabaseInfo"]}} +{"id": "astrapy.admin.AstraDBAdmin.async_database_info", "text": "Get the full information on a given database, through a request to the DevOps API.\nThis is an awaitable method suitable for use within an asyncio event loop.", "metadata": {"kind": "function", "name": "async_database_info", "path": "astrapy.admin.AstraDBAdmin.async_database_info", "parameters": [{"name": "id", "type": "str", "description": "the ID of the target database, e. g.\n\"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the API request.", "value": "None", "default": "None"}], "returns": [{"type": "AdminDatabaseInfo", "description": "An AdminDatabaseInfo object."}], "example": ">>> async def check_if_db_active(db_id: str) -> bool:\n... db_info = await my_astra_db_admin.async_database_info(db_id)\n... return db_info.status == \"ACTIVE\"\n...\n>>> asyncio.run(check_if_db_active(\"01234567-...\"))\nTrue", "gathered_types": ["astrapy.info.AdminDatabaseInfo"]}} +{"id": "astrapy.admin.AstraDBAdmin.create_database", "text": "Create a database as requested, optionally waiting for it to be ready.", "metadata": {"kind": "function", "name": "create_database", "path": "astrapy.admin.AstraDBAdmin.create_database", "parameters": [{"name": "name", "type": "str", "description": "the desired name for the database.", "default": null}, {"name": "cloud_provider", "type": "str", "description": "one of 'aws', 'gcp' or 'azure'.", "default": null}, {"name": "region", "type": "str", "description": "any of the available cloud regions.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "name for the one keyspace the database starts with.\nIf omitted, DevOps API will use its default.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe newly-created database is in ACTIVE state (a few minutes,\nusually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status before working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "An AstraDBDatabaseAdmin instance."}], "example": ">>> my_new_db_admin = my_astra_db_admin.create_database(\n... \"new_database\",\n... cloud_provider=\"aws\",\n... region=\"ap-south-1\",\n... )\n>>> my_new_db = my_new_db_admin.get_database()\n>>> my_coll = my_new_db.create_collection(\"movies\", dimension=2)\n>>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.1, 0.2]})", "gathered_types": ["astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBAdmin.async_create_database", "text": "Create a database as requested, optionally waiting for it to be ready.\nThis is an awaitable method suitable for use within an asyncio event loop.", "metadata": {"kind": "function", "name": "async_create_database", "path": "astrapy.admin.AstraDBAdmin.async_create_database", "parameters": [{"name": "name", "type": "str", "description": "the desired name for the database.", "default": null}, {"name": "cloud_provider", "type": "str", "description": "one of 'aws', 'gcp' or 'azure'.", "default": null}, {"name": "region", "type": "str", "description": "any of the available cloud regions.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "name for the one keyspace the database starts with.\nIf omitted, DevOps API will use its default.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe newly-created database is in ACTIVE state (a few minutes,\nusually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status before working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "An AstraDBDatabaseAdmin instance."}], "example": ">>> asyncio.run(\n... my_astra_db_admin.async_create_database(\n... \"new_database\",\n... cloud_provider=\"aws\",\n... region=\"ap-south-1\",\n.... )\n... )\nAstraDBDatabaseAdmin(id=...)", "gathered_types": ["astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBAdmin.drop_database", "text": "Drop a database, i.e. delete it completely and permanently with all its data.", "metadata": {"kind": "function", "name": "drop_database", "path": "astrapy.admin.AstraDBAdmin.drop_database", "parameters": [{"name": "id", "type": "str", "description": "The ID of the database to drop, e. g.\n\"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe database has actually been deleted (generally a few minutes).\nIf False, it will return right after issuing the\ndrop request to the DevOps API, and it will be responsibility\nof the caller to check the database status/availability\nafter that, if desired.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> database_list_pre = my_astra_db_admin.list_databases()\n>>> len(database_list_pre)\n3\n>>> my_astra_db_admin.drop_database(\"01234567-...\")\n{'ok': 1}\n>>> database_list_post = my_astra_db_admin.list_databases()\n>>> len(database_list_post)\n2"}} +{"id": "astrapy.admin.AstraDBAdmin.async_drop_database", "text": "Drop a database, i.e. delete it completely and permanently with all its data.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_drop_database", "path": "astrapy.admin.AstraDBAdmin.async_drop_database", "parameters": [{"name": "id", "type": "str", "description": "The ID of the database to drop, e. g.\n\"01234567-89ab-cdef-0123-456789abcdef\".", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe database has actually been deleted (generally a few minutes).\nIf False, it will return right after issuing the\ndrop request to the DevOps API, and it will be responsibility\nof the caller to check the database status/availability\nafter that, if desired.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(\n... my_astra_db_admin.async_drop_database(\"01234567-...\")\n... )\n{'ok': 1}"}} +{"id": "astrapy.admin.AstraDBAdmin.get_database_admin", "text": "Create an AstraDBDatabaseAdmin object for admin work within a certain database.", "metadata": {"kind": "function", "name": "get_database_admin", "path": "astrapy.admin.AstraDBAdmin.get_database_admin", "parameters": [{"name": "api_endpoint_or_id", "type": "str | None", "description": "positional parameter that can stand for both\n`api_endpoint` and `id`. Passing them together is an error.", "value": "None", "default": "None"}, {"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "value": "None", "default": "None"}, {"name": "id", "type": "str | None", "description": "the target database ID. This is alternative to using the API Endpoint.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "the region to use for connecting to the database. The\ndatabase must be located in that region. This parameter can be used\nonly if the database is specified by its ID (instead of API Endpoint).\nIf this parameter is not passed, and cannot be inferred\nfrom the API endpoint, an additional DevOps API request is made\nto determine the default region and use it subsequently.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "An AstraDBDatabaseAdmin instance representing the requested database."}], "example": ">>> my_db_admin = my_astra_db_admin.get_database_admin(\"01234567-...\")\n>>> my_db_admin.list_keyspaces()\n['default_keyspace']\n>>> my_db_admin.create_keyspace(\"that_other_one\")\n{'ok': 1}\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'that_other_one']", "note": "This method does not perform any admin-level operation through\nthe DevOps API. For actual creation of a database, see the\n`create_database` method.", "gathered_types": ["astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBAdmin.get_database", "text": "Create a Database instance for a specific database, to be used\nwhen doing data-level work (such as creating/managing collections).", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.admin.AstraDBAdmin.get_database", "parameters": [{"name": "api_endpoint_or_id", "type": "str | None", "description": "positional parameter that can stand for both\n`api_endpoint` and `id`. Passing them together is an error.", "value": "None", "default": "None"}, {"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of\nthe one set for this object.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "used to specify a certain keyspace the resulting\nDatabase will primarily work on. If not specified, an additional\nDevOps API call reveals the default keyspace for the target database.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "id", "type": "str | None", "description": "the target database ID. This is alternative to using the API Endpoint.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "the region to use for connecting to the database. The\ndatabase must be located in that region. This parameter can be used\nonly if the database is specified by its ID (instead of API Endpoint).\nIf this parameter is not passed, and cannot be inferred\nfrom the API endpoint, an additional DevOps API request is made\nto determine the default region and use it subsequently.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "A Database object ready to be used."}], "example": ">>> my_db = my_astra_db_admin.get_database(\n... \"https://-.apps.astra.datastax.com\",\n... keyspace=\"my_prod_keyspace\",\n... )\n>>> coll = my_db.create_collection(\"movies\", dimension=2)\n>>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.3, 0.4]})", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.admin.AstraDBAdmin.get_async_database", "text": "Create an AsyncDatabase instance for a specific database, to be used\nwhen doing data-level work (such as creating/managing collections).", "metadata": {"kind": "function", "name": "get_async_database", "path": "astrapy.admin.AstraDBAdmin.get_async_database", "parameters": [{"name": "api_endpoint_or_id", "type": "str | None", "description": "positional parameter that can stand for both\n`api_endpoint` and `id`. Passing them together is an error.", "value": "None", "default": "None"}, {"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of\nthe one set for this object.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "used to specify a certain keyspace the resulting\nAsyncDatabase will primarily work on. If not specified, an additional\nDevOps API call reveals the default keyspace for the target database.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "id", "type": "str | None", "description": "the target database ID. This is alternative to using the API Endpoint.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "the region to use for connecting to the database. The\ndatabase must be located in that region. This parameter can be used\nonly if the database is specified by its ID (instead of API Endpoint).\nIf this parameter is not passed, and cannot be inferred\nfrom the API endpoint, an additional DevOps API request is made\nto determine the default region and use it subsequently.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}, {"name": "max_time_ms", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "default": null}], "returns": [{"type": "AsyncDatabase", "description": "An AsyncDatabase object ready to be used."}], "example": ">>> async def create_use_collection(\n... admin: AstraDBAdmin,\n... api_endpoint: str,\n... keyspace: str,\n... ) -> None:\n... my_async_db = admin.get_async_database(\n... api_endpoint,\n... keyspace=keyspace,\n... )\n... a_coll = await my_async_db.create_collection(\"movies\", dimension=2)\n... await a_coll.insert_one(\n... {\"title\": \"The Title\", \"$vector\": [0.3, 0.4]}\n... )\n...\n>>> asyncio.run(create_use_collection(\n... my_admin,\n... \"https://-.apps.astra.datastax.com\",\n... \"default_keyspace\",\n... ))\n>>>", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.admin.DatabaseAdmin", "text": "An abstract class defining the interface for a database admin object.\nThis supports generic keyspace crud, as well as spawning databases,\nwithout committing to a specific database architecture (e.g. Astra DB).", "metadata": {"kind": "class", "name": "DatabaseAdmin", "path": "astrapy.admin.DatabaseAdmin", "bases": ["ABC"], "gathered_types": ["ABC"], "implemented_by": ["astrapy.admin.AstraDBDatabaseAdmin", "astrapy.admin.DataAPIDatabaseAdmin"]}} +{"id": "astrapy.admin.DatabaseAdmin.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.admin.DatabaseAdmin.environment", "value": "environment: str"}} +{"id": "astrapy.admin.DatabaseAdmin.spawner_database", "text": "", "metadata": {"kind": "attribute", "name": "spawner_database", "path": "astrapy.admin.DatabaseAdmin.spawner_database", "value": "spawner_database: Database | AsyncDatabase", "gathered_types": ["astrapy.database.Database", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.admin.DatabaseAdmin.list_namespaces", "text": "Get a list of namespaces for the database.", "metadata": {"kind": "function", "name": "list_namespaces", "path": "astrapy.admin.DatabaseAdmin.list_namespaces", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "list[str]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.list_keyspaces", "text": "Get a list of keyspaces for the database.", "metadata": {"kind": "function", "name": "list_keyspaces", "path": "astrapy.admin.DatabaseAdmin.list_keyspaces", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "list[str]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.create_namespace", "text": "Create a namespace in the database, returning {'ok': 1} if successful.", "metadata": {"kind": "function", "name": "create_namespace", "path": "astrapy.admin.DatabaseAdmin.create_namespace", "parameters": [{"name": "name", "type": "str"}, {"name": "update_db_keyspace", "default": "None", "type": "bool | None"}, {"name": "update_db_namespace", "default": "None", "type": "bool | None"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.create_keyspace", "text": "Create a keyspace in the database, returning {'ok': 1} if successful.", "metadata": {"kind": "function", "name": "create_keyspace", "path": "astrapy.admin.DatabaseAdmin.create_keyspace", "parameters": [{"name": "name", "type": "str"}, {"name": "update_db_keyspace", "default": "None", "type": "bool | None"}, {"name": "update_db_namespace", "default": "None", "type": "bool | None"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.drop_namespace", "text": "Drop (delete) a namespace from the database, returning {'ok': 1} if successful.", "metadata": {"kind": "function", "name": "drop_namespace", "path": "astrapy.admin.DatabaseAdmin.drop_namespace", "parameters": [{"name": "name", "type": "str"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.drop_keyspace", "text": "Drop (delete) a keyspace from the database, returning {'ok': 1} if successful.", "metadata": {"kind": "function", "name": "drop_keyspace", "path": "astrapy.admin.DatabaseAdmin.drop_keyspace", "parameters": [{"name": "name", "type": "str"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_list_namespaces", "text": "Get a list of namespaces for the database.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_list_namespaces", "path": "astrapy.admin.DatabaseAdmin.async_list_namespaces", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "list[str]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_list_keyspaces", "text": "Get a list of keyspaces for the database.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_list_keyspaces", "path": "astrapy.admin.DatabaseAdmin.async_list_keyspaces", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "list[str]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_create_namespace", "text": "Create a namespace in the database, returning {'ok': 1} if successful.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_create_namespace", "path": "astrapy.admin.DatabaseAdmin.async_create_namespace", "parameters": [{"name": "name", "type": "str"}, {"name": "update_db_keyspace", "default": "None", "type": "bool | None"}, {"name": "update_db_namespace", "default": "None", "type": "bool | None"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_create_keyspace", "text": "Create a keyspace in the database, returning {'ok': 1} if successful.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_create_keyspace", "path": "astrapy.admin.DatabaseAdmin.async_create_keyspace", "parameters": [{"name": "name", "type": "str"}, {"name": "update_db_keyspace", "default": "None", "type": "bool | None"}, {"name": "update_db_namespace", "default": "None", "type": "bool | None"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_drop_namespace", "text": "Drop (delete) a namespace from the database, returning {'ok': 1} if successful.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_drop_namespace", "path": "astrapy.admin.DatabaseAdmin.async_drop_namespace", "parameters": [{"name": "name", "type": "str"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.async_drop_keyspace", "text": "Drop (delete) a keyspace from the database, returning {'ok': 1} if successful.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_drop_keyspace", "path": "astrapy.admin.DatabaseAdmin.async_drop_keyspace", "parameters": [{"name": "name", "type": "str"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.admin.DatabaseAdmin.get_database", "text": "Get a Database object from this database admin.", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.admin.DatabaseAdmin.get_database", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "Database"}], "gathered_types": ["astrapy.database.Database"]}} +{"id": "astrapy.admin.DatabaseAdmin.get_async_database", "text": "Get an AsyncDatabase object from this database admin.", "metadata": {"kind": "function", "name": "get_async_database", "path": "astrapy.admin.DatabaseAdmin.get_async_database", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "AsyncDatabase"}], "gathered_types": ["astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.admin.DatabaseAdmin.find_embedding_providers", "text": "Query the Data API for the available embedding providers.", "metadata": {"kind": "function", "name": "find_embedding_providers", "path": "astrapy.admin.DatabaseAdmin.find_embedding_providers", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "FindEmbeddingProvidersResult"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.admin.DatabaseAdmin.async_find_embedding_providers", "text": "Query the Data API for the available embedding providers.\n(Async version of the method.)", "metadata": {"kind": "function", "name": "async_find_embedding_providers", "path": "astrapy.admin.DatabaseAdmin.async_find_embedding_providers", "parameters": [{"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "FindEmbeddingProvidersResult"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin", "text": "An \"admin\" object, able to perform administrative tasks at the keyspaces level\n(i.e. within a certain database), such as creating/listing/dropping keyspaces.\n\nThis is one layer below the AstraDBAdmin concept, in that it is tied to\na single database and enables admin work within it. As such, it is generally\ncreated by a method call on an AstraDBAdmin.", "metadata": {"kind": "class", "name": "AstraDBDatabaseAdmin", "path": "astrapy.admin.AstraDBDatabaseAdmin", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission to perform admin tasks.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a label, whose value is one of Environment.PROD (default),\nEnvironment.DEV or Environment.TEST.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API and DevOps API calls are performed.\nThese end up in the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API and\nDevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nclass is created by a method such as `Database.get_database_admin()`,\nwhich passes the matching value. Generally to be left to its Astra DB\ndefault of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this class is created by a method such as\n`Database.get_database_admin()`, which passes the matching value.\nGenerally to be left to its Astra DB default of \"/v1\".", "value": "None", "default": "None"}, {"name": "spawner_database", "type": "Database | AsyncDatabase | None", "description": "either a Database or an AsyncDatabase instance. This represents\nthe database class which spawns this admin object, so that, if required,\na keyspace creation can retroactively \"use\" the new keyspace in the spawner.\nUsed to enable the Async/Database.get_admin_database().create_keyspace() pattern.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "bases": ["astrapy.admin.DatabaseAdmin"], "example": ">>> from astrapy import DataAPIClient\n>>> my_client = DataAPIClient(\"AstraCS:...\")\n>>> admin_for_my_db = my_client.get_admin().get_database_admin(\n... \"https://-.apps.astra.datastax.com\"\n... )\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'staging_keyspace']\n>>> admin_for_my_db.info().status\n'ACTIVE'", "note": "creating an instance of AstraDBDatabaseAdmin does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.constants.CallerType", "astrapy.admin.DatabaseAdmin", "astrapy.database.AsyncDatabase", "astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.admin.AstraDBDatabaseAdmin.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.admin.AstraDBDatabaseAdmin.environment", "value": "environment = environment or Environment.PROD.lower()", "gathered_types": ["astrapy.constants.Environment", "PROD"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.admin.AstraDBDatabaseAdmin.api_endpoint", "value": "api_endpoint = api_endpoint"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.admin.AstraDBDatabaseAdmin.callers", "value": "callers = callers_param"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.admin.AstraDBDatabaseAdmin.api_path", "value": "api_path = api_path if api_path is not None else API_PATH_ENV_MAP[self.environment]", "gathered_types": ["astrapy.defaults.API_PATH_ENV_MAP"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.admin.AstraDBDatabaseAdmin.api_version", "value": "api_version = api_version if api_version is not None else API_VERSION_ENV_MAP[self.environment]", "gathered_types": ["astrapy.defaults.API_VERSION_ENV_MAP"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.spawner_database", "text": "", "metadata": {"kind": "attribute", "name": "spawner_database", "path": "astrapy.admin.AstraDBDatabaseAdmin.spawner_database", "value": "spawner_database = spawner_database"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.dev_ops_url", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_url", "path": "astrapy.admin.AstraDBDatabaseAdmin.dev_ops_url", "value": "dev_ops_url = dev_ops_url if dev_ops_url is not None else DEV_OPS_URL_ENV_MAP[self.environment].rstrip('/')", "gathered_types": ["astrapy.defaults.DEV_OPS_URL_ENV_MAP"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.dev_ops_api_version", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_api_version", "path": "astrapy.admin.AstraDBDatabaseAdmin.dev_ops_api_version", "value": "dev_ops_api_version = dev_ops_api_version if dev_ops_api_version is not None else DEV_OPS_VERSION_ENV_MAP[self.environment].strip('/')", "gathered_types": ["astrapy.defaults.DEV_OPS_VERSION_ENV_MAP"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.with_options", "text": "Create a clone of this AstraDBDatabaseAdmin with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.admin.AstraDBDatabaseAdmin.with_options", "parameters": [{"name": "api_endpoint", "type": "str | None", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API and DevOps API calls are performed.\nThese end up in the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API and\nDevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "a new AstraDBDatabaseAdmin instance."}], "example": ">>> admin_for_my_other_db = admin_for_my_db.with_options(\n... \"https://-.apps.astra.datastax.com\",\n... )", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType", "astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe DevOps API calls will be performed (the \"caller\").\n\nNew objects spawned from this client afterwards will inherit the new settings.", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.admin.AstraDBDatabaseAdmin.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe DevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> admin_for_my_db.set_caller(\n... caller_name=\"the_caller\",\n... caller_version=\"0.1.0\",\n... )"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.id", "text": "The ID of this database admin.", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.admin.AstraDBDatabaseAdmin.id", "value": "id: str", "example": ">>> my_db_admin.id\n'01234567-89ab-cdef-0123-456789abcdef'"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.region", "text": "The region for this database admin.", "metadata": {"kind": "attribute", "name": "region", "path": "astrapy.admin.AstraDBDatabaseAdmin.region", "value": "region: str", "example": ">>> my_db_admin.region\n'us-east-1'"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.from_astra_db_admin", "text": "Create an AstraDBDatabaseAdmin from an AstraDBAdmin and an API Endpoint.", "metadata": {"kind": "function", "name": "from_astra_db_admin", "path": "astrapy.admin.AstraDBDatabaseAdmin.from_astra_db_admin", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "default": null}, {"name": "astra_db_admin", "type": "AstraDBAdmin", "description": "an AstraDBAdmin object that has visibility over\nthe target database.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API\nHTTP request should it be necessary (see the `region` argument).", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "An AstraDBDatabaseAdmin object, for admin work within the database."}], "example": ">>> from astrapy import DataAPIClient, AstraDBDatabaseAdmin\n>>> admin_for_my_db = AstraDBDatabaseAdmin.from_astra_db_admin(\n... \"https://-.apps.astra.datastax.com\",\n... astra_db_admin=DataAPIClient(\"AstraCS:...\").get_admin(),\n... )\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'staging_keyspace']\n>>> admin_for_my_db.info().status\n'ACTIVE'", "note": "Creating an instance of AstraDBDatabaseAdmin does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "references": ["astrapy.admin.AstraDBDatabaseAdmin", "astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.admin.AstraDBAdmin", "astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.from_api_endpoint", "text": "Create an AstraDBDatabaseAdmin from an API Endpoint and optionally a token.", "metadata": {"kind": "function", "name": "from_api_endpoint", "path": "astrapy.admin.AstraDBDatabaseAdmin.from_api_endpoint", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the API Endpoint for the target database\n(e.g. `https://-.apps.astra.datastax.com`).\nThe database must exist already for the resulting object\nto be effectively used; in other words, this invocation\ndoes not create the database, just the object instance.", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permissions to do admin work.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API and DevOps API calls are performed.\nThese end up in the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API and\nDevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}, {"name": "dev_ops_url", "type": "str | None", "description": "in case of custom deployments, this can be used to specify\nthe URL to the DevOps API, such as \"https://api.astra.datastax.com\".\nGenerally it can be omitted. The environment (prod/dev/...) is\ndetermined from the API Endpoint.", "value": "None", "default": "None"}, {"name": "dev_ops_api_version", "type": "str | None", "description": "this can specify a custom version of the DevOps API\n(such as \"v2\"). Generally not needed.", "value": "None", "default": "None"}], "returns": [{"type": "AstraDBDatabaseAdmin", "description": "An AstraDBDatabaseAdmin object, for admin work within the database."}], "example": ">>> from astrapy import AstraDBDatabaseAdmin\n>>> admin_for_my_db = AstraDBDatabaseAdmin.from_api_endpoint(\n... api_endpoint=\"https://01234567-....apps.astra.datastax.com\",\n... token=\"AstraCS:...\",\n... )\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'another_keyspace']\n>>> admin_for_my_db.info().status\n'ACTIVE'", "note": "Creating an instance of AstraDBDatabaseAdmin does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "references": ["astrapy.admin.AstraDBDatabaseAdmin"], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType", "astrapy.admin.AstraDBDatabaseAdmin"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.info", "text": "Query the DevOps API for the full info on this database.", "metadata": {"kind": "function", "name": "info", "path": "astrapy.admin.AstraDBDatabaseAdmin.info", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "AdminDatabaseInfo", "description": "An AdminDatabaseInfo object."}], "example": ">>> my_db_info = admin_for_my_db.info()\n>>> my_db_info.status\n'ACTIVE'\n>>> my_db_info.info.region\n'us-east1'", "gathered_types": ["astrapy.info.AdminDatabaseInfo"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_info", "text": "Query the DevOps API for the full info on this database.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_info", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_info", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "AdminDatabaseInfo", "description": "An AdminDatabaseInfo object."}], "example": ">>> async def wait_until_active(db_admin: AstraDBDatabaseAdmin) -> None:\n... while True:\n... info = await db_admin.async_info()\n... if info.status == \"ACTIVE\":\n... return\n...\n>>> asyncio.run(wait_until_active(admin_for_my_db))", "gathered_types": ["astrapy.info.AdminDatabaseInfo"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.list_namespaces", "text": "Query the DevOps API for a list of the namespaces in the database.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"list_keyspaces\" method.**", "metadata": {"kind": "function", "name": "list_namespaces", "path": "astrapy.admin.AstraDBDatabaseAdmin.list_namespaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the namespaces, each a string, in no particular order."}], "example": ">>> admin_for_my_db.list_namespaces()\n['default_keyspace', 'staging_namespace']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.list_keyspaces", "text": "Query the DevOps API for a list of the keyspaces in the database.", "metadata": {"kind": "function", "name": "list_keyspaces", "path": "astrapy.admin.AstraDBDatabaseAdmin.list_keyspaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the keyspaces, each a string, in no particular order."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'staging_keyspace']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_list_namespaces", "text": "Query the DevOps API for a list of the namespaces in the database.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "function", "name": "async_list_namespaces", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_list_namespaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the namespaces, each a string, in no particular order."}], "example": ">>> async def check_if_ns_exists(\n... db_admin: AstraDBDatabaseAdmin, namespace: str\n... ) -> bool:\n... ns_list = await db_admin.async_list_namespaces()\n... return namespace in ns_list\n...\n>>> asyncio.run(check_if_ns_exists(admin_for_my_db, \"dragons\"))\nFalse\n>>> asyncio.run(check_if_db_exists(admin_for_my_db, \"app_namespace\"))\nTrue"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_list_keyspaces", "text": "Query the DevOps API for a list of the keyspaces in the database.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_list_keyspaces", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_list_keyspaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the keyspaces, each a string, in no particular order."}], "example": ">>> async def check_if_ks_exists(\n... db_admin: AstraDBDatabaseAdmin, keyspace: str\n... ) -> bool:\n... ks_list = await db_admin.async_list_keyspaces()\n... return keyspace in ks_list\n...\n>>> asyncio.run(check_if_ks_exists(admin_for_my_db, \"dragons\"))\nFalse\n>>> asyncio.run(check_if_db_exists(admin_for_my_db, \"app_keyspace\"))\nTrue"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.create_namespace", "text": "Create a namespace in this database as requested,\noptionally waiting for it to be ready.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "function", "name": "create_namespace", "path": "astrapy.admin.AstraDBDatabaseAdmin.create_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace name. If supplying a namespace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status/namespace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> my_db_admin.list_namespaces()\n['default_keyspace']\n>>> my_db_admin.create_namespace(\"that_other_one\")\n{'ok': 1}\n>>> my_db_admin.list_namespaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.create_keyspace", "text": "Create a keyspace in this database as requested,\noptionally waiting for it to be ready.", "metadata": {"kind": "function", "name": "create_keyspace", "path": "astrapy.admin.AstraDBDatabaseAdmin.create_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace name. If supplying a keyspace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status/keyspace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> my_db_admin.keyspaces()\n['default_keyspace']\n>>> my_db_admin.create_keyspace(\"that_other_one\")\n{'ok': 1}\n>>> my_db_admin.list_keyspaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_create_namespace", "text": "Create a namespace in this database as requested,\noptionally waiting for it to be ready.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"async_create_keyspace\" method.**", "metadata": {"kind": "function", "name": "async_create_namespace", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_create_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace name. If supplying a namespace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status/namespace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(\n... my_db_admin.async_create_namespace(\"app_namespace\")\n... )\n{'ok': 1}"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_create_keyspace", "text": "Create a keyspace in this database as requested,\noptionally waiting for it to be ready.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_create_keyspace", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_create_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace name. If supplying a keyspace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ncreation request to the DevOps API, and it will be responsibility\nof the caller to check the database status/keyspace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(\n... my_db_admin.async_create_keyspace(\"app_keyspace\")\n... )\n{'ok': 1}"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.drop_namespace", "text": "Delete a namespace from the database, optionally waiting for the database\nto become active again.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"drop_keyspace\" method.**", "metadata": {"kind": "function", "name": "drop_namespace", "path": "astrapy.admin.AstraDBDatabaseAdmin.drop_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ndeletion request to the DevOps API, and it will be responsibility\nof the caller to check the database status/namespace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> my_db_admin.list_namespaces()\n['default_keyspace', 'that_other_one']\n>>> my_db_admin.drop_namespace(\"that_other_one\")\n{'ok': 1}\n>>> my_db_admin.list_namespaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.drop_keyspace", "text": "Delete a keyspace from the database, optionally waiting for the database\nto become active again.", "metadata": {"kind": "function", "name": "drop_keyspace", "path": "astrapy.admin.AstraDBDatabaseAdmin.drop_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ndeletion request to the DevOps API, and it will be responsibility\nof the caller to check the database status/keyspace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> my_db_admin.list_keyspaces()\n['default_keyspace', 'that_other_one']\n>>> my_db_admin.drop_keyspace(\"that_other_one\")\n{'ok': 1}\n>>> my_db_admin.list_keyspaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_drop_namespace", "text": "Delete a namespace from the database, optionally waiting for the database\nto become active again.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"async_drop_namespace\" method.**", "metadata": {"kind": "function", "name": "async_drop_namespace", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_drop_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ndeletion request to the DevOps API, and it will be responsibility\nof the caller to check the database status/namespace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(\n... my_db_admin.async_drop_namespace(\"app_namespace\")\n... )\n{'ok': 1}"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_drop_keyspace", "text": "Delete a keyspace from the database, optionally waiting for the database\nto become active again.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_drop_keyspace", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_drop_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe target database is in ACTIVE state again (a few\nseconds, usually). If False, it will return right after issuing the\ndeletion request to the DevOps API, and it will be responsibility\nof the caller to check the database status/keyspace availability\nbefore working with it.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(\n... my_db_admin.async_drop_keyspace(\"app_keyspace\")\n... )\n{'ok': 1}"}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.drop", "text": "Drop this database, i.e. delete it completely and permanently with all its data.\n\nThis method wraps the `drop_database` method of the AstraDBAdmin class,\nwhere more information may be found.", "metadata": {"kind": "function", "name": "drop", "path": "astrapy.admin.AstraDBDatabaseAdmin.drop", "parameters": [{"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe database has actually been deleted (generally a few minutes).\nIf False, it will return right after issuing the\ndrop request to the DevOps API, and it will be responsibility\nof the caller to check the database status/availability\nafter that, if desired.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> my_db_admin.list_keyspaces()\n['default_keyspace', 'that_other_one']\n>>> my_db_admin.drop()\n{'ok': 1}\n>>> my_db_admin.list_keyspaces() # raises a 404 Not Found http error", "note": "Once the method succeeds, methods on this object -- such as `info()`,\nor `list_keyspaces()` -- can still be invoked: however, this hardly\nmakes sense as the underlying actual database is no more.\nIt is responsibility of the developer to design a correct flow\nwhich avoids using a deceased database any further."}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_drop", "text": "Drop this database, i.e. delete it completely and permanently with all its data.\nAsync version of the method, for use in an asyncio context.\n\nThis method wraps the `drop_database` method of the AstraDBAdmin class,\nwhere more information may be found.", "metadata": {"kind": "function", "name": "async_drop", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_drop", "parameters": [{"name": "wait_until_active", "type": "bool", "description": "if True (default), the method returns only after\nthe database has actually been deleted (generally a few minutes).\nIf False, it will return right after issuing the\ndrop request to the DevOps API, and it will be responsibility\nof the caller to check the database status/availability\nafter that, if desired.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> asyncio.run(my_db_admin.async_drop())\n{'ok': 1}", "note": "Once the method succeeds, methods on this object -- such as `info()`,\nor `list_keyspaces()` -- can still be invoked: however, this hardly\nmakes sense as the underlying actual database is no more.\nIt is responsibility of the developer to design a correct flow\nwhich avoids using a deceased database any further."}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.get_database", "text": "Create a Database instance from this database admin, for data-related tasks.", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.admin.AstraDBDatabaseAdmin.get_database", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of\nthe one set for this object. Useful if one wants to work in\na least-privilege manner, limiting the permissions for non-admin work.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "an optional keyspace to set in the resulting Database.\nThe same default logic as for `AstraDBAdmin.get_database` applies.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "region", "type": "str | None", "description": "*This parameter is deprecated and should not be used.*\nIgnored in the method.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"/api/json\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "A Database object, ready to be used for working with data and collections."}], "example": ">>> my_db = my_db_admin.get_database()\n>>> my_db.list_collection_names()\n['movies', 'another_collection']", "note": "creating an instance of Database does not trigger actual creation\nof the database itself, which should exist beforehand. To create databases,\nsee the AstraDBAdmin class.", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.get_async_database", "text": "Create an AsyncDatabase instance out of this class for working\nwith the data in it.\n\nThis method has identical behavior and signature as the sync\ncounterpart `get_database`: please see that one for more details.", "metadata": {"kind": "function", "name": "get_async_database", "path": "astrapy.admin.AstraDBDatabaseAdmin.get_async_database", "parameters": [{"name": "token", "default": "None", "type": "str | TokenProvider | None"}, {"name": "keyspace", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "region", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "max_time_ms", "default": "None", "type": "int | None"}], "returns": [{"type": "AsyncDatabase"}], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.find_embedding_providers", "text": "Example (output abridged and indented for clarity):\n >>> admin_for_my_db.find_embedding_providers()\n FindEmbeddingProvidersResult(embedding_providers=..., openai, ...)\n >>> admin_for_my_db.find_embedding_providers().embedding_providers\n {\n 'openai': EmbeddingProvider(\n display_name='OpenAI',\n models=[\n EmbeddingProviderModel(name='text-embedding-3-small'),\n ...\n ]\n ),\n ...\n }", "metadata": {"kind": "function", "name": "find_embedding_providers", "path": "astrapy.admin.AstraDBDatabaseAdmin.find_embedding_providers", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "FindEmbeddingProvidersResult", "description": "A `FindEmbeddingProvidersResult` object with the complete information"}, {"type": "FindEmbeddingProvidersResult", "description": "returned by the API about available embedding providers"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.admin.AstraDBDatabaseAdmin.async_find_embedding_providers", "text": "Example (output abridged and indented for clarity):\n >>> admin_for_my_db.find_embedding_providers()\n FindEmbeddingProvidersResult(embedding_providers=..., openai, ...)\n >>> admin_for_my_db.find_embedding_providers().embedding_providers\n {\n 'openai': EmbeddingProvider(\n display_name='OpenAI',\n models=[\n EmbeddingProviderModel(name='text-embedding-3-small'),\n ...\n ]\n ),\n ...\n }", "metadata": {"kind": "function", "name": "async_find_embedding_providers", "path": "astrapy.admin.AstraDBDatabaseAdmin.async_find_embedding_providers", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "FindEmbeddingProvidersResult", "description": "A `FindEmbeddingProvidersResult` object with the complete information"}, {"type": "FindEmbeddingProvidersResult", "description": "returned by the API about available embedding providers"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin", "text": "An \"admin\" object for non-Astra Data API environments, to perform administrative\ntasks at the keyspaces level such as creating/listing/dropping keyspaces.\n\nConforming to the architecture of non-Astra deployments of the Data API,\nthis object works within the one existing database. It is within that database\nthat the keyspace CRUD operations (and possibly other admin operations)\nare performed. Since non-Astra environment lack the concept of an overall\nadmin (such as the all-databases AstraDBAdmin class), a `DataAPIDatabaseAdmin`\nis generally created by invoking the `get_database_admin` method of the\ncorresponding `Database` object (which in turn is spawned by a DataAPIClient).", "metadata": {"kind": "class", "name": "DataAPIDatabaseAdmin", "path": "astrapy.admin.DataAPIDatabaseAdmin", "parameters": [{"name": "api_endpoint", "type": "str", "description": "the full URI to access the Data API,\ne.g. \"http://localhost:8181\".", "default": null}, {"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission to perform admin tasks.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "environment", "type": "str | None", "description": "a label, whose value is one of Environment.OTHER (default)\nor other non-Astra environment values in the `Environment` enum.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nclass is created by a method such as `Database.get_database_admin()`,\nwhich passes the matching value. Defaults to this portion of the path\nbeing absent.", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this class is created by a method such as\n`Database.get_database_admin()`, which passes the matching value.\nDefaults to this portion of the path being absent.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API calls are performed. These end up in the\nrequest user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}, {"name": "spawner_database", "type": "Database | AsyncDatabase | None", "description": "either a Database or an AsyncDatabase instance.\nThis represents the database class which spawns this admin object, so that,\nif required, a keyspace creation can retroactively \"use\" the new keyspace\nin the spawner. Used to enable the\nAsync/Database.get_admin_database().create_keyspace() pattern.", "value": "None", "default": "None"}], "bases": ["astrapy.admin.DatabaseAdmin"], "example": ">>> from astrapy import DataAPIClient\n>>> from astrapy.constants import Environment\n>>> from astrapy.authentication import UsernamePasswordTokenProvider\n>>>\n>>> token_provider = UsernamePasswordTokenProvider(\"username\", \"password\")\n>>> endpoint = \"http://localhost:8181\"\n>>>\n>>> client = DataAPIClient(\n>>> token=token_provider,\n>>> environment=Environment.OTHER,\n>>> )\n>>> database = client.get_database(endpoint)\n>>> admin_for_my_db = database.get_database_admin()\n>>>\n>>> admin_for_my_db.list_keyspaces()\n['keyspace1', 'keyspace2']", "references": ["astrapy.constants.Environment", "astrapy.client.DataAPIClient", "astrapy.authentication.UsernamePasswordTokenProvider"], "gathered_types": ["astrapy.constants.CallerType", "astrapy.admin.DatabaseAdmin", "astrapy.database.AsyncDatabase", "astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.admin.DataAPIDatabaseAdmin.environment", "value": "environment = environment or Environment.OTHER.lower()", "gathered_types": ["astrapy.constants.Environment", "OTHER"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.token_provider", "text": "", "metadata": {"kind": "attribute", "name": "token_provider", "path": "astrapy.admin.DataAPIDatabaseAdmin.token_provider", "value": "token_provider = coerce_token_provider(token)"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.admin.DataAPIDatabaseAdmin.api_endpoint", "value": "api_endpoint = api_endpoint"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.admin.DataAPIDatabaseAdmin.callers", "value": "callers = callers_param"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.admin.DataAPIDatabaseAdmin.api_path", "value": "api_path = api_path if api_path is not None else ''"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.admin.DataAPIDatabaseAdmin.api_version", "value": "api_version = api_version if api_version is not None else ''"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.spawner_database", "text": "", "metadata": {"kind": "attribute", "name": "spawner_database", "path": "astrapy.admin.DataAPIDatabaseAdmin.spawner_database", "value": "spawner_database = spawner_database"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.with_options", "text": "Create a clone of this DataAPIDatabaseAdmin with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.admin.DataAPIDatabaseAdmin.with_options", "parameters": [{"name": "api_endpoint", "type": "str | None", "description": "the full URI to access the Data API,\ne.g. \"http://localhost:8181\".", "value": "None", "default": "None"}, {"name": "token", "type": "str | TokenProvider | None", "description": "an access token with enough permission to perform admin tasks.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which Data API calls are performed. These end up in the\nrequest user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "DataAPIDatabaseAdmin", "description": "a new DataAPIDatabaseAdmin instance."}], "example": ">>> admin_for_my_other_db = admin_for_my_db.with_options(\n... api_endpoint=\"http://10.1.1.5:8181\",\n... )", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.constants.CallerType", "astrapy.admin.DataAPIDatabaseAdmin"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe DevOps API calls will be performed (the \"caller\").\n\nNew objects spawned from this client afterwards will inherit the new settings.", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.admin.DataAPIDatabaseAdmin.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe DevOps API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> admin_for_my_db.set_caller(\n... caller_name=\"the_caller\",\n... caller_version=\"0.1.0\",\n... )"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.list_namespaces", "text": "Query the API for a list of the namespaces in the database.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"list_keyspaces\" method.**", "metadata": {"kind": "function", "name": "list_namespaces", "path": "astrapy.admin.DataAPIDatabaseAdmin.list_namespaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the namespaces, each a string, in no particular order."}], "example": ">>> admin_for_my_db.list_namespaces()\n['default_keyspace', 'staging_namespace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.list_keyspaces", "text": "Query the API for a list of the keyspaces in the database.", "metadata": {"kind": "function", "name": "list_keyspaces", "path": "astrapy.admin.DataAPIDatabaseAdmin.list_keyspaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the keyspaces, each a string, in no particular order."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'staging_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.create_namespace", "text": "Create a namespace in the database, returning {'ok': 1} if successful.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"create_keyspace\" method.**", "metadata": {"kind": "function", "name": "create_namespace", "path": "astrapy.admin.DataAPIDatabaseAdmin.create_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace name. If supplying a namespace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "replication_options", "type": "dict[str, Any] | None", "description": "this dictionary can specify the options about\nreplication of the namespace (across database nodes). If provided,\nit must have a structure similar to:\n`{\"class\": \"SimpleStrategy\", \"replication_factor\": 1}`.", "value": "None", "default": "None"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_namespaces()\n['default_keyspace']\n>>> admin_for_my_db.create_namespace(\"that_other_one\")\n{'ok': 1}\n>>> admin_for_my_db.list_namespaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.create_keyspace", "text": "Create a keyspace in the database, returning {'ok': 1} if successful.", "metadata": {"kind": "function", "name": "create_keyspace", "path": "astrapy.admin.DataAPIDatabaseAdmin.create_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace name. If supplying a keyspace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "replication_options", "type": "dict[str, Any] | None", "description": "this dictionary can specify the options about\nreplication of the keyspace (across database nodes). If provided,\nit must have a structure similar to:\n`{\"class\": \"SimpleStrategy\", \"replication_factor\": 1}`.", "value": "None", "default": "None"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['default_keyspace']\n>>> admin_for_my_db.create_keyspace(\"that_other_one\")\n{'ok': 1}\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.drop_namespace", "text": "Drop (delete) a namespace from the database.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"drop_namespace\" method.**", "metadata": {"kind": "function", "name": "drop_namespace", "path": "astrapy.admin.DataAPIDatabaseAdmin.drop_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_namespaces()\n['default_keyspace', 'that_other_one']\n>>> admin_for_my_db.drop_namespace(\"that_other_one\")\n{'ok': 1}\n>>> admin_for_my_db.list_namespaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.drop_keyspace", "text": "Drop (delete) a keyspace from the database.", "metadata": {"kind": "function", "name": "drop_keyspace", "path": "astrapy.admin.DataAPIDatabaseAdmin.drop_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['default_keyspace', 'that_other_one']\n>>> admin_for_my_db.drop_keyspace(\"that_other_one\")\n{'ok': 1}\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_list_namespaces", "text": "Query the API for a list of the namespaces in the database.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"async_list_keyspaces\" method.**", "metadata": {"kind": "function", "name": "async_list_namespaces", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_list_namespaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the namespaces, each a string, in no particular order."}], "example": ">>> asyncio.run(admin_for_my_db.async_list_namespaces())\n['default_keyspace', 'staging_namespace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_list_keyspaces", "text": "Query the API for a list of the keyspaces in the database.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_list_keyspaces", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_list_keyspaces", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "list[str]", "description": "A list of the keyspaces, each a string, in no particular order."}], "example": ">>> asyncio.run(admin_for_my_db.async_list_keyspaces())\n['default_keyspace', 'staging_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_create_namespace", "text": "Create a namespace in the database, returning {'ok': 1} if successful.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"async_create_keyspace\" method.**", "metadata": {"kind": "function", "name": "async_create_namespace", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_create_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace name. If supplying a namespace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "replication_options", "type": "dict[str, Any] | None", "description": "this dictionary can specify the options about\nreplication of the namespace (across database nodes). If provided,\nit must have a structure similar to:\n`{\"class\": \"SimpleStrategy\", \"replication_factor\": 1}`.", "value": "None", "default": "None"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_namespaces()\n['default_keyspace']\n>>> asyncio.run(admin_for_my_db.async_create_namespace(\n... \"that_other_one\"\n... ))\n{'ok': 1}\n>>> admin_for_my_db.list_namespaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_create_keyspace", "text": "Create a keyspace in the database, returning {'ok': 1} if successful.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_create_keyspace", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_create_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace name. If supplying a keyspace that exists\nalready, the method call proceeds as usual, no errors are\nraised, and the whole invocation is a no-op.", "default": null}, {"name": "replication_options", "type": "dict[str, Any] | None", "description": "this dictionary can specify the options about\nreplication of the keyspace (across database nodes). If provided,\nit must have a structure similar to:\n`{\"class\": \"SimpleStrategy\", \"replication_factor\": 1}`.", "value": "None", "default": "None"}, {"name": "update_db_keyspace", "type": "bool | None", "description": "if True, the `Database` or `AsyncDatabase` class\nthat spawned this DatabaseAdmin, if any, gets updated to work on\nthe newly-created keyspace starting when this method returns.", "value": "None", "default": "None"}, {"name": "update_db_namespace", "type": "bool | None", "description": "an alias for update_db_keyspace.\n*DEPRECATED* as of v1.5.0, removal in v2.0.0.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the creation request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['default_keyspace']\n>>> asyncio.run(admin_for_my_db.async_create_keyspace(\n... \"that_other_one\"\n... ))\n{'ok': 1}\n>>> admin_for_my_db.list_leyspaces()\n['default_keyspace', 'that_other_one']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_drop_namespace", "text": "Drop (delete) a namespace from the database.\nAsync version of the method, for use in an asyncio context.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"async_drop_keyspace\" method.**", "metadata": {"kind": "function", "name": "async_drop_namespace", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_drop_namespace", "parameters": [{"name": "name", "type": "str", "description": "the namespace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_namespaces()\n['that_other_one', 'default_keyspace']\n>>> asyncio.run(admin_for_my_db.async_drop_namespace(\n... \"that_other_one\"\n... ))\n{'ok': 1}\n>>> admin_for_my_db.list_namespaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_drop_keyspace", "text": "Drop (delete) a keyspace from the database.\nAsync version of the method, for use in an asyncio context.", "metadata": {"kind": "function", "name": "async_drop_keyspace", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_drop_keyspace", "parameters": [{"name": "name", "type": "str", "description": "the keyspace to delete. If it does not exist in this database,\nan error is raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole requested\noperation to complete.\nNote that a timeout is no guarantee that the deletion request\nhas not reached the API server.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "A dictionary of the form {\"ok\": 1} in case of success."}, {"type": "dict[str, Any]", "description": "Otherwise, an exception is raised."}], "example": ">>> admin_for_my_db.list_keyspaces()\n['that_other_one', 'default_keyspace']\n>>> asyncio.run(admin_for_my_db.async_drop_keyspace(\n... \"that_other_one\"\n... ))\n{'ok': 1}\n>>> admin_for_my_db.list_keyspaces()\n['default_keyspace']"}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.get_database", "text": "Create a Database instance out of this class for working with the data in it.", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.admin.DataAPIDatabaseAdmin.get_database", "parameters": [{"name": "token", "type": "str | TokenProvider | None", "description": "if supplied, is passed to the Database instead of\nthe one set for this object. Useful if one wants to work in\na least-privilege manner, limiting the permissions for non-admin work.\nThis can be either a literal token string or a subclass of\n`astrapy.authentication.TokenProvider`.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "an optional keyspace to set in the resulting Database.\nIf not provided, no keyspace is set, limiting what the Database\ncan do until setting it with e.g. a `use_keyspace` method call.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "api_path", "type": "str | None", "description": "path to append to the API Endpoint. In typical usage, this\nshould be left to its default of \"\".", "value": "None", "default": "None"}, {"name": "api_version", "type": "str | None", "description": "version specifier to append to the API path. In typical\nusage, this should be left to its default of \"v1\".", "value": "None", "default": "None"}], "returns": [{"type": "Database", "description": "A Database object, ready to be used for working with data and collections."}], "example": ">>> my_db = admin_for_my_db.get_database()\n>>> my_db.list_collection_names()\n['movies', 'another_collection']", "note": "creating an instance of Database does not trigger actual creation\nof the database itself, which should exist beforehand.", "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.Database"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.get_async_database", "text": "Create an AsyncDatabase instance for the database, to be used\nwhen doing data-level work (such as creating/managing collections).\n\nThis method has identical behavior and signature as the sync\ncounterpart `get_database`: please see that one for more details.", "metadata": {"kind": "function", "name": "get_async_database", "path": "astrapy.admin.DataAPIDatabaseAdmin.get_async_database", "parameters": [{"name": "token", "default": "None", "type": "str | TokenProvider | None"}, {"name": "keyspace", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}], "returns": [{"type": "AsyncDatabase"}], "gathered_types": ["astrapy.authentication.TokenProvider", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.find_embedding_providers", "text": "Example (output abridged and indented for clarity):\n >>> admin_for_my_db.find_embedding_providers()\n FindEmbeddingProvidersResult(embedding_providers=..., openai, ...)\n >>> admin_for_my_db.find_embedding_providers().embedding_providers\n {\n 'openai': EmbeddingProvider(\n display_name='OpenAI',\n models=[\n EmbeddingProviderModel(name='text-embedding-3-small'),\n ...\n ]\n ),\n ...\n }", "metadata": {"kind": "function", "name": "find_embedding_providers", "path": "astrapy.admin.DataAPIDatabaseAdmin.find_embedding_providers", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "FindEmbeddingProvidersResult", "description": "A `FindEmbeddingProvidersResult` object with the complete information"}, {"type": "FindEmbeddingProvidersResult", "description": "returned by the API about available embedding providers"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.admin.DataAPIDatabaseAdmin.async_find_embedding_providers", "text": "Example (output abridged and indented for clarity):\n >>> admin_for_my_db.find_embedding_providers()\n FindEmbeddingProvidersResult(embedding_providers=..., openai, ...)\n >>> admin_for_my_db.find_embedding_providers().embedding_providers\n {\n 'openai': EmbeddingProvider(\n display_name='OpenAI',\n models=[\n EmbeddingProviderModel(name='text-embedding-3-small'),\n ...\n ]\n ),\n ...\n }", "metadata": {"kind": "function", "name": "async_find_embedding_providers", "path": "astrapy.admin.DataAPIDatabaseAdmin.async_find_embedding_providers", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the DevOps API request.", "value": "None", "default": "None"}], "returns": [{"type": "FindEmbeddingProvidersResult", "description": "A `FindEmbeddingProvidersResult` object with the complete information"}, {"type": "FindEmbeddingProvidersResult", "description": "returned by the API about available embedding providers"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.transform_payload", "text": "", "metadata": {"kind": "module", "name": "transform_payload", "path": "astrapy.transform_payload", "imports": {"annotations": "__future__.annotations", "datetime": "datetime", "time": "time", "Any": "typing.Any", "Dict": "typing.Dict", "Iterable": "typing.Iterable", "cast": "typing.cast", "DocumentType": "astrapy.constants.DocumentType", "UUID": "astrapy.ids.UUID", "ObjectId": "astrapy.ids.ObjectId"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.transform_payload.convert_vector_to_floats", "text": "Convert a vector of strings to a vector of floats.", "metadata": {"kind": "function", "name": "convert_vector_to_floats", "path": "astrapy.transform_payload.convert_vector_to_floats", "parameters": [{"name": "vector", "type": "list", "description": "A vector of objects.", "default": null}], "returns": [{"name": "list", "type": "list[float]", "description": "A vector of floats."}]}} +{"id": "astrapy.transform_payload.is_list_of_floats", "text": "Safely determine if it's a list of floats.\nAssumption: if list, and first item is float, then all items are.", "metadata": {"kind": "function", "name": "is_list_of_floats", "path": "astrapy.transform_payload.is_list_of_floats", "parameters": [{"name": "vector", "type": "Iterable[Any]"}], "returns": [{"type": "bool"}]}} +{"id": "astrapy.transform_payload.convert_to_ejson_date_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_date_object", "path": "astrapy.transform_payload.convert_to_ejson_date_object", "parameters": [{"name": "date_value", "type": "datetime.date | datetime.datetime"}], "returns": [{"type": "dict[str, int]"}]}} +{"id": "astrapy.transform_payload.convert_to_ejson_uuid_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_uuid_object", "path": "astrapy.transform_payload.convert_to_ejson_uuid_object", "parameters": [{"name": "uuid_value", "type": "UUID"}], "returns": [{"type": "dict[str, str]"}], "gathered_types": ["UUID"]}} +{"id": "astrapy.transform_payload.convert_to_ejson_objectid_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_objectid_object", "path": "astrapy.transform_payload.convert_to_ejson_objectid_object", "parameters": [{"name": "objectid_value", "type": "ObjectId"}], "returns": [{"type": "dict[str, str]"}], "gathered_types": ["ObjectId"]}} +{"id": "astrapy.transform_payload.convert_ejson_date_object_to_datetime", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_date_object_to_datetime", "path": "astrapy.transform_payload.convert_ejson_date_object_to_datetime", "parameters": [{"name": "date_object", "type": "dict[str, int]"}], "returns": [{"type": "datetime.datetime"}]}} +{"id": "astrapy.transform_payload.convert_ejson_uuid_object_to_uuid", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_uuid_object_to_uuid", "path": "astrapy.transform_payload.convert_ejson_uuid_object_to_uuid", "parameters": [{"name": "uuid_object", "type": "dict[str, str]"}], "returns": [{"type": "UUID"}], "gathered_types": ["UUID"]}} +{"id": "astrapy.transform_payload.convert_ejson_objectid_object_to_objectid", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_objectid_object_to_objectid", "path": "astrapy.transform_payload.convert_ejson_objectid_object_to_objectid", "parameters": [{"name": "objectid_object", "type": "dict[str, str]"}], "returns": [{"type": "ObjectId"}], "gathered_types": ["ObjectId"]}} +{"id": "astrapy.transform_payload.normalize_payload_value", "text": "The path helps determining special treatments", "metadata": {"kind": "function", "name": "normalize_payload_value", "path": "astrapy.transform_payload.normalize_payload_value", "parameters": [{"name": "path", "type": "list[str]"}, {"name": "value", "type": "Any"}], "returns": [{"type": "Any"}]}} +{"id": "astrapy.transform_payload.normalize_for_api", "text": "Normalize a payload for API calls.\nThis includes e.g. ensuring values for \"$vector\" key\nare made into plain lists of floats.", "metadata": {"kind": "function", "name": "normalize_for_api", "path": "astrapy.transform_payload.normalize_for_api", "parameters": [{"name": "payload", "type": "Dict[str, Any]", "description": "A dict expressing a payload for an API call", "default": null}], "returns": [{"type": "dict[str, Any] | None", "description": "Dict[str, Any]: a \"normalized\" payload dict"}]}} +{"id": "astrapy.transform_payload.restore_response_value", "text": "The path helps determining special treatments", "metadata": {"kind": "function", "name": "restore_response_value", "path": "astrapy.transform_payload.restore_response_value", "parameters": [{"name": "path", "type": "list[str]"}, {"name": "value", "type": "Any"}], "returns": [{"type": "Any"}]}} +{"id": "astrapy.transform_payload.restore_from_api", "text": "Process a dictionary just returned from the API.\nThis is the place where e.g. `{\"$date\": 123}` is\nconverted back into a datetime object.", "metadata": {"kind": "function", "name": "restore_from_api", "path": "astrapy.transform_payload.restore_from_api", "parameters": [{"name": "response", "type": "DocumentType"}], "returns": [{"type": "DocumentType"}], "gathered_types": ["astrapy.constants.DocumentType"]}} +{"id": "astrapy.authentication", "text": "", "metadata": {"kind": "module", "name": "authentication", "path": "astrapy.authentication", "imports": {"annotations": "__future__.annotations", "base64": "base64", "ABC": "abc.ABC", "abstractmethod": "abc.abstractmethod", "Any": "typing.Any", "EMBEDDING_HEADER_API_KEY": "astrapy.defaults.EMBEDDING_HEADER_API_KEY", "EMBEDDING_HEADER_AWS_ACCESS_ID": "astrapy.defaults.EMBEDDING_HEADER_AWS_ACCESS_ID", "EMBEDDING_HEADER_AWS_SECRET_ID": "astrapy.defaults.EMBEDDING_HEADER_AWS_SECRET_ID", "SECRETS_REDACT_CHAR": "astrapy.defaults.SECRETS_REDACT_CHAR", "SECRETS_REDACT_ENDING": "astrapy.defaults.SECRETS_REDACT_ENDING", "SECRETS_REDACT_ENDING_LENGTH": "astrapy.defaults.SECRETS_REDACT_ENDING_LENGTH"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.authentication.coerce_token_provider", "text": "", "metadata": {"kind": "function", "name": "coerce_token_provider", "path": "astrapy.authentication.coerce_token_provider", "parameters": [{"name": "token", "type": "str | TokenProvider | None"}], "returns": [{"type": "TokenProvider"}], "gathered_types": ["astrapy.authentication.TokenProvider"]}} +{"id": "astrapy.authentication.coerce_embedding_headers_provider", "text": "", "metadata": {"kind": "function", "name": "coerce_embedding_headers_provider", "path": "astrapy.authentication.coerce_embedding_headers_provider", "parameters": [{"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None"}], "returns": [{"type": "EmbeddingHeadersProvider"}], "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider"]}} +{"id": "astrapy.authentication.redact_secret", "text": "Return a shortened-if-necessary version of a 'secret' string (with ellipsis).", "metadata": {"kind": "function", "name": "redact_secret", "path": "astrapy.authentication.redact_secret", "parameters": [{"name": "secret", "type": "str", "description": "a secret string to redact", "default": null}, {"name": "max_length", "type": "int", "description": "if the secret and the fixed ending exceed this size,\nshortening takes place.", "default": null}, {"name": "hide_if_short", "type": "bool", "description": "this controls what to do when the input secret is\nshorter, i.e. when no shortening takes place.\nif False, the secret is returned as-is;\nIf True, a masked string is returned of the same length as secret.", "value": "True", "default": "True"}], "returns": [{"type": "str", "description": "a 'redacted' form of the secret string as per the rules outlined above."}]}} +{"id": "astrapy.authentication.TokenProvider", "text": "Abstract base class for a token provider.\nThe relevant method in this interface is returning a string to use as token.\n\nThe __str__ / __repr__ methods are NOT to be used as source of tokens:\nuse get_token instead.\n\nNote that equality (__eq__) checks if the generated tokens match\nunder all circumstances (e.g. a literal passthrough matches a\ndifferent-encoding token provider that yields the same token).\nIf a token provider comes that encodes a recipe for nondeterministic\nperiodic renewal, its __eq__ method will have to override the one in this class.", "metadata": {"kind": "class", "name": "TokenProvider", "path": "astrapy.authentication.TokenProvider", "bases": ["ABC"], "gathered_types": ["ABC"], "implemented_by": ["astrapy.authentication.UsernamePasswordTokenProvider", "astrapy.authentication.StaticTokenProvider"]}} +{"id": "astrapy.authentication.TokenProvider.get_token", "text": "Produce a string for direct use as token in a subsequent API request,\nor None for no token.", "metadata": {"kind": "function", "name": "get_token", "path": "astrapy.authentication.TokenProvider.get_token", "returns": [{"type": "str | None"}]}} +{"id": "astrapy.authentication.StaticTokenProvider", "text": "A \"pass-through\" provider that wraps a supplied literal token.", "metadata": {"kind": "class", "name": "StaticTokenProvider", "path": "astrapy.authentication.StaticTokenProvider", "parameters": [{"name": "token", "type": "str | None", "description": "an access token for subsequent use in the client.", "default": null}], "bases": ["astrapy.authentication.TokenProvider"], "example": ">>> from astrapy import DataAPIClient\n>>> from astrapy.authentication import StaticTokenProvider\n>>> token_provider = StaticTokenProvider(\"AstraCS:xyz...\")\n>>> database = DataAPIClient().get_database(\n... \"https://01234567-...-eu-west1.apps.datastax.com\",\n... token=token_provider,\n... )", "references": ["astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider"]}} +{"id": "astrapy.authentication.StaticTokenProvider.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.authentication.StaticTokenProvider.token", "value": "token = token"}} +{"id": "astrapy.authentication.StaticTokenProvider.get_token", "text": "", "metadata": {"kind": "function", "name": "get_token", "path": "astrapy.authentication.StaticTokenProvider.get_token", "returns": [{"type": "str | None"}]}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider", "text": "A token provider encoding username/password-based authentication,\nas used e.g. for DSE and HCD. These are base64-encoded and concatenated\nby colons, with a prepended suffix 'Cassandra', as required by\nthis authentication scheme.", "metadata": {"kind": "class", "name": "UsernamePasswordTokenProvider", "path": "astrapy.authentication.UsernamePasswordTokenProvider", "parameters": [{"name": "username", "type": "str", "description": "the username for accessing the database.", "default": null}, {"name": "password", "type": "str", "description": "the corresponding password.", "default": null}], "bases": ["astrapy.authentication.TokenProvider"], "example": ">>> from astrapy import DataAPIClient\n>>> from astrapy.constants imort Environment\n>>> from astrapy.authentication import UsernamePasswordTokenProvider\n>>> token_provider = UsernamePasswordTokenProvider(\"username\", \"password\")\n>>> database = DataAPIClient(environment=Environment.HCD).get_database(\n... \"http://localhost:8181\",\n... token=token_provider,\n... )", "references": ["astrapy.constants.Environment", "astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.TokenProvider"]}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider.PREFIX", "text": "", "metadata": {"kind": "attribute", "name": "PREFIX", "path": "astrapy.authentication.UsernamePasswordTokenProvider.PREFIX", "value": "PREFIX = 'Cassandra'"}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider.username", "text": "", "metadata": {"kind": "attribute", "name": "username", "path": "astrapy.authentication.UsernamePasswordTokenProvider.username", "value": "username = username"}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider.password", "text": "", "metadata": {"kind": "attribute", "name": "password", "path": "astrapy.authentication.UsernamePasswordTokenProvider.password", "value": "password = password"}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.authentication.UsernamePasswordTokenProvider.token", "value": "token = f'{self.PREFIX}:{self._b64(self.username)}:{self._b64(self.password)}'", "gathered_types": ["_b64", "PREFIX"]}} +{"id": "astrapy.authentication.UsernamePasswordTokenProvider.get_token", "text": "", "metadata": {"kind": "function", "name": "get_token", "path": "astrapy.authentication.UsernamePasswordTokenProvider.get_token", "returns": [{"type": "str"}]}} +{"id": "astrapy.authentication.EmbeddingHeadersProvider", "text": "Abstract base class for a provider of embedding-related headers (such as API Keys).\nThe relevant method in this interface is returning a dict to use as\n(part of the) headers in Data API requests for a collection.\n\nThis class captures the fact that, depending on the embedding provider for\nthe collection, there may be zero, one *or more* headers to be passed\nif relying on the HEADERS auth method for Vectorize.", "metadata": {"kind": "class", "name": "EmbeddingHeadersProvider", "path": "astrapy.authentication.EmbeddingHeadersProvider", "bases": ["ABC"], "gathered_types": ["ABC"], "implemented_by": ["astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "astrapy.authentication.AWSEmbeddingHeadersProvider"]}} +{"id": "astrapy.authentication.EmbeddingHeadersProvider.get_headers", "text": "Produce a dictionary for use as (part of) the headers in HTTP requests\nto the Data API.", "metadata": {"kind": "function", "name": "get_headers", "path": "astrapy.authentication.EmbeddingHeadersProvider.get_headers", "returns": [{"type": "dict[str, str]"}]}} +{"id": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "text": "A \"pass-through\" header provider representing the single-header\n(typically \"X-Embedding-Api-Key\") auth scheme, in use by most of the\nembedding models in Vectorize.", "metadata": {"kind": "class", "name": "EmbeddingAPIKeyHeaderProvider", "path": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider", "parameters": [{"name": "embedding_api_key", "type": "str | None", "description": "a string that will be the value for the header.\nIf None is passed, this results in a no-headers provider (such\nas the one used for non-Vectorize collections).", "default": null}], "bases": ["astrapy.authentication.EmbeddingHeadersProvider"], "example": ">>> from astrapy import DataAPIClient\n>>> from astrapy.authentication import (\n CollectionVectorServiceOptions,\n EmbeddingAPIKeyHeaderProvider,\n)\n>>> my_emb_api_key = EmbeddingAPIKeyHeaderProvider(\"abc012...\")\n>>> service_options = CollectionVectorServiceOptions(\n... provider=\"a-certain-provider\",\n... model_name=\"some-embedding-model\",\n... )\n>>>\n>>> database = DataAPIClient().get_database(\n... \"https://01234567-...-eu-west1.apps.datastax.com\",\n... token=\"AstraCS:...\",\n... )\n>>> collection = database.create_collection(\n... \"vectorize_collection\",\n... service=service_options,\n... embedding_api_key=my_emb_api_key,\n... )\n>>> # likewise:\n>>> collection_b = database.get_collection(\n... \"vectorize_collection\",\n... embedding_api_key=my_emb_api_key,\n... )", "references": ["astrapy.authentication.CollectionVectorServiceOptions", "astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider"]}} +{"id": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider.embedding_api_key", "text": "", "metadata": {"kind": "attribute", "name": "embedding_api_key", "path": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider.embedding_api_key", "value": "embedding_api_key = embedding_api_key"}} +{"id": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider.get_headers", "text": "", "metadata": {"kind": "function", "name": "get_headers", "path": "astrapy.authentication.EmbeddingAPIKeyHeaderProvider.get_headers", "returns": [{"type": "dict[str, str]"}]}} +{"id": "astrapy.authentication.AWSEmbeddingHeadersProvider", "text": "A header provider representing the two-header auth scheme in use\nby the Amazon Web Services (e.g. AWS Bedrock) when using header-based\nauthentication.", "metadata": {"kind": "class", "name": "AWSEmbeddingHeadersProvider", "path": "astrapy.authentication.AWSEmbeddingHeadersProvider", "parameters": [{"name": "embedding_access_id", "type": "str", "description": "value of the \"Access ID\" secret. This will become\nthe value for the corresponding header.", "default": null}, {"name": "embedding_secret_id", "type": "str", "description": "value of the \"Secret ID\" secret. This will become\nthe value for the corresponding header.", "default": null}], "bases": ["astrapy.authentication.EmbeddingHeadersProvider"], "example": ">>> from astrapy import DataAPIClient\n>>> from astrapy.authentication import (\n CollectionVectorServiceOptions,\n AWSEmbeddingHeadersProvider,\n)\n>>> my_aws_emb_api_key = AWSEmbeddingHeadersProvider(\n embedding_access_id=\"my-access-id-012...\",\n embedding_secret_id=\"my-secret-id-abc...\",\n)\n>>> service_options = CollectionVectorServiceOptions(\n... provider=\"bedrock\",\n... model_name=\"some-aws-bedrock-model\",\n... )\n>>>\n>>> database = DataAPIClient().get_database(\n... \"https://01234567-...-eu-west1.apps.datastax.com\",\n... token=\"AstraCS:...\",\n... )\n>>> collection = database.create_collection(\n... \"vectorize_aws_collection\",\n... service=service_options,\n... embedding_api_key=my_aws_emb_api_key,\n... )\n>>> # likewise:\n>>> collection_b = database.get_collection(\n... \"vectorize_aws_collection\",\n... embedding_api_key=my_aws_emb_api_key,\n... )", "references": ["astrapy.authentication.CollectionVectorServiceOptions", "astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider"]}} +{"id": "astrapy.authentication.AWSEmbeddingHeadersProvider.embedding_access_id", "text": "", "metadata": {"kind": "attribute", "name": "embedding_access_id", "path": "astrapy.authentication.AWSEmbeddingHeadersProvider.embedding_access_id", "value": "embedding_access_id = embedding_access_id"}} +{"id": "astrapy.authentication.AWSEmbeddingHeadersProvider.embedding_secret_id", "text": "", "metadata": {"kind": "attribute", "name": "embedding_secret_id", "path": "astrapy.authentication.AWSEmbeddingHeadersProvider.embedding_secret_id", "value": "embedding_secret_id = embedding_secret_id"}} +{"id": "astrapy.authentication.AWSEmbeddingHeadersProvider.get_headers", "text": "", "metadata": {"kind": "function", "name": "get_headers", "path": "astrapy.authentication.AWSEmbeddingHeadersProvider.get_headers", "returns": [{"type": "dict[str, str]"}]}} +{"id": "astrapy.collection", "text": "", "metadata": {"kind": "module", "name": "collection", "path": "astrapy.collection", "imports": {"annotations": "__future__.annotations", "asyncio": "asyncio", "json": "json", "logging": "logging", "warnings": "warnings", "ThreadPoolExecutor": "concurrent.futures.ThreadPoolExecutor", "TracebackType": "types.TracebackType", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Iterable": "typing.Iterable", "Sequence": "typing.Sequence", "deprecation": "deprecation", "__version__": "astrapy.__version__", "APICommander": "astrapy.api_commander.APICommander", "CollectionAPIOptions": "astrapy.api_options.CollectionAPIOptions", "coerce_embedding_headers_provider": "astrapy.authentication.coerce_embedding_headers_provider", "CallerType": "astrapy.constants.CallerType", "DocumentType": "astrapy.constants.DocumentType", "FilterType": "astrapy.constants.FilterType", "ProjectionType": "astrapy.constants.ProjectionType", "ReturnDocument": "astrapy.constants.ReturnDocument", "SortType": "astrapy.constants.SortType", "VectorType": "astrapy.constants.VectorType", "normalize_optional_projection": "astrapy.constants.normalize_optional_projection", "AsyncCursor": "astrapy.cursors.AsyncCursor", "Cursor": "astrapy.cursors.Cursor", "AsyncDatabase": "astrapy.database.AsyncDatabase", "Database": "astrapy.database.Database", "DEFAULT_BULK_WRITE_CONCURRENCY": "astrapy.defaults.DEFAULT_BULK_WRITE_CONCURRENCY", "DEFAULT_DATA_API_AUTH_HEADER": "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "DEFAULT_INSERT_MANY_CHUNK_SIZE": "astrapy.defaults.DEFAULT_INSERT_MANY_CHUNK_SIZE", "DEFAULT_INSERT_MANY_CONCURRENCY": "astrapy.defaults.DEFAULT_INSERT_MANY_CONCURRENCY", "NAMESPACE_DEPRECATION_NOTICE_METHOD": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_METHOD", "SET_CALLER_DEPRECATION_NOTICE": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "BulkWriteException": "astrapy.exceptions.BulkWriteException", "CollectionNotFoundException": "astrapy.exceptions.CollectionNotFoundException", "CumulativeOperationException": "astrapy.exceptions.CumulativeOperationException", "DataAPIFaultyResponseException": "astrapy.exceptions.DataAPIFaultyResponseException", "DataAPIResponseException": "astrapy.exceptions.DataAPIResponseException", "DeleteManyException": "astrapy.exceptions.DeleteManyException", "InsertManyException": "astrapy.exceptions.InsertManyException", "MultiCallTimeoutManager": "astrapy.exceptions.MultiCallTimeoutManager", "TooManyDocumentsToCountException": "astrapy.exceptions.TooManyDocumentsToCountException", "UpdateManyException": "astrapy.exceptions.UpdateManyException", "base_timeout_info": "astrapy.exceptions.base_timeout_info", "CollectionInfo": "astrapy.info.CollectionInfo", "CollectionOptions": "astrapy.info.CollectionOptions", "check_caller_parameters": "astrapy.meta.check_caller_parameters", "check_deprecated_vector_ize": "astrapy.meta.check_deprecated_vector_ize", "check_namespace_keyspace": "astrapy.meta.check_namespace_keyspace", "BulkWriteResult": "astrapy.results.BulkWriteResult", "DeleteResult": "astrapy.results.DeleteResult", "InsertManyResult": "astrapy.results.InsertManyResult", "InsertOneResult": "astrapy.results.InsertOneResult", "UpdateResult": "astrapy.results.UpdateResult", "EmbeddingHeadersProvider": "astrapy.authentication.EmbeddingHeadersProvider", "AsyncBaseOperation": "astrapy.operations.AsyncBaseOperation", "BaseOperation": "astrapy.operations.BaseOperation"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.collection.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.collection.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.collection.Collection", "text": "A Data API collection, the main object to interact with the Data API,\nespecially for DDL operations.\nThis class has a synchronous interface.\n\nA Collection is spawned from a Database object, from which it inherits\nthe details on how to reach the API server (endpoint, authentication token).", "metadata": {"kind": "class", "name": "Collection", "path": "astrapy.collection.Collection", "parameters": [{"name": "database", "type": "Database", "description": "a Database object, instantiated earlier. This represents\nthe database the collection belongs to.", "default": null}, {"name": "name", "type": "str", "description": "the collection name. This parameter should match an existing\ncollection on the database.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace to which the collection belongs.\nIf not specified, the database's working keyspace is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "api_options", "type": "CollectionAPIOptions | None", "description": "An instance of `astrapy.api_options.CollectionAPIOptions`\nproviding the general settings for interacting with the Data API.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient, Collection\n>>> my_client = astrapy.DataAPIClient(\"AstraCS:...\")\n>>> my_db = my_client.get_database(\n... \"https://01234567-....apps.astra.datastax.com\"\n... )\n>>> my_coll_1 = Collection(database=my_db, name=\"my_collection\")\n>>> my_coll_2 = my_db.create_collection(\n... \"my_v_collection\",\n... dimension=3,\n... metric=\"cosine\",\n... )\n>>> my_coll_3a = my_db.get_collection(\"my_already_existing_collection\")\n>>> my_coll_3b = my_db.my_already_existing_collection\n>>> my_coll_3c = my_db[\"my_already_existing_collection\"]", "note": "creating an instance of Collection does not trigger actual creation\nof the collection on the database. The latter should have been created\nbeforehand, e.g. through the `create_collection` method of a Database.", "references": ["astrapy.collection.Collection", "astrapy.client.DataAPIClient"], "gathered_types": ["astrapy.constants.CallerType", "astrapy.database.Database", "astrapy.api_options.CollectionAPIOptions"]}} +{"id": "astrapy.collection.Collection.api_options", "text": "", "metadata": {"kind": "attribute", "name": "api_options", "path": "astrapy.collection.Collection.api_options", "value": "api_options = CollectionAPIOptions()", "gathered_types": ["astrapy.api_options.CollectionAPIOptions"]}} +{"id": "astrapy.collection.Collection.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.collection.Collection.callers", "value": "callers = callers_param"}} +{"id": "astrapy.collection.Collection.with_options", "text": "Create a clone of this collection with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.collection.Collection.with_options", "parameters": [{"name": "name", "type": "str | None", "description": "the name of the collection. This parameter is useful to\nquickly spawn Collection instances each pointing to a different\ncollection existing in the same keyspace.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "Collection", "description": "a new Collection instance."}], "example": ">>> my_other_coll = my_coll.with_options(\n... name=\"the_other_coll\",\n... callers=[(\"caller_identity\", \"0.1.2\")],\n... )", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.collection.Collection.to_async", "text": "Create an AsyncCollection from this one. Save for the arguments\nexplicitly provided as overrides, everything else is kept identical\nto this collection in the copy (the database is converted into\nan async object).", "metadata": {"kind": "function", "name": "to_async", "path": "astrapy.collection.Collection.to_async", "parameters": [{"name": "database", "type": "AsyncDatabase | None", "description": "an AsyncDatabase object, instantiated earlier.\nThis represents the database the new collection belongs to.", "value": "None", "default": "None"}, {"name": "name", "type": "str | None", "description": "the collection name. This parameter should match an existing\ncollection on the database.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace to which the collection belongs.\nIf not specified, the database's working keyspace is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCollection", "description": "the new copy, an AsyncCollection instance."}], "example": ">>> asyncio.run(my_coll.to_async().count_documents({},upper_bound=100))\n77", "gathered_types": ["astrapy.collection.AsyncCollection", "astrapy.authentication.EmbeddingHeadersProvider", "astrapy.constants.CallerType", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.collection.Collection.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe Data API calls are performed (the \"caller\").", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.collection.Collection.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe Data API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_coll.set_caller(caller_name=\"the_caller\", caller_version=\"0.1.0\")"}} +{"id": "astrapy.collection.Collection.options", "text": "Get the collection options, i.e. its configuration as read from the database.\n\nThe method issues a request to the Data API each time is invoked,\nwithout caching mechanisms: this ensures up-to-date information\nfor usages such as real-time collection validation by the application.", "metadata": {"kind": "function", "name": "options", "path": "astrapy.collection.Collection.options", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "CollectionOptions", "description": "a CollectionOptions instance describing the collection."}, {"type": "CollectionOptions", "description": "(See also the database `list_collections` method.)"}], "example": ">>> my_coll.options()\nCollectionOptions(vector=CollectionVectorOptions(dimension=3, metric='cosine'))", "gathered_types": ["astrapy.info.CollectionOptions"]}} +{"id": "astrapy.collection.Collection.info", "text": "Information on the collection (name, location, database), in the\nform of a CollectionInfo object.\n\nNot to be confused with the collection `options` method (related\nto the collection internal configuration).", "metadata": {"kind": "function", "name": "info", "path": "astrapy.collection.Collection.info", "returns": [{"type": "CollectionInfo"}], "example": ">>> my_coll.info().database_info.region\n'eu-west-1'\n>>> my_coll.info().full_name\n'default_keyspace.my_v_collection'", "note": "the returned CollectionInfo wraps, among other things,\nthe database information: as such, calling this method\ntriggers the same-named method of a Database object (which, in turn,\nperforms a HTTP request to the DevOps API).\nSee the documentation for `Database.info()` for more details.", "gathered_types": ["astrapy.info.CollectionInfo"]}} +{"id": "astrapy.collection.Collection.database", "text": "a Database object, the database this collection belongs to.", "metadata": {"kind": "attribute", "name": "database", "path": "astrapy.collection.Collection.database", "value": "database: Database", "example": ">>> my_coll.database.name\n'the_application_database'", "gathered_types": ["astrapy.database.Database"]}} +{"id": "astrapy.collection.Collection.namespace", "text": "The namespace this collection is in.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.collection.Collection.namespace", "value": "namespace: str", "example": ">>> my_coll.namespace\n'default_keyspace'"}} +{"id": "astrapy.collection.Collection.keyspace", "text": "The keyspace this collection is in.", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.collection.Collection.keyspace", "value": "keyspace: str", "example": ">>> my_coll.keyspace\n'default_keyspace'"}} +{"id": "astrapy.collection.Collection.name", "text": "The name of this collection.", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.collection.Collection.name", "value": "name: str", "example": ">>> my_coll.name\n'my_v_collection'"}} +{"id": "astrapy.collection.Collection.full_name", "text": "The fully-qualified collection name within the database,\nin the form \"keyspace.collection_name\".", "metadata": {"kind": "attribute", "name": "full_name", "path": "astrapy.collection.Collection.full_name", "value": "full_name: str", "example": ">>> my_coll.full_name\n'default_keyspace.my_v_collection'"}} +{"id": "astrapy.collection.Collection.insert_one", "text": "Insert a single document in the collection in an atomic operation.", "metadata": {"kind": "function", "name": "insert_one", "path": "astrapy.collection.Collection.insert_one", "parameters": [{"name": "document", "type": "DocumentType", "description": "the dictionary expressing the document to insert.\nThe `_id` field of the document can be left out, in which\ncase it will be created automatically.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a vector (a list of numbers appropriate for the collection)\nfor the document. Passing this parameter is equivalent to\nproviding a `$vector` field within the document itself,\nhowever the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the document instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, if such a service\nis configured for the collection. Passing this parameter is\nequivalent to providing a `$vectorize` field in the document itself,\nhowever the two are mutually exclusive.\nMoreover, this parameter cannot coexist with `vector`.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the document instead.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "InsertOneResult", "description": "an InsertOneResult object."}], "example": ">>> my_coll.count_documents({}, upper_bound=10)\n0\n>>> my_coll.insert_one(\n... {\n... \"age\": 30,\n... \"name\": \"Smith\",\n... \"food\": [\"pear\", \"peach\"],\n... \"likes_fruit\": True,\n... },\n... )\nInsertOneResult(raw_results=..., inserted_id='ed4587a4-...-...-...')\n>>> my_coll.insert_one({\"_id\": \"user-123\", \"age\": 50, \"name\": \"Maccio\"})\nInsertOneResult(raw_results=..., inserted_id='user-123')\n>>> my_coll.count_documents({}, upper_bound=10)\n2/n/n/n>>> my_coll.insert_one({\"tag\": \"v\", \"$vector\": [10, 11]})\nInsertOneResult(...)", "note": "If an `_id` is explicitly provided, which corresponds to a document\nthat exists already in the collection, an error is raised and\nthe insertion fails.", "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.results.InsertOneResult"]}} +{"id": "astrapy.collection.Collection.insert_many", "text": "Insert a list of documents into the collection.\nThis is not an atomic operation.", "metadata": {"kind": "function", "name": "insert_many", "path": "astrapy.collection.Collection.insert_many", "parameters": [{"name": "documents", "type": "Iterable[DocumentType]", "description": "an iterable of dictionaries, each a document to insert.\nDocuments may specify their `_id` field or leave it out, in which\ncase it will be added automatically.", "default": null}, {"name": "vectors", "type": "Iterable[VectorType | None] | None", "description": "an optional list of vectors (as many vectors as the provided\ndocuments) to associate to the documents when inserting.\nPassing vectors this way is indeed equivalent to the \"$vector\" field\nof the documents, however the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the documents instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "Iterable[str | None] | None", "description": "an optional list of strings to be made into as many vectors\n(one per document), if such a service is configured for the collection.\nPassing this parameter is equivalent to providing a `$vectorize`\nfield in the documents themselves, however the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the documents instead.", "value": "None", "default": "None"}, {"name": "ordered", "type": "bool", "description": "if False (default), the insertions can occur in arbitrary order\nand possibly concurrently. If True, they are processed sequentially.\nIf there are no specific reasons against it, unordered insertions are to\nbe preferred as they complete much faster.", "value": "False", "default": "False"}, {"name": "chunk_size", "type": "int | None", "description": "how many documents to include in a single API request.\nExceeding the server maximum allowed value results in an error.\nLeave it unspecified (recommended) to use the system default.", "value": "None", "default": "None"}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent requests to the API at\na given time. It cannot be more than one for ordered insertions.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nIf many documents are being inserted, this method corresponds\nto several HTTP requests: in such cases one may want to specify\na more tolerant timeout here.", "value": "None", "default": "None"}], "returns": [{"type": "InsertManyResult", "description": "an InsertManyResult object."}], "example": ">>> my_coll.count_documents({}, upper_bound=10)\n0\n>>> my_coll.insert_many(\n... [{\"a\": 10}, {\"a\": 5}, {\"b\": [True, False, False]}],\n... ordered=True,\n... )\nInsertManyResult(raw_results=..., inserted_ids=['184bb06f-...', '...', '...'])\n>>> my_coll.count_documents({}, upper_bound=100)\n3\n>>> my_coll.insert_many(\n... [{\"seq\": i} for i in range(50)],\n... concurrency=5,\n... )\nInsertManyResult(raw_results=..., inserted_ids=[... ...])\n>>> my_coll.count_documents({}, upper_bound=100)\n53\n>>> my_coll.insert_many(\n... [\n... {\"tag\": \"a\", \"$vector\": [1, 2]},\n... {\"tag\": \"b\", \"$vector\": [3, 4]},\n... ]\n... )\nInsertManyResult(...)", "note": "A failure mode for this command is related to certain faulty documents\nfound among those to insert: a document may have the an `_id` already\npresent on the collection, or its vector dimension may not\nmatch the collection setting.\n\nFor an ordered insertion, the method will raise an exception at\nthe first such faulty document -- nevertheless, all documents processed\nuntil then will end up being written to the database.\n\nFor unordered insertions, if the error stems from faulty documents\nthe insertion proceeds until exhausting the input documents: then,\nan exception is raised -- and all insertable documents will have been\nwritten to the database, including those \"after\" the troublesome ones.\n\nIf, on the other hand, there are errors not related to individual\ndocuments (such as a network connectivity error), the whole\n`insert_many` operation will stop in mid-way, an exception will be raised,\nand only a certain amount of the input documents will\nhave made their way to the database.", "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.results.InsertManyResult"]}} +{"id": "astrapy.collection.Collection.find", "text": "Find documents on the collection, matching a certain provided filter.\n\nThe method returns a Cursor that can then be iterated over. Depending\non the method call pattern, the iteration over all documents can reflect\ncollection mutations occurred since the `find` method was called, or not.\nIn cases where the cursor reflects mutations in real-time, it will iterate\nover cursors in an approximate way (i.e. exhibiting occasional skipped\nor duplicate documents). This happens when making use of the `sort`\noption in a non-vector-search manner.", "metadata": {"kind": "function", "name": "find", "path": "astrapy.collection.Collection.find", "parameters": [{"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "skip", "type": "int | None", "description": "with this integer parameter, what would be the first `skip`\ndocuments returned by the query are discarded, and the results\nstart from the (skip+1)-th document.\nThis parameter can be used only in conjunction with an explicit\n`sort` criterion of the ascending/descending type (i.e. it cannot\nbe used when not sorting, nor with vector-based ANN search).", "value": "None", "default": "None"}, {"name": "limit", "type": "int | None", "description": "this (integer) parameter sets a limit over how many documents\nare returned. Once `limit` is reached (or the cursor is exhausted\nfor lack of matching documents), nothing more is returned.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to perform vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search).\nWhen running similarity search on a collection, no other sorting\ncriteria can be specified. Moreover, there is an upper bound\nto the number of documents that can be returned. For details,\nsee the Note about upper bounds and the Data API documentation.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nThis can be supplied in (exclusive) alternative to `vector`,\nprovided such a service is configured for the collection,\nand achieves the same effect.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool | None", "description": "a boolean to request the numeric value of the\nsimilarity to be returned as an added \"$similarity\" key in each\nreturned document. Can only be used for vector ANN search, i.e.\nwhen either `vector` is supplied or the `sort` parameter has the\nshape {\"$vector\": ...}.", "value": "None", "default": "None"}, {"name": "include_sort_vector", "type": "bool | None", "description": "a boolean to request query vector used in this search.\nIf set to True (and if the invocation is a vector search), calling\nthe `get_sort_vector` method on the returned cursor will yield\nthe vector used for the ANN search.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the order\nthe documents are returned. See the Note about sorting, as well as\nthe one about upper bounds, for details.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for each single one\nof the underlying HTTP requests used to fetch documents as the\ncursor is iterated over.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "Cursor", "description": "a Cursor object representing iterations over the matching documents"}, {"type": "Cursor", "description": "(see the Cursor object for how to use it. The simplest thing is to"}, {"type": "Cursor", "description": "run a for loop: `for document in collection.sort(...):`)."}], "example": ">>> filter = {\"seq\": {\"$exists\": True}}\n>>> for doc in my_coll.find(filter, projection={\"seq\": True}, limit=5):\n... print(doc[\"seq\"])\n...\n37\n35\n10\n36\n27\n>>> cursor1 = my_coll.find(\n... {},\n... limit=4,\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\n>>> [doc[\"_id\"] for doc in cursor1]\n['97e85f81-...', '1581efe4-...', '...', '...']\n>>> cursor2 = my_coll.find({}, limit=3)\n>>> cursor2.distinct(\"seq\")\n[37, 35, 10]/n/n/n>>> my_coll.insert_many([\n... {\"tag\": \"A\", \"$vector\": [4, 5]},\n... {\"tag\": \"B\", \"$vector\": [3, 4]},\n... {\"tag\": \"C\", \"$vector\": [3, 2]},\n... {\"tag\": \"D\", \"$vector\": [4, 1]},\n... {\"tag\": \"E\", \"$vector\": [2, 5]},\n... ])\n>>> ann_tags = [\n... document[\"tag\"]\n... for document in my_coll.find(\n... {},\n... sort={\"$vector\": [3, 3]},\n... limit=3,\n... )\n... ]\n>>> ann_tags\n['A', 'B', 'C']\n>>> # (assuming the collection has metric VectorMetric.COSINE)/n/n/n>>> cursor = my_coll.find(\n... sort={\"$vector\": [3, 3]},\n... limit=3,\n... include_sort_vector=True,\n... )\n>>> cursor.get_sort_vector()\n[3.0, 3.0]\n>>> matches = list(cursor)\n>>> cursor.get_sort_vector()\n[3.0, 3.0]", "note": "When not specifying sorting criteria at all (by vector or otherwise),\nthe cursor can scroll through an arbitrary number of documents as\nthe Data API and the client periodically exchange new chunks of documents.\nIt should be noted that the behavior of the cursor in the case documents\nhave been added/removed after the `find` was started depends on database\ninternals and it is not guaranteed, nor excluded, that such \"real-time\"\nchanges in the data would be picked up by the cursor.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.cursors.Cursor", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.Collection.find_one", "text": "Run a search, returning the first document in the collection that matches\nprovided filters, if any is found.", "metadata": {"kind": "function", "name": "find_one", "path": "astrapy.collection.Collection.find_one", "parameters": [{"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to perform vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), extracting the most\nsimilar document in the collection matching the filter.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool | None", "description": "a boolean to request the numeric value of the\nsimilarity to be returned as an added \"$similarity\" key in the\nreturned document. Can only be used for vector ANN search, i.e.\nwhen either `vector` is supplied or the `sort` parameter has the\nshape {\"$vector\": ...}.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the order\nthe documents are returned. See the Note about sorting for details.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "a dictionary expressing the required document, otherwise None."}], "example": ">>> my_coll.find_one({})\n{'_id': '68d1e515-...', 'seq': 37}\n>>> my_coll.find_one({\"seq\": 10})\n{'_id': 'd560e217-...', 'seq': 10}\n>>> my_coll.find_one({\"seq\": 1011})\n>>> # (returns None for no matches)\n>>> my_coll.find_one({}, projection={\"seq\": False})\n{'_id': '68d1e515-...'}\n>>> my_coll.find_one(\n... {},\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\n{'_id': '97e85f81-...', 'seq': 69}\n>>> my_coll.find_one({}, sort={\"$vector\": [1, 0]}, projection={\"*\": True})\n{'_id': '...', 'tag': 'D', '$vector': [4.0, 1.0]}", "note": "See the `find` method for more details on the accepted parameters\n(whereas `skip` and `limit` are not valid parameters for `find_one`).", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.Collection.distinct", "text": "Return a list of the unique values of `key` across the documents\nin the collection that match the provided filter.", "metadata": {"kind": "function", "name": "distinct", "path": "astrapy.collection.Collection.distinct", "parameters": [{"name": "key", "type": "str", "description": "the name of the field whose value is inspected across documents.\nKeys can use dot-notation to descend to deeper document levels.\nExample of acceptable `key` values:\n \"field\"\n \"field.subfield\"\n \"field.3\"\n \"field.3.subfield\"\nIf lists are encountered and no numeric index is specified,\nall items in the list are visited.", "default": null}, {"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, with the same meaning as for `find`.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "list[Any]", "description": "a list of all different values for `key` found across the documents"}, {"type": "list[Any]", "description": "that match the filter. The result list has no repeated items."}], "example": ">>> my_coll.insert_many(\n... [\n... {\"name\": \"Marco\", \"food\": [\"apple\", \"orange\"], \"city\": \"Helsinki\"},\n... {\"name\": \"Emma\", \"food\": {\"likes_fruit\": True, \"allergies\": []}},\n... ]\n... )\nInsertManyResult(raw_results=..., inserted_ids=['c5b99f37-...', 'd6416321-...'])\n>>> my_coll.distinct(\"name\")\n['Marco', 'Emma']\n>>> my_coll.distinct(\"city\")\n['Helsinki']\n>>> my_coll.distinct(\"food\")\n['apple', 'orange', {'likes_fruit': True, 'allergies': []}]\n>>> my_coll.distinct(\"food.1\")\n['orange']\n>>> my_coll.distinct(\"food.allergies\")\n[]\n>>> my_coll.distinct(\"food.likes_fruit\")\n[True]", "note": "For details on the behaviour of \"distinct\" in conjunction with\nreal-time changes in the collection contents, see the\nNote of the `find` command.", "gathered_types": ["astrapy.constants.FilterType"]}} +{"id": "astrapy.collection.Collection.count_documents", "text": "Count the documents in the collection matching the specified filter.", "metadata": {"kind": "function", "name": "count_documents", "path": "astrapy.collection.Collection.count_documents", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "upper_bound", "type": "int", "description": "a required ceiling on the result of the count operation.\nIf the actual number of documents exceeds this value,\nan exception will be raised.\nFurthermore, if the actual number of documents exceeds the maximum\ncount that the Data API can reach (regardless of upper_bound),\nan exception will be raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "int", "description": "the exact count of matching documents."}], "example": ">>> my_coll.insert_many([{\"seq\": i} for i in range(20)])\nInsertManyResult(...)\n>>> my_coll.count_documents({}, upper_bound=100)\n20\n>>> my_coll.count_documents({\"seq\":{\"$gt\": 15}}, upper_bound=100)\n4\n>>> my_coll.count_documents({}, upper_bound=10)\nTraceback (most recent call last):\n ... ...\nastrapy.exceptions.TooManyDocumentsToCountException", "note": "Count operations are expensive: for this reason, the best practice\nis to provide a reasonable `upper_bound` according to the caller\nexpectations. Moreover, indiscriminate usage of count operations\nfor sizeable amounts of documents (i.e. in the thousands and more)\nis discouraged in favor of alternative application-specific solutions.\nKeep in mind that the Data API has a hard upper limit on the amount\nof documents it will count, and that an exception will be thrown\nby this method if this limit is encountered.", "gathered_types": ["astrapy.constants.FilterType"]}} +{"id": "astrapy.collection.Collection.estimated_document_count", "text": "Query the API server for an estimate of the document count in the collection.\n\nContrary to `count_documents`, this method has no filtering parameters.", "metadata": {"kind": "function", "name": "estimated_document_count", "path": "astrapy.collection.Collection.estimated_document_count", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "int", "description": "a server-provided estimate count of the documents in the collection."}], "example": ">>> my_coll.estimated_document_count()\n35700"}} +{"id": "astrapy.collection.Collection.find_one_and_replace", "text": "Find a document on the collection and replace it entirely with a new one,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "find_one_and_replace", "path": "astrapy.collection.Collection.find_one_and_replace", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "replacement", "type": "DocumentType", "description": "the new document to write into the collection.", "default": null}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, `replacement` is inserted as a new document\nif no matches are found on the collection. If False,\nthe operation silently does nothing in case of no matches.", "value": "False", "default": "False"}, {"name": "return_document", "type": "str", "description": "a flag controlling what document is returned:\nif set to `ReturnDocument.BEFORE`, or the string \"before\",\nthe document found on database is returned; if set to\n`ReturnDocument.AFTER`, or the string \"after\", the new\ndocument is returned. The default is \"before\".", "value": "ReturnDocument.BEFORE", "default": "ReturnDocument.BEFORE"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "A document (or a projection thereof, as required), either the one"}, {"type": "DocumentType | None", "description": "before the replace operation or the one after that."}, {"type": "DocumentType | None", "description": "Alternatively, the method returns None to represent"}, {"type": "DocumentType | None", "description": "that no matching document was found, or that no replacement"}, {"type": "DocumentType | None", "description": "was inserted (depending on the `return_document` parameter)."}], "example": ">>> my_coll.insert_one({\"_id\": \"rule1\", \"text\": \"all animals are equal\"})\nInsertOneResult(...)\n>>> my_coll.find_one_and_replace(\n... {\"_id\": \"rule1\"},\n... {\"text\": \"some animals are more equal!\"},\n... )\n{'_id': 'rule1', 'text': 'all animals are equal'}\n>>> my_coll.find_one_and_replace(\n... {\"text\": \"some animals are more equal!\"},\n... {\"text\": \"and the pigs are the rulers\"},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n{'_id': 'rule1', 'text': 'and the pigs are the rulers'}\n>>> my_coll.find_one_and_replace(\n... {\"_id\": \"rule2\"},\n... {\"text\": \"F=ma^2\"},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n>>> # (returns None for no matches)\n>>> my_coll.find_one_and_replace(\n... {\"_id\": \"rule2\"},\n... {\"text\": \"F=ma\"},\n... upsert=True,\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... projection={\"_id\": False},\n... )\n{'text': 'F=ma'}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.ReturnDocument", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "BEFORE", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.Collection.replace_one", "text": "Replace a single document on the collection with a new one,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "replace_one", "path": "astrapy.collection.Collection.replace_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "replacement", "type": "DocumentType", "description": "the new document to write into the collection.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, `replacement` is inserted as a new document\nif no matches are found on the collection. If False,\nthe operation silently does nothing in case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the replace operation."}], "example": ">>> my_coll.insert_one({\"Marco\": \"Polo\"})\nInsertOneResult(...)\n>>> my_coll.replace_one({\"Marco\": {\"$exists\": True}}, {\"Buda\": \"Pest\"})\nUpdateResult(raw_results=..., update_info={'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1})\n>>> my_coll.find_one({\"Buda\": \"Pest\"})\n{'_id': '8424905a-...', 'Buda': 'Pest'}\n>>> my_coll.replace_one({\"Mirco\": {\"$exists\": True}}, {\"Oh\": \"yeah?\"})\nUpdateResult(raw_results=..., update_info={'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0})\n>>> my_coll.replace_one({\"Mirco\": {\"$exists\": True}}, {\"Oh\": \"yeah?\"}, upsert=True)\nUpdateResult(raw_results=..., update_info={'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '931b47d6-...'})", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.results.UpdateResult", "astrapy.constants.VectorType"]}} +{"id": "astrapy.collection.Collection.find_one_and_update", "text": "Find a document on the collection and update it as requested,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "find_one_and_update", "path": "astrapy.collection.Collection.find_one_and_update", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the document, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a new document (resulting from applying the `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "return_document", "type": "str", "description": "a flag controlling what document is returned:\nif set to `ReturnDocument.BEFORE`, or the string \"before\",\nthe document found on database is returned; if set to\n`ReturnDocument.AFTER`, or the string \"after\", the new\ndocument is returned. The default is \"before\".", "value": "ReturnDocument.BEFORE", "default": "ReturnDocument.BEFORE"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "A document (or a projection thereof, as required), either the one"}, {"type": "DocumentType | None", "description": "before the replace operation or the one after that."}, {"type": "DocumentType | None", "description": "Alternatively, the method returns None to represent"}, {"type": "DocumentType | None", "description": "that no matching document was found, or that no update"}, {"type": "DocumentType | None", "description": "was applied (depending on the `return_document` parameter)."}], "example": ">>> my_coll.insert_one({\"Marco\": \"Polo\"})\nInsertOneResult(...)\n>>> my_coll.find_one_and_update(\n... {\"Marco\": {\"$exists\": True}},\n... {\"$set\": {\"title\": \"Mr.\"}},\n... )\n{'_id': 'a80106f2-...', 'Marco': 'Polo'}\n>>> my_coll.find_one_and_update(\n... {\"title\": \"Mr.\"},\n... {\"$inc\": {\"rank\": 3}},\n... projection=[\"title\", \"rank\"],\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n{'_id': 'a80106f2-...', 'title': 'Mr.', 'rank': 3}\n>>> my_coll.find_one_and_update(\n... {\"name\": \"Johnny\"},\n... {\"$set\": {\"rank\": 0}},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n>>> # (returns None for no matches)\n>>> my_coll.find_one_and_update(\n... {\"name\": \"Johnny\"},\n... {\"$set\": {\"rank\": 0}},\n... upsert=True,\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n{'_id': 'cb4ef2ab-...', 'name': 'Johnny', 'rank': 0}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.ReturnDocument", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "BEFORE", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.Collection.update_one", "text": "Update a single document on the collection as requested,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "update_one", "path": "astrapy.collection.Collection.update_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the document, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a new document (resulting from applying the `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the update operation."}], "example": ">>> my_coll.insert_one({\"Marco\": \"Polo\"})\nInsertOneResult(...)\n>>> my_coll.update_one({\"Marco\": {\"$exists\": True}}, {\"$inc\": {\"rank\": 3}})\nUpdateResult(raw_results=..., update_info={'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1})\n>>> my_coll.update_one({\"Mirko\": {\"$exists\": True}}, {\"$inc\": {\"rank\": 3}})\nUpdateResult(raw_results=..., update_info={'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0})\n>>> my_coll.update_one({\"Mirko\": {\"$exists\": True}}, {\"$inc\": {\"rank\": 3}}, upsert=True)\nUpdateResult(raw_results=..., update_info={'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '2a45ff60-...'})", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.results.UpdateResult"]}} +{"id": "astrapy.collection.Collection.update_many", "text": "Apply an update operations to all documents matching a condition,\noptionally inserting one documents in absence of matches.", "metadata": {"kind": "function", "name": "update_many", "path": "astrapy.collection.Collection.update_many", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the documents, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a single new document (resulting from applying `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nif a large number of document updates is anticipated, it is suggested\nto specify a larger timeout than in most other operations as the\nupdate will span several HTTP calls to the API in sequence.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the update operation."}], "example": ">>> my_coll.insert_many([{\"c\": \"red\"}, {\"c\": \"green\"}, {\"c\": \"blue\"}])\nInsertManyResult(...)\n>>> my_coll.update_many({\"c\": {\"$ne\": \"green\"}}, {\"$set\": {\"nongreen\": True}})\nUpdateResult(raw_results=..., update_info={'n': 2, 'updatedExisting': True, 'ok': 1.0, 'nModified': 2})\n>>> my_coll.update_many({\"c\": \"orange\"}, {\"$set\": {\"is_also_fruit\": True}})\nUpdateResult(raw_results=..., update_info={'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0})\n>>> my_coll.update_many(\n... {\"c\": \"orange\"},\n... {\"$set\": {\"is_also_fruit\": True}},\n... upsert=True,\n... )\nUpdateResult(raw_results=..., update_info={'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '46643050-...'})", "note": "Similarly to the case of `find` (see its docstring for more details),\nrunning this command while, at the same time, another process is\ninserting new documents which match the filter of the `update_many`\ncan result in an unpredictable fraction of these documents being updated.\nIn other words, it cannot be easily predicted whether a given\nnewly-inserted document will be picked up by the update_many command or not.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.results.UpdateResult"]}} +{"id": "astrapy.collection.Collection.find_one_and_delete", "text": "Find a document in the collection and delete it. The deleted document,\nhowever, is the return value of the method.", "metadata": {"kind": "function", "name": "find_one_and_delete", "path": "astrapy.collection.Collection.find_one_and_delete", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\nThis parameter cannot be used together with `sort`.\nSee the `find` method for more details on this parameter.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nThis can be supplied in (exclusive) alternative to `vector`,\nprovided such a service is configured for the collection,\nand achieves the same effect.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\ndeleted one. See the `find` method for more on sorting.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "Either the document (or a projection thereof, as requested), or None"}, {"type": "DocumentType | None", "description": "if no matches were found in the first place."}], "example": ">>> my_coll.insert_many(\n... [\n... {\"species\": \"swan\", \"class\": \"Aves\"},\n... {\"species\": \"frog\", \"class\": \"Amphibia\"},\n... ],\n... )\nInsertManyResult(...)\n>>> my_coll.find_one_and_delete(\n... {\"species\": {\"$ne\": \"frog\"}},\n... projection=[\"species\"],\n... )\n{'_id': '5997fb48-...', 'species': 'swan'}\n>>> my_coll.find_one_and_delete({\"species\": {\"$ne\": \"frog\"}})\n>>> # (returns None for no matches)", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.Collection.delete_one", "text": "Delete one document matching a provided filter.\nThis method never deletes more than a single document, regardless\nof the number of matches to the provided filters.", "metadata": {"kind": "function", "name": "delete_one", "path": "astrapy.collection.Collection.delete_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\nThis parameter cannot be used together with `sort`.\nSee the `find` method for more details on this parameter.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nThis can be supplied in (exclusive) alternative to `vector`,\nprovided such a service is configured for the collection,\nand achieves the same effect.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\ndeleted one. See the `find` method for more on sorting.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DeleteResult", "description": "a DeleteResult object summarizing the outcome of the delete operation."}], "example": ">>> my_coll.insert_many([{\"seq\": 1}, {\"seq\": 0}, {\"seq\": 2}])\nInsertManyResult(...)\n>>> my_coll.delete_one({\"seq\": 1})\nDeleteResult(raw_results=..., deleted_count=1)\n>>> my_coll.distinct(\"seq\")\n[0, 2]\n>>> my_coll.delete_one(\n... {\"seq\": {\"$exists\": True}},\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\nDeleteResult(raw_results=..., deleted_count=1)\n>>> my_coll.distinct(\"seq\")\n[0]\n>>> my_coll.delete_one({\"seq\": 2})\nDeleteResult(raw_results=..., deleted_count=0)", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.results.DeleteResult"]}} +{"id": "astrapy.collection.Collection.delete_many", "text": "Delete all documents matching a provided filter.", "metadata": {"kind": "function", "name": "delete_many", "path": "astrapy.collection.Collection.delete_many", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.\nPassing an empty filter, `{}`, completely erases all contents\nof the collection.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nkeep in mind that this method entails successive HTTP requests\nto the API, depending on how many documents are to be deleted.\nFor this reason, in most cases it is suggested to relax the\ntimeout compared to other method calls.", "value": "None", "default": "None"}], "returns": [{"type": "DeleteResult", "description": "a DeleteResult object summarizing the outcome of the delete operation."}], "example": ">>> my_coll.insert_many([{\"seq\": 1}, {\"seq\": 0}, {\"seq\": 2}])\nInsertManyResult(...)\n>>> my_coll.delete_many({\"seq\": {\"$lte\": 1}})\nDeleteResult(raw_results=..., deleted_count=2)\n>>> my_coll.distinct(\"seq\")\n[2]\n>>> my_coll.delete_many({\"seq\": {\"$lte\": 1}})\nDeleteResult(raw_results=..., deleted_count=0)", "note": "This operation is in general not atomic. Depending on the amount\nof matching documents, it can keep running (in a blocking way)\nfor a macroscopic time. In that case, new documents that are\nmeanwhile inserted (e.g. from another process/application) will be\ndeleted during the execution of this method call until the\ncollection is devoid of matches.\nAn exception is the `filter={}` case, whereby the operation is atomic.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.results.DeleteResult"]}} +{"id": "astrapy.collection.Collection.delete_all", "text": "Delete all documents in a collection.", "metadata": {"kind": "function", "name": "delete_all", "path": "astrapy.collection.Collection.delete_all", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary of the form {\"ok\": 1} to signal successful deletion."}], "example": ">>> my_coll.distinct(\"seq\")\n[2, 1, 0]\n>>> my_coll.count_documents({}, upper_bound=100)\n4\n>>> my_coll.delete_all()\n{'ok': 1}\n>>> my_coll.count_documents({}, upper_bound=100)\n0", "note": "Use with caution."}} +{"id": "astrapy.collection.Collection.bulk_write", "text": "Execute an arbitrary amount of operations such as inserts, updates, deletes\neither sequentially or concurrently.\n\nThis method does not execute atomically, i.e. individual operations are\neach performed in the same way as the corresponding collection method,\nand each one is a different and unrelated database mutation.", "metadata": {"kind": "function", "name": "bulk_write", "path": "astrapy.collection.Collection.bulk_write", "parameters": [{"name": "requests", "type": "Iterable[BaseOperation]", "description": "an iterable over concrete subclasses of `BaseOperation`,\nsuch as `InsertMany` or `ReplaceOne`. Each such object\nrepresents an operation ready to be executed on a collection,\nand is instantiated by passing the same parameters as one\nwould the corresponding collection method.", "default": null}, {"name": "ordered", "type": "bool", "description": "whether to launch the `requests` one after the other or\nin arbitrary order, possibly in a concurrent fashion. For\nperformance reasons, False (default) should be preferred\nwhen compatible with the needs of the application flow.", "value": "False", "default": "False"}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent operations executing at\na given time. It cannot be more than one for ordered bulk writes.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole bulk write.\nRemember that, if the method call times out, then there's no\nguarantee about what portion of the bulk write has been received\nand successfully executed by the Data API.\nIf not passed, the collection-level setting is used instead:\nin most cases, however, one should pass a relaxed timeout\nif longer sequences of operations are to be executed in bulk.", "value": "None", "default": "None"}], "returns": [{"type": "BulkWriteResult", "description": "A single BulkWriteResult summarizing the whole list of requested"}, {"type": "BulkWriteResult", "description": "operations. The keys in the map attributes of BulkWriteResult"}, {"type": "BulkWriteResult", "description": "(when present) are the integer indices of the corresponding operation"}, {"type": "BulkWriteResult", "description": "in the `requests` iterable."}], "example": ">>> from astrapy.operations import InsertMany, ReplaceOne\n>>> op1 = InsertMany([{\"a\": 1}, {\"a\": 2}])\n>>> op2 = ReplaceOne({\"z\": 9}, replacement={\"z\": 9, \"replaced\": True}, upsert=True)\n>>> my_coll.bulk_write([op1, op2])\nBulkWriteResult(bulk_api_results={0: ..., 1: ...}, deleted_count=0, inserted_count=3, matched_count=0, modified_count=0, upserted_count=1, upserted_ids={1: '2addd676-...'})\n>>> my_coll.count_documents({}, upper_bound=100)\n3\n>>> my_coll.distinct(\"replaced\")\n[True]", "references": ["astrapy.operations.ReplaceOne", "astrapy.operations.InsertMany"], "gathered_types": ["astrapy.results.BulkWriteResult", "astrapy.operations.BaseOperation"]}} +{"id": "astrapy.collection.Collection.drop", "text": "Drop the collection, i.e. delete it from the database along with\nall the documents it contains.", "metadata": {"kind": "function", "name": "drop", "path": "astrapy.collection.Collection.drop", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.\nRemember there is not guarantee that a request that has\ntimed out us not in fact honored.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary of the form {\"ok\": 1} to signal successful deletion."}], "example": ">>> my_coll.find_one({})\n{'_id': '...', 'a': 100}\n>>> my_coll.drop()\n{'ok': 1}\n>>> my_coll.find_one({})\nTraceback (most recent call last):\n ... ...\nastrapy.exceptions.DataAPIResponseException: Collection does not exist, collection name: my_collection", "note": "Once the method succeeds, methods on this object can still be invoked:\nhowever, this hardly makes sense as the underlying actual collection\nis no more.\nIt is responsibility of the developer to design a correct flow\nwhich avoids using a deceased collection any further."}} +{"id": "astrapy.collection.Collection.command", "text": "Send a POST request to the Data API for this collection with\nan arbitrary, caller-provided payload.", "metadata": {"kind": "function", "name": "command", "path": "astrapy.collection.Collection.command", "parameters": [{"name": "body", "type": "dict[str, Any]", "description": "a JSON-serializable dictionary, the payload of the request.", "default": null}, {"name": "raise_api_errors", "type": "bool", "description": "if True, responses with a nonempty 'errors' field\nresult in an astrapy exception being raised.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary with the response of the HTTP request."}], "example": ">>> my_coll.command({\"countDocuments\": {}})\n{'status': {'count': 123}}"}} +{"id": "astrapy.collection.AsyncCollection", "text": "A Data API collection, the main object to interact with the Data API,\nespecially for DDL operations.\nThis class has an asynchronous interface for use with asyncio.\n\nAn AsyncCollection is spawned from a Database object, from which it inherits\nthe details on how to reach the API server (endpoint, authentication token).", "metadata": {"kind": "class", "name": "AsyncCollection", "path": "astrapy.collection.AsyncCollection", "parameters": [{"name": "database", "type": "AsyncDatabase", "description": "a Database object, instantiated earlier. This represents\nthe database the collection belongs to.", "default": null}, {"name": "name", "type": "str", "description": "the collection name. This parameter should match an existing\ncollection on the database.", "default": null}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace to which the collection belongs.\nIf not specified, the database's working keyspace is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "api_options", "type": "CollectionAPIOptions | None", "description": "An instance of `astrapy.api_options.CollectionAPIOptions`\nproviding the general settings for interacting with the Data API.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`. Removal 2.0.", "value": "None", "default": "None"}], "example": ">>> from astrapy import DataAPIClient, AsyncCollection\n>>> my_client = astrapy.DataAPIClient(\"AstraCS:...\")\n>>> my_async_db = my_client.get_async_database(\n... \"https://01234567-....apps.astra.datastax.com\"\n... )\n>>> my_async_coll_1 = AsyncCollection(database=my_async_db, name=\"my_collection\")\n>>> my_async coll_2 = asyncio.run(my_async_db.create_collection(\n... \"my_v_collection\",\n... dimension=3,\n... metric=\"cosine\",\n... ))\n>>> my_async_coll_3a = asyncio.run(my_async_db.get_collection(\n... \"my_already_existing_collection\",\n... ))\n>>> my_async_coll_3b = my_async_db.my_already_existing_collection\n>>> my_async_coll_3c = my_async_db[\"my_already_existing_collection\"]", "note": "creating an instance of AsyncCollection does not trigger actual creation\nof the collection on the database. The latter should have been created\nbeforehand, e.g. through the `create_collection` method of an AsyncDatabase.", "references": ["astrapy.client.DataAPIClient", "astrapy.collection.AsyncCollection"], "gathered_types": ["astrapy.constants.CallerType", "astrapy.api_options.CollectionAPIOptions", "astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.collection.AsyncCollection.api_options", "text": "", "metadata": {"kind": "attribute", "name": "api_options", "path": "astrapy.collection.AsyncCollection.api_options", "value": "api_options = CollectionAPIOptions()", "gathered_types": ["astrapy.api_options.CollectionAPIOptions"]}} +{"id": "astrapy.collection.AsyncCollection.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.collection.AsyncCollection.callers", "value": "callers = callers_param"}} +{"id": "astrapy.collection.AsyncCollection.with_options", "text": "Create a clone of this collection with some changed attributes.", "metadata": {"kind": "function", "name": "with_options", "path": "astrapy.collection.AsyncCollection.with_options", "parameters": [{"name": "name", "type": "str | None", "description": "the name of the collection. This parameter is useful to\nquickly spawn AsyncCollection instances each pointing to a different\ncollection existing in the same keyspace.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCollection", "description": "a new AsyncCollection instance."}], "example": ">>> my_other_async_coll = my_async_coll.with_options(\n... name=\"the_other_coll\",\n... callers=[(\"caller_identity\", \"0.1.2\")],\n... )", "gathered_types": ["astrapy.collection.AsyncCollection", "astrapy.authentication.EmbeddingHeadersProvider", "astrapy.constants.CallerType"]}} +{"id": "astrapy.collection.AsyncCollection.to_sync", "text": "Create a Collection from this one. Save for the arguments\nexplicitly provided as overrides, everything else is kept identical\nto this collection in the copy (the database is converted into\na sync object).", "metadata": {"kind": "function", "name": "to_sync", "path": "astrapy.collection.AsyncCollection.to_sync", "parameters": [{"name": "database", "type": "Database | None", "description": "a Database object, instantiated earlier.\nThis represents the database the new collection belongs to.", "value": "None", "default": "None"}, {"name": "name", "type": "str | None", "description": "the collection name. This parameter should match an existing\ncollection on the database.", "value": "None", "default": "None"}, {"name": "keyspace", "type": "str | None", "description": "this is the keyspace to which the collection belongs.\nIf not specified, the database's working keyspace is used.", "value": "None", "default": "None"}, {"name": "namespace", "type": "str | None", "description": "an alias for `keyspace`. *DEPRECATED*, removal in 2.0.", "value": "None", "default": "None"}, {"name": "embedding_api_key", "type": "str | EmbeddingHeadersProvider | None", "description": "optional API key(s) for interacting with the collection.\nIf an embedding service is configured, and this parameter is not None,\neach Data API call will include the necessary embedding-related headers\nas specified by this parameter. If a string is passed, it translates\ninto the one \"embedding api key\" header\n(i.e. `astrapy.authentication.EmbeddingAPIKeyHeaderProvider`).\nFor some vectorize providers/models, if using header-based authentication,\nspecialized subclasses of `astrapy.authentication.EmbeddingHeadersProvider`\nshould be supplied.", "value": "None", "default": "None"}, {"name": "collection_max_time_ms", "type": "int | None", "description": "a default timeout, in millisecond, for the duration of each\noperation on the collection. Individual timeouts can be provided to\neach collection method call and will take precedence, with this value\nbeing an overall default.\nNote that for some methods involving multiple API calls (such as\n`find`, `delete_many`, `insert_many` and so on), it is strongly suggested\nto provide a specific timeout as the default one likely wouldn't make\nmuch sense.", "value": "None", "default": "None"}, {"name": "callers", "type": "Sequence[CallerType]", "description": "a list of caller identities, i.e. applications, or frameworks,\non behalf of which the Data API calls are performed. These end up\nin the request user-agent.\nEach caller identity is a (\"caller_name\", \"caller_version\") pair.", "value": "[]", "default": "[]"}, {"name": "caller_name", "type": "str | None", "description": "*DEPRECATED*, use `callers`. Removal 2.0. Name of the\napplication, or framework, on behalf of which the Data API calls\nare performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller. *DEPRECATED*, use `callers`.\nRemoval 2.0.", "value": "None", "default": "None"}], "returns": [{"type": "Collection", "description": "the new copy, a Collection instance."}], "example": ">>> my_async_coll.to_sync().count_documents({}, upper_bound=100)\n77", "gathered_types": ["astrapy.authentication.EmbeddingHeadersProvider", "astrapy.database.Database", "astrapy.constants.CallerType"]}} +{"id": "astrapy.collection.AsyncCollection.set_caller", "text": "Set a new identity for the application/framework on behalf of which\nthe Data API calls are performed (the \"caller\").", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.collection.AsyncCollection.set_caller", "parameters": [{"name": "caller_name", "type": "str | None", "description": "name of the application, or framework, on behalf of which\nthe Data API calls are performed. This ends up in the request user-agent.", "value": "None", "default": "None"}, {"name": "caller_version", "type": "str | None", "description": "version of the caller.", "value": "None", "default": "None"}], "returns": [{"type": "None"}], "example": ">>> my_coll.set_caller(caller_name=\"the_caller\", caller_version=\"0.1.0\")"}} +{"id": "astrapy.collection.AsyncCollection.options", "text": "Get the collection options, i.e. its configuration as read from the database.\n\nThe method issues a request to the Data API each time is invoked,\nwithout caching mechanisms: this ensures up-to-date information\nfor usages such as real-time collection validation by the application.", "metadata": {"kind": "function", "name": "options", "path": "astrapy.collection.AsyncCollection.options", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "CollectionOptions", "description": "a CollectionOptions instance describing the collection."}, {"type": "CollectionOptions", "description": "(See also the database `list_collections` method.)"}], "example": ">>> asyncio.run(my_async_coll.options())\nCollectionOptions(vector=CollectionVectorOptions(dimension=3, metric='cosine'))", "gathered_types": ["astrapy.info.CollectionOptions"]}} +{"id": "astrapy.collection.AsyncCollection.info", "text": "Information on the collection (name, location, database), in the\nform of a CollectionInfo object.\n\nNot to be confused with the collection `options` method (related\nto the collection internal configuration).", "metadata": {"kind": "function", "name": "info", "path": "astrapy.collection.AsyncCollection.info", "returns": [{"type": "CollectionInfo"}], "example": ">>> my_async_coll.info().database_info.region\n'us-east1'\n>>> my_async_coll.info().full_name\n'default_keyspace.my_v_collection'", "note": "the returned CollectionInfo wraps, among other things,\nthe database information: as such, calling this method\ntriggers the same-named method of a Database object (which, in turn,\nperforms a HTTP request to the DevOps API).\nSee the documentation for `Database.info()` for more details.", "gathered_types": ["astrapy.info.CollectionInfo"]}} +{"id": "astrapy.collection.AsyncCollection.database", "text": "a Database object, the database this collection belongs to.", "metadata": {"kind": "attribute", "name": "database", "path": "astrapy.collection.AsyncCollection.database", "value": "database: AsyncDatabase", "example": ">>> my_async_coll.database.name\n'quicktest'", "gathered_types": ["astrapy.database.AsyncDatabase"]}} +{"id": "astrapy.collection.AsyncCollection.namespace", "text": "The namespace this collection is in.\n\n*DEPRECATED* (removal in 2.0). Switch to the \"keyspace\" property.**", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.collection.AsyncCollection.namespace", "value": "namespace: str", "example": ">>> my_async_coll.namespace\n'default_keyspace'"}} +{"id": "astrapy.collection.AsyncCollection.keyspace", "text": "The keyspace this collection is in.", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.collection.AsyncCollection.keyspace", "value": "keyspace: str", "example": ">>> my_coll.keyspace\n'default_keyspace'"}} +{"id": "astrapy.collection.AsyncCollection.name", "text": "The name of this collection.", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.collection.AsyncCollection.name", "value": "name: str", "example": ">>> my_async_coll.name\n'my_v_collection'"}} +{"id": "astrapy.collection.AsyncCollection.full_name", "text": "The fully-qualified collection name within the database,\nin the form \"keyspace.collection_name\".", "metadata": {"kind": "attribute", "name": "full_name", "path": "astrapy.collection.AsyncCollection.full_name", "value": "full_name: str", "example": ">>> my_async_coll.full_name\n'default_keyspace.my_v_collection'"}} +{"id": "astrapy.collection.AsyncCollection.insert_one", "text": "Insert a single document in the collection in an atomic operation.", "metadata": {"kind": "function", "name": "insert_one", "path": "astrapy.collection.AsyncCollection.insert_one", "parameters": [{"name": "document", "type": "DocumentType", "description": "the dictionary expressing the document to insert.\nThe `_id` field of the document can be left out, in which\ncase it will be created automatically.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a vector (a list of numbers appropriate for the collection)\nfor the document. Passing this parameter is equivalent to\nproviding a `$vector` field within the document itself,\nhowever the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the document instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector, if such a service\nis configured for the collection. Passing this parameter is\nequivalent to providing a `$vectorize` field in the document itself,\nhowever the two are mutually exclusive.\nMoreover, this parameter cannot coexist with `vector`.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the document instead.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "InsertOneResult", "description": "an InsertOneResult object."}], "example": ">>> async def write_and_count(acol: AsyncCollection) -> None:\n... count0 = await acol.count_documents({}, upper_bound=10)\n... print(\"count0\", count0)\n... await acol.insert_one(\n... {\n... \"age\": 30,\n... \"name\": \"Smith\",\n... \"food\": [\"pear\", \"peach\"],\n... \"likes_fruit\": True,\n... },\n... )\n... await acol.insert_one({\"_id\": \"user-123\", \"age\": 50, \"name\": \"Maccio\"})\n... count1 = await acol.count_documents({}, upper_bound=10)\n... print(\"count1\", count1)\n...\n>>> asyncio.run(write_and_count(my_async_coll))\ncount0 0\ncount1 2\n\n>>> asyncio.run(my_async_coll.insert_one({\"tag\": v\", \"$vector\": [10, 11]}))\nInsertOneResult(...)", "note": "If an `_id` is explicitly provided, which corresponds to a document\nthat exists already in the collection, an error is raised and\nthe insertion fails.", "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.results.InsertOneResult"]}} +{"id": "astrapy.collection.AsyncCollection.insert_many", "text": "Returns:\n an InsertManyResult object.", "metadata": {"kind": "function", "name": "insert_many", "path": "astrapy.collection.AsyncCollection.insert_many", "parameters": [{"name": "documents", "type": "Iterable[DocumentType]", "description": "an iterable of dictionaries, each a document to insert.\nDocuments may specify their `_id` field or leave it out, in which\ncase it will be added automatically.", "default": null}, {"name": "vectors", "type": "Iterable[VectorType | None] | None", "description": "an optional list of vectors (as many vectors as the provided\ndocuments) to associate to the documents when inserting.\nPassing vectors this way is indeed equivalent to the \"$vector\" field\nof the documents, however the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the documents instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "Iterable[str | None] | None", "description": "an optional list of strings to be made into as many vectors\n(one per document), if such a service is configured for the collection.\nPassing this parameter is equivalent to providing a `$vectorize`\nfield in the documents themselves, however the two are mutually exclusive.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the documents instead.", "value": "None", "default": "None"}, {"name": "ordered", "type": "bool", "description": "if False (default), the insertions can occur in arbitrary order\nand possibly concurrently. If True, they are processed sequentially.\nIf there are no specific reasons against it, unordered insertions are to\nbe preferred as they complete much faster.", "value": "False", "default": "False"}, {"name": "chunk_size", "type": "int | None", "description": "how many documents to include in a single API request.\nExceeding the server maximum allowed value results in an error.\nLeave it unspecified (recommended) to use the system default.", "value": "None", "default": "None"}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent requests to the API at\na given time. It cannot be more than one for ordered insertions.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nIf many documents are being inserted, this method corresponds\nto several HTTP requests: in such cases one may want to specify\na more tolerant timeout here.", "value": "None", "default": "None"}], "returns": [{"type": "InsertManyResult"}], "example": ">>> async def write_and_count(acol: AsyncCollection) -> None:\n... count0 = await acol.count_documents({}, upper_bound=10)\n... print(\"count0\", count0)\n... im_result1 = await acol.insert_many(\n... [\n... {\"a\": 10},\n... {\"a\": 5},\n... {\"b\": [True, False, False]},\n... ],\n... ordered=True,\n... )\n... print(\"inserted1\", im_result1.inserted_ids)\n... count1 = await acol.count_documents({}, upper_bound=100)\n... print(\"count1\", count1)\n... await acol.insert_many(\n... [{\"seq\": i} for i in range(50)],\n... concurrency=5,\n... )\n... count2 = await acol.count_documents({}, upper_bound=100)\n... print(\"count2\", count2)\n...\n>>> asyncio.run(write_and_count(my_async_coll))\ncount0 0\ninserted1 ['e3c2a684-...', '1de4949f-...', '167dacc3-...']\ncount1 3\ncount2 53\n>>> asyncio.run(my_async_coll.insert_many(\n... [\n... {\"tag\": \"a\", \"$vector\": [1, 2]},\n... {\"tag\": \"b\", \"$vector\": [3, 4]},\n... ]\n... ))\nInsertManyResult(...)", "note": "A failure mode for this command is related to certain faulty documents\nfound among those to insert: a document may have the an `_id` already\npresent on the collection, or its vector dimension may not\nmatch the collection setting.\n\nFor an ordered insertion, the method will raise an exception at\nthe first such faulty document -- nevertheless, all documents processed\nuntil then will end up being written to the database.\n\nFor unordered insertions, if the error stems from faulty documents\nthe insertion proceeds until exhausting the input documents: then,\nan exception is raised -- and all insertable documents will have been\nwritten to the database, including those \"after\" the troublesome ones.\n\nIf, on the other hand, there are errors not related to individual\ndocuments (such as a network connectivity error), the whole\n`insert_many` operation will stop in mid-way, an exception will be raised,\nand only a certain amount of the input documents will\nhave made their way to the database.", "gathered_types": ["astrapy.constants.VectorType", "astrapy.constants.DocumentType", "astrapy.results.InsertManyResult"]}} +{"id": "astrapy.collection.AsyncCollection.find", "text": "Find documents on the collection, matching a certain provided filter.\n\nThe method returns a Cursor that can then be iterated over. Depending\non the method call pattern, the iteration over all documents can reflect\ncollection mutations occurred since the `find` method was called, or not.\nIn cases where the cursor reflects mutations in real-time, it will iterate\nover cursors in an approximate way (i.e. exhibiting occasional skipped\nor duplicate documents). This happens when making use of the `sort`\noption in a non-vector-search manner.", "metadata": {"kind": "function", "name": "find", "path": "astrapy.collection.AsyncCollection.find", "parameters": [{"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "skip", "type": "int | None", "description": "with this integer parameter, what would be the first `skip`\ndocuments returned by the query are discarded, and the results\nstart from the (skip+1)-th document.\nThis parameter can be used only in conjunction with an explicit\n`sort` criterion of the ascending/descending type (i.e. it cannot\nbe used when not sorting, nor with vector-based ANN search).", "value": "None", "default": "None"}, {"name": "limit", "type": "int | None", "description": "this (integer) parameter sets a limit over how many documents\nare returned. Once `limit` is reached (or the cursor is exhausted\nfor lack of matching documents), nothing more is returned.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to perform vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search).\nWhen running similarity search on a collection, no other sorting\ncriteria can be specified. Moreover, there is an upper bound\nto the number of documents that can be returned. For details,\nsee the Note about upper bounds and the Data API documentation.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nThis can be supplied in (exclusive) alternative to `vector`,\nprovided such a service is configured for the collection,\nand achieves the same effect.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool | None", "description": "a boolean to request the numeric value of the\nsimilarity to be returned as an added \"$similarity\" key in each\nreturned document. Can only be used for vector ANN search, i.e.\nwhen either `vector` is supplied or the `sort` parameter has the\nshape {\"$vector\": ...}.", "value": "None", "default": "None"}, {"name": "include_sort_vector", "type": "bool | None", "description": "a boolean to request query vector used in this search.\nIf set to True (and if the invocation is a vector search), calling\nthe `get_sort_vector` method on the returned cursor will yield\nthe vector used for the ANN search.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the order\nthe documents are returned. See the Note about sorting, as well as\nthe one about upper bounds, for details.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for each single one\nof the underlying HTTP requests used to fetch documents as the\ncursor is iterated over.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncCursor", "description": "an AsyncCursor object representing iterations over the matching documents"}, {"type": "AsyncCursor", "description": "(see the AsyncCursor object for how to use it. The simplest thing is to"}, {"type": "AsyncCursor", "description": "run a for loop: `for document in collection.sort(...):`)."}], "example": ">>> async def run_finds(acol: AsyncCollection) -> None:\n... filter = {\"seq\": {\"$exists\": True}}\n... print(\"find results 1:\")\n... async for doc in acol.find(filter, projection={\"seq\": True}, limit=5):\n... print(doc[\"seq\"])\n... async_cursor1 = acol.find(\n... {},\n... limit=4,\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\n... ids = [doc[\"_id\"] async for doc in async_cursor1]\n... print(\"find results 2:\", ids)\n... async_cursor2 = acol.find({}, limit=3)\n... seqs = await async_cursor2.distinct(\"seq\")\n... print(\"distinct results 3:\", seqs)\n...\n>>> asyncio.run(run_finds(my_async_coll))\nfind results 1:\n48\n35\n7\n11\n13\nfind results 2: ['d656cd9d-...', '479c7ce8-...', '96dc87fd-...', '83f0a21f-...']\ndistinct results 3: [48, 35, 7]/n/n/n>>> async def run_vector_finds(acol: AsyncCollection) -> None:\n... await acol.insert_many([\n... {\"tag\": \"A\", \"$vector\": [4, 5]},\n... {\"tag\": \"B\", \"$vector\": [3, 4]},\n... {\"tag\": \"C\", \"$vector\": [3, 2]},\n... {\"tag\": \"D\", \"$vector\": [4, 1]},\n... {\"tag\": \"E\", \"$vector\": [2, 5]},\n... ])\n... ann_tags = [\n... document[\"tag\"]\n... async for document in acol.find(\n... {},\n... sort={\"$vector\": [3, 3]},\n... limit=3,\n... )\n... ]\n... return ann_tags\n...\n>>> asyncio.run(run_vector_finds(my_async_coll))\n['A', 'B', 'C']\n>>> # (assuming the collection has metric VectorMetric.COSINE)/n/n/n>>> async_cursor = my_async_coll.find(\n... sort={\"$vector\": [3, 3]},\n... limit=3,\n... include_sort_vector=True,\n... )\n>>> asyncio.run(async_cursor.get_sort_vector())\n[3.0, 3.0]\n>>> asyncio.run(async_cursor.__anext__())\n{'_id': 'b13ce177-738e-47ec-bce1-77738ee7ec93', 'tag': 'A'}\n>>> asyncio.run(async_cursor.get_sort_vector())\n[3.0, 3.0]", "note": "When not specifying sorting criteria at all (by vector or otherwise),\nthe cursor can scroll through an arbitrary number of documents as\nthe Data API and the client periodically exchange new chunks of documents.\nIt should be noted that the behavior of the cursor in the case documents\nhave been added/removed after the `find` was started depends on database\ninternals and it is not guaranteed, nor excluded, that such \"real-time\"\nchanges in the data would be picked up by the cursor.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.constants.ProjectionType", "astrapy.cursors.AsyncCursor"]}} +{"id": "astrapy.collection.AsyncCollection.find_one", "text": "Run a search, returning the first document in the collection that matches\nprovided filters, if any is found.", "metadata": {"kind": "function", "name": "find_one", "path": "astrapy.collection.AsyncCollection.find_one", "parameters": [{"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to perform vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), extracting the most\nsimilar document in the collection matching the filter.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool | None", "description": "a boolean to request the numeric value of the\nsimilarity to be returned as an added \"$similarity\" key in the\nreturned document. Can only be used for vector ANN search, i.e.\nwhen either `vector` is supplied or the `sort` parameter has the\nshape {\"$vector\": ...}.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the order\nthe documents are returned. See the Note about sorting for details.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "a dictionary expressing the required document, otherwise None."}], "example": ">>> async def demo_find_one(acol: AsyncCollection) -> None:\n.... print(\"Count:\", await acol.count_documents({}, upper_bound=100))\n... result0 = await acol.find_one({})\n... print(\"result0\", result0)\n... result1 = await acol.find_one({\"seq\": 10})\n... print(\"result1\", result1)\n... result2 = await acol.find_one({\"seq\": 1011})\n... print(\"result2\", result2)\n... result3 = await acol.find_one({}, projection={\"seq\": False})\n... print(\"result3\", result3)\n... result4 = await acol.find_one(\n... {},\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\n... print(\"result4\", result4)\n...\n>>>\n>>> asyncio.run(demo_find_one(my_async_coll))\nCount: 50\nresult0 {'_id': '479c7ce8-...', 'seq': 48}\nresult1 {'_id': '93e992c4-...', 'seq': 10}\nresult2 None\nresult3 {'_id': '479c7ce8-...'}\nresult4 {'_id': 'd656cd9d-...', 'seq': 49}\n\n>>> asyncio.run(my_async_coll.find_one(\n... {},\n... sort={\"$vector\": [1, 0]},\n... projection={\"*\": True},\n... ))\n{'_id': '...', 'tag': 'D', '$vector': [4.0, 1.0]}", "note": "See the `find` method for more details on the accepted parameters\n(whereas `skip` and `limit` are not valid parameters for `find_one`).", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.AsyncCollection.distinct", "text": "Return a list of the unique values of `key` across the documents\nin the collection that match the provided filter.", "metadata": {"kind": "function", "name": "distinct", "path": "astrapy.collection.AsyncCollection.distinct", "parameters": [{"name": "key", "type": "str", "description": "the name of the field whose value is inspected across documents.\nKeys can use dot-notation to descend to deeper document levels.\nExample of acceptable `key` values:\n \"field\"\n \"field.subfield\"\n \"field.3\"\n \"field.3.subfield\"\nIf lists are encountered and no numeric index is specified,\nall items in the list are visited.", "default": null}, {"name": "filter", "type": "FilterType | None", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, with the same meaning as for `find`.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "list[Any]", "description": "a list of all different values for `key` found across the documents"}, {"type": "list[Any]", "description": "that match the filter. The result list has no repeated items."}], "example": ">>> async def run_distinct(acol: AsyncCollection) -> None:\n... await acol.insert_many(\n... [\n... {\"name\": \"Marco\", \"food\": [\"apple\", \"orange\"], \"city\": \"Helsinki\"},\n... {\"name\": \"Emma\", \"food\": {\"likes_fruit\": True, \"allergies\": []}},\n... ]\n... )\n... distinct0 = await acol.distinct(\"name\")\n... print(\"distinct('name')\", distinct0)\n... distinct1 = await acol.distinct(\"city\")\n... print(\"distinct('city')\", distinct1)\n... distinct2 = await acol.distinct(\"food\")\n... print(\"distinct('food')\", distinct2)\n... distinct3 = await acol.distinct(\"food.1\")\n... print(\"distinct('food.1')\", distinct3)\n... distinct4 = await acol.distinct(\"food.allergies\")\n... print(\"distinct('food.allergies')\", distinct4)\n... distinct5 = await acol.distinct(\"food.likes_fruit\")\n... print(\"distinct('food.likes_fruit')\", distinct5)\n...\n>>> asyncio.run(run_distinct(my_async_coll))\ndistinct('name') ['Emma', 'Marco']\ndistinct('city') ['Helsinki']\ndistinct('food') [{'likes_fruit': True, 'allergies': []}, 'apple', 'orange']\ndistinct('food.1') ['orange']\ndistinct('food.allergies') []\ndistinct('food.likes_fruit') [True]", "note": "For details on the behaviour of \"distinct\" in conjunction with\nreal-time changes in the collection contents, see the\nNote of the `find` command.", "gathered_types": ["astrapy.constants.FilterType"]}} +{"id": "astrapy.collection.AsyncCollection.count_documents", "text": "Count the documents in the collection matching the specified filter.", "metadata": {"kind": "function", "name": "count_documents", "path": "astrapy.collection.AsyncCollection.count_documents", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "upper_bound", "type": "int", "description": "a required ceiling on the result of the count operation.\nIf the actual number of documents exceeds this value,\nan exception will be raised.\nFurthermore, if the actual number of documents exceeds the maximum\ncount that the Data API can reach (regardless of upper_bound),\nan exception will be raised.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "int", "description": "the exact count of matching documents."}], "example": ">>> async def do_count_docs(acol: AsyncCollection) -> None:\n... await acol.insert_many([{\"seq\": i} for i in range(20)])\n... count0 = await acol.count_documents({}, upper_bound=100)\n... print(\"count0\", count0)\n... count1 = await acol.count_documents({\"seq\":{\"$gt\": 15}}, upper_bound=100)\n... print(\"count1\", count1)\n... count2 = await acol.count_documents({}, upper_bound=10)\n... print(\"count2\", count2)\n...\n>>> asyncio.run(do_count_docs(my_async_coll))\ncount0 20\ncount1 4\nTraceback (most recent call last):\n ... ...\nastrapy.exceptions.TooManyDocumentsToCountException", "note": "Count operations are expensive: for this reason, the best practice\nis to provide a reasonable `upper_bound` according to the caller\nexpectations. Moreover, indiscriminate usage of count operations\nfor sizeable amounts of documents (i.e. in the thousands and more)\nis discouraged in favor of alternative application-specific solutions.\nKeep in mind that the Data API has a hard upper limit on the amount\nof documents it will count, and that an exception will be thrown\nby this method if this limit is encountered.", "gathered_types": ["astrapy.constants.FilterType"]}} +{"id": "astrapy.collection.AsyncCollection.estimated_document_count", "text": "Query the API server for an estimate of the document count in the collection.\n\nContrary to `count_documents`, this method has no filtering parameters.", "metadata": {"kind": "function", "name": "estimated_document_count", "path": "astrapy.collection.AsyncCollection.estimated_document_count", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "int", "description": "a server-provided estimate count of the documents in the collection."}], "example": ">>> asyncio.run(my_async_coll.estimated_document_count())\n35700"}} +{"id": "astrapy.collection.AsyncCollection.find_one_and_replace", "text": "Find a document on the collection and replace it entirely with a new one,\noptionally inserting a new one if no match is found.\n\nArgs:\n\n filter: a predicate expressed as a dictionary according to the\n Data API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\n See the Data API documentation for the full set of operators.\n replacement: the new document to write into the collection.\n projection: it controls which parts of the document are returned.\n It can be an allow-list: `{\"f1\": True, \"f2\": True}`,\n or a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n (except for the `_id` and other special fields, which can be\n associated to both True or False independently of the rest\n of the specification).\n The special star-projections `{\"*\": True}` and `{\"*\": False}`\n have the effect of returning the whole document and `{}` respectively.\n For lists in documents, slice directives can be passed to select\n portions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n `{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n `{\"array\": {\"$slice\": [-4, 2]}}`.\n An iterable over strings will be treated implicitly as an allow-list.\n The default projection (used if this parameter is not passed) does not\n necessarily include \"special\" fields such as `$vector` or `$vectorize`.\n See the Data API documentation for more on projections.\n vector: a suitable vector, i.e. a list of float numbers of the appropriate\n dimensionality, to use vector search (i.e. ANN,\n or \"approximate nearest-neighbours\" search), as the sorting criterion.\n In this way, the matched document (if any) will be the one\n that is most similar to the provided vector.\n *DEPRECATED* (removal in 2.0). Use a `$vector` key in the\n sort clause dict instead.\n vectorize: a string to be made into a vector to perform vector search.\n Using vectorize assumes a suitable service is configured for the collection.\n *DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\n sort clause dict instead.\n sort: with this dictionary parameter one can control the sorting\n order of the documents matching the filter, effectively\n determining what document will come first and hence be the\n replaced one. See the `find` method for more on sorting.\n Vector-based ANN sorting is achieved by providing a \"$vector\"\n or a \"$vectorize\" key in `sort`.\n upsert: this parameter controls the behavior in absence of matches.\n If True, `replacement` is inserted as a new document\n if no matches are found on the collection. If False,\n the operation silently does nothing in case of no matches.\n return_document: a flag controlling what document is returned:\n if set to `ReturnDocument.BEFORE`, or the string \"before\",\n the document found on database is returned; if set to\n `ReturnDocument.AFTER`, or the string \"after\", the new\n document is returned. The default is \"before\".\n max_time_ms: a timeout, in milliseconds, for the underlying HTTP request.\n If not passed, the collection-level setting is used instead.", "metadata": {"kind": "function", "name": "find_one_and_replace", "path": "astrapy.collection.AsyncCollection.find_one_and_replace", "parameters": [{"name": "filter", "type": "FilterType"}, {"name": "replacement", "type": "DocumentType"}, {"name": "projection", "default": "None", "type": "ProjectionType | None"}, {"name": "vector", "default": "None", "type": "VectorType | None"}, {"name": "vectorize", "default": "None", "type": "str | None"}, {"name": "sort", "default": "None", "type": "SortType | None"}, {"name": "upsert", "default": "False", "type": "bool"}, {"name": "return_document", "default": "ReturnDocument.BEFORE", "type": "str"}, {"name": "max_time_ms", "default": "None", "type": "int | None"}], "returns": [{"type": "DocumentType | None", "description": "A document, either the one before the replace operation or the"}, {"type": "DocumentType | None", "description": "one after that. Alternatively, the method returns None to represent"}, {"type": "DocumentType | None", "description": "that no matching document was found, or that no replacement"}, {"type": "DocumentType | None", "description": "was inserted (depending on the `return_document` parameter)."}], "example": ">>> async def do_find_one_and_replace(acol: AsyncCollection) -> None:\n... await acol.insert_one({\"_id\": \"rule1\", \"text\": \"all animals are equal\"})\n... result0 = await acol.find_one_and_replace(\n... {\"_id\": \"rule1\"},\n... {\"text\": \"some animals are more equal!\"},\n... )\n... print(\"result0\", result0)\n... result1 = await acol.find_one_and_replace(\n... {\"text\": \"some animals are more equal!\"},\n... {\"text\": \"and the pigs are the rulers\"},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n... print(\"result1\", result1)\n... result2 = await acol.find_one_and_replace(\n... {\"_id\": \"rule2\"},\n... {\"text\": \"F=ma^2\"},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n... print(\"result2\", result2)\n... result3 = await acol.find_one_and_replace(\n... {\"_id\": \"rule2\"},\n... {\"text\": \"F=ma\"},\n... upsert=True,\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... projection={\"_id\": False},\n... )\n... print(\"result3\", result3)\n...\n>>> asyncio.run(do_find_one_and_replace(my_async_coll))\nresult0 {'_id': 'rule1', 'text': 'all animals are equal'}\nresult1 {'_id': 'rule1', 'text': 'and the pigs are the rulers'}\nresult2 None\nresult3 {'text': 'F=ma'}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.ReturnDocument", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "BEFORE", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.AsyncCollection.replace_one", "text": "Replace a single document on the collection with a new one,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "replace_one", "path": "astrapy.collection.AsyncCollection.replace_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "replacement", "type": "DocumentType", "description": "the new document to write into the collection.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, `replacement` is inserted as a new document\nif no matches are found on the collection. If False,\nthe operation silently does nothing in case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the replace operation."}], "example": ">>> async def do_replace_one(acol: AsyncCollection) -> None:\n... await acol.insert_one({\"Marco\": \"Polo\"})\n... result0 = await acol.replace_one(\n... {\"Marco\": {\"$exists\": True}},\n... {\"Buda\": \"Pest\"},\n... )\n... print(\"result0.update_info\", result0.update_info)\n... doc1 = await acol.find_one({\"Buda\": \"Pest\"})\n... print(\"doc1\", doc1)\n... result1 = await acol.replace_one(\n... {\"Mirco\": {\"$exists\": True}},\n... {\"Oh\": \"yeah?\"},\n... )\n... print(\"result1.update_info\", result1.update_info)\n... result2 = await acol.replace_one(\n... {\"Mirco\": {\"$exists\": True}},\n... {\"Oh\": \"yeah?\"},\n... upsert=True,\n... )\n... print(\"result2.update_info\", result2.update_info)\n...\n>>> asyncio.run(do_replace_one(my_async_coll))\nresult0.update_info {'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1}\ndoc1 {'_id': '6e669a5a-...', 'Buda': 'Pest'}\nresult1.update_info {'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0}\nresult2.update_info {'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '30e34e00-...'}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.results.UpdateResult", "astrapy.constants.VectorType"]}} +{"id": "astrapy.collection.AsyncCollection.find_one_and_update", "text": "Find a document on the collection and update it as requested,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "find_one_and_update", "path": "astrapy.collection.AsyncCollection.find_one_and_update", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the document, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a new document (resulting from applying the `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "return_document", "type": "str", "description": "a flag controlling what document is returned:\nif set to `ReturnDocument.BEFORE`, or the string \"before\",\nthe document found on database is returned; if set to\n`ReturnDocument.AFTER`, or the string \"after\", the new\ndocument is returned. The default is \"before\".", "value": "ReturnDocument.BEFORE", "default": "ReturnDocument.BEFORE"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "A document (or a projection thereof, as required), either the one"}, {"type": "DocumentType | None", "description": "before the replace operation or the one after that."}, {"type": "DocumentType | None", "description": "Alternatively, the method returns None to represent"}, {"type": "DocumentType | None", "description": "that no matching document was found, or that no update"}, {"type": "DocumentType | None", "description": "was applied (depending on the `return_document` parameter)."}], "example": ">>> async def do_find_one_and_update(acol: AsyncCollection) -> None:\n... await acol.insert_one({\"Marco\": \"Polo\"})\n... result0 = await acol.find_one_and_update(\n... {\"Marco\": {\"$exists\": True}},\n... {\"$set\": {\"title\": \"Mr.\"}},\n... )\n... print(\"result0\", result0)\n... result1 = await acol.find_one_and_update(\n... {\"title\": \"Mr.\"},\n... {\"$inc\": {\"rank\": 3}},\n... projection=[\"title\", \"rank\"],\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n... print(\"result1\", result1)\n... result2 = await acol.find_one_and_update(\n... {\"name\": \"Johnny\"},\n... {\"$set\": {\"rank\": 0}},\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n... print(\"result2\", result2)\n... result3 = await acol.find_one_and_update(\n... {\"name\": \"Johnny\"},\n... {\"$set\": {\"rank\": 0}},\n... upsert=True,\n... return_document=astrapy.constants.ReturnDocument.AFTER,\n... )\n... print(\"result3\", result3)\n...\n>>> asyncio.run(do_find_one_and_update(my_async_coll))\nresult0 {'_id': 'f7c936d3-b0a0-45eb-a676-e2829662a57c', 'Marco': 'Polo'}\nresult1 {'_id': 'f7c936d3-b0a0-45eb-a676-e2829662a57c', 'title': 'Mr.', 'rank': 3}\nresult2 None\nresult3 {'_id': 'db3d678d-14d4-4caa-82d2-d5fb77dab7ec', 'name': 'Johnny', 'rank': 0}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.ReturnDocument", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "BEFORE", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.AsyncCollection.update_one", "text": "Update a single document on the collection as requested,\noptionally inserting a new one if no match is found.", "metadata": {"kind": "function", "name": "update_one", "path": "astrapy.collection.AsyncCollection.update_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the document, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a new document (resulting from applying the `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the update operation."}], "example": ">>> async def do_update_one(acol: AsyncCollection) -> None:\n... await acol.insert_one({\"Marco\": \"Polo\"})\n... result0 = await acol.update_one(\n... {\"Marco\": {\"$exists\": True}},\n... {\"$inc\": {\"rank\": 3}},\n... )\n... print(\"result0.update_info\", result0.update_info)\n... result1 = await acol.update_one(\n... {\"Mirko\": {\"$exists\": True}},\n... {\"$inc\": {\"rank\": 3}},\n... )\n... print(\"result1.update_info\", result1.update_info)\n... result2 = await acol.update_one(\n... {\"Mirko\": {\"$exists\": True}},\n... {\"$inc\": {\"rank\": 3}},\n... upsert=True,\n... )\n... print(\"result2.update_info\", result2.update_info)\n...\n>>> asyncio.run(do_update_one(my_async_coll))\nresult0.update_info {'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1})\nresult1.update_info {'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0})\nresult2.update_info {'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '75748092-...'}", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.results.UpdateResult"]}} +{"id": "astrapy.collection.AsyncCollection.update_many", "text": "Apply an update operations to all documents matching a condition,\noptionally inserting one documents in absence of matches.", "metadata": {"kind": "function", "name": "update_many", "path": "astrapy.collection.AsyncCollection.update_many", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "update", "type": "dict[str, Any]", "description": "the update prescription to apply to the documents, expressed\nas a dictionary as per Data API syntax. Examples are:\n {\"$set\": {\"field\": \"value}}\n {\"$inc\": {\"counter\": 10}}\n {\"$unset\": {\"field\": \"\"}}\nSee the Data API documentation for the full syntax.", "default": null}, {"name": "upsert", "type": "bool", "description": "this parameter controls the behavior in absence of matches.\nIf True, a single new document (resulting from applying `update`\nto an empty document) is inserted if no matches are found on\nthe collection. If False, the operation silently does nothing\nin case of no matches.", "value": "False", "default": "False"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nif a large number of document updates is anticipated, it is suggested\nto specify a larger timeout than in most other operations as the\nupdate will span several HTTP calls to the API in sequence.", "value": "None", "default": "None"}], "returns": [{"type": "UpdateResult", "description": "an UpdateResult object summarizing the outcome of the update operation."}], "example": ">>> async def do_update_many(acol: AsyncCollection) -> None:\n... await acol.insert_many([{\"c\": \"red\"}, {\"c\": \"green\"}, {\"c\": \"blue\"}])\n... result0 = await acol.update_many(\n... {\"c\": {\"$ne\": \"green\"}},\n... {\"$set\": {\"nongreen\": True}},\n... )\n... print(\"result0.update_info\", result0.update_info)\n... result1 = await acol.update_many(\n... {\"c\": \"orange\"},\n... {\"$set\": {\"is_also_fruit\": True}},\n... )\n... print(\"result1.update_info\", result1.update_info)\n... result2 = await acol.update_many(\n... {\"c\": \"orange\"},\n... {\"$set\": {\"is_also_fruit\": True}},\n... upsert=True,\n... )\n... print(\"result2.update_info\", result2.update_info)\n...\n>>> asyncio.run(do_update_many(my_async_coll))\nresult0.update_info {'n': 2, 'updatedExisting': True, 'ok': 1.0, 'nModified': 2}\nresult1.update_info {'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0}\nresult2.update_info {'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '79ffd5a3-ab99-4dff-a2a5-4aaa0e59e854'}", "note": "Similarly to the case of `find` (see its docstring for more details),\nrunning this command while, at the same time, another process is\ninserting new documents which match the filter of the `update_many`\ncan result in an unpredictable fraction of these documents being updated.\nIn other words, it cannot be easily predicted whether a given\nnewly-inserted document will be picked up by the update_many command or not.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.results.UpdateResult"]}} +{"id": "astrapy.collection.AsyncCollection.find_one_and_delete", "text": "Find a document in the collection and delete it. The deleted document,\nhowever, is the return value of the method.", "metadata": {"kind": "function", "name": "find_one_and_delete", "path": "astrapy.collection.AsyncCollection.find_one_and_delete", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "projection", "type": "ProjectionType | None", "description": "it controls which parts of the document are returned.\nIt can be an allow-list: `{\"f1\": True, \"f2\": True}`,\nor a deny-list: `{\"fx\": False, \"fy\": False}`, but not a mixture\n(except for the `_id` and other special fields, which can be\nassociated to both True or False independently of the rest\nof the specification).\nThe special star-projections `{\"*\": True}` and `{\"*\": False}`\nhave the effect of returning the whole document and `{}` respectively.\nFor lists in documents, slice directives can be passed to select\nportions of the list: for instance, `{\"array\": {\"$slice\": 2}}`,\n`{\"array\": {\"$slice\": -2}}`, `{\"array\": {\"$slice\": [4, 2]}}` or\n`{\"array\": {\"$slice\": [-4, 2]}}`.\nAn iterable over strings will be treated implicitly as an allow-list.\nThe default projection (used if this parameter is not passed) does not\nnecessarily include \"special\" fields such as `$vector` or `$vectorize`.\nSee the Data API documentation for more on projections.", "value": "None", "default": "None"}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DocumentType | None", "description": "Either the document (or a projection thereof, as requested), or None"}, {"type": "DocumentType | None", "description": "if no matches were found in the first place."}], "example": ">>> async def do_find_one_and_delete(acol: AsyncCollection) -> None:\n... await acol.insert_many(\n... [\n... {\"species\": \"swan\", \"class\": \"Aves\"},\n... {\"species\": \"frog\", \"class\": \"Amphibia\"},\n... ],\n... )\n... delete_result0 = await acol.find_one_and_delete(\n... {\"species\": {\"$ne\": \"frog\"}},\n... projection=[\"species\"],\n... )\n... print(\"delete_result0\", delete_result0)\n... delete_result1 = await acol.find_one_and_delete(\n... {\"species\": {\"$ne\": \"frog\"}},\n... )\n... print(\"delete_result1\", delete_result1)\n...\n>>> asyncio.run(do_find_one_and_delete(my_async_coll))\ndelete_result0 {'_id': 'f335cd0f-...', 'species': 'swan'}\ndelete_result1 None", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.DocumentType", "astrapy.constants.VectorType", "astrapy.constants.ProjectionType"]}} +{"id": "astrapy.collection.AsyncCollection.delete_one", "text": "Delete one document matching a provided filter.\nThis method never deletes more than a single document, regardless\nof the number of matches to the provided filters.", "metadata": {"kind": "function", "name": "delete_one", "path": "astrapy.collection.AsyncCollection.delete_one", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.", "default": null}, {"name": "vector", "type": "VectorType | None", "description": "a suitable vector, i.e. a list of float numbers of the appropriate\ndimensionality, to use vector search (i.e. ANN,\nor \"approximate nearest-neighbours\" search), as the sorting criterion.\nIn this way, the matched document (if any) will be the one\nthat is most similar to the provided vector.\n*DEPRECATED* (removal in 2.0). Use a `$vector` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "vectorize", "type": "str | None", "description": "a string to be made into a vector to perform vector search.\nUsing vectorize assumes a suitable service is configured for the collection.\n*DEPRECATED* (removal in 2.0). Use a `$vectorize` key in the\nsort clause dict instead.", "value": "None", "default": "None"}, {"name": "sort", "type": "SortType | None", "description": "with this dictionary parameter one can control the sorting\norder of the documents matching the filter, effectively\ndetermining what document will come first and hence be the\nreplaced one. See the `find` method for more on sorting.\nVector-based ANN sorting is achieved by providing a \"$vector\"\nor a \"$vectorize\" key in `sort`.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "DeleteResult", "description": "a DeleteResult object summarizing the outcome of the delete operation."}], "example": ">>> my_coll.insert_many([{\"seq\": 1}, {\"seq\": 0}, {\"seq\": 2}])\nInsertManyResult(...)\n>>> my_coll.delete_one({\"seq\": 1})\nDeleteResult(raw_results=..., deleted_count=1)\n>>> my_coll.distinct(\"seq\")\n[0, 2]\n>>> my_coll.delete_one(\n... {\"seq\": {\"$exists\": True}},\n... sort={\"seq\": astrapy.constants.SortDocuments.DESCENDING},\n... )\nDeleteResult(raw_results=..., deleted_count=1)\n>>> my_coll.distinct(\"seq\")\n[0]\n>>> my_coll.delete_one({\"seq\": 2})\nDeleteResult(raw_results=..., deleted_count=0)", "gathered_types": ["astrapy.constants.FilterType", "astrapy.constants.SortType", "astrapy.constants.VectorType", "astrapy.results.DeleteResult"]}} +{"id": "astrapy.collection.AsyncCollection.delete_many", "text": "Delete all documents matching a provided filter.", "metadata": {"kind": "function", "name": "delete_many", "path": "astrapy.collection.AsyncCollection.delete_many", "parameters": [{"name": "filter", "type": "FilterType", "description": "a predicate expressed as a dictionary according to the\nData API filter syntax. Examples are:\n {}\n {\"name\": \"John\"}\n {\"price\": {\"$lt\": 100}}\n {\"$and\": [{\"name\": \"John\"}, {\"price\": {\"$lt\": 100}}]}\nSee the Data API documentation for the full set of operators.\nPassing an empty filter, `{}`, completely erases all contents\nof the collection.", "default": null}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the operation.\nIf not passed, the collection-level setting is used instead:\nkeep in mind that this method entails successive HTTP requests\nto the API, depending on how many documents are to be deleted.\nFor this reason, in most cases it is suggested to relax the\ntimeout compared to other method calls.", "value": "None", "default": "None"}], "returns": [{"type": "DeleteResult", "description": "a DeleteResult object summarizing the outcome of the delete operation."}], "example": ">>> async def do_delete_many(acol: AsyncCollection) -> None:\n... await acol.insert_many([{\"seq\": 1}, {\"seq\": 0}, {\"seq\": 2}])\n... delete_result0 = await acol.delete_many({\"seq\": {\"$lte\": 1}})\n... print(\"delete_result0.deleted_count\", delete_result0.deleted_count)\n... distinct1 = await acol.distinct(\"seq\")\n... print(\"distinct1\", distinct1)\n... delete_result2 = await acol.delete_many({\"seq\": {\"$lte\": 1}})\n... print(\"delete_result2.deleted_count\", delete_result2.deleted_count)\n...\n>>> asyncio.run(do_delete_many(my_async_coll))\ndelete_result0.deleted_count 2\ndistinct1 [2]\ndelete_result2.deleted_count 0", "note": "This operation is in general not atomic. Depending on the amount\nof matching documents, it can keep running (in a blocking way)\nfor a macroscopic time. In that case, new documents that are\nmeanwhile inserted (e.g. from another process/application) will be\ndeleted during the execution of this method call until the\ncollection is devoid of matches.\nAn exception is the `filter={}` case, whereby the operation is atomic.", "gathered_types": ["astrapy.constants.FilterType", "astrapy.results.DeleteResult"]}} +{"id": "astrapy.collection.AsyncCollection.delete_all", "text": "Delete all documents in a collection.", "metadata": {"kind": "function", "name": "delete_all", "path": "astrapy.collection.AsyncCollection.delete_all", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary of the form {\"ok\": 1} to signal successful deletion."}], "example": ">>> async def do_delete_all(acol: AsyncCollection) -> None:\n... distinct0 = await acol.distinct(\"seq\")\n... print(\"distinct0\", distinct0)\n... count1 = await acol.count_documents({}, upper_bound=100)\n... print(\"count1\", count1)\n... delete_result2 = await acol.delete_all()\n... print(\"delete_result2\", delete_result2)\n... count3 = await acol.count_documents({}, upper_bound=100)\n... print(\"count3\", count3)\n...\n>>> asyncio.run(do_delete_all(my_async_coll))\ndistinct0 [4, 2, 3, 0, 1]\ncount1 5\ndelete_result2 {'ok': 1}\ncount3 0", "note": "Use with caution."}} +{"id": "astrapy.collection.AsyncCollection.bulk_write", "text": "Execute an arbitrary amount of operations such as inserts, updates, deletes\neither sequentially or concurrently.\n\nThis method does not execute atomically, i.e. individual operations are\neach performed in the same way as the corresponding collection method,\nand each one is a different and unrelated database mutation.", "metadata": {"kind": "function", "name": "bulk_write", "path": "astrapy.collection.AsyncCollection.bulk_write", "parameters": [{"name": "requests", "type": "Iterable[AsyncBaseOperation]", "description": "an iterable over concrete subclasses of `BaseOperation`,\nsuch as `AsyncInsertMany` or `AsyncReplaceOne`. Each such object\nrepresents an operation ready to be executed on a collection,\nand is instantiated by passing the same parameters as one\nwould the corresponding collection method.", "default": null}, {"name": "ordered", "type": "bool", "description": "whether to launch the `requests` one after the other or\nin arbitrary order, possibly in a concurrent fashion. For\nperformance reasons, False (default) should be preferred\nwhen compatible with the needs of the application flow.", "value": "False", "default": "False"}, {"name": "concurrency", "type": "int | None", "description": "maximum number of concurrent operations executing at\na given time. It cannot be more than one for ordered bulk writes.", "value": "None", "default": "None"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the whole bulk write.\nRemember that, if the method call times out, then there's no\nguarantee about what portion of the bulk write has been received\nand successfully executed by the Data API.\nIf not passed, the collection-level setting is used instead:\nin most cases, however, one should pass a relaxed timeout\nif longer sequences of operations are to be executed in bulk.", "value": "None", "default": "None"}], "returns": [{"type": "BulkWriteResult", "description": "A single BulkWriteResult summarizing the whole list of requested"}, {"type": "BulkWriteResult", "description": "operations. The keys in the map attributes of BulkWriteResult"}, {"type": "BulkWriteResult", "description": "(when present) are the integer indices of the corresponding operation"}, {"type": "BulkWriteResult", "description": "in the `requests` iterable."}], "example": ">>> from astrapy.operations import AsyncInsertMany, AsyncReplaceOne, AsyncOperation\n>>> from astrapy.results import BulkWriteResult\n>>>\n>>> async def do_bulk_write(\n... acol: AsyncCollection,\n... async_operations: List[AsyncOperation],\n... ) -> BulkWriteResult:\n... bw_result = await acol.bulk_write(async_operations)\n... count0 = await acol.count_documents({}, upper_bound=100)\n... print(\"count0\", count0)\n... distinct0 = await acol.distinct(\"replaced\")\n... print(\"distinct0\", distinct0)\n... return bw_result\n...\n>>> op1 = AsyncInsertMany([{\"a\": 1}, {\"a\": 2}])\n>>> op2 = AsyncReplaceOne(\n... {\"z\": 9},\n... replacement={\"z\": 9, \"replaced\": True},\n... upsert=True,\n... )\n>>> result = asyncio.run(do_bulk_write(my_async_coll, [op1, op2]))\ncount0 3\ndistinct0 [True]\n>>> print(\"result\", result)\nresult BulkWriteResult(bulk_api_results={0: ..., 1: ...}, deleted_count=0, inserted_count=3, matched_count=0, modified_count=0, upserted_count=1, upserted_ids={1: 'ccd0a800-...'})", "references": ["astrapy.results.BulkWriteResult", "astrapy.operations.AsyncReplaceOne", "astrapy.operations.AsyncInsertMany", "astrapy.operations.AsyncOperation"], "gathered_types": ["astrapy.operations.AsyncBaseOperation", "astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.collection.AsyncCollection.drop", "text": "Drop the collection, i.e. delete it from the database along with\nall the documents it contains.", "metadata": {"kind": "function", "name": "drop", "path": "astrapy.collection.AsyncCollection.drop", "parameters": [{"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.\nRemember there is not guarantee that a request that has\ntimed out us not in fact honored.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary of the form {\"ok\": 1} to signal successful deletion."}], "example": ">>> async def drop_and_check(acol: AsyncCollection) -> None:\n... doc0 = await acol.find_one({})\n... print(\"doc0\", doc0)\n... drop_result = await acol.drop()\n... print(\"drop_result\", drop_result)\n... doc1 = await acol.find_one({})\n...\n>>> asyncio.run(drop_and_check(my_async_coll))\ndoc0 {'_id': '...', 'z': -10}\ndrop_result {'ok': 1}\nTraceback (most recent call last):\n ... ...\nastrapy.exceptions.DataAPIResponseException: Collection does not exist, collection name: my_collection", "note": "Once the method succeeds, methods on this object can still be invoked:\nhowever, this hardly makes sense as the underlying actual collection\nis no more.\nIt is responsibility of the developer to design a correct flow\nwhich avoids using a deceased collection any further."}} +{"id": "astrapy.collection.AsyncCollection.command", "text": "Send a POST request to the Data API for this collection with\nan arbitrary, caller-provided payload.", "metadata": {"kind": "function", "name": "command", "path": "astrapy.collection.AsyncCollection.command", "parameters": [{"name": "body", "type": "dict[str, Any]", "description": "a JSON-serializable dictionary, the payload of the request.", "default": null}, {"name": "raise_api_errors", "type": "bool", "description": "if True, responses with a nonempty 'errors' field\nresult in an astrapy exception being raised.", "value": "True", "default": "True"}, {"name": "max_time_ms", "type": "int | None", "description": "a timeout, in milliseconds, for the underlying HTTP request.\nIf not passed, the collection-level setting is used instead.", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, Any]", "description": "a dictionary with the response of the HTTP request."}], "example": ">>> asyncio.await(my_async_coll.command({\"countDocuments\": {}}))\n{'status': {'count': 123}}"}} +{"id": "astrapy.exceptions", "text": "", "metadata": {"kind": "module", "name": "exceptions", "path": "astrapy.exceptions", "imports": {"annotations": "__future__.annotations", "time": "time", "dataclass": "dataclasses.dataclass", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "httpx": "httpx", "TimeoutInfo": "astrapy.request_tools.TimeoutInfo", "BulkWriteResult": "astrapy.results.BulkWriteResult", "DeleteResult": "astrapy.results.DeleteResult", "InsertManyResult": "astrapy.results.InsertManyResult", "OperationResult": "astrapy.results.OperationResult", "UpdateResult": "astrapy.results.UpdateResult"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.exceptions.DevOpsAPIException", "text": "An exception specific to issuing requests to the DevOps API.", "metadata": {"kind": "class", "name": "DevOpsAPIException", "path": "astrapy.exceptions.DevOpsAPIException", "parameters": [{"name": "text", "default": "''", "type": "str"}], "bases": ["ValueError"], "gathered_types": ["ValueError"], "implemented_by": ["astrapy.exceptions.DevOpsAPIFaultyResponseException", "astrapy.exceptions.DevOpsAPIResponseException", "astrapy.exceptions.DevOpsAPITimeoutException", "astrapy.exceptions.DevOpsAPIHttpException"]}} +{"id": "astrapy.exceptions.DevOpsAPIHttpException", "text": "A request to the DevOps API resulted in an HTTP 4xx or 5xx response.\n\nThough the DevOps API seldom enriches such errors with a response text,\nthis class acts as the DevOps counterpart to DataAPIHttpException\nto facilitate a symmetryc handling of errors at application lebel.", "metadata": {"kind": "class", "name": "DevOpsAPIHttpException", "path": "astrapy.exceptions.DevOpsAPIHttpException", "parameters": [{"name": "text", "type": "str | None"}, {"name": "httpx_error", "type": "httpx.HTTPStatusError"}, {"name": "error_descriptors", "type": "list[DevOpsAPIErrorDescriptor]"}], "bases": ["astrapy.exceptions.DevOpsAPIException", "httpx.HTTPStatusError"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DevOpsAPIErrorDescriptor]", "description": "a list of all DevOpsAPIErrorDescriptor objects\nfound in the response."}], "gathered_types": ["DevOpsAPIErrorDescriptor", "HTTPStatusError", "astrapy.exceptions.DevOpsAPIException"]}} +{"id": "astrapy.exceptions.DevOpsAPIHttpException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DevOpsAPIHttpException.text", "value": "text: str | None = text"}} +{"id": "astrapy.exceptions.DevOpsAPIHttpException.error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "error_descriptors", "path": "astrapy.exceptions.DevOpsAPIHttpException.error_descriptors", "value": "error_descriptors: list[DevOpsAPIErrorDescriptor] = error_descriptors", "gathered_types": ["DevOpsAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DevOpsAPIHttpException.httpx_error", "text": "", "metadata": {"kind": "attribute", "name": "httpx_error", "path": "astrapy.exceptions.DevOpsAPIHttpException.httpx_error", "value": "httpx_error = httpx_error"}} +{"id": "astrapy.exceptions.DevOpsAPIHttpException.from_httpx_error", "text": "Parse a httpx status error into this exception.", "metadata": {"kind": "function", "name": "from_httpx_error", "path": "astrapy.exceptions.DevOpsAPIHttpException.from_httpx_error", "parameters": [{"name": "cls"}, {"name": "httpx_error", "type": "httpx.HTTPStatusError"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "DevOpsAPIHttpException"}], "gathered_types": ["astrapy.exceptions.DevOpsAPIHttpException", "HTTPStatusError"]}} +{"id": "astrapy.exceptions.DevOpsAPITimeoutException", "text": "A DevOps API operation timed out.", "metadata": {"kind": "class", "name": "DevOpsAPITimeoutException", "path": "astrapy.exceptions.DevOpsAPITimeoutException", "parameters": [{"name": "text", "type": "str"}, {"name": "timeout_type", "type": "str"}, {"name": "endpoint", "type": "str | None"}, {"name": "raw_payload", "type": "str | None"}], "bases": ["astrapy.exceptions.DevOpsAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a textual description of the error"}, {"name": "timeout_type", "type": "str", "description": "this denotes the phase of the HTTP request when the event\noccurred (\"connect\", \"read\", \"write\", \"pool\") or \"generic\" if there is\nnot a specific request associated to the exception."}, {"name": "endpoint", "type": "str | None", "description": "if the timeout is tied to a specific request, this is the\nURL that the request was targeting."}, {"name": "raw_payload", "type": "str | None", "description": "if the timeout is tied to a specific request, this is the\nassociated payload (as a string)."}], "gathered_types": ["astrapy.exceptions.DevOpsAPIException"]}} +{"id": "astrapy.exceptions.DevOpsAPITimeoutException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DevOpsAPITimeoutException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.DevOpsAPITimeoutException.timeout_type", "text": "", "metadata": {"kind": "attribute", "name": "timeout_type", "path": "astrapy.exceptions.DevOpsAPITimeoutException.timeout_type", "value": "timeout_type: str = timeout_type"}} +{"id": "astrapy.exceptions.DevOpsAPITimeoutException.endpoint", "text": "", "metadata": {"kind": "attribute", "name": "endpoint", "path": "astrapy.exceptions.DevOpsAPITimeoutException.endpoint", "value": "endpoint: str | None = endpoint"}} +{"id": "astrapy.exceptions.DevOpsAPITimeoutException.raw_payload", "text": "", "metadata": {"kind": "attribute", "name": "raw_payload", "path": "astrapy.exceptions.DevOpsAPITimeoutException.raw_payload", "value": "raw_payload: str | None = raw_payload"}} +{"id": "astrapy.exceptions.DevOpsAPIErrorDescriptor", "text": "An object representing a single error returned from the DevOps API,\ntypically with an error code and a text message.\n\nA single response from the Devops API may return zero, one or more of these.", "metadata": {"kind": "class", "name": "DevOpsAPIErrorDescriptor", "path": "astrapy.exceptions.DevOpsAPIErrorDescriptor", "parameters": [{"name": "error_dict", "type": "dict[str, Any]"}], "attributes": [{"name": "id", "type": "int | None", "description": "a numeric code as found in the API \"ID\" item."}, {"name": "message", "type": "str | None", "description": "the text found in the API \"error\" item."}, {"name": "attributes", "type": "dict[str, Any]", "description": "a dict with any further key-value pairs returned by the API."}]}} +{"id": "astrapy.exceptions.DevOpsAPIErrorDescriptor.id", "text": "", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.exceptions.DevOpsAPIErrorDescriptor.id", "value": "id: int | None = error_dict.get('ID')"}} +{"id": "astrapy.exceptions.DevOpsAPIErrorDescriptor.message", "text": "", "metadata": {"kind": "attribute", "name": "message", "path": "astrapy.exceptions.DevOpsAPIErrorDescriptor.message", "value": "message: str | None = error_dict.get('message')"}} +{"id": "astrapy.exceptions.DevOpsAPIErrorDescriptor.attributes", "text": "", "metadata": {"kind": "attribute", "name": "attributes", "path": "astrapy.exceptions.DevOpsAPIErrorDescriptor.attributes", "value": "attributes: dict[str, Any] = {k: vfor (k, v) in error_dict.items() if k not in {'ID', 'message'}}"}} +{"id": "astrapy.exceptions.DevOpsAPIFaultyResponseException", "text": "The DevOps API response is malformed in that it does not have\nexpected field(s), or they are of the wrong type.", "metadata": {"kind": "class", "name": "DevOpsAPIFaultyResponseException", "path": "astrapy.exceptions.DevOpsAPIFaultyResponseException", "parameters": [{"name": "text", "type": "str"}, {"name": "raw_response", "type": "dict[str, Any] | None"}], "bases": ["astrapy.exceptions.DevOpsAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "raw_response", "type": "dict[str, Any] | None", "description": "the response returned by the API in the form of a dict."}], "gathered_types": ["astrapy.exceptions.DevOpsAPIException"]}} +{"id": "astrapy.exceptions.DevOpsAPIFaultyResponseException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DevOpsAPIFaultyResponseException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.DevOpsAPIFaultyResponseException.raw_response", "text": "", "metadata": {"kind": "attribute", "name": "raw_response", "path": "astrapy.exceptions.DevOpsAPIFaultyResponseException.raw_response", "value": "raw_response: dict[str, Any] | None = raw_response"}} +{"id": "astrapy.exceptions.DevOpsAPIResponseException", "text": "A request to the DevOps API returned with a non-success return code\nand one of more errors in the HTTP response.", "metadata": {"kind": "class", "name": "DevOpsAPIResponseException", "path": "astrapy.exceptions.DevOpsAPIResponseException", "parameters": [{"name": "text", "default": "None", "type": "str | None"}, {"name": "command", "default": "None", "type": "dict[str, Any] | None"}, {"name": "error_descriptors", "default": "[]", "type": "list[DevOpsAPIErrorDescriptor]"}], "bases": ["astrapy.exceptions.DevOpsAPIException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "command", "type": "dict[str, Any] | None", "description": "the raw payload that was sent to the DevOps API."}, {"name": "error_descriptors", "type": "list[DevOpsAPIErrorDescriptor]", "description": "a list of all DevOpsAPIErrorDescriptor objects\nreturned by the API in the response."}], "gathered_types": ["DevOpsAPIErrorDescriptor", "astrapy.exceptions.DevOpsAPIException"]}} +{"id": "astrapy.exceptions.DevOpsAPIResponseException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DevOpsAPIResponseException.text", "value": "text: str | None = text"}} +{"id": "astrapy.exceptions.DevOpsAPIResponseException.command", "text": "", "metadata": {"kind": "attribute", "name": "command", "path": "astrapy.exceptions.DevOpsAPIResponseException.command", "value": "command: dict[str, Any] | None = command"}} +{"id": "astrapy.exceptions.DevOpsAPIResponseException.error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "error_descriptors", "path": "astrapy.exceptions.DevOpsAPIResponseException.error_descriptors", "value": "error_descriptors: list[DevOpsAPIErrorDescriptor] = error_descriptors", "gathered_types": ["DevOpsAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DevOpsAPIResponseException.from_response", "text": "Parse a raw response from the API into this exception.", "metadata": {"kind": "function", "name": "from_response", "path": "astrapy.exceptions.DevOpsAPIResponseException.from_response", "parameters": [{"name": "command", "type": "dict[str, Any] | None"}, {"name": "raw_response", "type": "dict[str, Any]"}], "returns": [{"type": "DevOpsAPIResponseException"}], "gathered_types": ["astrapy.exceptions.DevOpsAPIResponseException"]}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor", "text": "An object representing a single error returned from the Data API,\ntypically with an error code and a text message.\nAn API request would return with an HTTP 200 success error code,\nbut contain a nonzero amount of these.\n\nA single response from the Data API may return zero, one or more of these.\nMoreover, some operations, such as an insert_many, may partally succeed\nyet return these errors about the rest of the operation (such as,\nsome of the input documents could not be inserted).", "metadata": {"kind": "class", "name": "DataAPIErrorDescriptor", "path": "astrapy.exceptions.DataAPIErrorDescriptor", "parameters": [{"name": "error_dict", "type": "dict[str, str]"}], "attributes": [{"name": "error_code", "type": "str | None", "description": "a string code as found in the API \"error\" item."}, {"name": "message", "type": "str | None", "description": "the text found in the API \"error\" item."}, {"name": "attributes", "type": "dict[str, Any]", "description": "a dict with any further key-value pairs returned by the API."}]}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.title", "text": "", "metadata": {"kind": "attribute", "name": "title", "path": "astrapy.exceptions.DataAPIErrorDescriptor.title", "value": "title: str | None = error_dict.get('title')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.error_code", "text": "", "metadata": {"kind": "attribute", "name": "error_code", "path": "astrapy.exceptions.DataAPIErrorDescriptor.error_code", "value": "error_code: str | None = error_dict.get('errorCode')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.message", "text": "", "metadata": {"kind": "attribute", "name": "message", "path": "astrapy.exceptions.DataAPIErrorDescriptor.message", "value": "message: str | None = error_dict.get('message')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.family", "text": "", "metadata": {"kind": "attribute", "name": "family", "path": "astrapy.exceptions.DataAPIErrorDescriptor.family", "value": "family: str | None = error_dict.get('family')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.scope", "text": "", "metadata": {"kind": "attribute", "name": "scope", "path": "astrapy.exceptions.DataAPIErrorDescriptor.scope", "value": "scope: str | None = error_dict.get('scope')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.id", "text": "", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.exceptions.DataAPIErrorDescriptor.id", "value": "id: str | None = error_dict.get('id')"}} +{"id": "astrapy.exceptions.DataAPIErrorDescriptor.attributes", "text": "", "metadata": {"kind": "attribute", "name": "attributes", "path": "astrapy.exceptions.DataAPIErrorDescriptor.attributes", "value": "attributes: dict[str, Any] = {k: vfor (k, v) in error_dict.items() if k not in self._known_dict_fields}", "gathered_types": ["_known_dict_fields"]}} +{"id": "astrapy.exceptions.DataAPIDetailedErrorDescriptor", "text": "An object representing an errorful response from the Data API.\nErrors specific to the Data API (as opposed to e.g. network failures)\nwould result in an HTTP 200 success response code but coming with\none or more DataAPIErrorDescriptor objects.\n\nThis object corresponds to one response, and as such its attributes\nare a single request payload, a single response, but a list of\nDataAPIErrorDescriptor instances.", "metadata": {"kind": "class", "name": "DataAPIDetailedErrorDescriptor", "path": "astrapy.exceptions.DataAPIDetailedErrorDescriptor", "parameters": [{"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]"}, {"name": "command", "type": "dict[str, Any] | None"}, {"name": "raw_response", "type": "dict[str, Any]"}], "attributes": [{"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of DataAPIErrorDescriptor objects."}, {"name": "command", "type": "dict[str, Any] | None", "description": "the raw payload of the API request."}, {"name": "raw_response", "type": "dict[str, Any]", "description": "the full API response in the form of a dict."}], "gathered_types": ["DataAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "error_descriptors", "path": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.error_descriptors", "value": "error_descriptors: list[DataAPIErrorDescriptor]", "gathered_types": ["DataAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.command", "text": "", "metadata": {"kind": "attribute", "name": "command", "path": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.command", "value": "command: dict[str, Any] | None"}} +{"id": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.raw_response", "text": "", "metadata": {"kind": "attribute", "name": "raw_response", "path": "astrapy.exceptions.DataAPIDetailedErrorDescriptor.raw_response", "value": "raw_response: dict[str, Any]"}} +{"id": "astrapy.exceptions.DataAPIException", "text": "Any exception occurred while issuing requests to the Data API\nand specific to it, such as:\n - a collection is found not to exist when gettings its metadata,\n - the API return a response with an error,\nbut not, for instance,\n - a network error while sending an HTTP request to the API.", "metadata": {"kind": "class", "name": "DataAPIException", "path": "astrapy.exceptions.DataAPIException", "bases": ["ValueError"], "gathered_types": ["ValueError"]}} +{"id": "astrapy.exceptions.DataAPIHttpException", "text": "A request to the Data API resulted in an HTTP 4xx or 5xx response.\n\nIn most cases this comes with additional information: the purpose\nof this class is to present such information in a structured way,\nakin to what happens for the DataAPIResponseException, while\nstill raising (a subclass of) `httpx.HTTPStatusError`.", "metadata": {"kind": "class", "name": "DataAPIHttpException", "path": "astrapy.exceptions.DataAPIHttpException", "parameters": [{"name": "text", "type": "str | None"}, {"name": "httpx_error", "type": "httpx.HTTPStatusError"}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]"}], "bases": ["DataAPIException", "httpx.HTTPStatusError"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound in the response."}], "gathered_types": ["HTTPStatusError", "DataAPIErrorDescriptor", "DataAPIException"]}} +{"id": "astrapy.exceptions.DataAPIHttpException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DataAPIHttpException.text", "value": "text: str | None = text"}} +{"id": "astrapy.exceptions.DataAPIHttpException.error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "error_descriptors", "path": "astrapy.exceptions.DataAPIHttpException.error_descriptors", "value": "error_descriptors: list[DataAPIErrorDescriptor] = error_descriptors", "gathered_types": ["DataAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DataAPIHttpException.httpx_error", "text": "", "metadata": {"kind": "attribute", "name": "httpx_error", "path": "astrapy.exceptions.DataAPIHttpException.httpx_error", "value": "httpx_error = httpx_error"}} +{"id": "astrapy.exceptions.DataAPIHttpException.from_httpx_error", "text": "Parse a httpx status error into this exception.", "metadata": {"kind": "function", "name": "from_httpx_error", "path": "astrapy.exceptions.DataAPIHttpException.from_httpx_error", "parameters": [{"name": "cls"}, {"name": "httpx_error", "type": "httpx.HTTPStatusError"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "DataAPIHttpException"}], "gathered_types": ["HTTPStatusError", "astrapy.exceptions.DataAPIHttpException"]}} +{"id": "astrapy.exceptions.DataAPITimeoutException", "text": "A Data API operation timed out. This can be a request timeout occurring\nduring a specific HTTP request, or can happen over the course of a method\ninvolving several requests in a row, such as a paginated find.", "metadata": {"kind": "class", "name": "DataAPITimeoutException", "path": "astrapy.exceptions.DataAPITimeoutException", "parameters": [{"name": "text", "type": "str"}, {"name": "timeout_type", "type": "str"}, {"name": "endpoint", "type": "str | None"}, {"name": "raw_payload", "type": "str | None"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a textual description of the error"}, {"name": "timeout_type", "type": "str", "description": "this denotes the phase of the HTTP request when the event\noccurred (\"connect\", \"read\", \"write\", \"pool\") or \"generic\" if there is\nnot a specific request associated to the exception."}, {"name": "endpoint", "type": "str | None", "description": "if the timeout is tied to a specific request, this is the\nURL that the request was targeting."}, {"name": "raw_payload", "type": "str | None", "description": "if the timeout is tied to a specific request, this is the\nassociated payload (as a string)."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.DataAPITimeoutException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DataAPITimeoutException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.DataAPITimeoutException.timeout_type", "text": "", "metadata": {"kind": "attribute", "name": "timeout_type", "path": "astrapy.exceptions.DataAPITimeoutException.timeout_type", "value": "timeout_type: str = timeout_type"}} +{"id": "astrapy.exceptions.DataAPITimeoutException.endpoint", "text": "", "metadata": {"kind": "attribute", "name": "endpoint", "path": "astrapy.exceptions.DataAPITimeoutException.endpoint", "value": "endpoint: str | None = endpoint"}} +{"id": "astrapy.exceptions.DataAPITimeoutException.raw_payload", "text": "", "metadata": {"kind": "attribute", "name": "raw_payload", "path": "astrapy.exceptions.DataAPITimeoutException.raw_payload", "value": "raw_payload: str | None = raw_payload"}} +{"id": "astrapy.exceptions.CursorIsStartedException", "text": "The cursor operation cannot be invoked if a cursor is not in its pristine\nstate (i.e. is already being consumed or is exhausted altogether).", "metadata": {"kind": "class", "name": "CursorIsStartedException", "path": "astrapy.exceptions.CursorIsStartedException", "parameters": [{"name": "text", "type": "str"}, {"name": "cursor_state", "type": "str"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "cursor_state", "type": "str", "description": "a string description of the current state\nof the cursor. See the documentation for Cursor."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.CursorIsStartedException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.CursorIsStartedException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.CursorIsStartedException.cursor_state", "text": "", "metadata": {"kind": "attribute", "name": "cursor_state", "path": "astrapy.exceptions.CursorIsStartedException.cursor_state", "value": "cursor_state: str = cursor_state"}} +{"id": "astrapy.exceptions.CollectionNotFoundException", "text": "A collection is found non-existing and the requested operation\ncannot be performed.", "metadata": {"kind": "class", "name": "CollectionNotFoundException", "path": "astrapy.exceptions.CollectionNotFoundException", "parameters": [{"name": "text", "type": "str"}, {"name": "keyspace", "type": "str"}, {"name": "collection_name", "type": "str"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "keyspace", "type": "str", "description": "the keyspace where the collection was supposed to be."}, {"name": "namespace", "type": "str", "description": "an alias for 'keyspace'. *DEPRECATED*, removal in 2.0"}, {"name": "collection_name", "type": "str", "description": "the name of the expected collection."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.CollectionNotFoundException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.CollectionNotFoundException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.CollectionNotFoundException.keyspace", "text": "", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.exceptions.CollectionNotFoundException.keyspace", "value": "keyspace: str = keyspace"}} +{"id": "astrapy.exceptions.CollectionNotFoundException.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.exceptions.CollectionNotFoundException.namespace", "value": "namespace: str = keyspace"}} +{"id": "astrapy.exceptions.CollectionNotFoundException.collection_name", "text": "", "metadata": {"kind": "attribute", "name": "collection_name", "path": "astrapy.exceptions.CollectionNotFoundException.collection_name", "value": "collection_name: str = collection_name"}} +{"id": "astrapy.exceptions.CollectionAlreadyExistsException", "text": "An operation expected a collection not to exist, yet it has\nbeen detected as pre-existing.", "metadata": {"kind": "class", "name": "CollectionAlreadyExistsException", "path": "astrapy.exceptions.CollectionAlreadyExistsException", "parameters": [{"name": "text", "type": "str"}, {"name": "keyspace", "type": "str"}, {"name": "collection_name", "type": "str"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "keyspace", "type": "str", "description": "the keyspace where the collection was expected not to exist."}, {"name": "namespace", "type": "str", "description": "an alias for 'keyspace'. *DEPRECATED*, removal in 2.0"}, {"name": "collection_name", "type": "str", "description": "the name of the collection."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.CollectionAlreadyExistsException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.CollectionAlreadyExistsException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.CollectionAlreadyExistsException.keyspace", "text": "", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.exceptions.CollectionAlreadyExistsException.keyspace", "value": "keyspace: str = keyspace"}} +{"id": "astrapy.exceptions.CollectionAlreadyExistsException.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.exceptions.CollectionAlreadyExistsException.namespace", "value": "namespace: str = keyspace"}} +{"id": "astrapy.exceptions.CollectionAlreadyExistsException.collection_name", "text": "", "metadata": {"kind": "attribute", "name": "collection_name", "path": "astrapy.exceptions.CollectionAlreadyExistsException.collection_name", "value": "collection_name: str = collection_name"}} +{"id": "astrapy.exceptions.TooManyDocumentsToCountException", "text": "A `count_documents()` operation failed because the resulting number of documents\nexceeded either the upper bound set by the caller or the hard limit imposed\nby the Data API.", "metadata": {"kind": "class", "name": "TooManyDocumentsToCountException", "path": "astrapy.exceptions.TooManyDocumentsToCountException", "parameters": [{"name": "text", "type": "str"}, {"name": "server_max_count_exceeded", "type": "bool"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "server_max_count_exceeded", "type": "bool", "description": "True if the count limit imposed by the API\nis reached. In that case, increasing the upper bound in the method\ninvocation is of no help."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.TooManyDocumentsToCountException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.TooManyDocumentsToCountException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.TooManyDocumentsToCountException.server_max_count_exceeded", "text": "", "metadata": {"kind": "attribute", "name": "server_max_count_exceeded", "path": "astrapy.exceptions.TooManyDocumentsToCountException.server_max_count_exceeded", "value": "server_max_count_exceeded: bool = server_max_count_exceeded"}} +{"id": "astrapy.exceptions.DataAPIFaultyResponseException", "text": "The Data API response is malformed in that it does not have\nexpected field(s), or they are of the wrong type.", "metadata": {"kind": "class", "name": "DataAPIFaultyResponseException", "path": "astrapy.exceptions.DataAPIFaultyResponseException", "parameters": [{"name": "text", "type": "str"}, {"name": "raw_response", "type": "dict[str, Any] | None"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str", "description": "a text message about the exception."}, {"name": "raw_response", "type": "dict[str, Any] | None", "description": "the response returned by the API in the form of a dict."}], "gathered_types": ["DataAPIException"]}} +{"id": "astrapy.exceptions.DataAPIFaultyResponseException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DataAPIFaultyResponseException.text", "value": "text: str = text"}} +{"id": "astrapy.exceptions.DataAPIFaultyResponseException.raw_response", "text": "", "metadata": {"kind": "attribute", "name": "raw_response", "path": "astrapy.exceptions.DataAPIFaultyResponseException.raw_response", "value": "raw_response: dict[str, Any] | None = raw_response"}} +{"id": "astrapy.exceptions.DataAPIResponseException", "text": "The Data API returned an HTTP 200 success response, which however\nreports about API-specific error(s), possibly alongside partial successes.\n\nThis exception is related to an operation that can have spanned several\nHTTP requests in sequence (e.g. a chunked insert_many). For this\nreason, it should be not thought as being in a 1:1 relation with\nactual API requests, rather with operations invoked by the user,\nsuch as the methods of the Collection object.", "metadata": {"kind": "class", "name": "DataAPIResponseException", "path": "astrapy.exceptions.DataAPIResponseException", "parameters": [{"name": "text", "type": "str | None"}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]"}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]"}], "bases": ["DataAPIException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in this exception, which are\npossibly more than one."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during this operation.\nFor single-request methods, such as insert_one, this list always\nhas a single element."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "DataAPIErrorDescriptor", "DataAPIException"], "implemented_by": ["astrapy.exceptions.CumulativeOperationException", "astrapy.exceptions.BulkWriteException"]}} +{"id": "astrapy.exceptions.DataAPIResponseException.text", "text": "", "metadata": {"kind": "attribute", "name": "text", "path": "astrapy.exceptions.DataAPIResponseException.text", "value": "text: str | None = text"}} +{"id": "astrapy.exceptions.DataAPIResponseException.error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "error_descriptors", "path": "astrapy.exceptions.DataAPIResponseException.error_descriptors", "value": "error_descriptors: list[DataAPIErrorDescriptor] = error_descriptors", "gathered_types": ["DataAPIErrorDescriptor"]}} +{"id": "astrapy.exceptions.DataAPIResponseException.detailed_error_descriptors", "text": "", "metadata": {"kind": "attribute", "name": "detailed_error_descriptors", "path": "astrapy.exceptions.DataAPIResponseException.detailed_error_descriptors", "value": "detailed_error_descriptors: list[DataAPIDetailedErrorDescriptor] = detailed_error_descriptors", "gathered_types": ["DataAPIDetailedErrorDescriptor"]}} +{"id": "astrapy.exceptions.DataAPIResponseException.from_response", "text": "Parse a raw response from the API into this exception.", "metadata": {"kind": "function", "name": "from_response", "path": "astrapy.exceptions.DataAPIResponseException.from_response", "parameters": [{"name": "cls"}, {"name": "command", "type": "dict[str, Any] | None"}, {"name": "raw_response", "type": "dict[str, Any]"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "DataAPIResponseException"}], "gathered_types": ["astrapy.exceptions.DataAPIResponseException"]}} +{"id": "astrapy.exceptions.DataAPIResponseException.from_responses", "text": "Parse a list of raw responses from the API into this exception.", "metadata": {"kind": "function", "name": "from_responses", "path": "astrapy.exceptions.DataAPIResponseException.from_responses", "parameters": [{"name": "cls"}, {"name": "commands", "type": "list[dict[str, Any] | None]"}, {"name": "raw_responses", "type": "list[dict[str, Any]]"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "DataAPIResponseException"}], "gathered_types": ["astrapy.exceptions.DataAPIResponseException"]}} +{"id": "astrapy.exceptions.DataAPIResponseException.data_api_response_exception", "text": "Cast the exception, whatever the subclass, into this parent superclass.", "metadata": {"kind": "function", "name": "data_api_response_exception", "path": "astrapy.exceptions.DataAPIResponseException.data_api_response_exception", "returns": [{"type": "DataAPIResponseException"}], "gathered_types": ["astrapy.exceptions.DataAPIResponseException"]}} +{"id": "astrapy.exceptions.CumulativeOperationException", "text": "An exception of type DataAPIResponseException (see) occurred\nduring an operation that in general spans several requests.\nAs such, besides information on the error, it may have accumulated\na partial result from past successful Data API requests.", "metadata": {"kind": "class", "name": "CumulativeOperationException", "path": "astrapy.exceptions.CumulativeOperationException", "parameters": [{"name": "text", "type": "str | None"}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]"}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]"}], "bases": ["astrapy.exceptions.DataAPIResponseException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in this exception, which are\npossibly more than one."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during this operation.\nFor single-request methods, such as insert_one, this list always\nhas a single element."}, {"name": "partial_result", "type": "OperationResult", "description": "an OperationResult object, just like the one that would\nbe the return value of the operation, had it succeeded completely."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "astrapy.exceptions.DataAPIResponseException", "DataAPIErrorDescriptor", "astrapy.results.OperationResult"], "implemented_by": ["astrapy.exceptions.InsertManyException", "astrapy.exceptions.DeleteManyException", "astrapy.exceptions.UpdateManyException"]}} +{"id": "astrapy.exceptions.CumulativeOperationException.partial_result", "text": "", "metadata": {"kind": "attribute", "name": "partial_result", "path": "astrapy.exceptions.CumulativeOperationException.partial_result", "value": "partial_result: OperationResult", "gathered_types": ["astrapy.results.OperationResult"]}} +{"id": "astrapy.exceptions.InsertManyException", "text": "An exception of type DataAPIResponseException (see) occurred\nduring an insert_many (that in general spans several requests).\nAs such, besides information on the error, it may have accumulated\na partial result from past successful Data API requests.", "metadata": {"kind": "class", "name": "InsertManyException", "path": "astrapy.exceptions.InsertManyException", "parameters": [{"name": "text", "type": "str"}, {"name": "partial_result", "type": "InsertManyResult"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "bases": ["astrapy.exceptions.CumulativeOperationException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in this exception, which are\npossibly more than one."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during this operation.\nFor single-request methods, such as insert_one, this list always\nhas a single element."}, {"name": "partial_result", "type": "InsertManyResult", "description": "an InsertManyResult object, just like the one that would\nbe the return value of the operation, had it succeeded completely."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "DataAPIErrorDescriptor", "astrapy.exceptions.CumulativeOperationException", "astrapy.results.InsertManyResult"]}} +{"id": "astrapy.exceptions.InsertManyException.partial_result", "text": "", "metadata": {"kind": "attribute", "name": "partial_result", "path": "astrapy.exceptions.InsertManyException.partial_result", "value": "partial_result: InsertManyResult = partial_result", "gathered_types": ["astrapy.results.InsertManyResult"]}} +{"id": "astrapy.exceptions.DeleteManyException", "text": "An exception of type DataAPIResponseException (see) occurred\nduring a delete_many (that in general spans several requests).\nAs such, besides information on the error, it may have accumulated\na partial result from past successful Data API requests.", "metadata": {"kind": "class", "name": "DeleteManyException", "path": "astrapy.exceptions.DeleteManyException", "parameters": [{"name": "text", "type": "str"}, {"name": "partial_result", "type": "DeleteResult"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "bases": ["astrapy.exceptions.CumulativeOperationException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in this exception, which are\npossibly more than one."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during this operation.\nFor single-request methods, such as insert_one, this list always\nhas a single element."}, {"name": "partial_result", "type": "DeleteResult", "description": "a DeleteResult object, just like the one that would\nbe the return value of the operation, had it succeeded completely."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "astrapy.results.DeleteResult", "DataAPIErrorDescriptor", "astrapy.exceptions.CumulativeOperationException"]}} +{"id": "astrapy.exceptions.DeleteManyException.partial_result", "text": "", "metadata": {"kind": "attribute", "name": "partial_result", "path": "astrapy.exceptions.DeleteManyException.partial_result", "value": "partial_result: DeleteResult = partial_result", "gathered_types": ["astrapy.results.DeleteResult"]}} +{"id": "astrapy.exceptions.UpdateManyException", "text": "An exception of type DataAPIResponseException (see) occurred\nduring an update_many (that in general spans several requests).\nAs such, besides information on the error, it may have accumulated\na partial result from past successful Data API requests.", "metadata": {"kind": "class", "name": "UpdateManyException", "path": "astrapy.exceptions.UpdateManyException", "parameters": [{"name": "text", "type": "str"}, {"name": "partial_result", "type": "UpdateResult"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "bases": ["astrapy.exceptions.CumulativeOperationException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in this exception, which are\npossibly more than one."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during this operation.\nFor single-request methods, such as insert_one, this list always\nhas a single element."}, {"name": "partial_result", "type": "UpdateResult", "description": "an UpdateResult object, just like the one that would\nbe the return value of the operation, had it succeeded completely."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "astrapy.results.UpdateResult", "DataAPIErrorDescriptor", "astrapy.exceptions.CumulativeOperationException"]}} +{"id": "astrapy.exceptions.UpdateManyException.partial_result", "text": "", "metadata": {"kind": "attribute", "name": "partial_result", "path": "astrapy.exceptions.UpdateManyException.partial_result", "value": "partial_result: UpdateResult = partial_result", "gathered_types": ["astrapy.results.UpdateResult"]}} +{"id": "astrapy.exceptions.BulkWriteException", "text": "An exception of type DataAPIResponseException (see) occurred\nduring a bulk_write of a list of operations.\nAs such, besides information on the error, it may have accumulated\na partial result from past successful operations.", "metadata": {"kind": "class", "name": "BulkWriteException", "path": "astrapy.exceptions.BulkWriteException", "parameters": [{"name": "text", "type": "str | None"}, {"name": "partial_result", "type": "BulkWriteResult"}, {"name": "exceptions", "type": "list[DataAPIResponseException]"}, {"name": "pargs", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "bases": ["astrapy.exceptions.DataAPIResponseException"], "attributes": [{"name": "text", "type": "str | None", "description": "a text message about the exception."}, {"name": "error_descriptors", "type": "list[DataAPIErrorDescriptor]", "description": "a list of all DataAPIErrorDescriptor objects\nfound across all requests involved in the first\noperation that has failed."}, {"name": "detailed_error_descriptors", "type": "list[DataAPIDetailedErrorDescriptor]", "description": "a list of DataAPIDetailedErrorDescriptor\nobjects, one for each of the requests performed during the first operation\nthat has failed."}, {"name": "partial_result", "type": "BulkWriteResult", "description": "a BulkWriteResult object, just like the one that would\nbe the return value of the operation, had it succeeded completely."}, {"name": "exceptions", "type": "list[DataAPIResponseException]", "description": "a list of DataAPIResponseException objects, one for each\noperation in the bulk that has failed. This information is made\navailable here since the top-level fields of this error\nonly surface the first such failure that is detected across the bulk.\nIn case of bulk_writes with ordered=True, this trivially contains\na single element, the same described by the top-level fields\ntext, error_descriptors and detailed_error_descriptors."}], "gathered_types": ["DataAPIDetailedErrorDescriptor", "DataAPIErrorDescriptor", "astrapy.exceptions.DataAPIResponseException", "astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.exceptions.BulkWriteException.partial_result", "text": "", "metadata": {"kind": "attribute", "name": "partial_result", "path": "astrapy.exceptions.BulkWriteException.partial_result", "value": "partial_result: BulkWriteResult = partial_result", "gathered_types": ["astrapy.results.BulkWriteResult"]}} +{"id": "astrapy.exceptions.BulkWriteException.exceptions", "text": "", "metadata": {"kind": "attribute", "name": "exceptions", "path": "astrapy.exceptions.BulkWriteException.exceptions", "value": "exceptions: list[DataAPIResponseException] = exceptions", "gathered_types": ["astrapy.exceptions.DataAPIResponseException"]}} +{"id": "astrapy.exceptions.to_dataapi_timeout_exception", "text": "", "metadata": {"kind": "function", "name": "to_dataapi_timeout_exception", "path": "astrapy.exceptions.to_dataapi_timeout_exception", "parameters": [{"name": "httpx_timeout", "type": "httpx.TimeoutException"}], "returns": [{"type": "DataAPITimeoutException"}], "gathered_types": ["astrapy.exceptions.DataAPITimeoutException", "TimeoutException"]}} +{"id": "astrapy.exceptions.to_devopsapi_timeout_exception", "text": "", "metadata": {"kind": "function", "name": "to_devopsapi_timeout_exception", "path": "astrapy.exceptions.to_devopsapi_timeout_exception", "parameters": [{"name": "httpx_timeout", "type": "httpx.TimeoutException"}], "returns": [{"type": "DevOpsAPITimeoutException"}], "gathered_types": ["DevOpsAPITimeoutException", "TimeoutException"]}} +{"id": "astrapy.exceptions.base_timeout_info", "text": "", "metadata": {"kind": "function", "name": "base_timeout_info", "path": "astrapy.exceptions.base_timeout_info", "parameters": [{"name": "max_time_ms", "type": "int | None"}], "returns": [{"type": "TimeoutInfo | None"}], "gathered_types": ["astrapy.request_tools.TimeoutInfo"]}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager", "text": "A helper class to keep track of timing and timeouts\nin a multi-call method context.", "metadata": {"kind": "class", "name": "MultiCallTimeoutManager", "path": "astrapy.exceptions.MultiCallTimeoutManager", "parameters": [{"name": "overall_max_time_ms", "type": "int | None", "description": "an optional max duration to track (milliseconds)", "default": null}], "attributes": [{"name": "overall_max_time_ms", "type": "int | None", "description": "an optional max duration to track (milliseconds)"}, {"name": "started_ms", "type": "int", "description": "timestamp of the instance construction (milliseconds)"}, {"name": "deadline_ms", "type": "int | None", "description": "optional deadline in milliseconds (computed by the class)."}]}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.overall_max_time_ms", "text": "", "metadata": {"kind": "attribute", "name": "overall_max_time_ms", "path": "astrapy.exceptions.MultiCallTimeoutManager.overall_max_time_ms", "value": "overall_max_time_ms: int | None = overall_max_time_ms"}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.started_ms", "text": "", "metadata": {"kind": "attribute", "name": "started_ms", "path": "astrapy.exceptions.MultiCallTimeoutManager.started_ms", "value": "started_ms: int = int(time.time() * 1000)"}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.deadline_ms", "text": "", "metadata": {"kind": "attribute", "name": "deadline_ms", "path": "astrapy.exceptions.MultiCallTimeoutManager.deadline_ms", "value": "deadline_ms: int | None"}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.dev_ops_api", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_api", "path": "astrapy.exceptions.MultiCallTimeoutManager.dev_ops_api", "value": "dev_ops_api = dev_ops_api"}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.remaining_timeout_ms", "text": "Ensure the deadline, if any, is not yet in the past.\nIf it is, raise an appropriate timeout error.\nIf not, return either None (if no timeout) or the remaining milliseconds.\nFor use within the multi-call method.", "metadata": {"kind": "function", "name": "remaining_timeout_ms", "path": "astrapy.exceptions.MultiCallTimeoutManager.remaining_timeout_ms", "returns": [{"type": "int | None"}]}} +{"id": "astrapy.exceptions.MultiCallTimeoutManager.remaining_timeout_info", "text": "Ensure the deadline, if any, is not yet in the past.\nIf it is, raise an appropriate timeout error.\nIt it is not, or there is no deadline, return a suitable TimeoutInfo\nfor use within the multi-call method.", "metadata": {"kind": "function", "name": "remaining_timeout_info", "path": "astrapy.exceptions.MultiCallTimeoutManager.remaining_timeout_info", "returns": [{"type": "TimeoutInfo | None"}], "gathered_types": ["astrapy.request_tools.TimeoutInfo"]}} +{"id": "astrapy.defaults", "text": "", "metadata": {"kind": "module", "name": "defaults", "path": "astrapy.defaults", "imports": {"annotations": "__future__.annotations"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_PROD", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "value": "DATA_API_ENVIRONMENT_PROD = 'prod'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_DEV", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "value": "DATA_API_ENVIRONMENT_DEV = 'dev'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_TEST", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_TEST", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_TEST", "value": "DATA_API_ENVIRONMENT_TEST = 'test'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_DSE", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_DSE", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_DSE", "value": "DATA_API_ENVIRONMENT_DSE = 'dse'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_HCD", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_HCD", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_HCD", "value": "DATA_API_ENVIRONMENT_HCD = 'hcd'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_CASSANDRA", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA", "value": "DATA_API_ENVIRONMENT_CASSANDRA = 'cassandra'"}} +{"id": "astrapy.defaults.DATA_API_ENVIRONMENT_OTHER", "text": "", "metadata": {"kind": "attribute", "name": "DATA_API_ENVIRONMENT_OTHER", "path": "astrapy.defaults.DATA_API_ENVIRONMENT_OTHER", "value": "DATA_API_ENVIRONMENT_OTHER = 'other'"}} +{"id": "astrapy.defaults.DEFAULT_ASTRA_DB_KEYSPACE", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_ASTRA_DB_KEYSPACE", "path": "astrapy.defaults.DEFAULT_ASTRA_DB_KEYSPACE", "value": "DEFAULT_ASTRA_DB_KEYSPACE = 'default_keyspace'"}} +{"id": "astrapy.defaults.API_ENDPOINT_TEMPLATE_ENV_MAP", "text": "", "metadata": {"kind": "attribute", "name": "API_ENDPOINT_TEMPLATE_ENV_MAP", "path": "astrapy.defaults.API_ENDPOINT_TEMPLATE_ENV_MAP", "value": "API_ENDPOINT_TEMPLATE_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: 'https://{database_id}-{region}.apps.astra.datastax.com', DATA_API_ENVIRONMENT_DEV: 'https://{database_id}-{region}.apps.astra-dev.datastax.com', DATA_API_ENVIRONMENT_TEST: 'https://{database_id}-{region}.apps.astra-test.datastax.com'}", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "astrapy.defaults.DATA_API_ENVIRONMENT_TEST"]}} +{"id": "astrapy.defaults.API_PATH_ENV_MAP", "text": "", "metadata": {"kind": "attribute", "name": "API_PATH_ENV_MAP", "path": "astrapy.defaults.API_PATH_ENV_MAP", "value": "API_PATH_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: '/api/json', DATA_API_ENVIRONMENT_DEV: '/api/json', DATA_API_ENVIRONMENT_TEST: '/api/json', DATA_API_ENVIRONMENT_DSE: '', DATA_API_ENVIRONMENT_HCD: '', DATA_API_ENVIRONMENT_CASSANDRA: '', DATA_API_ENVIRONMENT_OTHER: ''}", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "astrapy.defaults.DATA_API_ENVIRONMENT_TEST", "astrapy.defaults.DATA_API_ENVIRONMENT_DSE", "astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA", "astrapy.defaults.DATA_API_ENVIRONMENT_OTHER", "astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "astrapy.defaults.DATA_API_ENVIRONMENT_HCD"]}} +{"id": "astrapy.defaults.API_VERSION_ENV_MAP", "text": "", "metadata": {"kind": "attribute", "name": "API_VERSION_ENV_MAP", "path": "astrapy.defaults.API_VERSION_ENV_MAP", "value": "API_VERSION_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: '/v1', DATA_API_ENVIRONMENT_DEV: '/v1', DATA_API_ENVIRONMENT_TEST: '/v1', DATA_API_ENVIRONMENT_DSE: 'v1', DATA_API_ENVIRONMENT_HCD: 'v1', DATA_API_ENVIRONMENT_CASSANDRA: 'v1', DATA_API_ENVIRONMENT_OTHER: 'v1'}", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "astrapy.defaults.DATA_API_ENVIRONMENT_TEST", "astrapy.defaults.DATA_API_ENVIRONMENT_DSE", "astrapy.defaults.DATA_API_ENVIRONMENT_CASSANDRA", "astrapy.defaults.DATA_API_ENVIRONMENT_OTHER", "astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "astrapy.defaults.DATA_API_ENVIRONMENT_HCD"]}} +{"id": "astrapy.defaults.DEFAULT_INSERT_MANY_CHUNK_SIZE", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_INSERT_MANY_CHUNK_SIZE", "path": "astrapy.defaults.DEFAULT_INSERT_MANY_CHUNK_SIZE", "value": "DEFAULT_INSERT_MANY_CHUNK_SIZE = 50"}} +{"id": "astrapy.defaults.DEFAULT_INSERT_MANY_CONCURRENCY", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_INSERT_MANY_CONCURRENCY", "path": "astrapy.defaults.DEFAULT_INSERT_MANY_CONCURRENCY", "value": "DEFAULT_INSERT_MANY_CONCURRENCY = 20"}} +{"id": "astrapy.defaults.DEFAULT_BULK_WRITE_CONCURRENCY", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_BULK_WRITE_CONCURRENCY", "path": "astrapy.defaults.DEFAULT_BULK_WRITE_CONCURRENCY", "value": "DEFAULT_BULK_WRITE_CONCURRENCY = 10"}} +{"id": "astrapy.defaults.DEFAULT_REQUEST_TIMEOUT_MS", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_REQUEST_TIMEOUT_MS", "path": "astrapy.defaults.DEFAULT_REQUEST_TIMEOUT_MS", "value": "DEFAULT_REQUEST_TIMEOUT_MS = 30000"}} +{"id": "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DATA_API_AUTH_HEADER", "path": "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "value": "DEFAULT_DATA_API_AUTH_HEADER = 'Token'"}} +{"id": "astrapy.defaults.EMBEDDING_HEADER_AWS_ACCESS_ID", "text": "", "metadata": {"kind": "attribute", "name": "EMBEDDING_HEADER_AWS_ACCESS_ID", "path": "astrapy.defaults.EMBEDDING_HEADER_AWS_ACCESS_ID", "value": "EMBEDDING_HEADER_AWS_ACCESS_ID = 'X-Embedding-Access-Id'"}} +{"id": "astrapy.defaults.EMBEDDING_HEADER_AWS_SECRET_ID", "text": "", "metadata": {"kind": "attribute", "name": "EMBEDDING_HEADER_AWS_SECRET_ID", "path": "astrapy.defaults.EMBEDDING_HEADER_AWS_SECRET_ID", "value": "EMBEDDING_HEADER_AWS_SECRET_ID = 'X-Embedding-Secret-Id'"}} +{"id": "astrapy.defaults.EMBEDDING_HEADER_API_KEY", "text": "", "metadata": {"kind": "attribute", "name": "EMBEDDING_HEADER_API_KEY", "path": "astrapy.defaults.EMBEDDING_HEADER_API_KEY", "value": "EMBEDDING_HEADER_API_KEY = 'X-Embedding-Api-Key'"}} +{"id": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DEV_OPS_AUTH_HEADER", "path": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "value": "DEFAULT_DEV_OPS_AUTH_HEADER = 'Authorization'"}} +{"id": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_PREFIX", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DEV_OPS_AUTH_PREFIX", "path": "astrapy.defaults.DEFAULT_DEV_OPS_AUTH_PREFIX", "value": "DEFAULT_DEV_OPS_AUTH_PREFIX = 'Bearer '"}} +{"id": "astrapy.defaults.DEV_OPS_KEYSPACE_POLL_INTERVAL_S", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_KEYSPACE_POLL_INTERVAL_S", "path": "astrapy.defaults.DEV_OPS_KEYSPACE_POLL_INTERVAL_S", "value": "DEV_OPS_KEYSPACE_POLL_INTERVAL_S = 2"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_POLL_INTERVAL_S", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_POLL_INTERVAL_S", "path": "astrapy.defaults.DEV_OPS_DATABASE_POLL_INTERVAL_S", "value": "DEV_OPS_DATABASE_POLL_INTERVAL_S = 15"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_MAINTENANCE", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_MAINTENANCE", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_MAINTENANCE", "value": "DEV_OPS_DATABASE_STATUS_MAINTENANCE = 'MAINTENANCE'"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_ACTIVE", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_ACTIVE", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_ACTIVE", "value": "DEV_OPS_DATABASE_STATUS_ACTIVE = 'ACTIVE'"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_PENDING", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_PENDING", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_PENDING", "value": "DEV_OPS_DATABASE_STATUS_PENDING = 'PENDING'"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_INITIALIZING", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_INITIALIZING", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_INITIALIZING", "value": "DEV_OPS_DATABASE_STATUS_INITIALIZING = 'INITIALIZING'"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_ERROR", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_ERROR", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_ERROR", "value": "DEV_OPS_DATABASE_STATUS_ERROR = 'ERROR'"}} +{"id": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_TERMINATING", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DATABASE_STATUS_TERMINATING", "path": "astrapy.defaults.DEV_OPS_DATABASE_STATUS_TERMINATING", "value": "DEV_OPS_DATABASE_STATUS_TERMINATING = 'TERMINATING'"}} +{"id": "astrapy.defaults.DEV_OPS_URL_ENV_MAP", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_URL_ENV_MAP", "path": "astrapy.defaults.DEV_OPS_URL_ENV_MAP", "value": "DEV_OPS_URL_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: 'https://api.astra.datastax.com', DATA_API_ENVIRONMENT_DEV: 'https://api.dev.cloud.datastax.com', DATA_API_ENVIRONMENT_TEST: 'https://api.test.cloud.datastax.com'}", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "astrapy.defaults.DATA_API_ENVIRONMENT_TEST"]}} +{"id": "astrapy.defaults.DEV_OPS_VERSION_ENV_MAP", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_VERSION_ENV_MAP", "path": "astrapy.defaults.DEV_OPS_VERSION_ENV_MAP", "value": "DEV_OPS_VERSION_ENV_MAP = {DATA_API_ENVIRONMENT_PROD: 'v2', DATA_API_ENVIRONMENT_DEV: 'v2', DATA_API_ENVIRONMENT_TEST: 'v2'}", "gathered_types": ["astrapy.defaults.DATA_API_ENVIRONMENT_PROD", "astrapy.defaults.DATA_API_ENVIRONMENT_DEV", "astrapy.defaults.DATA_API_ENVIRONMENT_TEST"]}} +{"id": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_ACCEPTED", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_RESPONSE_HTTP_ACCEPTED", "path": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_ACCEPTED", "value": "DEV_OPS_RESPONSE_HTTP_ACCEPTED = 202"}} +{"id": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_CREATED", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_RESPONSE_HTTP_CREATED", "path": "astrapy.defaults.DEV_OPS_RESPONSE_HTTP_CREATED", "value": "DEV_OPS_RESPONSE_HTTP_CREATED = 201"}} +{"id": "astrapy.defaults.DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE", "text": "", "metadata": {"kind": "attribute", "name": "DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE", "path": "astrapy.defaults.DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE", "value": "DEV_OPS_DEFAULT_DATABASES_PAGE_SIZE = 25"}} +{"id": "astrapy.defaults.SECRETS_REDACT_ENDING", "text": "", "metadata": {"kind": "attribute", "name": "SECRETS_REDACT_ENDING", "path": "astrapy.defaults.SECRETS_REDACT_ENDING", "value": "SECRETS_REDACT_ENDING = '...'"}} +{"id": "astrapy.defaults.SECRETS_REDACT_CHAR", "text": "", "metadata": {"kind": "attribute", "name": "SECRETS_REDACT_CHAR", "path": "astrapy.defaults.SECRETS_REDACT_CHAR", "value": "SECRETS_REDACT_CHAR = '*'"}} +{"id": "astrapy.defaults.SECRETS_REDACT_ENDING_LENGTH", "text": "", "metadata": {"kind": "attribute", "name": "SECRETS_REDACT_ENDING_LENGTH", "path": "astrapy.defaults.SECRETS_REDACT_ENDING_LENGTH", "value": "SECRETS_REDACT_ENDING_LENGTH = 3"}} +{"id": "astrapy.defaults.HEADER_REDACT_PLACEHOLDER", "text": "", "metadata": {"kind": "attribute", "name": "HEADER_REDACT_PLACEHOLDER", "path": "astrapy.defaults.HEADER_REDACT_PLACEHOLDER", "value": "HEADER_REDACT_PLACEHOLDER = '***'"}} +{"id": "astrapy.defaults.DEFAULT_REDACTED_HEADER_NAMES", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_REDACTED_HEADER_NAMES", "path": "astrapy.defaults.DEFAULT_REDACTED_HEADER_NAMES", "value": "DEFAULT_REDACTED_HEADER_NAMES = {DEFAULT_DATA_API_AUTH_HEADER, DEFAULT_DEV_OPS_AUTH_HEADER, EMBEDDING_HEADER_AWS_ACCESS_ID, EMBEDDING_HEADER_AWS_SECRET_ID, EMBEDDING_HEADER_API_KEY}", "gathered_types": ["astrapy.defaults.EMBEDDING_HEADER_API_KEY", "astrapy.defaults.EMBEDDING_HEADER_AWS_SECRET_ID", "astrapy.defaults.DEFAULT_DATA_API_AUTH_HEADER", "astrapy.defaults.EMBEDDING_HEADER_AWS_ACCESS_ID", "astrapy.core.defaults.DEFAULT_DEV_OPS_AUTH_HEADER"]}} +{"id": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_METHOD", "text": "", "metadata": {"kind": "attribute", "name": "NAMESPACE_DEPRECATION_NOTICE_METHOD", "path": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_METHOD", "value": "NAMESPACE_DEPRECATION_NOTICE_METHOD = \"The term 'namespace' is being replaced by 'keyspace' throughout the Data API and the clients. Please adapt method and parameter names consistently (examples: `db_admin.findNamespaces` => `db_admin.findKeyspaces`; `collection.namespace` => `collection.keyspace`; `database.list_collections(namespace=...)` => `database.list_collections(keyspace=...)`). See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information.\""}} +{"id": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT", "text": "", "metadata": {"kind": "attribute", "name": "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT", "path": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT", "value": "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT = 'Parameter `update_db_namespace`'"}} +{"id": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS", "text": "", "metadata": {"kind": "attribute", "name": "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS", "path": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS", "value": "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS = 'Please replace the parameter with `update_db_keyspace`. See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information.'"}} +{"id": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT", "text": "", "metadata": {"kind": "attribute", "name": "NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT", "path": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT", "value": "NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT = 'Parameter `namespace`'"}} +{"id": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS", "text": "", "metadata": {"kind": "attribute", "name": "NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS", "path": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS", "value": "NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS = 'Please replace the parameter with `keyspace`. See https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5 for more information.'"}} +{"id": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "text": "", "metadata": {"kind": "attribute", "name": "SET_CALLER_DEPRECATION_NOTICE", "path": "astrapy.defaults.SET_CALLER_DEPRECATION_NOTICE", "value": "SET_CALLER_DEPRECATION_NOTICE = 'Please provide the caller(s) at constructor time through the `callers` list parameter.'"}} +{"id": "astrapy.defaults.CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS", "text": "", "metadata": {"kind": "attribute", "name": "CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS", "path": "astrapy.defaults.CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS", "value": "CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS = \"Please pass any caller identities as the `callers` constructor parameter: `callers=[('cname1', 'cversion1'), ('cname2', 'cversion2'), ...]`.\""}} +{"id": "astrapy.ids", "text": "", "metadata": {"kind": "module", "name": "ids", "path": "astrapy.ids", "imports": {"annotations": "__future__.annotations", "UUID": "uuid.UUID", "uuid1": "uuid.uuid1", "uuid3": "uuid.uuid3", "uuid4": "uuid.uuid4", "uuid5": "uuid.uuid5", "ObjectId": "bson.objectid.ObjectId", "uuid6": "uuid6.uuid6", "uuid7": "uuid6.uuid7", "uuid8": "uuid6.uuid8"}, "exports": ["uuid6", "uuid4", "uuid1", "uuid7", "UUID", "ObjectId", "uuid3", "uuid8", "uuid5"], "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.user_agents", "text": "", "metadata": {"kind": "module", "name": "user_agents", "path": "astrapy.user_agents", "imports": {"annotations": "__future__.annotations", "Sequence": "typing.Sequence", "__version__": "astrapy.__version__", "CallerType": "astrapy.constants.CallerType"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.user_agents.detect_astrapy_user_agent", "text": "", "metadata": {"kind": "function", "name": "detect_astrapy_user_agent", "path": "astrapy.user_agents.detect_astrapy_user_agent", "returns": [{"type": "CallerType"}], "gathered_types": ["astrapy.constants.CallerType"]}} +{"id": "astrapy.user_agents.compose_user_agent_string", "text": "", "metadata": {"kind": "function", "name": "compose_user_agent_string", "path": "astrapy.user_agents.compose_user_agent_string", "parameters": [{"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}], "returns": [{"type": "str | None"}]}} +{"id": "astrapy.user_agents.compose_full_user_agent", "text": "", "metadata": {"kind": "function", "name": "compose_full_user_agent", "path": "astrapy.user_agents.compose_full_user_agent", "parameters": [{"name": "callers", "type": "Sequence[CallerType]"}], "returns": [{"type": "str | None"}], "gathered_types": ["astrapy.constants.CallerType"]}} +{"id": "astrapy.api_commander", "text": "", "metadata": {"kind": "module", "name": "api_commander", "path": "astrapy.api_commander", "imports": {"annotations": "__future__.annotations", "json": "json", "logging": "logging", "TracebackType": "types.TracebackType", "TYPE_CHECKING": "typing.TYPE_CHECKING", "Any": "typing.Any", "Dict": "typing.Dict", "Iterable": "typing.Iterable", "Sequence": "typing.Sequence", "cast": "typing.cast", "httpx": "httpx", "CallerType": "astrapy.constants.CallerType", "DEFAULT_REDACTED_HEADER_NAMES": "astrapy.defaults.DEFAULT_REDACTED_HEADER_NAMES", "DEFAULT_REQUEST_TIMEOUT_MS": "astrapy.defaults.DEFAULT_REQUEST_TIMEOUT_MS", "HEADER_REDACT_PLACEHOLDER": "astrapy.defaults.HEADER_REDACT_PLACEHOLDER", "DataAPIFaultyResponseException": "astrapy.exceptions.DataAPIFaultyResponseException", "DataAPIHttpException": "astrapy.exceptions.DataAPIHttpException", "DataAPIResponseException": "astrapy.exceptions.DataAPIResponseException", "DevOpsAPIFaultyResponseException": "astrapy.exceptions.DevOpsAPIFaultyResponseException", "DevOpsAPIHttpException": "astrapy.exceptions.DevOpsAPIHttpException", "DevOpsAPIResponseException": "astrapy.exceptions.DevOpsAPIResponseException", "to_dataapi_timeout_exception": "astrapy.exceptions.to_dataapi_timeout_exception", "to_devopsapi_timeout_exception": "astrapy.exceptions.to_devopsapi_timeout_exception", "HttpMethod": "astrapy.request_tools.HttpMethod", "log_httpx_request": "astrapy.request_tools.log_httpx_request", "log_httpx_response": "astrapy.request_tools.log_httpx_response", "to_httpx_timeout": "astrapy.request_tools.to_httpx_timeout", "normalize_for_api": "astrapy.transform_payload.normalize_for_api", "restore_from_api": "astrapy.transform_payload.restore_from_api", "compose_full_user_agent": "astrapy.user_agents.compose_full_user_agent", "detect_astrapy_user_agent": "astrapy.user_agents.detect_astrapy_user_agent", "TimeoutInfoWideType": "astrapy.request_tools.TimeoutInfoWideType"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.api_commander.user_agent_astrapy", "text": "", "metadata": {"kind": "attribute", "name": "user_agent_astrapy", "path": "astrapy.api_commander.user_agent_astrapy", "value": "user_agent_astrapy = detect_astrapy_user_agent()"}} +{"id": "astrapy.api_commander.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.api_commander.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.api_commander.APICommander", "text": "", "metadata": {"kind": "class", "name": "APICommander", "path": "astrapy.api_commander.APICommander", "parameters": [{"name": "api_endpoint", "type": "str"}, {"name": "path", "type": "str"}, {"name": "headers", "default": "{}", "type": "dict[str, str | None]"}, {"name": "callers", "default": "[]", "type": "Sequence[CallerType]"}, {"name": "redacted_header_names", "default": "DEFAULT_REDACTED_HEADER_NAMES", "type": "Iterable[str]"}, {"name": "dev_ops_api", "default": "False", "type": "bool"}], "gathered_types": ["astrapy.defaults.DEFAULT_REDACTED_HEADER_NAMES", "astrapy.constants.CallerType"]}} +{"id": "astrapy.api_commander.APICommander.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.api_commander.APICommander.client", "value": "client = httpx.Client()", "gathered_types": ["Client"]}} +{"id": "astrapy.api_commander.APICommander.async_client", "text": "", "metadata": {"kind": "attribute", "name": "async_client", "path": "astrapy.api_commander.APICommander.async_client", "value": "async_client = httpx.AsyncClient()", "gathered_types": ["AsyncClient"]}} +{"id": "astrapy.api_commander.APICommander.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.api_commander.APICommander.api_endpoint", "value": "api_endpoint = api_endpoint.rstrip('/')"}} +{"id": "astrapy.api_commander.APICommander.path", "text": "", "metadata": {"kind": "attribute", "name": "path", "path": "astrapy.api_commander.APICommander.path", "value": "path = path.lstrip('/')"}} +{"id": "astrapy.api_commander.APICommander.headers", "text": "", "metadata": {"kind": "attribute", "name": "headers", "path": "astrapy.api_commander.APICommander.headers", "value": "headers = headers"}} +{"id": "astrapy.api_commander.APICommander.callers", "text": "", "metadata": {"kind": "attribute", "name": "callers", "path": "astrapy.api_commander.APICommander.callers", "value": "callers = callers"}} +{"id": "astrapy.api_commander.APICommander.redacted_header_names", "text": "", "metadata": {"kind": "attribute", "name": "redacted_header_names", "path": "astrapy.api_commander.APICommander.redacted_header_names", "value": "redacted_header_names = set(redacted_header_names)"}} +{"id": "astrapy.api_commander.APICommander.dev_ops_api", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_api", "path": "astrapy.api_commander.APICommander.dev_ops_api", "value": "dev_ops_api = dev_ops_api"}} +{"id": "astrapy.api_commander.APICommander.caller_header", "text": "", "metadata": {"kind": "attribute", "name": "caller_header", "path": "astrapy.api_commander.APICommander.caller_header", "value": "caller_header: dict[str, str] = {'User-Agent': full_user_agent_string} if full_user_agent_string else {}"}} +{"id": "astrapy.api_commander.APICommander.full_headers", "text": "", "metadata": {"kind": "attribute", "name": "full_headers", "path": "astrapy.api_commander.APICommander.full_headers", "value": "full_headers: dict[str, str] = {None: {k: vfor (k, v) in self.headers.items() if v is not None}, None: self.caller_header, None: {'Content-Type': 'application/json'}}"}} +{"id": "astrapy.api_commander.APICommander.full_path", "text": "", "metadata": {"kind": "attribute", "name": "full_path", "path": "astrapy.api_commander.APICommander.full_path", "value": "full_path = '/'.join([self.api_endpoint, self.path]).rstrip('/')"}} +{"id": "astrapy.api_commander.APICommander.raw_request", "text": "", "metadata": {"kind": "function", "name": "raw_request", "path": "astrapy.api_commander.APICommander.raw_request", "parameters": [{"name": "http_method", "default": "HttpMethod.POST", "type": "str"}, {"name": "payload", "default": "None", "type": "dict[str, Any] | None"}, {"name": "additional_path", "default": "None", "type": "str | None"}, {"name": "request_params", "default": "{}", "type": "dict[str, Any]"}, {"name": "raise_api_errors", "default": "True", "type": "bool"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "httpx.Response"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.request_tools.HttpMethod", "POST", "Response"]}} +{"id": "astrapy.api_commander.APICommander.async_raw_request", "text": "", "metadata": {"kind": "function", "name": "async_raw_request", "path": "astrapy.api_commander.APICommander.async_raw_request", "parameters": [{"name": "http_method", "default": "HttpMethod.POST", "type": "str"}, {"name": "payload", "default": "None", "type": "dict[str, Any] | None"}, {"name": "additional_path", "default": "None", "type": "str | None"}, {"name": "request_params", "default": "{}", "type": "dict[str, Any]"}, {"name": "raise_api_errors", "default": "True", "type": "bool"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "httpx.Response"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.request_tools.HttpMethod", "POST", "Response"]}} +{"id": "astrapy.api_commander.APICommander.request", "text": "", "metadata": {"kind": "function", "name": "request", "path": "astrapy.api_commander.APICommander.request", "parameters": [{"name": "http_method", "default": "HttpMethod.POST", "type": "str"}, {"name": "payload", "default": "None", "type": "dict[str, Any] | None"}, {"name": "additional_path", "default": "None", "type": "str | None"}, {"name": "request_params", "default": "{}", "type": "dict[str, Any]"}, {"name": "raise_api_errors", "default": "True", "type": "bool"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "dict[str, Any]"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.request_tools.HttpMethod", "POST"]}} +{"id": "astrapy.api_commander.APICommander.async_request", "text": "", "metadata": {"kind": "function", "name": "async_request", "path": "astrapy.api_commander.APICommander.async_request", "parameters": [{"name": "http_method", "default": "HttpMethod.POST", "type": "str"}, {"name": "payload", "default": "None", "type": "dict[str, Any] | None"}, {"name": "additional_path", "default": "None", "type": "str | None"}, {"name": "request_params", "default": "{}", "type": "dict[str, Any]"}, {"name": "raise_api_errors", "default": "True", "type": "bool"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "dict[str, Any]"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.request_tools.HttpMethod", "POST"]}} +{"id": "astrapy.info", "text": "", "metadata": {"kind": "module", "name": "info", "path": "astrapy.info", "imports": {"annotations": "__future__.annotations", "warnings": "warnings", "dataclass": "dataclasses.dataclass", "Any": "typing.Any"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.info.DatabaseInfo", "text": "Represents the identifying information for a database,\nincluding the region the connection is established to.", "metadata": {"kind": "class", "name": "DatabaseInfo", "path": "astrapy.info.DatabaseInfo", "parameters": [{"name": "id", "type": "str"}, {"name": "region", "type": "str"}, {"name": "keyspace", "type": "str | None"}, {"name": "namespace", "type": "str | None"}, {"name": "name", "type": "str"}, {"name": "environment", "type": "str"}, {"name": "raw_info", "type": "dict[str, Any] | None"}], "attributes": [{"name": "id", "type": "str", "description": "the database ID."}, {"name": "region", "type": "str", "description": "the ID of the region through which the connection to DB is done."}, {"name": "keyspace", "type": "str | None", "description": "the namespace this DB is set to work with. None if not set."}, {"name": "namespace", "type": "str | None", "description": "an alias for 'keyspace'. *DEPRECATED*, removal in 2.0"}, {"name": "name", "type": "str", "description": "the database name. Not necessarily unique: there can be multiple\ndatabases with the same name."}, {"name": "environment", "type": "str", "description": "a label, whose value can be `Environment.PROD`,\nor another value in `Environment.*`."}, {"name": "raw_info", "type": "dict[str, Any] | None", "description": "the full response from the DevOPS API call to get this info."}], "note": "The `raw_info` dictionary usually has a `region` key describing\nthe default region as configured in the database, which does not\nnecessarily (for multi-region databases) match the region through\nwhich the connection is established: the latter is the one specified\nby the \"api endpoint\" used for connecting. In other words, for multi-region\ndatabases it is possible that\n database_info.region != database_info.raw_info[\"region\"]\nConversely, in case of a DatabaseInfo not obtained through a\nconnected database, such as when calling `Admin.list_databases()`,\nall fields except `environment` (e.g. keyspace, region, etc)\nare set as found on the DevOps API response directly."}} +{"id": "astrapy.info.DatabaseInfo.id", "text": "", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.info.DatabaseInfo.id", "value": "id: str"}} +{"id": "astrapy.info.DatabaseInfo.region", "text": "", "metadata": {"kind": "attribute", "name": "region", "path": "astrapy.info.DatabaseInfo.region", "value": "region: str"}} +{"id": "astrapy.info.DatabaseInfo.keyspace", "text": "", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.info.DatabaseInfo.keyspace", "value": "keyspace: str | None"}} +{"id": "astrapy.info.DatabaseInfo.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.info.DatabaseInfo.namespace", "value": "namespace: str | None"}} +{"id": "astrapy.info.DatabaseInfo.name", "text": "", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.info.DatabaseInfo.name", "value": "name: str"}} +{"id": "astrapy.info.DatabaseInfo.environment", "text": "", "metadata": {"kind": "attribute", "name": "environment", "path": "astrapy.info.DatabaseInfo.environment", "value": "environment: str"}} +{"id": "astrapy.info.DatabaseInfo.raw_info", "text": "", "metadata": {"kind": "attribute", "name": "raw_info", "path": "astrapy.info.DatabaseInfo.raw_info", "value": "raw_info: dict[str, Any] | None"}} +{"id": "astrapy.info.AdminDatabaseInfo", "text": "Represents the full response from the DevOps API about a database info.\n\nMost attributes just contain the corresponding part of the raw response:\nfor this reason, please consult the DevOps API documentation for details.", "metadata": {"kind": "class", "name": "AdminDatabaseInfo", "path": "astrapy.info.AdminDatabaseInfo", "parameters": [{"name": "info", "type": "DatabaseInfo"}, {"name": "available_actions", "type": "list[str] | None"}, {"name": "cost", "type": "dict[str, Any]"}, {"name": "cqlsh_url", "type": "str"}, {"name": "creation_time", "type": "str"}, {"name": "data_endpoint_url", "type": "str"}, {"name": "grafana_url", "type": "str"}, {"name": "graphql_url", "type": "str"}, {"name": "id", "type": "str"}, {"name": "last_usage_time", "type": "str"}, {"name": "metrics", "type": "dict[str, Any]"}, {"name": "observed_status", "type": "str"}, {"name": "org_id", "type": "str"}, {"name": "owner_id", "type": "str"}, {"name": "status", "type": "str"}, {"name": "storage", "type": "dict[str, Any]"}, {"name": "termination_time", "type": "str"}, {"name": "raw_info", "type": "dict[str, Any] | None"}], "attributes": [{"name": "info", "type": "DatabaseInfo", "description": "a DatabaseInfo instance for the underlying database.\nThe DatabaseInfo is a subset of the information described by\nAdminDatabaseInfo - in terms of the DevOps API response,\nit corresponds to just its \"info\" subdictionary."}, {"name": "available_actions", "type": "list[str] | None", "description": "the \"availableActions\" value in the full API response."}, {"name": "cost", "type": "dict[str, Any]", "description": "the \"cost\" value in the full API response."}, {"name": "cqlsh_url", "type": "str", "description": "the \"cqlshUrl\" value in the full API response."}, {"name": "creation_time", "type": "str", "description": "the \"creationTime\" value in the full API response."}, {"name": "data_endpoint_url", "type": "str", "description": "the \"dataEndpointUrl\" value in the full API response."}, {"name": "grafana_url", "type": "str", "description": "the \"grafanaUrl\" value in the full API response."}, {"name": "graphql_url", "type": "str", "description": "the \"graphqlUrl\" value in the full API response."}, {"name": "id", "type": "str", "description": "the \"id\" value in the full API response."}, {"name": "last_usage_time", "type": "str", "description": "the \"lastUsageTime\" value in the full API response."}, {"name": "metrics", "type": "dict[str, Any]", "description": "the \"metrics\" value in the full API response."}, {"name": "observed_status", "type": "str", "description": "the \"observedStatus\" value in the full API response."}, {"name": "org_id", "type": "str", "description": "the \"orgId\" value in the full API response."}, {"name": "owner_id", "type": "str", "description": "the \"ownerId\" value in the full API response."}, {"name": "status", "type": "str", "description": "the \"status\" value in the full API response."}, {"name": "storage", "type": "dict[str, Any]", "description": "the \"storage\" value in the full API response."}, {"name": "termination_time", "type": "str", "description": "the \"terminationTime\" value in the full API response."}, {"name": "raw_info", "type": "dict[str, Any] | None", "description": "the full raw response from the DevOps API."}], "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.info.AdminDatabaseInfo.info", "text": "", "metadata": {"kind": "attribute", "name": "info", "path": "astrapy.info.AdminDatabaseInfo.info", "value": "info: DatabaseInfo", "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.info.AdminDatabaseInfo.available_actions", "text": "", "metadata": {"kind": "attribute", "name": "available_actions", "path": "astrapy.info.AdminDatabaseInfo.available_actions", "value": "available_actions: list[str] | None"}} +{"id": "astrapy.info.AdminDatabaseInfo.cost", "text": "", "metadata": {"kind": "attribute", "name": "cost", "path": "astrapy.info.AdminDatabaseInfo.cost", "value": "cost: dict[str, Any]"}} +{"id": "astrapy.info.AdminDatabaseInfo.cqlsh_url", "text": "", "metadata": {"kind": "attribute", "name": "cqlsh_url", "path": "astrapy.info.AdminDatabaseInfo.cqlsh_url", "value": "cqlsh_url: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.creation_time", "text": "", "metadata": {"kind": "attribute", "name": "creation_time", "path": "astrapy.info.AdminDatabaseInfo.creation_time", "value": "creation_time: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.data_endpoint_url", "text": "", "metadata": {"kind": "attribute", "name": "data_endpoint_url", "path": "astrapy.info.AdminDatabaseInfo.data_endpoint_url", "value": "data_endpoint_url: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.grafana_url", "text": "", "metadata": {"kind": "attribute", "name": "grafana_url", "path": "astrapy.info.AdminDatabaseInfo.grafana_url", "value": "grafana_url: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.graphql_url", "text": "", "metadata": {"kind": "attribute", "name": "graphql_url", "path": "astrapy.info.AdminDatabaseInfo.graphql_url", "value": "graphql_url: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.id", "text": "", "metadata": {"kind": "attribute", "name": "id", "path": "astrapy.info.AdminDatabaseInfo.id", "value": "id: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.last_usage_time", "text": "", "metadata": {"kind": "attribute", "name": "last_usage_time", "path": "astrapy.info.AdminDatabaseInfo.last_usage_time", "value": "last_usage_time: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.metrics", "text": "", "metadata": {"kind": "attribute", "name": "metrics", "path": "astrapy.info.AdminDatabaseInfo.metrics", "value": "metrics: dict[str, Any]"}} +{"id": "astrapy.info.AdminDatabaseInfo.observed_status", "text": "", "metadata": {"kind": "attribute", "name": "observed_status", "path": "astrapy.info.AdminDatabaseInfo.observed_status", "value": "observed_status: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.org_id", "text": "", "metadata": {"kind": "attribute", "name": "org_id", "path": "astrapy.info.AdminDatabaseInfo.org_id", "value": "org_id: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.owner_id", "text": "", "metadata": {"kind": "attribute", "name": "owner_id", "path": "astrapy.info.AdminDatabaseInfo.owner_id", "value": "owner_id: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.status", "text": "", "metadata": {"kind": "attribute", "name": "status", "path": "astrapy.info.AdminDatabaseInfo.status", "value": "status: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.storage", "text": "", "metadata": {"kind": "attribute", "name": "storage", "path": "astrapy.info.AdminDatabaseInfo.storage", "value": "storage: dict[str, Any]"}} +{"id": "astrapy.info.AdminDatabaseInfo.termination_time", "text": "", "metadata": {"kind": "attribute", "name": "termination_time", "path": "astrapy.info.AdminDatabaseInfo.termination_time", "value": "termination_time: str"}} +{"id": "astrapy.info.AdminDatabaseInfo.raw_info", "text": "", "metadata": {"kind": "attribute", "name": "raw_info", "path": "astrapy.info.AdminDatabaseInfo.raw_info", "value": "raw_info: dict[str, Any] | None"}} +{"id": "astrapy.info.CollectionInfo", "text": "Represents the identifying information for a collection,\nincluding the information about the database the collection belongs to.", "metadata": {"kind": "class", "name": "CollectionInfo", "path": "astrapy.info.CollectionInfo", "parameters": [{"name": "database_info", "type": "DatabaseInfo"}, {"name": "keyspace", "type": "str"}, {"name": "namespace", "type": "str"}, {"name": "name", "type": "str"}, {"name": "full_name", "type": "str"}], "attributes": [{"name": "database_info", "type": "DatabaseInfo", "description": "a DatabaseInfo instance for the underlying database."}, {"name": "keyspace", "type": "str", "description": "the keyspace where the collection is located."}, {"name": "namespace", "type": "str", "description": "an alias for 'keyspace'. *DEPRECATED*, removal in 2.0"}, {"name": "name", "type": "str", "description": "collection name. Unique within a keyspace."}, {"name": "full_name", "type": "str", "description": "identifier for the collection within the database,\nin the form \"keyspace.collection_name\"."}], "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.info.CollectionInfo.database_info", "text": "", "metadata": {"kind": "attribute", "name": "database_info", "path": "astrapy.info.CollectionInfo.database_info", "value": "database_info: DatabaseInfo", "gathered_types": ["astrapy.info.DatabaseInfo"]}} +{"id": "astrapy.info.CollectionInfo.keyspace", "text": "", "metadata": {"kind": "attribute", "name": "keyspace", "path": "astrapy.info.CollectionInfo.keyspace", "value": "keyspace: str"}} +{"id": "astrapy.info.CollectionInfo.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.info.CollectionInfo.namespace", "value": "namespace: str"}} +{"id": "astrapy.info.CollectionInfo.name", "text": "", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.info.CollectionInfo.name", "value": "name: str"}} +{"id": "astrapy.info.CollectionInfo.full_name", "text": "", "metadata": {"kind": "attribute", "name": "full_name", "path": "astrapy.info.CollectionInfo.full_name", "value": "full_name: str"}} +{"id": "astrapy.info.CollectionDefaultIDOptions", "text": "The \"defaultId\" component of the collection options.\nSee the Data API specifications for allowed values.", "metadata": {"kind": "class", "name": "CollectionDefaultIDOptions", "path": "astrapy.info.CollectionDefaultIDOptions", "parameters": [{"name": "default_id_type", "type": "str"}], "attributes": [{"name": "default_id_type", "type": "str", "description": "string such as `objectId`, `uuid6` and so on."}]}} +{"id": "astrapy.info.CollectionDefaultIDOptions.default_id_type", "text": "", "metadata": {"kind": "attribute", "name": "default_id_type", "path": "astrapy.info.CollectionDefaultIDOptions.default_id_type", "value": "default_id_type: str"}} +{"id": "astrapy.info.CollectionDefaultIDOptions.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.CollectionDefaultIDOptions.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionDefaultIDOptions.from_dict", "text": "Create an instance of CollectionDefaultIDOptions from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.CollectionDefaultIDOptions.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any] | None"}], "returns": [{"type": "CollectionDefaultIDOptions | None"}], "gathered_types": ["CollectionDefaultIDOptions"]}} +{"id": "astrapy.info.CollectionVectorServiceOptions", "text": "The \"vector.service\" component of the collection options.\nSee the Data API specifications for allowed values.", "metadata": {"kind": "class", "name": "CollectionVectorServiceOptions", "path": "astrapy.info.CollectionVectorServiceOptions", "parameters": [{"name": "provider", "type": "str | None"}, {"name": "model_name", "type": "str | None"}, {"name": "authentication", "default": "None", "type": "dict[str, Any] | None"}, {"name": "parameters", "default": "None", "type": "dict[str, Any] | None"}], "attributes": [{"name": "provider", "type": "str | None", "description": "the name of a service provider for embedding calculation."}, {"name": "model_name", "type": "str | None", "description": "the name of a specific model for use by the service."}, {"name": "authentication", "type": "dict[str, Any] | None", "description": "a key-value dictionary for the \"authentication\" specification,\nif any, in the vector service options."}, {"name": "parameters", "type": "dict[str, Any] | None", "description": "a key-value dictionary for the \"parameters\" specification, if any,\nin the vector service options."}]}} +{"id": "astrapy.info.CollectionVectorServiceOptions.provider", "text": "", "metadata": {"kind": "attribute", "name": "provider", "path": "astrapy.info.CollectionVectorServiceOptions.provider", "value": "provider: str | None"}} +{"id": "astrapy.info.CollectionVectorServiceOptions.model_name", "text": "", "metadata": {"kind": "attribute", "name": "model_name", "path": "astrapy.info.CollectionVectorServiceOptions.model_name", "value": "model_name: str | None"}} +{"id": "astrapy.info.CollectionVectorServiceOptions.authentication", "text": "", "metadata": {"kind": "attribute", "name": "authentication", "path": "astrapy.info.CollectionVectorServiceOptions.authentication", "value": "authentication: dict[str, Any] | None = None"}} +{"id": "astrapy.info.CollectionVectorServiceOptions.parameters", "text": "", "metadata": {"kind": "attribute", "name": "parameters", "path": "astrapy.info.CollectionVectorServiceOptions.parameters", "value": "parameters: dict[str, Any] | None = None"}} +{"id": "astrapy.info.CollectionVectorServiceOptions.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.CollectionVectorServiceOptions.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionVectorServiceOptions.from_dict", "text": "Create an instance of CollectionVectorServiceOptions from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.CollectionVectorServiceOptions.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any] | None"}], "returns": [{"type": "CollectionVectorServiceOptions | None"}], "gathered_types": ["astrapy.info.CollectionVectorServiceOptions"]}} +{"id": "astrapy.info.CollectionVectorOptions", "text": "The \"vector\" component of the collection options.\nSee the Data API specifications for allowed values.", "metadata": {"kind": "class", "name": "CollectionVectorOptions", "path": "astrapy.info.CollectionVectorOptions", "parameters": [{"name": "dimension", "type": "int | None"}, {"name": "metric", "type": "str | None"}, {"name": "service", "type": "CollectionVectorServiceOptions | None"}], "attributes": [{"name": "dimension", "type": "int | None", "description": "an optional positive integer, the dimensionality of the vector space."}, {"name": "metric", "type": "str | None", "description": "an optional metric among `VectorMetric.DOT_PRODUCT`,\n`VectorMetric.EUCLIDEAN` and `VectorMetric.COSINE`."}, {"name": "service", "type": "CollectionVectorServiceOptions | None", "description": "an optional CollectionVectorServiceOptions object in case a\nservice is configured for the collection."}], "gathered_types": ["astrapy.info.CollectionVectorServiceOptions"]}} +{"id": "astrapy.info.CollectionVectorOptions.dimension", "text": "", "metadata": {"kind": "attribute", "name": "dimension", "path": "astrapy.info.CollectionVectorOptions.dimension", "value": "dimension: int | None"}} +{"id": "astrapy.info.CollectionVectorOptions.metric", "text": "", "metadata": {"kind": "attribute", "name": "metric", "path": "astrapy.info.CollectionVectorOptions.metric", "value": "metric: str | None"}} +{"id": "astrapy.info.CollectionVectorOptions.service", "text": "", "metadata": {"kind": "attribute", "name": "service", "path": "astrapy.info.CollectionVectorOptions.service", "value": "service: CollectionVectorServiceOptions | None", "gathered_types": ["astrapy.info.CollectionVectorServiceOptions"]}} +{"id": "astrapy.info.CollectionVectorOptions.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.CollectionVectorOptions.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionVectorOptions.from_dict", "text": "Create an instance of CollectionVectorOptions from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.CollectionVectorOptions.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any] | None"}], "returns": [{"type": "CollectionVectorOptions | None"}], "gathered_types": ["CollectionVectorOptions"]}} +{"id": "astrapy.info.CollectionOptions", "text": "A structure expressing the options of a collection.\nSee the Data API specifications for detailed specification and allowed values.", "metadata": {"kind": "class", "name": "CollectionOptions", "path": "astrapy.info.CollectionOptions", "parameters": [{"name": "vector", "type": "CollectionVectorOptions | None"}, {"name": "indexing", "type": "dict[str, Any] | None"}, {"name": "default_id", "type": "CollectionDefaultIDOptions | None"}, {"name": "raw_options", "type": "dict[str, Any] | None"}], "attributes": [{"name": "vector", "type": "CollectionVectorOptions | None", "description": "an optional CollectionVectorOptions object."}, {"name": "indexing", "type": "dict[str, Any] | None", "description": "an optional dictionary with the \"indexing\" collection properties."}, {"name": "default_id", "type": "CollectionDefaultIDOptions | None", "description": "an optional CollectionDefaultIDOptions object."}, {"name": "raw_options", "type": "dict[str, Any] | None", "description": "the raw response from the Data API for the collection configuration."}], "gathered_types": ["CollectionVectorOptions", "CollectionDefaultIDOptions"]}} +{"id": "astrapy.info.CollectionOptions.vector", "text": "", "metadata": {"kind": "attribute", "name": "vector", "path": "astrapy.info.CollectionOptions.vector", "value": "vector: CollectionVectorOptions | None", "gathered_types": ["CollectionVectorOptions"]}} +{"id": "astrapy.info.CollectionOptions.indexing", "text": "", "metadata": {"kind": "attribute", "name": "indexing", "path": "astrapy.info.CollectionOptions.indexing", "value": "indexing: dict[str, Any] | None"}} +{"id": "astrapy.info.CollectionOptions.default_id", "text": "", "metadata": {"kind": "attribute", "name": "default_id", "path": "astrapy.info.CollectionOptions.default_id", "value": "default_id: CollectionDefaultIDOptions | None", "gathered_types": ["CollectionDefaultIDOptions"]}} +{"id": "astrapy.info.CollectionOptions.raw_options", "text": "", "metadata": {"kind": "attribute", "name": "raw_options", "path": "astrapy.info.CollectionOptions.raw_options", "value": "raw_options: dict[str, Any] | None"}} +{"id": "astrapy.info.CollectionOptions.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.CollectionOptions.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionOptions.flatten", "text": "Recast this object as a flat key-value pair suitable for\nuse as kwargs in a create_collection method call (including recasts).", "metadata": {"kind": "function", "name": "flatten", "path": "astrapy.info.CollectionOptions.flatten", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionOptions.from_dict", "text": "Create an instance of CollectionOptions from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.CollectionOptions.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "CollectionOptions"}], "gathered_types": ["astrapy.info.CollectionOptions"]}} +{"id": "astrapy.info.CollectionDescriptor", "text": "A structure expressing full description of a collection as the Data API\nreturns it, i.e. its name and its `options` sub-structure.", "metadata": {"kind": "class", "name": "CollectionDescriptor", "path": "astrapy.info.CollectionDescriptor", "parameters": [{"name": "name", "type": "str"}, {"name": "options", "type": "CollectionOptions"}, {"name": "raw_descriptor", "type": "dict[str, Any] | None"}], "attributes": [{"name": "name", "type": "str", "description": "the name of the collection."}, {"name": "options", "type": "CollectionOptions", "description": "a CollectionOptions instance."}, {"name": "raw_descriptor", "type": "dict[str, Any] | None", "description": "the raw response from the Data API."}], "gathered_types": ["astrapy.info.CollectionOptions"]}} +{"id": "astrapy.info.CollectionDescriptor.name", "text": "", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.info.CollectionDescriptor.name", "value": "name: str"}} +{"id": "astrapy.info.CollectionDescriptor.options", "text": "", "metadata": {"kind": "attribute", "name": "options", "path": "astrapy.info.CollectionDescriptor.options", "value": "options: CollectionOptions", "gathered_types": ["astrapy.info.CollectionOptions"]}} +{"id": "astrapy.info.CollectionDescriptor.raw_descriptor", "text": "", "metadata": {"kind": "attribute", "name": "raw_descriptor", "path": "astrapy.info.CollectionDescriptor.raw_descriptor", "value": "raw_descriptor: dict[str, Any] | None"}} +{"id": "astrapy.info.CollectionDescriptor.as_dict", "text": "Recast this object into a dictionary.\nEmpty `options` will not be returned at all.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.CollectionDescriptor.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionDescriptor.flatten", "text": "Recast this object as a flat key-value pair suitable for\nuse as kwargs in a create_collection method call (including recasts).", "metadata": {"kind": "function", "name": "flatten", "path": "astrapy.info.CollectionDescriptor.flatten", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.CollectionDescriptor.from_dict", "text": "Create an instance of CollectionDescriptor from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.CollectionDescriptor.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "CollectionDescriptor"}], "gathered_types": ["astrapy.info.CollectionDescriptor"]}} +{"id": "astrapy.info.EmbeddingProviderParameter", "text": "A representation of a parameter as returned by the 'findEmbeddingProviders'\nData API endpoint.", "metadata": {"kind": "class", "name": "EmbeddingProviderParameter", "path": "astrapy.info.EmbeddingProviderParameter", "parameters": [{"name": "default_value", "type": "Any"}, {"name": "display_name", "type": "str | None"}, {"name": "help", "type": "str | None"}, {"name": "hint", "type": "str | None"}, {"name": "name", "type": "str"}, {"name": "required", "type": "bool"}, {"name": "parameter_type", "type": "str"}, {"name": "validation", "type": "dict[str, Any]"}], "attributes": [{"name": "default_value", "type": "Any", "description": "the default value for the parameter."}, {"name": "help", "type": "str | None", "description": "a textual description of the parameter."}, {"name": "name", "type": "str", "description": "the name to use when passing the parameter for vectorize operations."}, {"name": "required", "type": "bool", "description": "whether the parameter is required or not."}, {"name": "parameter_type", "type": "str", "description": "a textual description of the data type for the parameter."}, {"name": "validation", "type": "dict[str, Any]", "description": "a dictionary describing a parameter-specific validation policy."}]}} +{"id": "astrapy.info.EmbeddingProviderParameter.default_value", "text": "", "metadata": {"kind": "attribute", "name": "default_value", "path": "astrapy.info.EmbeddingProviderParameter.default_value", "value": "default_value: Any"}} +{"id": "astrapy.info.EmbeddingProviderParameter.display_name", "text": "", "metadata": {"kind": "attribute", "name": "display_name", "path": "astrapy.info.EmbeddingProviderParameter.display_name", "value": "display_name: str | None"}} +{"id": "astrapy.info.EmbeddingProviderParameter.help", "text": "", "metadata": {"kind": "attribute", "name": "help", "path": "astrapy.info.EmbeddingProviderParameter.help", "value": "help: str | None"}} +{"id": "astrapy.info.EmbeddingProviderParameter.hint", "text": "", "metadata": {"kind": "attribute", "name": "hint", "path": "astrapy.info.EmbeddingProviderParameter.hint", "value": "hint: str | None"}} +{"id": "astrapy.info.EmbeddingProviderParameter.name", "text": "", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.info.EmbeddingProviderParameter.name", "value": "name: str"}} +{"id": "astrapy.info.EmbeddingProviderParameter.required", "text": "", "metadata": {"kind": "attribute", "name": "required", "path": "astrapy.info.EmbeddingProviderParameter.required", "value": "required: bool"}} +{"id": "astrapy.info.EmbeddingProviderParameter.parameter_type", "text": "", "metadata": {"kind": "attribute", "name": "parameter_type", "path": "astrapy.info.EmbeddingProviderParameter.parameter_type", "value": "parameter_type: str"}} +{"id": "astrapy.info.EmbeddingProviderParameter.validation", "text": "", "metadata": {"kind": "attribute", "name": "validation", "path": "astrapy.info.EmbeddingProviderParameter.validation", "value": "validation: dict[str, Any]"}} +{"id": "astrapy.info.EmbeddingProviderParameter.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.EmbeddingProviderParameter.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.EmbeddingProviderParameter.from_dict", "text": "Create an instance of EmbeddingProviderParameter from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.EmbeddingProviderParameter.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "EmbeddingProviderParameter"}], "gathered_types": ["EmbeddingProviderParameter"]}} +{"id": "astrapy.info.EmbeddingProviderModel", "text": "A representation of an embedding model as returned by the 'findEmbeddingProviders'\nData API endpoint.", "metadata": {"kind": "class", "name": "EmbeddingProviderModel", "path": "astrapy.info.EmbeddingProviderModel", "parameters": [{"name": "name", "type": "str"}, {"name": "parameters", "type": "list[EmbeddingProviderParameter]"}, {"name": "vector_dimension", "type": "int | None"}], "attributes": [{"name": "name", "type": "str", "description": "the model name as must be passed when issuing\nvectorize operations to the API."}, {"name": "parameters", "type": "list[EmbeddingProviderParameter]", "description": "a list of the `EmbeddingProviderParameter` objects the model admits."}, {"name": "vector_dimension", "type": "int | None", "description": "an integer for the dimensionality of the embedding model.\nif this is None, the dimension can assume multiple values as specified\nby a corresponding parameter listed with the model."}], "gathered_types": ["EmbeddingProviderParameter"]}} +{"id": "astrapy.info.EmbeddingProviderModel.name", "text": "", "metadata": {"kind": "attribute", "name": "name", "path": "astrapy.info.EmbeddingProviderModel.name", "value": "name: str"}} +{"id": "astrapy.info.EmbeddingProviderModel.parameters", "text": "", "metadata": {"kind": "attribute", "name": "parameters", "path": "astrapy.info.EmbeddingProviderModel.parameters", "value": "parameters: list[EmbeddingProviderParameter]", "gathered_types": ["EmbeddingProviderParameter"]}} +{"id": "astrapy.info.EmbeddingProviderModel.vector_dimension", "text": "", "metadata": {"kind": "attribute", "name": "vector_dimension", "path": "astrapy.info.EmbeddingProviderModel.vector_dimension", "value": "vector_dimension: int | None"}} +{"id": "astrapy.info.EmbeddingProviderModel.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.EmbeddingProviderModel.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.EmbeddingProviderModel.from_dict", "text": "Create an instance of EmbeddingProviderModel from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.EmbeddingProviderModel.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "EmbeddingProviderModel"}], "gathered_types": ["EmbeddingProviderModel"]}} +{"id": "astrapy.info.EmbeddingProviderToken", "text": "A representation of a \"token\", that is a specific secret string, needed by\nan embedding model; this models a part of the response from the\n'findEmbeddingProviders' Data API endpoint.", "metadata": {"kind": "class", "name": "EmbeddingProviderToken", "path": "astrapy.info.EmbeddingProviderToken", "parameters": [{"name": "accepted", "type": "str"}, {"name": "forwarded", "type": "str"}], "attributes": [{"name": "accepted", "type": "str", "description": "the name of this \"token\" as seen by the Data API. This is the\nname that should be used in the clients when supplying the secret,\nwhether as header or by shared-secret."}, {"name": "forwarded", "type": "str", "description": "the name used by the API when issuing the embedding request\nto the embedding provider. This is of no direct interest for the Data API user."}]}} +{"id": "astrapy.info.EmbeddingProviderToken.accepted", "text": "", "metadata": {"kind": "attribute", "name": "accepted", "path": "astrapy.info.EmbeddingProviderToken.accepted", "value": "accepted: str"}} +{"id": "astrapy.info.EmbeddingProviderToken.forwarded", "text": "", "metadata": {"kind": "attribute", "name": "forwarded", "path": "astrapy.info.EmbeddingProviderToken.forwarded", "value": "forwarded: str"}} +{"id": "astrapy.info.EmbeddingProviderToken.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.EmbeddingProviderToken.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.EmbeddingProviderToken.from_dict", "text": "Create an instance of EmbeddingProviderToken from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.EmbeddingProviderToken.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "EmbeddingProviderToken"}], "gathered_types": ["EmbeddingProviderToken"]}} +{"id": "astrapy.info.EmbeddingProviderAuthentication", "text": "A representation of an authentication mode for using an embedding model,\nmodeling the corresponding part of the response returned by the\n'findEmbeddingProviders' Data API endpoint (namely \"supportedAuthentication\").", "metadata": {"kind": "class", "name": "EmbeddingProviderAuthentication", "path": "astrapy.info.EmbeddingProviderAuthentication", "parameters": [{"name": "enabled", "type": "bool"}, {"name": "tokens", "type": "list[EmbeddingProviderToken]"}], "attributes": [{"name": "enabled", "type": "bool", "description": "whether this authentication mode is available for a given model."}, {"name": "tokens", "type": "list[EmbeddingProviderToken]", "description": "a list of `EmbeddingProviderToken` objects,\ndetailing the secrets required for the authentication mode."}], "gathered_types": ["EmbeddingProviderToken"]}} +{"id": "astrapy.info.EmbeddingProviderAuthentication.enabled", "text": "", "metadata": {"kind": "attribute", "name": "enabled", "path": "astrapy.info.EmbeddingProviderAuthentication.enabled", "value": "enabled: bool"}} +{"id": "astrapy.info.EmbeddingProviderAuthentication.tokens", "text": "", "metadata": {"kind": "attribute", "name": "tokens", "path": "astrapy.info.EmbeddingProviderAuthentication.tokens", "value": "tokens: list[EmbeddingProviderToken]", "gathered_types": ["EmbeddingProviderToken"]}} +{"id": "astrapy.info.EmbeddingProviderAuthentication.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.EmbeddingProviderAuthentication.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.EmbeddingProviderAuthentication.from_dict", "text": "Create an instance of EmbeddingProviderAuthentication from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.EmbeddingProviderAuthentication.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "EmbeddingProviderAuthentication"}], "gathered_types": ["EmbeddingProviderAuthentication"]}} +{"id": "astrapy.info.EmbeddingProvider", "text": "A representation of an embedding provider, as returned by the 'findEmbeddingProviders'\nData API endpoint.", "metadata": {"kind": "class", "name": "EmbeddingProvider", "path": "astrapy.info.EmbeddingProvider", "parameters": [{"name": "display_name", "type": "str | None"}, {"name": "models", "type": "list[EmbeddingProviderModel]"}, {"name": "parameters", "type": "list[EmbeddingProviderParameter]"}, {"name": "supported_authentication", "type": "dict[str, EmbeddingProviderAuthentication]"}, {"name": "url", "type": "str | None"}], "attributes": [{"name": "display_name", "type": "str | None", "description": "a version of the provider name for display and pretty printing.\nNot to be used when issuing vectorize API requests (for the latter, it is\nthe key in the providers dictionary that is required)."}, {"name": "models", "type": "list[EmbeddingProviderModel]", "description": "a list of `EmbeddingProviderModel` objects pertaining to the provider."}, {"name": "parameters", "type": "list[EmbeddingProviderParameter]", "description": "a list of `EmbeddingProviderParameter` objects common to all models\nfor this provider."}, {"name": "supported_authentication", "type": "dict[str, EmbeddingProviderAuthentication]", "description": "a dictionary of the authentication modes for\nthis provider. Note that disabled modes may still appear in this map,\nalbeit with the `enabled` property set to False."}, {"name": "url", "type": "str | None", "description": "a string template for the URL used by the Data API when issuing the request\ntoward the embedding provider. This is of no direct concern to the Data API user."}], "gathered_types": ["EmbeddingProviderAuthentication", "EmbeddingProviderModel", "EmbeddingProviderParameter"]}} +{"id": "astrapy.info.EmbeddingProvider.display_name", "text": "", "metadata": {"kind": "attribute", "name": "display_name", "path": "astrapy.info.EmbeddingProvider.display_name", "value": "display_name: str | None"}} +{"id": "astrapy.info.EmbeddingProvider.models", "text": "", "metadata": {"kind": "attribute", "name": "models", "path": "astrapy.info.EmbeddingProvider.models", "value": "models: list[EmbeddingProviderModel]", "gathered_types": ["EmbeddingProviderModel"]}} +{"id": "astrapy.info.EmbeddingProvider.parameters", "text": "", "metadata": {"kind": "attribute", "name": "parameters", "path": "astrapy.info.EmbeddingProvider.parameters", "value": "parameters: list[EmbeddingProviderParameter]", "gathered_types": ["EmbeddingProviderParameter"]}} +{"id": "astrapy.info.EmbeddingProvider.supported_authentication", "text": "", "metadata": {"kind": "attribute", "name": "supported_authentication", "path": "astrapy.info.EmbeddingProvider.supported_authentication", "value": "supported_authentication: dict[str, EmbeddingProviderAuthentication]", "gathered_types": ["EmbeddingProviderAuthentication"]}} +{"id": "astrapy.info.EmbeddingProvider.url", "text": "", "metadata": {"kind": "attribute", "name": "url", "path": "astrapy.info.EmbeddingProvider.url", "value": "url: str | None"}} +{"id": "astrapy.info.EmbeddingProvider.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.EmbeddingProvider.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.EmbeddingProvider.from_dict", "text": "Create an instance of EmbeddingProvider from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.EmbeddingProvider.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "EmbeddingProvider"}], "gathered_types": ["EmbeddingProvider"]}} +{"id": "astrapy.info.FindEmbeddingProvidersResult", "text": "A representation of the whole response from the 'findEmbeddingProviders'\nData API endpoint.", "metadata": {"kind": "class", "name": "FindEmbeddingProvidersResult", "path": "astrapy.info.FindEmbeddingProvidersResult", "parameters": [{"name": "embedding_providers", "type": "dict[str, EmbeddingProvider]"}, {"name": "raw_info", "type": "dict[str, Any] | None"}], "attributes": [{"name": "embedding_providers", "type": "dict[str, EmbeddingProvider]", "description": "a dictionary of provider names to EmbeddingProvider objects."}, {"name": "raw_info", "type": "dict[str, Any] | None", "description": "a (nested) dictionary containing the original full response from the endpoint."}], "gathered_types": ["EmbeddingProvider"]}} +{"id": "astrapy.info.FindEmbeddingProvidersResult.embedding_providers", "text": "", "metadata": {"kind": "attribute", "name": "embedding_providers", "path": "astrapy.info.FindEmbeddingProvidersResult.embedding_providers", "value": "embedding_providers: dict[str, EmbeddingProvider]", "gathered_types": ["EmbeddingProvider"]}} +{"id": "astrapy.info.FindEmbeddingProvidersResult.raw_info", "text": "", "metadata": {"kind": "attribute", "name": "raw_info", "path": "astrapy.info.FindEmbeddingProvidersResult.raw_info", "value": "raw_info: dict[str, Any] | None"}} +{"id": "astrapy.info.FindEmbeddingProvidersResult.as_dict", "text": "Recast this object into a dictionary.", "metadata": {"kind": "function", "name": "as_dict", "path": "astrapy.info.FindEmbeddingProvidersResult.as_dict", "returns": [{"type": "dict[str, Any]"}]}} +{"id": "astrapy.info.FindEmbeddingProvidersResult.from_dict", "text": "Create an instance of FindEmbeddingProvidersResult from a dictionary\nsuch as one from the Data API.", "metadata": {"kind": "function", "name": "from_dict", "path": "astrapy.info.FindEmbeddingProvidersResult.from_dict", "parameters": [{"name": "raw_dict", "type": "dict[str, Any]"}], "returns": [{"type": "FindEmbeddingProvidersResult"}], "gathered_types": ["astrapy.info.FindEmbeddingProvidersResult"]}} +{"id": "astrapy.request_tools", "text": "", "metadata": {"kind": "module", "name": "request_tools", "path": "astrapy.request_tools", "imports": {"annotations": "__future__.annotations", "logging": "logging", "Any": "typing.Any", "TypedDict": "typing.TypedDict", "Union": "typing.Union", "httpx": "httpx", "DEFAULT_REQUEST_TIMEOUT_MS": "astrapy.defaults.DEFAULT_REQUEST_TIMEOUT_MS"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.request_tools.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.request_tools.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.request_tools.log_httpx_request", "text": "Log the details of an HTTP request for debugging purposes.", "metadata": {"kind": "function", "name": "log_httpx_request", "path": "astrapy.request_tools.log_httpx_request", "parameters": [{"name": "http_method", "type": "str", "description": "the HTTP verb of the request (e.g. \"POST\").", "default": null}, {"name": "full_url", "type": "str", "description": "the URL of the request (e.g. \"https://domain.com/full/path\").", "default": null}, {"name": "request_params", "type": "dict[str, Any] | None", "description": "parameters of the request.", "default": null}, {"name": "redacted_request_headers", "type": "dict[str, str]", "description": "caution, as these will be logged as they are.", "default": null}, {"name": "payload", "type": "dict[str, Any] | None", "description": "The payload sent with the request, if any.", "default": null}], "returns": [{"type": "None"}]}} +{"id": "astrapy.request_tools.log_httpx_response", "text": "Log the details of an httpx.Response.", "metadata": {"kind": "function", "name": "log_httpx_response", "path": "astrapy.request_tools.log_httpx_response", "parameters": [{"name": "response", "type": "httpx.Response", "description": "the httpx.Response object to log.", "default": null}], "returns": [{"type": "None"}], "gathered_types": ["Response"]}} +{"id": "astrapy.request_tools.HttpMethod", "text": "", "metadata": {"kind": "class", "name": "HttpMethod", "path": "astrapy.request_tools.HttpMethod"}} +{"id": "astrapy.request_tools.HttpMethod.GET", "text": "", "metadata": {"kind": "attribute", "name": "GET", "path": "astrapy.request_tools.HttpMethod.GET", "value": "GET = 'GET'"}} +{"id": "astrapy.request_tools.HttpMethod.POST", "text": "", "metadata": {"kind": "attribute", "name": "POST", "path": "astrapy.request_tools.HttpMethod.POST", "value": "POST = 'POST'"}} +{"id": "astrapy.request_tools.HttpMethod.PUT", "text": "", "metadata": {"kind": "attribute", "name": "PUT", "path": "astrapy.request_tools.HttpMethod.PUT", "value": "PUT = 'PUT'"}} +{"id": "astrapy.request_tools.HttpMethod.PATCH", "text": "", "metadata": {"kind": "attribute", "name": "PATCH", "path": "astrapy.request_tools.HttpMethod.PATCH", "value": "PATCH = 'PATCH'"}} +{"id": "astrapy.request_tools.HttpMethod.DELETE", "text": "", "metadata": {"kind": "attribute", "name": "DELETE", "path": "astrapy.request_tools.HttpMethod.DELETE", "value": "DELETE = 'DELETE'"}} +{"id": "astrapy.request_tools.TimeoutInfo", "text": "", "metadata": {"kind": "class", "name": "TimeoutInfo", "path": "astrapy.request_tools.TimeoutInfo", "bases": ["TypedDict"]}} +{"id": "astrapy.request_tools.TimeoutInfo.read", "text": "", "metadata": {"kind": "attribute", "name": "read", "path": "astrapy.request_tools.TimeoutInfo.read", "value": "read: float"}} +{"id": "astrapy.request_tools.TimeoutInfo.write", "text": "", "metadata": {"kind": "attribute", "name": "write", "path": "astrapy.request_tools.TimeoutInfo.write", "value": "write: float"}} +{"id": "astrapy.request_tools.TimeoutInfo.base", "text": "", "metadata": {"kind": "attribute", "name": "base", "path": "astrapy.request_tools.TimeoutInfo.base", "value": "base: float"}} +{"id": "astrapy.request_tools.TimeoutInfoWideType", "text": "", "metadata": {"kind": "attribute", "name": "TimeoutInfoWideType", "path": "astrapy.request_tools.TimeoutInfoWideType", "value": "TimeoutInfoWideType = Union[TimeoutInfo, float, None]", "gathered_types": ["astrapy.request_tools.TimeoutInfo"]}} +{"id": "astrapy.request_tools.to_httpx_timeout", "text": "", "metadata": {"kind": "function", "name": "to_httpx_timeout", "path": "astrapy.request_tools.to_httpx_timeout", "parameters": [{"name": "timeout_info", "type": "TimeoutInfoWideType"}], "returns": [{"type": "httpx.Timeout | None"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "Timeout"]}} +{"id": "astrapy.meta", "text": "", "metadata": {"kind": "module", "name": "meta", "path": "astrapy.meta", "imports": {"annotations": "__future__.annotations", "warnings": "warnings", "Any": "typing.Any", "Sequence": "typing.Sequence", "DeprecatedWarning": "deprecation.DeprecatedWarning", "CallerType": "astrapy.constants.CallerType", "CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS": "astrapy.defaults.CALLER_NAME_VERSION_DEPRECATION_NOTICE_DETAILS", "NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_DETAILS", "NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_NS_SUBJECT", "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_DETAILS", "NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT": "astrapy.defaults.NAMESPACE_DEPRECATION_NOTICE_UPDATEDBNS_SUBJECT"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.meta.check_deprecated_vector_ize", "text": "", "metadata": {"kind": "function", "name": "check_deprecated_vector_ize", "path": "astrapy.meta.check_deprecated_vector_ize", "parameters": [{"name": "vector", "type": "Any"}, {"name": "vectors", "type": "Any"}, {"name": "vectorize", "type": "Any"}, {"name": "kind", "type": "str"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.meta.check_caller_parameters", "text": "", "metadata": {"kind": "function", "name": "check_caller_parameters", "path": "astrapy.meta.check_caller_parameters", "parameters": [{"name": "callers", "type": "Sequence[CallerType]"}, {"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}], "returns": [{"type": "Sequence[CallerType]"}], "gathered_types": ["astrapy.constants.CallerType"]}} +{"id": "astrapy.meta.check_deprecated_id_region", "text": "", "metadata": {"kind": "function", "name": "check_deprecated_id_region", "path": "astrapy.meta.check_deprecated_id_region", "parameters": [{"name": "id", "type": "str | None"}, {"name": "region", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.meta.check_namespace_keyspace", "text": "", "metadata": {"kind": "function", "name": "check_namespace_keyspace", "path": "astrapy.meta.check_namespace_keyspace", "parameters": [{"name": "keyspace", "type": "str | None"}, {"name": "namespace", "type": "str | None"}], "returns": [{"type": "str | None"}]}} +{"id": "astrapy.meta.check_update_db_namespace_keyspace", "text": "", "metadata": {"kind": "function", "name": "check_update_db_namespace_keyspace", "path": "astrapy.meta.check_update_db_namespace_keyspace", "parameters": [{"name": "update_db_keyspace", "type": "bool | None"}, {"name": "update_db_namespace", "type": "bool | None"}], "returns": [{"type": "bool | None"}]}} +{"id": "astrapy.core", "text": "", "metadata": {"kind": "module", "name": "core", "path": "astrapy.core", "imports": {"annotations": "__future__.annotations", "inspect": "inspect", "warnings": "warnings", "DeprecatedWarning": "deprecation.DeprecatedWarning"}, "properties": {"is_init_module": true, "is_package": false, "is_subpackage": true, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.DEPRECATED_MODULE_PATHS", "text": "", "metadata": {"kind": "attribute", "name": "DEPRECATED_MODULE_PATHS", "path": "astrapy.core.DEPRECATED_MODULE_PATHS", "value": "DEPRECATED_MODULE_PATHS = {'astrapy.api', 'astrapy.core', 'astrapy.db', 'astrapy.ops'}"}} +{"id": "astrapy.core.issue_deprecation_warning", "text": "Issue a DeprecatedWarning (subclass of DeprecationWarning).\n\nIn order to correctly refer to user code, this function needs to\ndynamically adjust the `stacklevel` parameter.", "metadata": {"kind": "function", "name": "issue_deprecation_warning", "path": "astrapy.core.issue_deprecation_warning", "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db", "text": "", "metadata": {"kind": "module", "name": "db", "path": "astrapy.core.db", "imports": {"annotations": "__future__.annotations", "asyncio": "asyncio", "json": "json", "logging": "logging", "queue": "queue", "threading": "threading", "weakref": "weakref", "AsyncGenerator": "collections.abc.AsyncGenerator", "AsyncIterator": "collections.abc.AsyncIterator", "ThreadPoolExecutor": "concurrent.futures.ThreadPoolExecutor", "partial": "functools.partial", "TracebackType": "types.TracebackType", "Any": "typing.Any", "Callable": "typing.Callable", "Iterator": "typing.Iterator", "List": "typing.List", "Union": "typing.Union", "cast": "typing.cast", "httpx": "httpx", "APIRequestError": "astrapy.core.api.APIRequestError", "api_request": "astrapy.core.api.api_request", "async_api_request": "astrapy.core.api.async_api_request", "API_DOC": "astrapy.core.core_types.API_DOC", "API_RESPONSE": "astrapy.core.core_types.API_RESPONSE", "AsyncPaginableRequestMethod": "astrapy.core.core_types.AsyncPaginableRequestMethod", "PaginableRequestMethod": "astrapy.core.core_types.PaginableRequestMethod", "DEFAULT_AUTH_HEADER": "astrapy.core.defaults.DEFAULT_AUTH_HEADER", "DEFAULT_INSERT_NUM_DOCUMENTS": "astrapy.core.defaults.DEFAULT_INSERT_NUM_DOCUMENTS", "DEFAULT_JSON_API_PATH": "astrapy.core.defaults.DEFAULT_JSON_API_PATH", "DEFAULT_JSON_API_VERSION": "astrapy.core.defaults.DEFAULT_JSON_API_VERSION", "DEFAULT_KEYSPACE_NAME": "astrapy.core.defaults.DEFAULT_KEYSPACE_NAME", "TimeoutInfoWideType": "astrapy.core.utils.TimeoutInfoWideType", "convert_vector_to_floats": "astrapy.core.utils.convert_vector_to_floats", "http_methods": "astrapy.core.utils.http_methods", "make_payload": "astrapy.core.utils.make_payload", "normalize_for_api": "astrapy.core.utils.normalize_for_api", "restore_from_api": "astrapy.core.utils.restore_from_api", "to_httpx_timeout": "astrapy.core.utils.to_httpx_timeout"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.db.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.core.db.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.core.db._PrefetchIterator.queue", "text": "", "metadata": {"kind": "attribute", "name": "queue", "path": "astrapy.core.db._PrefetchIterator.queue", "value": "queue: queue.Queue[API_DOC | None] = queue.Queue(prefetched)", "gathered_types": ["Queue", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db._PrefetchIterator.request_method", "text": "", "metadata": {"kind": "attribute", "name": "request_method", "path": "astrapy.core.db._PrefetchIterator.request_method", "value": "request_method = request_method"}} +{"id": "astrapy.core.db._PrefetchIterator.options", "text": "", "metadata": {"kind": "attribute", "name": "options", "path": "astrapy.core.db._PrefetchIterator.options", "value": "options = options"}} +{"id": "astrapy.core.db._PrefetchIterator.raw_response_callback", "text": "", "metadata": {"kind": "attribute", "name": "raw_response_callback", "path": "astrapy.core.db._PrefetchIterator.raw_response_callback", "value": "raw_response_callback = raw_response_callback"}} +{"id": "astrapy.core.db._PrefetchIterator.initialised", "text": "", "metadata": {"kind": "attribute", "name": "initialised", "path": "astrapy.core.db._PrefetchIterator.initialised", "value": "initialised = threading.Event()", "gathered_types": ["Event"]}} +{"id": "astrapy.core.db._PrefetchIterator.stop", "text": "", "metadata": {"kind": "attribute", "name": "stop", "path": "astrapy.core.db._PrefetchIterator.stop", "value": "stop = threading.Event()", "gathered_types": ["Event"]}} +{"id": "astrapy.core.db._PrefetchIterator.thread", "text": "", "metadata": {"kind": "attribute", "name": "thread", "path": "astrapy.core.db._PrefetchIterator.thread", "value": "thread = threading.Thread(target=_PrefetchIterator.queued_paginate, args=(weakref.proxy(self),))", "gathered_types": ["Thread", "_PrefetchIterator"]}} +{"id": "astrapy.core.db._PrefetchIterator.queue_put", "text": "", "metadata": {"kind": "function", "name": "queue_put", "path": "astrapy.core.db._PrefetchIterator.queue_put", "parameters": [{"name": "q", "type": "queue.Queue[API_DOC | None]"}, {"name": "item", "type": "API_DOC | None"}, {"name": "stop", "type": "threading.Event"}], "returns": [{"type": "None"}], "gathered_types": ["Queue", "Event", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db._PrefetchIterator.queued_paginate", "text": "", "metadata": {"kind": "function", "name": "queued_paginate", "path": "astrapy.core.db._PrefetchIterator.queued_paginate", "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db.AstraDBCollection", "text": "", "metadata": {"kind": "class", "name": "AstraDBCollection", "path": "astrapy.core.db.AstraDBCollection", "parameters": [{"name": "collection_name", "type": "str"}, {"name": "astra_db", "default": "None", "type": "AstraDB | None"}, {"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}, {"name": "additional_headers", "default": "{}", "type": "dict[str, str]"}], "gathered_types": ["astrapy.core.db.AstraDB"]}} +{"id": "astrapy.core.db.AstraDBCollection.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.core.db.AstraDBCollection.client", "value": "client = httpx.Client()", "gathered_types": ["Client"]}} +{"id": "astrapy.core.db.AstraDBCollection.astra_db", "text": "", "metadata": {"kind": "attribute", "name": "astra_db", "path": "astrapy.core.db.AstraDBCollection.astra_db", "value": "astra_db = astra_db"}} +{"id": "astrapy.core.db.AstraDBCollection.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.db.AstraDBCollection.caller_name", "value": "caller_name: str | None = self.astra_db.caller_name"}} +{"id": "astrapy.core.db.AstraDBCollection.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.db.AstraDBCollection.caller_version", "value": "caller_version: str | None = self.astra_db.caller_version"}} +{"id": "astrapy.core.db.AstraDBCollection.additional_headers", "text": "", "metadata": {"kind": "attribute", "name": "additional_headers", "path": "astrapy.core.db.AstraDBCollection.additional_headers", "value": "additional_headers = additional_headers"}} +{"id": "astrapy.core.db.AstraDBCollection.collection_name", "text": "", "metadata": {"kind": "attribute", "name": "collection_name", "path": "astrapy.core.db.AstraDBCollection.collection_name", "value": "collection_name = collection_name"}} +{"id": "astrapy.core.db.AstraDBCollection.base_path", "text": "", "metadata": {"kind": "attribute", "name": "base_path", "path": "astrapy.core.db.AstraDBCollection.base_path", "value": "base_path: str = f'{self.astra_db.base_path}/{self.collection_name}'"}} +{"id": "astrapy.core.db.AstraDBCollection.copy", "text": "", "metadata": {"kind": "function", "name": "copy", "path": "astrapy.core.db.AstraDBCollection.copy", "parameters": [{"name": "collection_name", "default": "None", "type": "str | None"}, {"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}, {"name": "additional_headers", "default": "None", "type": "dict[str, str] | None"}], "returns": [{"type": "AstraDBCollection"}], "gathered_types": ["astrapy.core.db.AstraDBCollection"]}} +{"id": "astrapy.core.db.AstraDBCollection.to_async", "text": "", "metadata": {"kind": "function", "name": "to_async", "path": "astrapy.core.db.AstraDBCollection.to_async", "returns": [{"type": "AsyncAstraDBCollection"}], "gathered_types": ["astrapy.core.db.AsyncAstraDBCollection"]}} +{"id": "astrapy.core.db.AstraDBCollection.set_caller", "text": "", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.core.db.AstraDBCollection.set_caller", "parameters": [{"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db.AstraDBCollection.post_raw_request", "text": "", "metadata": {"kind": "function", "name": "post_raw_request", "path": "astrapy.core.db.AstraDBCollection.post_raw_request", "parameters": [{"name": "body", "type": "dict[str, Any]"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.get", "text": "Retrieve a document from the collection by its path.", "metadata": {"kind": "function", "name": "get", "path": "astrapy.core.db.AstraDBCollection.get", "parameters": [{"name": "path", "type": "str", "description": "The path of the document to retrieve.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE | None", "description": "The retrieved document."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.find", "text": "Find documents in the collection that match the given filter.", "metadata": {"kind": "function", "name": "find", "path": "astrapy.core.db.AstraDBCollection.find", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return matching documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The query response containing matched documents."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.vector_find", "text": "Perform a vector-based search in the collection.", "metadata": {"kind": "function", "name": "vector_find", "path": "astrapy.core.db.AstraDBCollection.vector_find", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "limit", "type": "int", "description": "The maximum number of documents to return.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool", "description": "Whether to include similarity score in the result.", "value": "True", "default": "True"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "list[API_DOC]", "description": "A list of documents matching the vector search criteria."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.paginate", "text": "Generate paginated results for a given database query method.", "metadata": {"kind": "function", "name": "paginate", "path": "astrapy.core.db.AstraDBCollection.paginate", "parameters": [{"name": "request_method", "type": "function", "description": "The database query method to paginate.", "default": null}, {"name": "options", "type": "dict", "description": "Options for the database query.", "default": null}, {"name": "prefetched", "type": "int", "description": "Number of pre-fetched documents.", "default": null}, {"name": "raw_response_callback", "type": "Callable[[dict[str, Any]], None] | None", "description": "an optional callback invoked at each new\nresponse coming from the API. The only argument is the raw\nAPI response and the callback must return None.", "value": "None", "default": "None"}], "returns": [{"type": "Iterator[API_DOC]"}], "yields": [{"name": "dict", "type": "API_DOC", "description": "The next document in the paginated result set."}], "gathered_types": ["astrapy.core.core_types.PaginableRequestMethod", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.paginated_find", "text": "Perform a paginated search in the collection.", "metadata": {"kind": "function", "name": "paginated_find", "path": "astrapy.core.db.AstraDBCollection.paginated_find", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return matching documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "None", "default": "None"}, {"name": "prefetched", "type": "int", "description": "Number of pre-fetched documents.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each\nsingle HTTP request.\nThis is a paginated method, that issues several requests as it\nneeds more data. This parameter controls a single request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}, {"name": "raw_response_callback", "type": "Callable[[dict[str, Any]], None] | None", "description": "an optional callback invoked at each new\nresponse coming from the API. The only argument is the raw\nAPI response and the callback must return None.", "value": "None", "default": "None"}], "returns": [{"name": "generator", "type": "Iterator[API_DOC]", "description": "A generator yielding documents in the paginated result set."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.pop", "text": "Pop the last data in the tags array", "metadata": {"kind": "function", "name": "pop", "path": "astrapy.core.db.AstraDBCollection.pop", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "pop", "type": "dict", "description": "The pop to apply to the tags.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the update operation.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The original document before the update."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.push", "text": "Push new data to the tags array", "metadata": {"kind": "function", "name": "push", "path": "astrapy.core.db.AstraDBCollection.push", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "push", "type": "dict", "description": "The push to apply to the tags.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the update operation.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.find_one_and_replace", "text": "Find a single document and replace it.", "metadata": {"kind": "function", "name": "find_one_and_replace", "path": "astrapy.core.db.AstraDBCollection.find_one_and_replace", "parameters": [{"name": "replacement", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and replace operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.vector_find_one_and_replace", "text": "Perform a vector-based search and replace the first matched document.", "metadata": {"kind": "function", "name": "vector_find_one_and_replace", "path": "astrapy.core.db.AstraDBCollection.vector_find_one_and_replace", "parameters": [{"name": "vector", "type": "dict", "description": "The vector to search with.", "default": null}, {"name": "replacement", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the result.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: either the matched document or None if nothing found"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.find_one_and_update", "text": "Find a single document and update it.", "metadata": {"kind": "function", "name": "find_one_and_update", "path": "astrapy.core.db.AstraDBCollection.find_one_and_update", "parameters": [{"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "{}", "default": "{}"}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.vector_find_one_and_update", "text": "Perform a vector-based search and update the first matched document.", "metadata": {"kind": "function", "name": "vector_find_one_and_update", "path": "astrapy.core.db.AstraDBCollection.vector_find_one_and_update", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the matched document.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents before applying the vector search.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the updated document.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: The result of the vector-based find and\nupdate operation, or None if nothing found"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.find_one_and_delete", "text": "Find a single document and delete it.", "metadata": {"kind": "function", "name": "find_one_and_delete", "path": "astrapy.core.db.AstraDBCollection.find_one_and_delete", "parameters": [{"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "{}", "default": "{}"}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.count_documents", "text": "Count documents matching a given predicate (expressed as filter).", "metadata": {"kind": "function", "name": "count_documents", "path": "astrapy.core.db.AstraDBCollection.count_documents", "parameters": [{"name": "filter", "type": "dict, defaults to {}", "description": "Criteria to filter documents.", "value": "{}", "default": "{}"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "the response, either\n{\"status\": {\"count\": }}"}, {"type": "API_RESPONSE", "description": "or\n{\"errors\": [...]}"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.find_one", "text": "Find a single document in the collection.", "metadata": {"kind": "function", "name": "find_one", "path": "astrapy.core.db.AstraDBCollection.find_one", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "{}", "default": "{}"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "{}", "default": "{}"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return the document.", "value": "{}", "default": "{}"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "{}", "default": "{}"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "the response, either\n{\"data\": {\"document\": }}"}, {"type": "API_RESPONSE", "description": "or\n{\"data\": {\"document\": None}}"}, {"type": "API_RESPONSE", "description": "depending on whether a matching document is found or not."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.vector_find_one", "text": "Perform a vector-based search to find a single document in the collection.", "metadata": {"kind": "function", "name": "vector_find_one", "path": "astrapy.core.db.AstraDBCollection.vector_find_one", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "filter", "type": "dict", "description": "Additional criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the result.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool", "description": "Whether to include similarity score in the result.", "value": "True", "default": "True"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: The found document or None if no matching document is found."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.insert_one", "text": "Insert a single document into the collection.", "metadata": {"kind": "function", "name": "insert_one", "path": "astrapy.core.db.AstraDBCollection.insert_one", "parameters": [{"name": "document", "type": "dict", "description": "The document to insert.", "default": null}, {"name": "failures_allowed", "type": "bool", "description": "Whether to allow failures in the insert operation.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the insert operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.insert_many", "text": "Insert multiple documents into the collection.", "metadata": {"kind": "function", "name": "insert_many", "path": "astrapy.core.db.AstraDBCollection.insert_many", "parameters": [{"name": "documents", "type": "list", "description": "A list of documents to insert.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the insert operation.", "value": "None", "default": "None"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures through the insertion (i.e. on some documents).", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the insert operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.chunked_insert_many", "text": "Insert multiple documents into the collection, handling chunking and\noptionally with concurrent insertions.", "metadata": {"kind": "function", "name": "chunked_insert_many", "path": "astrapy.core.db.AstraDBCollection.chunked_insert_many", "parameters": [{"name": "documents", "type": "list", "description": "A list of documents to insert.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the insert operation.", "value": "None", "default": "None"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures in the chunk. Should be used combined with\noptions={\"ordered\": False} in most cases.", "value": "False", "default": "False"}, {"name": "chunk_size", "type": "int", "description": "Override the default insertion chunk size.", "value": "DEFAULT_INSERT_NUM_DOCUMENTS", "default": "DEFAULT_INSERT_NUM_DOCUMENTS"}, {"name": "concurrency", "type": "int", "description": "The number of concurrent chunk insertions.\nDefault is no concurrency.", "value": "1", "default": "1"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each single HTTP request.\nThis method runs a number of HTTP requests as it works on chunked\ndata. The timeout refers to each individual such request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "list[API_RESPONSE | Exception]", "description": "The responses from the database after the chunked insert operation.\nThis is a list of individual responses from the API: the caller\nwill need to inspect them all, e.g. to collate the inserted IDs."}], "gathered_types": ["astrapy.core.core_types.API_DOC", "astrapy.core.defaults.DEFAULT_INSERT_NUM_DOCUMENTS", "astrapy.core.core_types.API_RESPONSE", "astrapy.core.utils.TimeoutInfoWideType", "Exception"]}} +{"id": "astrapy.core.db.AstraDBCollection.update_one", "text": "Update a single document in the collection.", "metadata": {"kind": "function", "name": "update_one", "path": "astrapy.core.db.AstraDBCollection.update_one", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.update_many", "text": "Updates multiple documents in the collection.", "metadata": {"kind": "function", "name": "update_many", "path": "astrapy.core.db.AstraDBCollection.update_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.replace", "text": "Replace a document in the collection.", "metadata": {"kind": "function", "name": "replace", "path": "astrapy.core.db.AstraDBCollection.replace", "parameters": [{"name": "path", "type": "str", "description": "The path to the document to replace.", "default": null}, {"name": "document", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the replace operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.delete_one", "text": "Delete a single document from the collection based on its ID.", "metadata": {"kind": "function", "name": "delete_one", "path": "astrapy.core.db.AstraDBCollection.delete_one", "parameters": [{"name": "id", "type": "str", "description": "The ID of the document to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.delete_one_by_predicate", "text": "Delete a single document from the collection based on a filter clause", "metadata": {"kind": "function", "name": "delete_one_by_predicate", "path": "astrapy.core.db.AstraDBCollection.delete_one_by_predicate", "parameters": [{"name": "filter", "type": "dict[str, Any]", "description": "any filter dictionary", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.delete_many", "text": "Delete many documents from the collection based on a filter condition", "metadata": {"kind": "function", "name": "delete_many", "path": "astrapy.core.db.AstraDBCollection.delete_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the documents to delete.", "default": null}, {"name": "skip_error_check", "type": "bool", "description": "whether to ignore the check for API error\nand return the response untouched. Default is False.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.chunked_delete_many", "text": "Delete many documents from the collection based on a filter condition,\nchaining several API calls until exhaustion of the documents to delete.", "metadata": {"kind": "function", "name": "chunked_delete_many", "path": "astrapy.core.db.AstraDBCollection.chunked_delete_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the documents to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each single HTTP request.\nThis method runs a number of HTTP requests as it works on a\npagination basis. The timeout refers to each individual such request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "list[API_RESPONSE]", "description": "List[dict]: The responses from the database from all the calls"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.clear", "text": "Clear the collection, deleting all documents", "metadata": {"kind": "function", "name": "clear", "path": "astrapy.core.db.AstraDBCollection.clear", "parameters": [{"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.delete_subdocument", "text": "Delete a subdocument or field from a document in the collection.", "metadata": {"kind": "function", "name": "delete_subdocument", "path": "astrapy.core.db.AstraDBCollection.delete_subdocument", "parameters": [{"name": "id", "type": "str", "description": "The ID of the document containing the subdocument.", "default": null}, {"name": "subdoc", "type": "str", "description": "The key of the subdocument or field to remove.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDBCollection.upsert_one", "text": "Emulate an upsert operation for a single document in the collection.\n\nThis method attempts to insert the document.\nIf a document with the same _id exists, it updates the existing document.", "metadata": {"kind": "function", "name": "upsert_one", "path": "astrapy.core.db.AstraDBCollection.upsert_one", "parameters": [{"name": "document", "type": "dict", "description": "The document to insert or update.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP requests.\nThis method may issue one or two requests, depending on what\nis detected on DB. This timeout controls each HTTP request individually.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The _id of the inserted or updated document."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AstraDBCollection.upsert_many", "text": "Emulate an upsert operation for multiple documents in the collection.\n\nThis method attempts to insert the documents.\nIf a document with the same _id exists, it updates the existing document.", "metadata": {"kind": "function", "name": "upsert_many", "path": "astrapy.core.db.AstraDBCollection.upsert_many", "parameters": [{"name": "documents", "type": "List[dict]", "description": "The documents to insert or update.", "default": null}, {"name": "concurrency", "type": "int", "description": "The number of concurrent upserts.", "value": "1", "default": "1"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures in the batch.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each HTTP request.\nThis method issues a separate HTTP request for each document to\ninsert: the timeout controls each such request individually.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "list[str | Exception]", "description": "List[Union[str, Exception]]: A list of \"_id\"s of the inserted or updated documents."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "Exception"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection", "text": "", "metadata": {"kind": "class", "name": "AsyncAstraDBCollection", "path": "astrapy.core.db.AsyncAstraDBCollection", "parameters": [{"name": "collection_name", "type": "str"}, {"name": "astra_db", "default": "None", "type": "AsyncAstraDB | None"}, {"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}, {"name": "additional_headers", "default": "{}", "type": "dict[str, str]"}], "gathered_types": ["astrapy.core.db.AsyncAstraDB"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.astra_db", "text": "", "metadata": {"kind": "attribute", "name": "astra_db", "path": "astrapy.core.db.AsyncAstraDBCollection.astra_db", "value": "astra_db: AsyncAstraDB = astra_db", "gathered_types": ["astrapy.core.db.AsyncAstraDB"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.db.AsyncAstraDBCollection.caller_name", "value": "caller_name: str | None = self.astra_db.caller_name"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.db.AsyncAstraDBCollection.caller_version", "value": "caller_version: str | None = self.astra_db.caller_version"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.additional_headers", "text": "", "metadata": {"kind": "attribute", "name": "additional_headers", "path": "astrapy.core.db.AsyncAstraDBCollection.additional_headers", "value": "additional_headers = additional_headers"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.core.db.AsyncAstraDBCollection.client", "value": "client = astra_db.client"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.collection_name", "text": "", "metadata": {"kind": "attribute", "name": "collection_name", "path": "astrapy.core.db.AsyncAstraDBCollection.collection_name", "value": "collection_name = collection_name"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.base_path", "text": "", "metadata": {"kind": "attribute", "name": "base_path", "path": "astrapy.core.db.AsyncAstraDBCollection.base_path", "value": "base_path: str = f'{self.astra_db.base_path}/{self.collection_name}'"}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.copy", "text": "", "metadata": {"kind": "function", "name": "copy", "path": "astrapy.core.db.AsyncAstraDBCollection.copy", "parameters": [{"name": "collection_name", "default": "None", "type": "str | None"}, {"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}, {"name": "additional_headers", "default": "None", "type": "dict[str, str] | None"}], "returns": [{"type": "AsyncAstraDBCollection"}], "gathered_types": ["astrapy.core.db.AsyncAstraDBCollection"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.set_caller", "text": "", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.core.db.AsyncAstraDBCollection.set_caller", "parameters": [{"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.to_sync", "text": "", "metadata": {"kind": "function", "name": "to_sync", "path": "astrapy.core.db.AsyncAstraDBCollection.to_sync", "returns": [{"type": "AstraDBCollection"}], "gathered_types": ["astrapy.core.db.AstraDBCollection"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.post_raw_request", "text": "", "metadata": {"kind": "function", "name": "post_raw_request", "path": "astrapy.core.db.AsyncAstraDBCollection.post_raw_request", "parameters": [{"name": "body", "type": "dict[str, Any]"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.get", "text": "Retrieve a document from the collection by its path.", "metadata": {"kind": "function", "name": "get", "path": "astrapy.core.db.AsyncAstraDBCollection.get", "parameters": [{"name": "path", "type": "str", "description": "The path of the document to retrieve.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE | None", "description": "The retrieved document."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.find", "text": "Find documents in the collection that match the given filter.", "metadata": {"kind": "function", "name": "find", "path": "astrapy.core.db.AsyncAstraDBCollection.find", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return matching documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The query response containing matched documents."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.vector_find", "text": "Perform a vector-based search in the collection.", "metadata": {"kind": "function", "name": "vector_find", "path": "astrapy.core.db.AsyncAstraDBCollection.vector_find", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "limit", "type": "int", "description": "The maximum number of documents to return.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool", "description": "Whether to include similarity score in the result.", "value": "True", "default": "True"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "list[API_DOC]", "description": "A list of documents matching the vector search criteria."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.paginate", "text": "Generate paginated results for a given database query method.", "metadata": {"kind": "function", "name": "paginate", "path": "astrapy.core.db.AsyncAstraDBCollection.paginate", "parameters": [{"name": "request_method", "type": "function", "description": "The database query method to paginate.", "default": null}, {"name": "options", "type": "dict", "description": "Options for the database query.", "default": null}, {"name": "prefetched", "type": "int", "description": "Number of pre-fetched documents.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}, {"name": "raw_response_callback", "type": "Callable[[dict[str, Any]], None] | None", "description": "an optional callback invoked at each new\nresponse coming from the API. The only argument is the raw\nAPI response and the callback must return None.", "value": "None", "default": "None"}], "returns": [{"type": "AsyncGenerator[API_DOC, None]"}], "yields": [{"name": "dict", "type": "AsyncGenerator[API_DOC, None]", "description": "The next document in the paginated result set."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.AsyncPaginableRequestMethod"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.paginated_find", "text": "Perform a paginated search in the collection.", "metadata": {"kind": "function", "name": "paginated_find", "path": "astrapy.core.db.AsyncAstraDBCollection.paginated_find", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return matching documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "None", "default": "None"}, {"name": "prefetched", "type": "int", "description": "Number of pre-fetched documents", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each\nsingle HTTP request.\nThis is a paginated method, that issues several requests as it\nneeds more data. This parameter controls a single request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}, {"name": "raw_response_callback", "type": "Callable[[dict[str, Any]], None] | None", "description": "an optional callback invoked at each new\nresponse coming from the API. The only argument is the raw\nAPI response and the callback must return None.", "value": "None", "default": "None"}], "returns": [{"name": "generator", "type": "AsyncIterator[API_DOC]", "description": "A generator yielding documents in the paginated result set."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.pop", "text": "Pop the last data in the tags array", "metadata": {"kind": "function", "name": "pop", "path": "astrapy.core.db.AsyncAstraDBCollection.pop", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "pop", "type": "dict", "description": "The pop to apply to the tags.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the update operation.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The original document before the update."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.push", "text": "Push new data to the tags array", "metadata": {"kind": "function", "name": "push", "path": "astrapy.core.db.AsyncAstraDBCollection.push", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "push", "type": "dict", "description": "The push to apply to the tags.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the update operation.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_replace", "text": "Find a single document and replace it.", "metadata": {"kind": "function", "name": "find_one_and_replace", "path": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_replace", "parameters": [{"name": "replacement", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and replace operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one_and_replace", "text": "Perform a vector-based search and replace the first matched document.", "metadata": {"kind": "function", "name": "vector_find_one_and_replace", "path": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one_and_replace", "parameters": [{"name": "vector", "type": "dict", "description": "The vector to search with.", "default": null}, {"name": "replacement", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the result.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: either the matched document or None if nothing found"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_update", "text": "Find a single document and update it.", "metadata": {"kind": "function", "name": "find_one_and_update", "path": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_update", "parameters": [{"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "{}", "default": "{}"}, {"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one_and_update", "text": "Perform a vector-based search and update the first matched document.", "metadata": {"kind": "function", "name": "vector_find_one_and_update", "path": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one_and_update", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the matched document.", "default": null}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents before applying the vector search.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the updated document.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: The result of the vector-based find and\nupdate operation, or None if nothing found"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_delete", "text": "Find a single document and delete it.", "metadata": {"kind": "function", "name": "find_one_and_delete", "path": "astrapy.core.db.AsyncAstraDBCollection.find_one_and_delete", "parameters": [{"name": "sort", "type": "dict", "description": "Specifies the order in which to find the document.", "value": "{}", "default": "{}"}, {"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "None", "default": "None"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The result of the find and delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.count_documents", "text": "Count documents matching a given predicate (expressed as filter).", "metadata": {"kind": "function", "name": "count_documents", "path": "astrapy.core.db.AsyncAstraDBCollection.count_documents", "parameters": [{"name": "filter", "type": "dict, defaults to {}", "description": "Criteria to filter documents.", "value": "{}", "default": "{}"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "the response, either\n{\"status\": {\"count\": }}"}, {"type": "API_RESPONSE", "description": "or\n{\"errors\": [...]}"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.find_one", "text": "Find a single document in the collection.", "metadata": {"kind": "function", "name": "find_one", "path": "astrapy.core.db.AsyncAstraDBCollection.find_one", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to filter documents.", "value": "{}", "default": "{}"}, {"name": "projection", "type": "dict", "description": "Specifies the fields to return.", "value": "{}", "default": "{}"}, {"name": "sort", "type": "dict", "description": "Specifies the order in which to return the document.", "value": "{}", "default": "{}"}, {"name": "options", "type": "dict", "description": "Additional options for the query.", "value": "{}", "default": "{}"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "the response, either\n{\"data\": {\"document\": }}"}, {"type": "API_RESPONSE", "description": "or\n{\"data\": {\"document\": None}}"}, {"type": "API_RESPONSE", "description": "depending on whether a matching document is found or not."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one", "text": "Perform a vector-based search to find a single document in the collection.", "metadata": {"kind": "function", "name": "vector_find_one", "path": "astrapy.core.db.AsyncAstraDBCollection.vector_find_one", "parameters": [{"name": "vector", "type": "list", "description": "The vector to search with.", "default": null}, {"name": "filter", "type": "dict", "description": "Additional criteria to filter documents.", "value": "None", "default": "None"}, {"name": "fields", "type": "list", "description": "Specifies the fields to return in the result.", "value": "None", "default": "None"}, {"name": "include_similarity", "type": "bool", "description": "Whether to include similarity score in the result.", "value": "True", "default": "True"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "API_DOC | None", "description": "dict or None: The found document or None if no matching document is found."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.insert_one", "text": "Insert a single document into the collection.", "metadata": {"kind": "function", "name": "insert_one", "path": "astrapy.core.db.AsyncAstraDBCollection.insert_one", "parameters": [{"name": "document", "type": "dict", "description": "The document to insert.", "default": null}, {"name": "failures_allowed", "type": "bool", "description": "Whether to allow failures in the insert operation.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the insert operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.insert_many", "text": "Insert multiple documents into the collection.", "metadata": {"kind": "function", "name": "insert_many", "path": "astrapy.core.db.AsyncAstraDBCollection.insert_many", "parameters": [{"name": "documents", "type": "list", "description": "A list of documents to insert.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the insert operation.", "value": "None", "default": "None"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures through the insertion (i.e. on some documents).", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the insert operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.chunked_insert_many", "text": "Insert multiple documents into the collection, handling chunking and\noptionally with concurrent insertions.", "metadata": {"kind": "function", "name": "chunked_insert_many", "path": "astrapy.core.db.AsyncAstraDBCollection.chunked_insert_many", "parameters": [{"name": "documents", "type": "list", "description": "A list of documents to insert.", "default": null}, {"name": "options", "type": "dict", "description": "Additional options for the insert operation.", "value": "None", "default": "None"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures in the chunk. Should be used combined with\noptions={\"ordered\": False} in most cases.", "value": "False", "default": "False"}, {"name": "chunk_size", "type": "int", "description": "Override the default insertion chunk size.", "value": "DEFAULT_INSERT_NUM_DOCUMENTS", "default": "DEFAULT_INSERT_NUM_DOCUMENTS"}, {"name": "concurrency", "type": "int", "description": "The number of concurrent chunk insertions.\nDefault is no concurrency.", "value": "1", "default": "1"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each single HTTP request.\nThis method runs a number of HTTP requests as it works on chunked\ndata. The timeout refers to each individual such request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "list[API_RESPONSE | Exception]", "description": "The responses from the database after the chunked insert operation.\nThis is a list of individual responses from the API: the caller\nwill need to inspect them all, e.g. to collate the inserted IDs."}], "gathered_types": ["astrapy.core.core_types.API_DOC", "astrapy.core.defaults.DEFAULT_INSERT_NUM_DOCUMENTS", "astrapy.core.core_types.API_RESPONSE", "astrapy.core.utils.TimeoutInfoWideType", "Exception"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.update_one", "text": "Update a single document in the collection.", "metadata": {"kind": "function", "name": "update_one", "path": "astrapy.core.db.AsyncAstraDBCollection.update_one", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}, {"name": "options", "type": "dict", "description": "Additional options for the operation.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.update_many", "text": "Updates multiple documents in the collection.", "metadata": {"kind": "function", "name": "update_many", "path": "astrapy.core.db.AsyncAstraDBCollection.update_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the document to update.", "default": null}, {"name": "update", "type": "dict", "description": "The update to apply to the document.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.replace", "text": "Replace a document in the collection.", "metadata": {"kind": "function", "name": "replace", "path": "astrapy.core.db.AsyncAstraDBCollection.replace", "parameters": [{"name": "path", "type": "str", "description": "The path to the document to replace.", "default": null}, {"name": "document", "type": "dict", "description": "The new document to replace the existing one.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the replace operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.delete_one", "text": "Delete a single document from the collection based on its ID.", "metadata": {"kind": "function", "name": "delete_one", "path": "astrapy.core.db.AsyncAstraDBCollection.delete_one", "parameters": [{"name": "id", "type": "str", "description": "The ID of the document to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.delete_one_by_predicate", "text": "Delete a single document from the collection based on a filter clause", "metadata": {"kind": "function", "name": "delete_one_by_predicate", "path": "astrapy.core.db.AsyncAstraDBCollection.delete_one_by_predicate", "parameters": [{"name": "filter", "type": "dict[str, Any]", "description": "any filter dictionary", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.delete_many", "text": "Delete many documents from the collection based on a filter condition", "metadata": {"kind": "function", "name": "delete_many", "path": "astrapy.core.db.AsyncAstraDBCollection.delete_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the documents to delete.", "default": null}, {"name": "skip_error_check", "type": "bool", "description": "whether to ignore the check for API error\nand return the response untouched. Default is False.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the delete operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.chunked_delete_many", "text": "Delete many documents from the collection based on a filter condition,\nchaining several API calls until exhaustion of the documents to delete.", "metadata": {"kind": "function", "name": "chunked_delete_many", "path": "astrapy.core.db.AsyncAstraDBCollection.chunked_delete_many", "parameters": [{"name": "filter", "type": "dict", "description": "Criteria to identify the documents to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each single HTTP request.\nThis method runs a number of HTTP requests as it works on a\npagination basis. The timeout refers to each individual such request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "list[API_RESPONSE]", "description": "List[dict]: The responses from the database from all the calls"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.clear", "text": "Clear the collection, deleting all documents", "metadata": {"kind": "function", "name": "clear", "path": "astrapy.core.db.AsyncAstraDBCollection.clear", "parameters": [{"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.delete_subdocument", "text": "Delete a subdocument or field from a document in the collection.", "metadata": {"kind": "function", "name": "delete_subdocument", "path": "astrapy.core.db.AsyncAstraDBCollection.delete_subdocument", "parameters": [{"name": "id", "type": "str", "description": "The ID of the document containing the subdocument.", "default": null}, {"name": "subdoc", "type": "str", "description": "The key of the subdocument or field to remove.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database after the update operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.upsert_one", "text": "Emulate an upsert operation for a single document in the collection.\n\nThis method attempts to insert the document.\nIf a document with the same _id exists, it updates the existing document.", "metadata": {"kind": "function", "name": "upsert_one", "path": "astrapy.core.db.AsyncAstraDBCollection.upsert_one", "parameters": [{"name": "document", "type": "dict", "description": "The document to insert or update.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP requests.\nThis method may issue one or two requests, depending on what\nis detected on DB. This timeout controls each HTTP request individually.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The _id of the inserted or updated document."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC"]}} +{"id": "astrapy.core.db.AsyncAstraDBCollection.upsert_many", "text": "Emulate an upsert operation for multiple documents in the collection.\nThis method attempts to insert the documents.\nIf a document with the same _id exists, it updates the existing document.", "metadata": {"kind": "function", "name": "upsert_many", "path": "astrapy.core.db.AsyncAstraDBCollection.upsert_many", "parameters": [{"name": "documents", "type": "List[dict]", "description": "The documents to insert or update.", "default": null}, {"name": "concurrency", "type": "int", "description": "The number of concurrent upserts.", "value": "1", "default": "1"}, {"name": "partial_failures_allowed", "type": "bool", "description": "Whether to allow partial\nfailures in the batch.", "value": "False", "default": "False"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for each HTTP request.\nThis method issues a separate HTTP request for each document to\ninsert: the timeout controls each such request individually.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"type": "list[str | Exception]", "description": "List[Union[str, Exception]]: A list of \"_id\"s of the inserted or updated documents."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_DOC", "Exception"]}} +{"id": "astrapy.core.db.AstraDB", "text": "", "metadata": {"kind": "class", "name": "AstraDB", "path": "astrapy.core.db.AstraDB", "parameters": [{"name": "token", "type": "str | None"}, {"name": "api_endpoint", "type": "str"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}]}} +{"id": "astrapy.core.db.AstraDB.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.core.db.AstraDB.client", "value": "client = httpx.Client()", "gathered_types": ["Client"]}} +{"id": "astrapy.core.db.AstraDB.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.db.AstraDB.caller_name", "value": "caller_name = caller_name"}} +{"id": "astrapy.core.db.AstraDB.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.db.AstraDB.caller_version", "value": "caller_version = caller_version"}} +{"id": "astrapy.core.db.AstraDB.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.core.db.AstraDB.token", "value": "token = token"}} +{"id": "astrapy.core.db.AstraDB.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.core.db.AstraDB.api_endpoint", "value": "api_endpoint = api_endpoint"}} +{"id": "astrapy.core.db.AstraDB.base_url", "text": "", "metadata": {"kind": "attribute", "name": "base_url", "path": "astrapy.core.db.AstraDB.base_url", "value": "base_url = self.api_endpoint.strip('/')"}} +{"id": "astrapy.core.db.AstraDB.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.core.db.AstraDB.api_path", "value": "api_path = DEFAULT_JSON_API_PATH if api_path is None else api_path.strip('/')", "gathered_types": ["astrapy.core.defaults.DEFAULT_JSON_API_PATH"]}} +{"id": "astrapy.core.db.AstraDB.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.core.db.AstraDB.api_version", "value": "api_version = DEFAULT_JSON_API_VERSION if api_version is None else api_version.strip('/')", "gathered_types": ["astrapy.core.defaults.DEFAULT_JSON_API_VERSION"]}} +{"id": "astrapy.core.db.AstraDB.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.core.db.AstraDB.namespace", "value": "namespace = namespace"}} +{"id": "astrapy.core.db.AstraDB.base_path", "text": "", "metadata": {"kind": "attribute", "name": "base_path", "path": "astrapy.core.db.AstraDB.base_path", "value": "base_path: str = f'/{'/'.join(base_path_components)}'"}} +{"id": "astrapy.core.db.AstraDB.copy", "text": "", "metadata": {"kind": "function", "name": "copy", "path": "astrapy.core.db.AstraDB.copy", "parameters": [{"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "AstraDB"}], "gathered_types": ["astrapy.core.db.AstraDB"]}} +{"id": "astrapy.core.db.AstraDB.to_async", "text": "", "metadata": {"kind": "function", "name": "to_async", "path": "astrapy.core.db.AstraDB.to_async", "returns": [{"type": "AsyncAstraDB"}], "gathered_types": ["astrapy.core.db.AsyncAstraDB"]}} +{"id": "astrapy.core.db.AstraDB.set_caller", "text": "", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.core.db.AstraDB.set_caller", "parameters": [{"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db.AstraDB.post_raw_request", "text": "", "metadata": {"kind": "function", "name": "post_raw_request", "path": "astrapy.core.db.AstraDB.post_raw_request", "parameters": [{"name": "body", "type": "dict[str, Any]"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDB.collection", "text": "Retrieve a collection from the database.", "metadata": {"kind": "function", "name": "collection", "path": "astrapy.core.db.AstraDB.collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to retrieve.", "default": null}], "returns": [{"name": "AstraDBCollection", "type": "AstraDBCollection", "description": "The collection object."}], "gathered_types": ["astrapy.core.db.AstraDBCollection"]}} +{"id": "astrapy.core.db.AstraDB.get_collections", "text": "Retrieve a list of collections from the database.", "metadata": {"kind": "function", "name": "get_collections", "path": "astrapy.core.db.AstraDB.get_collections", "parameters": [{"name": "options", "type": "dict", "description": "Options to get the collection list", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "An object containing the list of collections in the database:\n{\"status\": {\"collections\": [...]}}"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AstraDB.create_collection", "text": "Create a new collection in the database.", "metadata": {"kind": "function", "name": "create_collection", "path": "astrapy.core.db.AstraDB.create_collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to create.", "default": null}, {"name": "options", "type": "dict", "description": "Options for the collection.", "value": "None", "default": "None"}, {"name": "dimension", "type": "int", "description": "Dimension for vector search.", "value": "None", "default": "None"}, {"name": "metric", "type": "str", "description": "Metric choice for vector search.", "value": "None", "default": "None"}, {"name": "service_dict", "type": "dict", "description": "a definition for the $vectorize service", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "AstraDBCollection", "type": "AstraDBCollection", "description": "The created collection object."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.db.AstraDBCollection"]}} +{"id": "astrapy.core.db.AstraDB.delete_collection", "text": "Delete a collection from the database.", "metadata": {"kind": "function", "name": "delete_collection", "path": "astrapy.core.db.AstraDB.delete_collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDB", "text": "", "metadata": {"kind": "class", "name": "AsyncAstraDB", "path": "astrapy.core.db.AsyncAstraDB", "parameters": [{"name": "token", "type": "str | None"}, {"name": "api_endpoint", "type": "str"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}]}} +{"id": "astrapy.core.db.AsyncAstraDB.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.db.AsyncAstraDB.caller_name", "value": "caller_name = caller_name"}} +{"id": "astrapy.core.db.AsyncAstraDB.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.db.AsyncAstraDB.caller_version", "value": "caller_version = caller_version"}} +{"id": "astrapy.core.db.AsyncAstraDB.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.core.db.AsyncAstraDB.client", "value": "client = httpx.AsyncClient()", "gathered_types": ["AsyncClient"]}} +{"id": "astrapy.core.db.AsyncAstraDB.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.core.db.AsyncAstraDB.token", "value": "token = token"}} +{"id": "astrapy.core.db.AsyncAstraDB.api_endpoint", "text": "", "metadata": {"kind": "attribute", "name": "api_endpoint", "path": "astrapy.core.db.AsyncAstraDB.api_endpoint", "value": "api_endpoint = api_endpoint"}} +{"id": "astrapy.core.db.AsyncAstraDB.base_url", "text": "", "metadata": {"kind": "attribute", "name": "base_url", "path": "astrapy.core.db.AsyncAstraDB.base_url", "value": "base_url = self.api_endpoint.strip('/')"}} +{"id": "astrapy.core.db.AsyncAstraDB.api_path", "text": "", "metadata": {"kind": "attribute", "name": "api_path", "path": "astrapy.core.db.AsyncAstraDB.api_path", "value": "api_path = DEFAULT_JSON_API_PATH if api_path is None else api_path.strip('/')", "gathered_types": ["astrapy.core.defaults.DEFAULT_JSON_API_PATH"]}} +{"id": "astrapy.core.db.AsyncAstraDB.api_version", "text": "", "metadata": {"kind": "attribute", "name": "api_version", "path": "astrapy.core.db.AsyncAstraDB.api_version", "value": "api_version = DEFAULT_JSON_API_VERSION if api_version is None else api_version.strip('/')", "gathered_types": ["astrapy.core.defaults.DEFAULT_JSON_API_VERSION"]}} +{"id": "astrapy.core.db.AsyncAstraDB.namespace", "text": "", "metadata": {"kind": "attribute", "name": "namespace", "path": "astrapy.core.db.AsyncAstraDB.namespace", "value": "namespace = namespace"}} +{"id": "astrapy.core.db.AsyncAstraDB.base_path", "text": "", "metadata": {"kind": "attribute", "name": "base_path", "path": "astrapy.core.db.AsyncAstraDB.base_path", "value": "base_path: str = f'/{'/'.join(base_path_components)}'"}} +{"id": "astrapy.core.db.AsyncAstraDB.copy", "text": "", "metadata": {"kind": "function", "name": "copy", "path": "astrapy.core.db.AsyncAstraDB.copy", "parameters": [{"name": "token", "default": "None", "type": "str | None"}, {"name": "api_endpoint", "default": "None", "type": "str | None"}, {"name": "api_path", "default": "None", "type": "str | None"}, {"name": "api_version", "default": "None", "type": "str | None"}, {"name": "namespace", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "AsyncAstraDB"}], "gathered_types": ["astrapy.core.db.AsyncAstraDB"]}} +{"id": "astrapy.core.db.AsyncAstraDB.to_sync", "text": "", "metadata": {"kind": "function", "name": "to_sync", "path": "astrapy.core.db.AsyncAstraDB.to_sync", "returns": [{"type": "AstraDB"}], "gathered_types": ["astrapy.core.db.AstraDB"]}} +{"id": "astrapy.core.db.AsyncAstraDB.set_caller", "text": "", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.core.db.AsyncAstraDB.set_caller", "parameters": [{"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.db.AsyncAstraDB.post_raw_request", "text": "", "metadata": {"kind": "function", "name": "post_raw_request", "path": "astrapy.core.db.AsyncAstraDB.post_raw_request", "parameters": [{"name": "body", "type": "dict[str, Any]"}, {"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDB.collection", "text": "Retrieve a collection from the database.", "metadata": {"kind": "function", "name": "collection", "path": "astrapy.core.db.AsyncAstraDB.collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to retrieve.", "default": null}, {"name": "timeout_info", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "default": null}], "returns": [{"name": "AstraDBCollection", "type": "AsyncAstraDBCollection", "description": "The collection object."}], "gathered_types": ["astrapy.core.db.AsyncAstraDBCollection"]}} +{"id": "astrapy.core.db.AsyncAstraDB.get_collections", "text": "Retrieve a list of collections from the database.", "metadata": {"kind": "function", "name": "get_collections", "path": "astrapy.core.db.AsyncAstraDB.get_collections", "parameters": [{"name": "options", "type": "dict", "description": "Options to get the collection list", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "An object containing the list of collections in the database:\n{\"status\": {\"collections\": [...]}}"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.db.AsyncAstraDB.create_collection", "text": "Create a new collection in the database.", "metadata": {"kind": "function", "name": "create_collection", "path": "astrapy.core.db.AsyncAstraDB.create_collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to create.", "default": null}, {"name": "options", "type": "dict", "description": "Options for the collection.", "value": "None", "default": "None"}, {"name": "dimension", "type": "int", "description": "Dimension for vector search.", "value": "None", "default": "None"}, {"name": "metric", "type": "str", "description": "Metric choice for vector search.", "value": "None", "default": "None"}, {"name": "service_dict", "type": "dict", "description": "a definition for the $vectorize service", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "AsyncAstraDBCollection", "type": "AsyncAstraDBCollection", "description": "The created collection object."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.db.AsyncAstraDBCollection"]}} +{"id": "astrapy.core.db.AsyncAstraDB.delete_collection", "text": "Delete a collection from the database.", "metadata": {"kind": "function", "name": "delete_collection", "path": "astrapy.core.db.AsyncAstraDB.delete_collection", "parameters": [{"name": "collection_name", "type": "str", "description": "The name of the collection to delete.", "default": null}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "a float, or a TimeoutInfo dict, for the HTTP request.\nNote that a 'read' timeout event will not block the action taken\nby the API server if it has received the request already.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "The response from the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.api", "text": "", "metadata": {"kind": "module", "name": "api", "path": "astrapy.core.api", "imports": {"annotations": "__future__.annotations", "logging": "logging", "Any": "typing.Any", "cast": "typing.cast", "httpx": "httpx", "API_RESPONSE": "astrapy.core.core_types.API_RESPONSE", "amake_request": "astrapy.core.utils.amake_request", "make_request": "astrapy.core.utils.make_request"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.api.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.core.api.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.core.api.APIRequestError", "text": "", "metadata": {"kind": "class", "name": "APIRequestError", "path": "astrapy.core.api.APIRequestError", "parameters": [{"name": "response", "type": "httpx.Response"}, {"name": "payload", "type": "dict[str, Any] | None"}], "bases": ["ValueError"], "gathered_types": ["Response", "ValueError"]}} +{"id": "astrapy.core.api.APIRequestError.response", "text": "", "metadata": {"kind": "attribute", "name": "response", "path": "astrapy.core.api.APIRequestError.response", "value": "response = response"}} +{"id": "astrapy.core.api.APIRequestError.payload", "text": "", "metadata": {"kind": "attribute", "name": "payload", "path": "astrapy.core.api.APIRequestError.payload", "value": "payload = payload"}} +{"id": "astrapy.core.api.raw_api_request", "text": "", "metadata": {"kind": "function", "name": "raw_api_request", "path": "astrapy.core.api.raw_api_request", "parameters": [{"name": "client", "type": "httpx.Client"}, {"name": "base_url", "type": "str"}, {"name": "auth_header", "type": "str"}, {"name": "token", "type": "str | None"}, {"name": "method", "type": "str"}, {"name": "json_data", "type": "dict[str, Any] | None"}, {"name": "url_params", "type": "dict[str, Any] | None"}, {"name": "path", "type": "str | None"}, {"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}, {"name": "timeout", "type": "httpx.Timeout | float | None"}, {"name": "additional_headers", "type": "dict[str, str]"}], "returns": [{"type": "httpx.Response"}], "gathered_types": ["Client", "Response", "Timeout"]}} +{"id": "astrapy.core.api.process_raw_api_response", "text": "", "metadata": {"kind": "function", "name": "process_raw_api_response", "path": "astrapy.core.api.process_raw_api_response", "parameters": [{"name": "raw_response", "type": "httpx.Response"}, {"name": "skip_error_check", "type": "bool"}, {"name": "json_data", "type": "dict[str, Any] | None"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.core_types.API_RESPONSE", "Response"]}} +{"id": "astrapy.core.api.api_request", "text": "", "metadata": {"kind": "function", "name": "api_request", "path": "astrapy.core.api.api_request", "parameters": [{"name": "client", "type": "httpx.Client"}, {"name": "base_url", "type": "str"}, {"name": "auth_header", "type": "str"}, {"name": "token", "type": "str | None"}, {"name": "method", "type": "str"}, {"name": "json_data", "type": "dict[str, Any] | None"}, {"name": "url_params", "type": "dict[str, Any] | None"}, {"name": "path", "type": "str | None"}, {"name": "skip_error_check", "type": "bool"}, {"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}, {"name": "timeout", "type": "httpx.Timeout | float | None"}, {"name": "additional_headers", "type": "dict[str, str]"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["Client", "astrapy.core.core_types.API_RESPONSE", "Timeout"]}} +{"id": "astrapy.core.api.async_raw_api_request", "text": "", "metadata": {"kind": "function", "name": "async_raw_api_request", "path": "astrapy.core.api.async_raw_api_request", "parameters": [{"name": "client", "type": "httpx.AsyncClient"}, {"name": "base_url", "type": "str"}, {"name": "auth_header", "type": "str"}, {"name": "token", "type": "str | None"}, {"name": "method", "type": "str"}, {"name": "json_data", "type": "dict[str, Any] | None"}, {"name": "url_params", "type": "dict[str, Any] | None"}, {"name": "path", "type": "str | None"}, {"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}, {"name": "timeout", "type": "httpx.Timeout | float | None"}, {"name": "additional_headers", "type": "dict[str, str]"}], "returns": [{"type": "httpx.Response"}], "gathered_types": ["AsyncClient", "Response", "Timeout"]}} +{"id": "astrapy.core.api.async_process_raw_api_response", "text": "", "metadata": {"kind": "function", "name": "async_process_raw_api_response", "path": "astrapy.core.api.async_process_raw_api_response", "parameters": [{"name": "raw_response", "type": "httpx.Response"}, {"name": "skip_error_check", "type": "bool"}, {"name": "json_data", "type": "dict[str, Any] | None"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.core_types.API_RESPONSE", "Response"]}} +{"id": "astrapy.core.api.async_api_request", "text": "", "metadata": {"kind": "function", "name": "async_api_request", "path": "astrapy.core.api.async_api_request", "parameters": [{"name": "client", "type": "httpx.AsyncClient"}, {"name": "base_url", "type": "str"}, {"name": "auth_header", "type": "str"}, {"name": "token", "type": "str | None"}, {"name": "method", "type": "str"}, {"name": "json_data", "type": "dict[str, Any] | None"}, {"name": "url_params", "type": "dict[str, Any] | None"}, {"name": "path", "type": "str | None"}, {"name": "skip_error_check", "type": "bool"}, {"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}, {"name": "timeout", "type": "httpx.Timeout | float | None"}, {"name": "additional_headers", "type": "dict[str, str]"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["AsyncClient", "astrapy.core.core_types.API_RESPONSE", "Timeout"]}} +{"id": "astrapy.core.ops", "text": "", "metadata": {"kind": "module", "name": "ops", "path": "astrapy.core.ops", "imports": {"annotations": "__future__.annotations", "logging": "logging", "Any": "typing.Any", "TypedDict": "typing.TypedDict", "cast": "typing.cast", "httpx": "httpx", "APIRequestError": "astrapy.core.api.APIRequestError", "api_request": "astrapy.core.api.api_request", "async_api_request": "astrapy.core.api.async_api_request", "async_raw_api_request": "astrapy.core.api.async_raw_api_request", "raw_api_request": "astrapy.core.api.raw_api_request", "API_RESPONSE": "astrapy.core.core_types.API_RESPONSE", "OPS_API_RESPONSE": "astrapy.core.core_types.OPS_API_RESPONSE", "DEFAULT_DEV_OPS_API_VERSION": "astrapy.core.defaults.DEFAULT_DEV_OPS_API_VERSION", "DEFAULT_DEV_OPS_AUTH_HEADER": "astrapy.core.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "DEFAULT_DEV_OPS_URL": "astrapy.core.defaults.DEFAULT_DEV_OPS_URL", "TimeoutInfoWideType": "astrapy.core.utils.TimeoutInfoWideType", "http_methods": "astrapy.core.utils.http_methods", "to_httpx_timeout": "astrapy.core.utils.to_httpx_timeout"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.ops.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.core.ops.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams", "text": "", "metadata": {"kind": "class", "name": "AstraDBOpsConstructorParams", "path": "astrapy.core.ops.AstraDBOpsConstructorParams", "bases": ["TypedDict"]}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.core.ops.AstraDBOpsConstructorParams.token", "value": "token: str | None"}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams.dev_ops_url", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_url", "path": "astrapy.core.ops.AstraDBOpsConstructorParams.dev_ops_url", "value": "dev_ops_url: str | None"}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams.dev_ops_api_version", "text": "", "metadata": {"kind": "attribute", "name": "dev_ops_api_version", "path": "astrapy.core.ops.AstraDBOpsConstructorParams.dev_ops_api_version", "value": "dev_ops_api_version: str | None"}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.ops.AstraDBOpsConstructorParams.caller_name", "value": "caller_name: str | None"}} +{"id": "astrapy.core.ops.AstraDBOpsConstructorParams.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.ops.AstraDBOpsConstructorParams.caller_version", "value": "caller_version: str | None"}} +{"id": "astrapy.core.ops.AstraDBOps", "text": "", "metadata": {"kind": "class", "name": "AstraDBOps", "path": "astrapy.core.ops.AstraDBOps", "parameters": [{"name": "token", "type": "str | None"}, {"name": "dev_ops_url", "default": "None", "type": "str | None"}, {"name": "dev_ops_api_version", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}]}} +{"id": "astrapy.core.ops.AstraDBOps.client", "text": "", "metadata": {"kind": "attribute", "name": "client", "path": "astrapy.core.ops.AstraDBOps.client", "value": "client = httpx.Client()", "gathered_types": ["Client"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_client", "text": "", "metadata": {"kind": "attribute", "name": "async_client", "path": "astrapy.core.ops.AstraDBOps.async_client", "value": "async_client = httpx.AsyncClient()", "gathered_types": ["AsyncClient"]}} +{"id": "astrapy.core.ops.AstraDBOps.caller_name", "text": "", "metadata": {"kind": "attribute", "name": "caller_name", "path": "astrapy.core.ops.AstraDBOps.caller_name", "value": "caller_name = caller_name"}} +{"id": "astrapy.core.ops.AstraDBOps.caller_version", "text": "", "metadata": {"kind": "attribute", "name": "caller_version", "path": "astrapy.core.ops.AstraDBOps.caller_version", "value": "caller_version = caller_version"}} +{"id": "astrapy.core.ops.AstraDBOps.constructor_params", "text": "", "metadata": {"kind": "attribute", "name": "constructor_params", "path": "astrapy.core.ops.AstraDBOps.constructor_params", "value": "constructor_params: AstraDBOpsConstructorParams = {'token': token, 'dev_ops_url': dev_ops_url, 'dev_ops_api_version': dev_ops_api_version, 'caller_name': caller_name, 'caller_version': caller_version}", "gathered_types": ["AstraDBOpsConstructorParams"]}} +{"id": "astrapy.core.ops.AstraDBOps.token", "text": "", "metadata": {"kind": "attribute", "name": "token", "path": "astrapy.core.ops.AstraDBOps.token", "value": "token: str | None"}} +{"id": "astrapy.core.ops.AstraDBOps.base_url", "text": "", "metadata": {"kind": "attribute", "name": "base_url", "path": "astrapy.core.ops.AstraDBOps.base_url", "value": "base_url = f'{dev_ops_url}/{dev_ops_api_version}'"}} +{"id": "astrapy.core.ops.AstraDBOps.copy", "text": "", "metadata": {"kind": "function", "name": "copy", "path": "astrapy.core.ops.AstraDBOps.copy", "parameters": [{"name": "token", "default": "None", "type": "str | None"}, {"name": "dev_ops_url", "default": "None", "type": "str | None"}, {"name": "dev_ops_api_version", "default": "None", "type": "str | None"}, {"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "AstraDBOps"}], "gathered_types": ["astrapy.core.ops.AstraDBOps"]}} +{"id": "astrapy.core.ops.AstraDBOps.set_caller", "text": "", "metadata": {"kind": "function", "name": "set_caller", "path": "astrapy.core.ops.AstraDBOps.set_caller", "parameters": [{"name": "caller_name", "default": "None", "type": "str | None"}, {"name": "caller_version", "default": "None", "type": "str | None"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.ops.AstraDBOps.get_databases", "text": "Retrieve a list of databases.", "metadata": {"kind": "function", "name": "get_databases", "path": "astrapy.core.ops.AstraDBOps.get_databases", "parameters": [{"name": "options", "type": "dict", "description": "Additional options for the request.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "OPS_API_RESPONSE", "description": "a JSON list of dictionaries, one per database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_get_databases", "text": "Retrieve a list of databases - async version of the method.", "metadata": {"kind": "function", "name": "async_get_databases", "path": "astrapy.core.ops.AstraDBOps.async_get_databases", "parameters": [{"name": "options", "type": "dict", "description": "Additional options for the request.", "value": "None", "default": "None"}], "returns": [{"name": "list", "type": "OPS_API_RESPONSE", "description": "a JSON list of dictionaries, one per database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_database", "text": "Create a new database.", "metadata": {"kind": "function", "name": "create_database", "path": "astrapy.core.ops.AstraDBOps.create_database", "parameters": [{"name": "database_definition", "type": "dict", "description": "A dictionary defining the properties of the database to be created.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "dict[str, str]", "description": "A dictionary such as: {\"id\": the ID of the created database}"}, {"type": "dict[str, str]", "description": "Raises an error if not successful."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_create_database", "text": "Create a new database - async version of the method.", "metadata": {"kind": "function", "name": "async_create_database", "path": "astrapy.core.ops.AstraDBOps.async_create_database", "parameters": [{"name": "database_definition", "type": "dict", "description": "A dictionary defining the properties of the database to be created.", "value": "None", "default": "None"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "dict[str, str]", "description": "A dictionary such as: {\"id\": the ID of the created database}"}, {"type": "dict[str, str]", "description": "Raises an error if not successful."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.terminate_database", "text": "Terminate an existing database.", "metadata": {"kind": "function", "name": "terminate_database", "path": "astrapy.core.ops.AstraDBOps.terminate_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to terminate.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The identifier of the terminated database, or None if termination was unsuccessful."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_terminate_database", "text": "Terminate an existing database - async version of the method.", "metadata": {"kind": "function", "name": "async_terminate_database", "path": "astrapy.core.ops.AstraDBOps.async_terminate_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to terminate.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The identifier of the terminated database, or None if termination was unsuccessful."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_database", "text": "Retrieve details of a specific database.", "metadata": {"kind": "function", "name": "get_database", "path": "astrapy.core.ops.AstraDBOps.get_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to retrieve.", "value": "''", "default": "''"}, {"name": "options", "type": "dict", "description": "Additional options for the request.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "A JSON response containing the details of the specified database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_get_database", "text": "Retrieve details of a specific database - async version of the method.", "metadata": {"kind": "function", "name": "async_get_database", "path": "astrapy.core.ops.AstraDBOps.async_get_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to retrieve.", "value": "''", "default": "''"}, {"name": "options", "type": "dict", "description": "Additional options for the request.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "API_RESPONSE", "description": "A JSON response containing the details of the specified database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_keyspace", "text": "Create a keyspace in a specified database.", "metadata": {"kind": "function", "name": "create_keyspace", "path": "astrapy.core.ops.AstraDBOps.create_keyspace", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database where the keyspace will be created.", "value": "''", "default": "''"}, {"name": "keyspace", "type": "str", "description": "The name of the keyspace to create.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, str]", "description": "{\"ok\": 1} if successful. Raises errors otherwise."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_create_keyspace", "text": "Create a keyspace in a specified database - async version of the method.", "metadata": {"kind": "function", "name": "async_create_keyspace", "path": "astrapy.core.ops.AstraDBOps.async_create_keyspace", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database where the keyspace will be created.", "value": "''", "default": "''"}, {"name": "keyspace", "type": "str", "description": "The name of the keyspace to create.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"type": "dict[str, str]", "description": "{\"ok\": 1} if successful. Raises errors otherwise."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_keyspace", "text": "Delete a keyspace from a database", "metadata": {"kind": "function", "name": "delete_keyspace", "path": "astrapy.core.ops.AstraDBOps.delete_keyspace", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to terminate.", "value": "''", "default": "''"}, {"name": "keyspace", "type": "str", "description": "The name of the keyspace to create.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The identifier of the deleted keyspace. Otherwise raises an error."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.async_delete_keyspace", "text": "Delete a keyspace from a database - async version of the method.", "metadata": {"kind": "function", "name": "async_delete_keyspace", "path": "astrapy.core.ops.AstraDBOps.async_delete_keyspace", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to terminate.", "value": "''", "default": "''"}, {"name": "keyspace", "type": "str", "description": "The name of the keyspace to create.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "str", "type": "str", "description": "The identifier of the deleted keyspace. Otherwise raises an error."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.park_database", "text": "Park a specific database, making it inactive.", "metadata": {"kind": "function", "name": "park_database", "path": "astrapy.core.ops.AstraDBOps.park_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to park.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after parking the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.unpark_database", "text": "Unpark a specific database, making it active again.", "metadata": {"kind": "function", "name": "unpark_database", "path": "astrapy.core.ops.AstraDBOps.unpark_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to unpark.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after unparking the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.resize_database", "text": "Resize a specific database according to provided options.", "metadata": {"kind": "function", "name": "resize_database", "path": "astrapy.core.ops.AstraDBOps.resize_database", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database to resize.", "value": "''", "default": "''"}, {"name": "options", "type": "dict", "description": "The specifications for the resize operation.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after the resize operation."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.reset_database_password", "text": "Reset the password for a specific database.", "metadata": {"kind": "function", "name": "reset_database_password", "path": "astrapy.core.ops.AstraDBOps.reset_database_password", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to reset the password.", "value": "''", "default": "''"}, {"name": "options", "type": "dict", "description": "Additional options for the password reset.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after resetting the password."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_secure_bundle", "text": "Retrieve a secure bundle URL for a specific database.", "metadata": {"kind": "function", "name": "get_secure_bundle", "path": "astrapy.core.ops.AstraDBOps.get_secure_bundle", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to get the secure bundle.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The secure bundle URL and related information."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_datacenters", "text": "Get a list of datacenters associated with a specific database.", "metadata": {"kind": "function", "name": "get_datacenters", "path": "astrapy.core.ops.AstraDBOps.get_datacenters", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to list datacenters.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of datacenters and their details."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_datacenter", "text": "Create a new datacenter for a specific database.", "metadata": {"kind": "function", "name": "create_datacenter", "path": "astrapy.core.ops.AstraDBOps.create_datacenter", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to create the datacenter.", "value": "''", "default": "''"}, {"name": "options", "type": "dict", "description": "Specifications for the new datacenter.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the datacenter."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.terminate_datacenter", "text": "Terminate a specific datacenter in a database.", "metadata": {"kind": "function", "name": "terminate_datacenter", "path": "astrapy.core.ops.AstraDBOps.terminate_datacenter", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database containing the datacenter.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter to terminate.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after terminating the datacenter."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_access_list", "text": "Retrieve the access list for a specific database.", "metadata": {"kind": "function", "name": "get_access_list", "path": "astrapy.core.ops.AstraDBOps.get_access_list", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to get the access list.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The current access list for the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.replace_access_list", "text": "Replace the entire access list for a specific database.", "metadata": {"kind": "function", "name": "replace_access_list", "path": "astrapy.core.ops.AstraDBOps.replace_access_list", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to replace the access list.", "value": "''", "default": "''"}, {"name": "access_list", "type": "dict", "description": "The new access list to be set.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after replacing the access list."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.update_access_list", "text": "Update the access list for a specific database.", "metadata": {"kind": "function", "name": "update_access_list", "path": "astrapy.core.ops.AstraDBOps.update_access_list", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to update the access list.", "value": "''", "default": "''"}, {"name": "access_list", "type": "dict", "description": "The updates to be applied to the access list.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after updating the access list."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.add_access_list_address", "text": "Add a new address to the access list for a specific database.", "metadata": {"kind": "function", "name": "add_access_list_address", "path": "astrapy.core.ops.AstraDBOps.add_access_list_address", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to add the address.", "value": "''", "default": "''"}, {"name": "address", "type": "dict", "description": "The address details to add to the access list.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after adding the address."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_access_list", "text": "Delete the access list for a specific database.", "metadata": {"kind": "function", "name": "delete_access_list", "path": "astrapy.core.ops.AstraDBOps.delete_access_list", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database for which to delete the access list.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after deleting the access list."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_private_link", "text": "Retrieve the private link information for a specified database.", "metadata": {"kind": "function", "name": "get_private_link", "path": "astrapy.core.ops.AstraDBOps.get_private_link", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The private link information for the database."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_datacenter_private_link", "text": "Retrieve the private link information for a specific datacenter in a database.", "metadata": {"kind": "function", "name": "get_datacenter_private_link", "path": "astrapy.core.ops.AstraDBOps.get_datacenter_private_link", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The private link information for the specified datacenter."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_datacenter_private_link", "text": "Create a private link for a specific datacenter in a database.", "metadata": {"kind": "function", "name": "create_datacenter_private_link", "path": "astrapy.core.ops.AstraDBOps.create_datacenter_private_link", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}, {"name": "private_link", "type": "dict", "description": "The private link configuration details.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the private link."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_datacenter_endpoint", "text": "Create an endpoint for a specific datacenter in a database.", "metadata": {"kind": "function", "name": "create_datacenter_endpoint", "path": "astrapy.core.ops.AstraDBOps.create_datacenter_endpoint", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}, {"name": "endpoint", "type": "dict", "description": "The endpoint configuration details.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the endpoint."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.update_datacenter_endpoint", "text": "Update an existing endpoint for a specific datacenter in a database.", "metadata": {"kind": "function", "name": "update_datacenter_endpoint", "path": "astrapy.core.ops.AstraDBOps.update_datacenter_endpoint", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}, {"name": "endpoint", "type": "dict", "description": "The updated endpoint configuration details.", "value": "{}", "default": "{}"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after updating the endpoint."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_datacenter_endpoint", "text": "Retrieve information about a specific endpoint in a datacenter of a database.", "metadata": {"kind": "function", "name": "get_datacenter_endpoint", "path": "astrapy.core.ops.AstraDBOps.get_datacenter_endpoint", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}, {"name": "endpoint", "type": "str", "description": "The identifier of the endpoint.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The endpoint information for the specified datacenter."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_datacenter_endpoint", "text": "Delete a specific endpoint in a datacenter of a database.", "metadata": {"kind": "function", "name": "delete_datacenter_endpoint", "path": "astrapy.core.ops.AstraDBOps.delete_datacenter_endpoint", "parameters": [{"name": "database", "type": "str", "description": "The identifier of the database.", "value": "''", "default": "''"}, {"name": "datacenter", "type": "str", "description": "The identifier of the datacenter.", "value": "''", "default": "''"}, {"name": "endpoint", "type": "str", "description": "The identifier of the endpoint to delete.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after deleting the endpoint."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_available_classic_regions", "text": "Retrieve a list of available classic regions.", "metadata": {"kind": "function", "name": "get_available_classic_regions", "path": "astrapy.core.ops.AstraDBOps.get_available_classic_regions", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of available classic regions."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_available_regions", "text": "Retrieve a list of available regions for serverless deployment.", "metadata": {"kind": "function", "name": "get_available_regions", "path": "astrapy.core.ops.AstraDBOps.get_available_regions", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of available regions for serverless deployment."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_roles", "text": "Retrieve a list of roles within the organization.", "metadata": {"kind": "function", "name": "get_roles", "path": "astrapy.core.ops.AstraDBOps.get_roles", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of roles within the organization."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_role", "text": "Create a new role within the organization.", "metadata": {"kind": "function", "name": "create_role", "path": "astrapy.core.ops.AstraDBOps.create_role", "parameters": [{"name": "role_definition", "type": "dict", "description": "The definition of the role to be created.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the role."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_role", "text": "Retrieve details of a specific role within the organization.", "metadata": {"kind": "function", "name": "get_role", "path": "astrapy.core.ops.AstraDBOps.get_role", "parameters": [{"name": "role", "type": "str", "description": "The identifier of the role.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The details of the specified role."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.update_role", "text": "Update the definition of an existing role within the organization.", "metadata": {"kind": "function", "name": "update_role", "path": "astrapy.core.ops.AstraDBOps.update_role", "parameters": [{"name": "role", "type": "str", "description": "The identifier of the role to update.", "value": "''", "default": "''"}, {"name": "role_definition", "type": "dict", "description": "The new definition of the role.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after updating the role."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_role", "text": "Delete a specific role from the organization.", "metadata": {"kind": "function", "name": "delete_role", "path": "astrapy.core.ops.AstraDBOps.delete_role", "parameters": [{"name": "role", "type": "str", "description": "The identifier of the role to delete.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after deleting the role."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.invite_user", "text": "Invite a new user to the organization.", "metadata": {"kind": "function", "name": "invite_user", "path": "astrapy.core.ops.AstraDBOps.invite_user", "parameters": [{"name": "user_definition", "type": "dict", "description": "The definition of the user to be invited.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after inviting the user."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_users", "text": "Retrieve a list of users within the organization.", "metadata": {"kind": "function", "name": "get_users", "path": "astrapy.core.ops.AstraDBOps.get_users", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of users within the organization."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_user", "text": "Retrieve details of a specific user within the organization.", "metadata": {"kind": "function", "name": "get_user", "path": "astrapy.core.ops.AstraDBOps.get_user", "parameters": [{"name": "user", "type": "str", "description": "The identifier of the user.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The details of the specified user."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.remove_user", "text": "Remove a user from the organization.", "metadata": {"kind": "function", "name": "remove_user", "path": "astrapy.core.ops.AstraDBOps.remove_user", "parameters": [{"name": "user", "type": "str", "description": "The identifier of the user to remove.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after removing the user."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.update_user_roles", "text": "Update the roles assigned to a specific user within the organization.", "metadata": {"kind": "function", "name": "update_user_roles", "path": "astrapy.core.ops.AstraDBOps.update_user_roles", "parameters": [{"name": "user", "type": "str", "description": "The identifier of the user.", "value": "''", "default": "''"}, {"name": "roles", "type": "list", "description": "The list of new roles to assign to the user.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after updating the user's roles."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_clients", "text": "Retrieve a list of client IDs and secrets associated with the organization.", "metadata": {"kind": "function", "name": "get_clients", "path": "astrapy.core.ops.AstraDBOps.get_clients", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of client IDs and their associated secrets."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_token", "text": "Create a new token with specific roles.", "metadata": {"kind": "function", "name": "create_token", "path": "astrapy.core.ops.AstraDBOps.create_token", "parameters": [{"name": "roles", "type": "dict", "description": "The roles to associate with the token:\n{\"roles\": [\"\"]}", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the token."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_token", "text": "Delete a specific token.", "metadata": {"kind": "function", "name": "delete_token", "path": "astrapy.core.ops.AstraDBOps.delete_token", "parameters": [{"name": "token", "type": "str", "description": "The identifier of the token to delete.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after deleting the token."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_organization", "text": "Retrieve details of the current organization.", "metadata": {"kind": "function", "name": "get_organization", "path": "astrapy.core.ops.AstraDBOps.get_organization", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The details of the organization."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_access_lists", "text": "Retrieve a list of access lists for the organization.", "metadata": {"kind": "function", "name": "get_access_lists", "path": "astrapy.core.ops.AstraDBOps.get_access_lists", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of access lists."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_access_list_template", "text": "Retrieve a template for creating an access list.", "metadata": {"kind": "function", "name": "get_access_list_template", "path": "astrapy.core.ops.AstraDBOps.get_access_list_template", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "An access list template."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.validate_access_list", "text": "Validate the configuration of the access list.", "metadata": {"kind": "function", "name": "validate_access_list", "path": "astrapy.core.ops.AstraDBOps.validate_access_list", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The validation result of the access list configuration."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_private_links", "text": "Retrieve a list of private link connections for the organization.", "metadata": {"kind": "function", "name": "get_private_links", "path": "astrapy.core.ops.AstraDBOps.get_private_links", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of private link connections."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_streaming_providers", "text": "Retrieve a list of streaming service providers.", "metadata": {"kind": "function", "name": "get_streaming_providers", "path": "astrapy.core.ops.AstraDBOps.get_streaming_providers", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of available streaming service providers."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_streaming_tenants", "text": "Retrieve a list of streaming tenants.", "metadata": {"kind": "function", "name": "get_streaming_tenants", "path": "astrapy.core.ops.AstraDBOps.get_streaming_tenants", "parameters": [{"name": "timeout_info", "default": "None", "type": "TimeoutInfoWideType"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "A list of streaming tenants and their details."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.create_streaming_tenant", "text": "Create a new streaming tenant.", "metadata": {"kind": "function", "name": "create_streaming_tenant", "path": "astrapy.core.ops.AstraDBOps.create_streaming_tenant", "parameters": [{"name": "tenant", "type": "dict", "description": "The configuration details for the new streaming tenant.", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "The response from the server after creating the streaming tenant."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.ops.AstraDBOps.delete_streaming_tenant", "text": "Delete a specific streaming tenant from a cluster.", "metadata": {"kind": "function", "name": "delete_streaming_tenant", "path": "astrapy.core.ops.AstraDBOps.delete_streaming_tenant", "parameters": [{"name": "tenant", "type": "str", "description": "The identifier of the tenant to delete.", "value": "''", "default": "''"}, {"name": "cluster", "type": "str", "description": "The identifier of the cluster from which the tenant is to be deleted.", "value": "''", "default": "''"}, {"name": "timeout_info", "type": "TimeoutInfoWideType", "description": "either a float (seconds) or a TimeoutInfo dict (see)", "value": "None", "default": "None"}], "returns": [{"name": "dict", "type": "None", "description": "The response from the server after deleting the streaming tenant."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType"]}} +{"id": "astrapy.core.ops.AstraDBOps.get_streaming_tenant", "text": "Retrieve information about the limits and usage of a specific streaming tenant.", "metadata": {"kind": "function", "name": "get_streaming_tenant", "path": "astrapy.core.ops.AstraDBOps.get_streaming_tenant", "parameters": [{"name": "tenant", "type": "str", "description": "The identifier of the streaming tenant.", "value": "''", "default": "''"}], "returns": [{"name": "dict", "type": "OPS_API_RESPONSE", "description": "Details of the specified streaming tenant, including limits and current usage."}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "astrapy.core.core_types.OPS_API_RESPONSE"]}} +{"id": "astrapy.core.core_types", "text": "", "metadata": {"kind": "module", "name": "core_types", "path": "astrapy.core.core_types", "imports": {"annotations": "__future__.annotations", "Any": "typing.Any", "Dict": "typing.Dict", "List": "typing.List", "Protocol": "typing.Protocol", "Union": "typing.Union"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.core_types.API_RESPONSE", "text": "", "metadata": {"kind": "attribute", "name": "API_RESPONSE", "path": "astrapy.core.core_types.API_RESPONSE", "value": "API_RESPONSE = Dict[str, Any]"}} +{"id": "astrapy.core.core_types.OPS_API_RESPONSE", "text": "", "metadata": {"kind": "attribute", "name": "OPS_API_RESPONSE", "path": "astrapy.core.core_types.OPS_API_RESPONSE", "value": "OPS_API_RESPONSE = Union[API_RESPONSE, List[Any]]", "gathered_types": ["astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.core_types.API_DOC", "text": "", "metadata": {"kind": "attribute", "name": "API_DOC", "path": "astrapy.core.core_types.API_DOC", "value": "API_DOC = Dict[str, Any]"}} +{"id": "astrapy.core.core_types.PaginableRequestMethod", "text": "", "metadata": {"kind": "class", "name": "PaginableRequestMethod", "path": "astrapy.core.core_types.PaginableRequestMethod", "bases": ["Protocol"]}} +{"id": "astrapy.core.core_types.AsyncPaginableRequestMethod", "text": "", "metadata": {"kind": "class", "name": "AsyncPaginableRequestMethod", "path": "astrapy.core.core_types.AsyncPaginableRequestMethod", "bases": ["Protocol"]}} +{"id": "astrapy.core.utils", "text": "", "metadata": {"kind": "module", "name": "utils", "path": "astrapy.core.utils", "imports": {"annotations": "__future__.annotations", "datetime": "datetime", "json": "json", "logging": "logging", "time": "time", "Any": "typing.Any", "Dict": "typing.Dict", "Iterable": "typing.Iterable", "TypedDict": "typing.TypedDict", "Union": "typing.Union", "cast": "typing.cast", "httpx": "httpx", "__version__": "astrapy.__version__", "API_RESPONSE": "astrapy.core.core_types.API_RESPONSE", "DEFAULT_REDACTED_HEADERS": "astrapy.core.defaults.DEFAULT_REDACTED_HEADERS", "DEFAULT_TIMEOUT": "astrapy.core.defaults.DEFAULT_TIMEOUT", "UUID": "astrapy.core.ids.UUID", "ObjectId": "astrapy.core.ids.ObjectId"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.utils.CustomLogger", "text": "", "metadata": {"kind": "class", "name": "CustomLogger", "path": "astrapy.core.utils.CustomLogger", "bases": ["logging.Logger"], "gathered_types": ["Logger"]}} +{"id": "astrapy.core.utils.CustomLogger.trace", "text": "", "metadata": {"kind": "function", "name": "trace", "path": "astrapy.core.utils.CustomLogger.trace", "parameters": [{"name": "msg", "type": "str"}, {"name": "args", "default": "()", "type": "Any"}, {"name": "kwargs", "default": "{}", "type": "Any"}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.utils.logger", "text": "", "metadata": {"kind": "attribute", "name": "logger", "path": "astrapy.core.utils.logger", "value": "logger = logging.getLogger(__name__)", "gathered_types": ["__name__"]}} +{"id": "astrapy.core.utils.http_methods", "text": "", "metadata": {"kind": "class", "name": "http_methods", "path": "astrapy.core.utils.http_methods"}} +{"id": "astrapy.core.utils.http_methods.GET", "text": "", "metadata": {"kind": "attribute", "name": "GET", "path": "astrapy.core.utils.http_methods.GET", "value": "GET = 'GET'"}} +{"id": "astrapy.core.utils.http_methods.POST", "text": "", "metadata": {"kind": "attribute", "name": "POST", "path": "astrapy.core.utils.http_methods.POST", "value": "POST = 'POST'"}} +{"id": "astrapy.core.utils.http_methods.PUT", "text": "", "metadata": {"kind": "attribute", "name": "PUT", "path": "astrapy.core.utils.http_methods.PUT", "value": "PUT = 'PUT'"}} +{"id": "astrapy.core.utils.http_methods.PATCH", "text": "", "metadata": {"kind": "attribute", "name": "PATCH", "path": "astrapy.core.utils.http_methods.PATCH", "value": "PATCH = 'PATCH'"}} +{"id": "astrapy.core.utils.http_methods.DELETE", "text": "", "metadata": {"kind": "attribute", "name": "DELETE", "path": "astrapy.core.utils.http_methods.DELETE", "value": "DELETE = 'DELETE'"}} +{"id": "astrapy.core.utils.package_name", "text": "", "metadata": {"kind": "attribute", "name": "package_name", "path": "astrapy.core.utils.package_name", "value": "package_name = __name__.split('.')[0]", "gathered_types": ["__name__"]}} +{"id": "astrapy.core.utils.user_agent_astrapy", "text": "", "metadata": {"kind": "attribute", "name": "user_agent_astrapy", "path": "astrapy.core.utils.user_agent_astrapy", "value": "user_agent_astrapy = f'{package_name}/{__version__}'", "gathered_types": ["astrapy.__version__"]}} +{"id": "astrapy.core.utils.detect_ragstack_user_agent", "text": "", "metadata": {"kind": "function", "name": "detect_ragstack_user_agent", "path": "astrapy.core.utils.detect_ragstack_user_agent", "returns": [{"type": "str | None"}]}} +{"id": "astrapy.core.utils.user_agent_rs", "text": "", "metadata": {"kind": "attribute", "name": "user_agent_rs", "path": "astrapy.core.utils.user_agent_rs", "value": "user_agent_rs = detect_ragstack_user_agent()"}} +{"id": "astrapy.core.utils.log_request", "text": "Log the details of an HTTP request for debugging purposes.", "metadata": {"kind": "function", "name": "log_request", "path": "astrapy.core.utils.log_request", "parameters": [{"name": "json_data", "type": "dict or None", "description": "The JSON payload sent with the request, if any.", "default": null}], "returns": [{"type": "None"}]}} +{"id": "astrapy.core.utils.log_response", "text": "Log the details of an HTTP response for debugging purposes.", "metadata": {"kind": "function", "name": "log_response", "path": "astrapy.core.utils.log_response", "parameters": [{"name": "r", "type": "requests.Response", "description": "The response object from the HTTP request.", "default": null}], "returns": [{"type": "None"}], "gathered_types": ["Response"]}} +{"id": "astrapy.core.utils.user_agent_string", "text": "", "metadata": {"kind": "function", "name": "user_agent_string", "path": "astrapy.core.utils.user_agent_string", "parameters": [{"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}], "returns": [{"type": "str | None"}]}} +{"id": "astrapy.core.utils.compose_user_agent", "text": "", "metadata": {"kind": "function", "name": "compose_user_agent", "path": "astrapy.core.utils.compose_user_agent", "parameters": [{"name": "caller_name", "type": "str | None"}, {"name": "caller_version", "type": "str | None"}], "returns": [{"type": "str"}]}} +{"id": "astrapy.core.utils.TimeoutInfo", "text": "", "metadata": {"kind": "class", "name": "TimeoutInfo", "path": "astrapy.core.utils.TimeoutInfo", "bases": ["TypedDict"]}} +{"id": "astrapy.core.utils.TimeoutInfo.read", "text": "", "metadata": {"kind": "attribute", "name": "read", "path": "astrapy.core.utils.TimeoutInfo.read", "value": "read: float"}} +{"id": "astrapy.core.utils.TimeoutInfo.write", "text": "", "metadata": {"kind": "attribute", "name": "write", "path": "astrapy.core.utils.TimeoutInfo.write", "value": "write: float"}} +{"id": "astrapy.core.utils.TimeoutInfo.base", "text": "", "metadata": {"kind": "attribute", "name": "base", "path": "astrapy.core.utils.TimeoutInfo.base", "value": "base: float"}} +{"id": "astrapy.core.utils.TimeoutInfoWideType", "text": "", "metadata": {"kind": "attribute", "name": "TimeoutInfoWideType", "path": "astrapy.core.utils.TimeoutInfoWideType", "value": "TimeoutInfoWideType = Union[TimeoutInfo, float, None]", "gathered_types": ["astrapy.request_tools.TimeoutInfo"]}} +{"id": "astrapy.core.utils.to_httpx_timeout", "text": "", "metadata": {"kind": "function", "name": "to_httpx_timeout", "path": "astrapy.core.utils.to_httpx_timeout", "parameters": [{"name": "timeout_info", "type": "TimeoutInfoWideType"}], "returns": [{"type": "httpx.Timeout | None"}], "gathered_types": ["astrapy.core.utils.TimeoutInfoWideType", "Timeout"]}} +{"id": "astrapy.core.utils.make_request", "text": "Make an HTTP request to a specified URL.", "metadata": {"kind": "function", "name": "make_request", "path": "astrapy.core.utils.make_request", "parameters": [{"name": "client", "type": "httpx", "description": "The httpx client for the request.", "default": null}, {"name": "base_url", "type": "str", "description": "The base URL for the request.", "default": null}, {"name": "auth_header", "type": "str", "description": "The authentication header key.", "default": null}, {"name": "token", "type": "str", "description": "The token used for authentication.", "default": null}, {"name": "method", "type": "str", "description": "The HTTP method to use for the request. Default is POST.", "default": null}, {"name": "path", "type": "str", "description": "The specific path to append to the base URL.", "default": null}, {"name": "json_data", "type": "dict", "description": "JSON payload to be sent with the request.", "default": null}, {"name": "url_params", "type": "dict", "description": "URL parameters to be sent with the request.", "default": null}], "returns": [{"type": "httpx.Response", "description": "requests.Response: The response from the HTTP request."}], "gathered_types": ["Client", "Response", "Timeout"]}} +{"id": "astrapy.core.utils.amake_request", "text": "Make an HTTP request to a specified URL.", "metadata": {"kind": "function", "name": "amake_request", "path": "astrapy.core.utils.amake_request", "parameters": [{"name": "client", "type": "httpx", "description": "The httpx client for the request.", "default": null}, {"name": "base_url", "type": "str", "description": "The base URL for the request.", "default": null}, {"name": "auth_header", "type": "str", "description": "The authentication header key.", "default": null}, {"name": "token", "type": "str", "description": "The token used for authentication.", "default": null}, {"name": "method", "type": "str", "description": "The HTTP method to use for the request. Default is POST.", "default": null}, {"name": "path", "type": "str", "description": "The specific path to append to the base URL.", "default": null}, {"name": "json_data", "type": "dict", "description": "JSON payload to be sent with the request.", "default": null}, {"name": "url_params", "type": "dict", "description": "URL parameters to be sent with the request.", "default": null}], "returns": [{"type": "httpx.Response", "description": "requests.Response: The response from the HTTP request."}], "gathered_types": ["AsyncClient", "Response", "Timeout"]}} +{"id": "astrapy.core.utils.make_payload", "text": "Construct a JSON payload for an HTTP request with a specified top-level key.", "metadata": {"kind": "function", "name": "make_payload", "path": "astrapy.core.utils.make_payload", "parameters": [{"name": "top_level", "type": "str", "description": "The top-level key for the JSON payload.", "default": null}, {"name": "**kwargs", "type": "Any", "description": "Arbitrary keyword arguments representing other keys and their values to be included in the payload.", "value": "{}", "default": "{}"}], "returns": [{"name": "dict", "type": "dict[str, Any]", "description": "The constructed JSON payload."}]}} +{"id": "astrapy.core.utils.convert_vector_to_floats", "text": "Convert a vector of strings to a vector of floats.", "metadata": {"kind": "function", "name": "convert_vector_to_floats", "path": "astrapy.core.utils.convert_vector_to_floats", "parameters": [{"name": "vector", "type": "list", "description": "A vector of objects.", "default": null}], "returns": [{"name": "list", "type": "list[float]", "description": "A vector of floats."}]}} +{"id": "astrapy.core.utils.is_list_of_floats", "text": "Safely determine if it's a list of floats.\nAssumption: if list, and first item is float, then all items are.", "metadata": {"kind": "function", "name": "is_list_of_floats", "path": "astrapy.core.utils.is_list_of_floats", "parameters": [{"name": "vector", "type": "Iterable[Any]"}], "returns": [{"type": "bool"}]}} +{"id": "astrapy.core.utils.convert_to_ejson_date_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_date_object", "path": "astrapy.core.utils.convert_to_ejson_date_object", "parameters": [{"name": "date_value", "type": "datetime.date | datetime.datetime"}], "returns": [{"type": "dict[str, int]"}]}} +{"id": "astrapy.core.utils.convert_to_ejson_uuid_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_uuid_object", "path": "astrapy.core.utils.convert_to_ejson_uuid_object", "parameters": [{"name": "uuid_value", "type": "UUID"}], "returns": [{"type": "dict[str, str]"}], "gathered_types": ["UUID"]}} +{"id": "astrapy.core.utils.convert_to_ejson_objectid_object", "text": "", "metadata": {"kind": "function", "name": "convert_to_ejson_objectid_object", "path": "astrapy.core.utils.convert_to_ejson_objectid_object", "parameters": [{"name": "objectid_value", "type": "ObjectId"}], "returns": [{"type": "dict[str, str]"}], "gathered_types": ["ObjectId"]}} +{"id": "astrapy.core.utils.convert_ejson_date_object_to_datetime", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_date_object_to_datetime", "path": "astrapy.core.utils.convert_ejson_date_object_to_datetime", "parameters": [{"name": "date_object", "type": "dict[str, int]"}], "returns": [{"type": "datetime.datetime"}]}} +{"id": "astrapy.core.utils.convert_ejson_uuid_object_to_uuid", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_uuid_object_to_uuid", "path": "astrapy.core.utils.convert_ejson_uuid_object_to_uuid", "parameters": [{"name": "uuid_object", "type": "dict[str, str]"}], "returns": [{"type": "UUID"}], "gathered_types": ["UUID"]}} +{"id": "astrapy.core.utils.convert_ejson_objectid_object_to_objectid", "text": "", "metadata": {"kind": "function", "name": "convert_ejson_objectid_object_to_objectid", "path": "astrapy.core.utils.convert_ejson_objectid_object_to_objectid", "parameters": [{"name": "objectid_object", "type": "dict[str, str]"}], "returns": [{"type": "ObjectId"}], "gathered_types": ["ObjectId"]}} +{"id": "astrapy.core.utils.normalize_for_api", "text": "Normalize a payload for API calls.\nThis includes e.g. ensuring values for \"$vector\" key\nare made into plain lists of floats.", "metadata": {"kind": "function", "name": "normalize_for_api", "path": "astrapy.core.utils.normalize_for_api", "parameters": [{"name": "payload", "type": "Dict[str, Any]", "description": "A dict expressing a payload for an API call", "default": null}], "returns": [{"type": "dict[str, Any] | None", "description": "Dict[str, Any]: a \"normalized\" payload dict"}]}} +{"id": "astrapy.core.utils.restore_from_api", "text": "Process a dictionary just returned from the API.\nThis is the place where e.g. `{\"$date\": 123}` is\nconverted back into a datetime object.", "metadata": {"kind": "function", "name": "restore_from_api", "path": "astrapy.core.utils.restore_from_api", "parameters": [{"name": "response", "type": "API_RESPONSE"}], "returns": [{"type": "API_RESPONSE"}], "gathered_types": ["astrapy.core.core_types.API_RESPONSE"]}} +{"id": "astrapy.core.defaults", "text": "", "metadata": {"kind": "module", "name": "defaults", "path": "astrapy.core.defaults", "imports": {"annotations": "__future__.annotations"}, "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.core.defaults.DEFAULT_AUTH_PATH", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_AUTH_PATH", "path": "astrapy.core.defaults.DEFAULT_AUTH_PATH", "value": "DEFAULT_AUTH_PATH = '/api/rest/v1/auth'"}} +{"id": "astrapy.core.defaults.DEFAULT_JSON_API_PATH", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_JSON_API_PATH", "path": "astrapy.core.defaults.DEFAULT_JSON_API_PATH", "value": "DEFAULT_JSON_API_PATH = '/api/json'"}} +{"id": "astrapy.core.defaults.DEFAULT_JSON_API_VERSION", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_JSON_API_VERSION", "path": "astrapy.core.defaults.DEFAULT_JSON_API_VERSION", "value": "DEFAULT_JSON_API_VERSION = 'v1'"}} +{"id": "astrapy.core.defaults.DEFAULT_DEV_OPS_URL", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DEV_OPS_URL", "path": "astrapy.core.defaults.DEFAULT_DEV_OPS_URL", "value": "DEFAULT_DEV_OPS_URL = 'https://api.astra.datastax.com'"}} +{"id": "astrapy.core.defaults.DEFAULT_DEV_OPS_API_VERSION", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DEV_OPS_API_VERSION", "path": "astrapy.core.defaults.DEFAULT_DEV_OPS_API_VERSION", "value": "DEFAULT_DEV_OPS_API_VERSION = 'v2'"}} +{"id": "astrapy.core.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_DEV_OPS_AUTH_HEADER", "path": "astrapy.core.defaults.DEFAULT_DEV_OPS_AUTH_HEADER", "value": "DEFAULT_DEV_OPS_AUTH_HEADER = 'Authorization'"}} +{"id": "astrapy.core.defaults.DEFAULT_TIMEOUT", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_TIMEOUT", "path": "astrapy.core.defaults.DEFAULT_TIMEOUT", "value": "DEFAULT_TIMEOUT = 30000"}} +{"id": "astrapy.core.defaults.DEFAULT_AUTH_HEADER", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_AUTH_HEADER", "path": "astrapy.core.defaults.DEFAULT_AUTH_HEADER", "value": "DEFAULT_AUTH_HEADER = 'Token'"}} +{"id": "astrapy.core.defaults.DEFAULT_KEYSPACE_NAME", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_KEYSPACE_NAME", "path": "astrapy.core.defaults.DEFAULT_KEYSPACE_NAME", "value": "DEFAULT_KEYSPACE_NAME = 'default_keyspace'"}} +{"id": "astrapy.core.defaults.DEFAULT_REGION", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_REGION", "path": "astrapy.core.defaults.DEFAULT_REGION", "value": "DEFAULT_REGION = 'us-east1'"}} +{"id": "astrapy.core.defaults.DEFAULT_INSERT_NUM_DOCUMENTS", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_INSERT_NUM_DOCUMENTS", "path": "astrapy.core.defaults.DEFAULT_INSERT_NUM_DOCUMENTS", "value": "DEFAULT_INSERT_NUM_DOCUMENTS = 50"}} +{"id": "astrapy.core.defaults.DEFAULT_REDACTED_HEADERS", "text": "", "metadata": {"kind": "attribute", "name": "DEFAULT_REDACTED_HEADERS", "path": "astrapy.core.defaults.DEFAULT_REDACTED_HEADERS", "value": "DEFAULT_REDACTED_HEADERS = {DEFAULT_DEV_OPS_AUTH_HEADER, DEFAULT_AUTH_HEADER, 'X-Embedding-Api-Key', 'X-Embedding-Access-Id', 'X-Embedding-Secret-Id'}", "gathered_types": ["astrapy.core.defaults.DEFAULT_AUTH_HEADER", "astrapy.core.defaults.DEFAULT_DEV_OPS_AUTH_HEADER"]}} +{"id": "astrapy.core.ids", "text": "", "metadata": {"kind": "module", "name": "ids", "path": "astrapy.core.ids", "imports": {"annotations": "__future__.annotations", "UUID": "uuid.UUID", "uuid1": "uuid.uuid1", "uuid3": "uuid.uuid3", "uuid4": "uuid.uuid4", "uuid5": "uuid.uuid5", "ObjectId": "bson.objectid.ObjectId", "uuid6": "uuid6.uuid6", "uuid7": "uuid6.uuid7", "uuid8": "uuid6.uuid8"}, "exports": ["ObjectId", "uuid1", "uuid3", "uuid4", "uuid5", "uuid6", "uuid7", "uuid8", "UUID"], "properties": {"is_init_module": false, "is_package": false, "is_subpackage": false, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.db", "text": "Core \"db\" subpackage, exported here to preserve import patterns.", "metadata": {"kind": "module", "name": "db", "path": "astrapy.db", "imports": {"annotations": "__future__.annotations", "AstraDB": "astrapy.core.db.AstraDB", "AstraDBCollection": "astrapy.core.db.AstraDBCollection", "AsyncAstraDB": "astrapy.core.db.AsyncAstraDB", "AsyncAstraDBCollection": "astrapy.core.db.AsyncAstraDBCollection", "logger": "astrapy.core.db.logger"}, "exports": ["AsyncAstraDBCollection", "AsyncAstraDB", "logger", "AstraDBCollection", "AstraDB"], "properties": {"is_init_module": true, "is_package": false, "is_subpackage": true, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.api", "text": "Core \"api\" subpackage, exported here to preserve import patterns.", "metadata": {"kind": "module", "name": "api", "path": "astrapy.api", "imports": {"annotations": "__future__.annotations", "APIRequestError": "astrapy.core.api.APIRequestError"}, "exports": ["APIRequestError"], "properties": {"is_init_module": true, "is_package": false, "is_subpackage": true, "is_namespace_package": false, "is_namespace_subpackage": false}}} +{"id": "astrapy.ops", "text": "Core \"ops\" subpackage, exported here to preserve import patterns.", "metadata": {"kind": "module", "name": "ops", "path": "astrapy.ops", "imports": {"annotations": "__future__.annotations", "AstraDBOps": "astrapy.core.ops.AstraDBOps"}, "exports": ["AstraDBOps"], "properties": {"is_init_module": true, "is_package": false, "is_subpackage": true, "is_namespace_package": false, "is_namespace_subpackage": false}}} diff --git a/docs/examples/code-generation.ipynb b/docs/examples/code-generation.ipynb new file mode 100644 index 00000000..c25c3fb2 --- /dev/null +++ b/docs/examples/code-generation.ipynb @@ -0,0 +1,817 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "hide_input" + ] + }, + "outputs": [], + "source": [ + "# ruff: noqa: T201" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "# Code Generation with GraphRAG\n", + "\n", + "## Introduction\n", + "\n", + "In this notebook we will show how GraphRAG can be used to traverse through python library documentation in order to provide help to an LLM that is generating code.\n", + "\n", + "We'll use a custom Strategy to traverse through the documents and select nodes that contain code examples and/or descriptive text.\n", + "\n", + "The query we will be sending to the LLM is the following:" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "query = \"\"\"\n", + "Generate a function for connecting to an AstraDB cluster using the AstraPy library,\n", + "and retrieve some rows from a collection. The number of rows to return should be a\n", + "parameter on the method. Use Token Authentication. Assume the cluster is hosted on\n", + "AstraDB. Include the necessary imports and any other necessary setup. The following\n", + "environment variables are available for your use:\n", + "\n", + "- `ASTRA_DB_API_ENDPOINT`: The Astra DB API endpoint.\n", + "- `ASTRA_DB_APPLICATION_TOKEN`: The Astra DB Application token.\n", + "- `ASTRA_DB_KEYSPACE`: The Astra DB keyspace.\n", + "- `ASTRA_DB_COLLECTION`: The Astra DB collection.\" \\\n", + "\"\"\"" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Environment Setup\n", + "\n", + "The following block will configure the environment from the Colab Secrets.\n", + "To run it, you should have the following Colab Secrets defined and accessible to this notebook:\n", + "\n", + "- `OPENAI_API_KEY`: The OpenAI key.\n", + "- `ASTRA_DB_API_ENDPOINT`: The Astra DB API endpoint.\n", + "- `ASTRA_DB_APPLICATION_TOKEN`: The Astra DB Application token.\n", + "- `LANGCHAIN_API_KEY`: Optional. If defined, will enable LangSmith tracing.\n", + "- `ASTRA_DB_KEYSPACE`: Optional. If defined, will specify the Astra DB keyspace. If not defined, will use the default." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Install modules.\n", + "\n", + "%pip install \\\n", + " langchain-core \\\n", + " langchain-astradb \\\n", + " langchain-openai \\\n", + " langchain-graph-retriever \\\n", + " graph-rag-example-helpers" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The last package -- `graph-rag-example-helpers` -- includes the helpers and example documents that we will use in this notebook." + ] + }, + { + "cell_type": "code", + "execution_count": 49, + "metadata": {}, + "outputs": [], + "source": [ + "# Configure import paths.\n", + "import os\n", + "import sys\n", + "\n", + "from langchain_core.documents import Document\n", + "\n", + "sys.path.append(\"../../\")\n", + "\n", + "# Initialize environment variables.\n", + "from graph_rag_example_helpers.env import Environment, initialize_environment\n", + "\n", + "initialize_environment(Environment.ASTRAPY)\n", + "\n", + "os.environ[\"LANGCHAIN_PROJECT\"] = \"code-generation\"\n", + "os.environ[\"ASTRA_DB_COLLECTION\"] = \"code_generation\"\n", + "\n", + "\n", + "def print_doc_ids(docs: list[Document]):\n", + " [print(f\"`{doc.id}` has example: {'example' in doc.metadata}\") for doc in docs]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Part 1: Loading Data\n", + "\n", + "First, we'll demonstrate how to load the example AstraPy documentation into `AstraDBVectorStore`. We will be creating a LangChain Document for every module, class, attribute, and function in the package. \n", + "\n", + "We will use the pydoc description field for the `page_content` field in the document. Note that not every item in the package has a description. Because of this, there will be many documents that have no page content. \n", + "\n", + "Besides the description, we will also include a bunch of extra information related to the item in the `metadata` field. This info can include the item's name, kind, parameters, return type, base class, etc.\n", + "\n", + "The item's `id` will be the items path in the package.\n", + "\n", + "Below are two example documents... One with page content and one without." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Example doc with page content\n", + "\n", + "
Click to expand\n", + "\n", + "```yaml\n", + "id: astrapy.client.DataAPIClient\n", + "\n", + "page_content: |\n", + " A client for using the Data API. This is the main entry point and sits\n", + " at the top of the conceptual \"client -> database -> collection\" hierarchy.\n", + "\n", + " A client is created first, optionally passing it a suitable Access Token.\n", + " Starting from the client, then:\n", + " - databases (Database and AsyncDatabase) are created for working with data\n", + " - AstraDBAdmin objects can be created for admin-level work\n", + "\n", + "metadata:\n", + " name: DataAPIClient\n", + " kind: class\n", + " path: astrapy.client.DataAPIClient\n", + " parameters: \n", + " token: |\n", + " str | TokenProvider | None = None\n", + " an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\n", + " This can be either a literal token string or a subclass of\n", + " `astrapy.authentication.TokenProvider`.\n", + " \n", + " environment: |\n", + " str | None = None\n", + " a string representing the target Data API environment.\n", + " It can be left unspecified for the default value of `Environment.PROD`;\n", + " other values include `Environment.OTHER`, `Environment.DSE`.\n", + " \n", + " callers: |\n", + " Sequence[CallerType] = []\n", + " a list of caller identities, i.e. applications, or frameworks,\n", + " on behalf of which Data API and DevOps API calls are performed.\n", + " These end up in the request user-agent.\n", + " Each caller identity is a (\"caller_name\", \"caller_version\") pair.\n", + "\n", + " example: |\n", + " >>> from astrapy import DataAPIClient\n", + " >>> my_client = DataAPIClient(\"AstraCS:...\")\n", + " >>> my_db0 = my_client.get_database(\n", + " ... \"https://01234567-....apps.astra.datastax.com\"\n", + " ... )\n", + " >>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n", + " >>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.1, 0.3]})\n", + " >>> my_db1 = my_client.get_database(\"01234567-...\")\n", + " >>> my_db2 = my_client.get_database(\"01234567-...\", region=\"us-east1\")\n", + " >>> my_adm0 = my_client.get_admin()\n", + " >>> my_adm1 = my_client.get_admin(token=more_powerful_token_override)\n", + " >>> database_list = my_adm0.list_databases()\n", + "\n", + " references: \n", + " astrapy.client.DataAPIClient\n", + "\n", + " gathered_types: \n", + " astrapy.constants.CallerType\n", + " astrapy.authentication.TokenProvider\n", + "```\n", + "
\n", + "\n", + "This is the documentation for [`astrapy.client.DataAPIClient`](https://github.com/datastax/astrapy/blob/v1.5.2/astrapy/client.py#L50) class. The `page_content` field contains the description of the class, and the `metadata` field contains the rest of the details, including example code of how to use the class.\n", + "\n", + "The `references` metadata field contains the list of related items used in the example code block. The `gathered_types` field contains the list of types from the parameters section. In GraphRAG, we can use these fields to link to other documents." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Example doc without page content\n", + "\n", + "
Click to expand\n", + "\n", + "```yaml\n", + "id: astrapy.admin.AstraDBAdmin.callers\n", + "\n", + "page_content: \"\"\n", + "\n", + "metadata:\n", + " name: callers\n", + " path: astrapy.admin.AstraDBAdmin.callers\n", + " kind: attribute\n", + "```\n", + "\n", + "
\n", + "\n", + "This is the documentation for `astrapy.admin.AstraDBAdmin.callers`. The `page_content` field is empty, and the `metadata` field contains the details.\n", + "\n", + "Despite having no page content, this document can still be useful for Graph RAG. We'll add a `parent` field to the metadata at vector store insertion time to link it to the parent document: `astrapy.admin.AstraDBAdmin`, and we can use this for traversal." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create the AstraDBVectorStore\n", + "Next, we'll create the Vector Store we're going to load these documents into.\n", + "In our case, we'll use DataStax Astra DB with Open AI embeddings." + ] + }, + { + "cell_type": "code", + "execution_count": 50, + "metadata": {}, + "outputs": [], + "source": [ + "from langchain_astradb import AstraDBVectorStore\n", + "from langchain_openai import OpenAIEmbeddings\n", + "\n", + "store = AstraDBVectorStore(\n", + " embedding=OpenAIEmbeddings(),\n", + " collection_name=os.getenv(\"ASTRA_DB_COLLECTION\"),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Loading Data\n", + "\n", + "Now its time to load the data into our Vector Store. We'll use a helper method to download already prepared documents from the `graph-rag-example-helpers` package. If you want to see how these documents were created from the AstraPy package, see details in the Appendix.\n", + "\n", + "We will use the [`ParentTransformer`](../../guide/transformers/#parenttransformer) to add a parent field to the metadata document field. This will allow us to traverse the graph from a child to its parent.\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from graph_rag_example_helpers.datasets.astrapy import fetch_documents\n", + "from langchain_graph_retriever.transformers import ParentTransformer\n", + "\n", + "transformer = ParentTransformer(path_delimiter=\".\")\n", + "doc_ids = store.add_documents(transformer.transform_documents(fetch_documents()))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can retrieve a sample document to check if the parent field was added correctly:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "callers (attribute)\n", + "\n", + "path: \n", + "\tastrapy.admin.AstraDBAdmin.callers\n", + "\n", + "callers = callers_param\n", + "\n", + "parent: astrapy.admin.AstraDBAdmin\n", + "\n", + "\n" + ] + } + ], + "source": [ + "from graph_rag_example_helpers.examples.code_generation import format_document\n", + "\n", + "print(\n", + " format_document(\n", + " store.get_by_document_id(\"astrapy.admin.AstraDBAdmin.callers\"), debug=True\n", + " )\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "At this point, we've created a Vector Store with all the documents from the AstraPy documentation. Each document contains metadata about the module, class, attribute, or function, and the page content contains the description of the item.\n", + "\n", + "In the next section we'll see how to build relationships from the metadata in order to traverse through the documentation in a similar way to how a human would." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Part 2: Graph Traversal\n", + "\n", + "The GraphRAG library allows us to traverse through the documents in the Vector Store. By changing the [`Strategy`](../../guide/strategies/), we can control how the traversal is performed." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Basic Traversal\n", + "\n", + "We'll start with the default [`Eager`](../../guide/strategies/#eager) strategy, which will traverse the graph in a breadth-first manner. In order to do this we need to set up the relationships between the documents. This is done by defining the \"edges\" between the documents.\n", + "\n", + "In our case we will connect the \"references\", \"gathered_types\", \"parent\", \"implemented_by\", and \"bases\" fields in the metadata to the \"id\" field of the document they reference." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "edges = [\n", + " (\"gathered_types\", \"$id\"),\n", + " (\"references\", \"$id\"),\n", + " (\"parent\", \"$id\"),\n", + " (\"implemented_by\", \"$id\"),\n", + " (\"bases\", \"$id\"),\n", + "]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that edges are directional, and indicate metadata fields by default. The magic string `$id` is used to indicate the document's id.\n", + "\n", + "In the above `edges` list, any document id found in `gathered_types` will be connected to documents with the corresponding id. The other edges will work in a similar way.\n", + "\n", + "Lets use these edges to create a LangChain retriever and documents for our query." + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "`astrapy.core.db.AsyncAstraDB.collection` has example: False\n", + "`astrapy.core.db.AstraDB.collection` has example: False\n", + "`astrapy.admin.DataAPIDatabaseAdmin.list_keyspaces` has example: True\n", + "`astrapy.admin.DataAPIDatabaseAdmin` has example: True\n", + "`astrapy.core.db.AsyncAstraDB` has example: False\n", + "`astrapy.core.db.AstraDBCollection` has example: False\n" + ] + } + ], + "source": [ + "from langchain_graph_retriever import GraphRetriever\n", + "\n", + "default_retriever = GraphRetriever(store=store, edges=edges)\n", + "\n", + "print_doc_ids(default_retriever.invoke(query, select_k=6, start_k=3, max_depth=2))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Notes on the extra keyword args:\n", + "- `select_k` in GraphRAG is equivalent to `k` in LangChain. It specifies the number of nodes to select during retrieval.\n", + "- `start_k` indicates the number of nodes to select using standard vector retrieval before moving onto graph traversal. \n", + "- `max_depth` is the maximum depth to traverse in the graph.\n", + "\n", + "With this configuration, we were only able to find 2 documents with example code." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Custom Strategy\n", + "\n", + "Now we will create a custom strategy that will traverse a larger portion of the graph and return the documents that contain code examples or descriptive text. \n", + "\n", + "To do this, we need to implement a class that inherits from the base [`Strategy`](../../reference/graph_retriever/strategies/#graph_retriever.strategies.Strategy) class and overrides [`iteration`](../../reference/graph_retriever/strategies/#graph_retriever.strategies.Strategy.iteration) method:" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "metadata": {}, + "outputs": [], + "source": [ + "import dataclasses\n", + "from collections.abc import Iterable\n", + "\n", + "from graph_retriever.strategies import NodeTracker, Strategy\n", + "from graph_retriever.types import Node\n", + "\n", + "\n", + "@dataclasses.dataclass\n", + "class CodeExamples(Strategy):\n", + " # internal dictionary to store all nodes found during the traversal\n", + " _nodes: dict[str, Node] = dataclasses.field(default_factory=dict)\n", + "\n", + " def iteration(self, *, nodes: Iterable[Node], tracker: NodeTracker) -> None:\n", + " # save all newly found nodes to the internal node dictionary for later use\n", + " self._nodes.update({n.id: n for n in nodes})\n", + " # traverse the newly found nodes\n", + " new_count = tracker.traverse(nodes=nodes)\n", + "\n", + " # if no new nodes were found, we have reached the end of the traversal\n", + " if new_count == 0:\n", + " example_nodes = []\n", + " description_nodes = []\n", + "\n", + " # iterate over all nodes and separate nodes with examples from nodes with\n", + " # descriptions\n", + " for node in self._nodes.values():\n", + " if \"example\" in node.metadata:\n", + " example_nodes.append(node)\n", + " elif node.content != \"\":\n", + " description_nodes.append(node)\n", + "\n", + " # select the nodes with examples first and descriptions second\n", + " # note: the base `finalize_nodes` method will truncate the list to the\n", + " # `select_k` number of nodes\n", + " tracker.select(example_nodes)\n", + " tracker.select(description_nodes)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "As described in the comments above, this custom strategy will first try to select documents that contain code examples, and then will use documents that contain descriptive text.\n", + "\n", + "We can now use this custom strategy to build a custom retriever, and ask the query again:" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "`astrapy.admin.DataAPIDatabaseAdmin.list_keyspaces` has example: True\n", + "`astrapy.admin.DataAPIDatabaseAdmin` has example: True\n", + "`astrapy.client.DataAPIClient` has example: True\n", + "`astrapy.database.AsyncDatabase` has example: True\n", + "`astrapy.database.Database` has example: True\n", + "`astrapy.authentication.UsernamePasswordTokenProvider` has example: True\n" + ] + } + ], + "source": [ + "custom_retriever = GraphRetriever(store=store, edges=edges, strategy=CodeExamples())\n", + "\n", + "print_doc_ids(custom_retriever.invoke(query, select_k=6, start_k=3, max_depth=2))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now we have found 6 documents with code examples! That is a significant improvement over the default strategy." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 3: Using GraphRAG to Generate Code\n", + "\n", + "We now use the `CodeExamples` strategy inside a Langchain pipeline to generate code snippets.\n", + "\n", + "We will also use a custom document formatter, which will format the document in a way that makes it look like standard documentation. In particular, it will format all the extra details stored in the metadata in a way that is easy to read. This will help the LLM use the information in the documents to generate code.\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": 59, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "```python\n", + "import os\n", + "from astrapy.client import DataAPIClient\n", + "from astrapy.collection import Collection\n", + "\n", + "def connect_and_retrieve_rows(num_rows):\n", + " api_endpoint = os.getenv('ASTRA_DB_API_ENDPOINT')\n", + " application_token = os.getenv('ASTRA_DB_APPLICATION_TOKEN')\n", + " keyspace = os.getenv('ASTRA_DB_KEYSPACE')\n", + " collection_name = os.getenv('ASTRA_DB_COLLECTION')\n", + "\n", + " client = DataAPIClient(token=application_token)\n", + " database = client.get_database(api_endpoint)\n", + " collection = Collection(database=database, name=collection_name, keyspace=keyspace)\n", + "\n", + " rows = collection.find(limit=num_rows)\n", + " return list(rows)\n", + "```\n" + ] + } + ], + "source": [ + "from graph_rag_example_helpers.examples.code_generation import format_docs\n", + "from langchain.chat_models import init_chat_model\n", + "from langchain_core.output_parsers import StrOutputParser\n", + "from langchain_core.prompts import ChatPromptTemplate\n", + "from langchain_core.runnables import RunnablePassthrough\n", + "\n", + "llm = init_chat_model(\"gpt-4o-mini\", model_provider=\"openai\")\n", + "\n", + "prompt = ChatPromptTemplate.from_template(\n", + " \"\"\"Generate a block of runnable python code using the following documentation as\n", + " guidance. Return only the code. Don't include any example usage.\n", + "\n", + " Each documentation page is separated by three dashes (---) on its own line.\n", + " If certain pages of the provided documentation aren't useful for answering the\n", + " question, feel free to ignore them.\n", + "\n", + " Question: {question}\n", + "\n", + " Related Documentation:\n", + "\n", + " {context}\n", + " \"\"\"\n", + ")\n", + "\n", + "graph_chain = (\n", + " {\"context\": custom_retriever | format_docs, \"question\": RunnablePassthrough()}\n", + " | prompt\n", + " | llm\n", + " | StrOutputParser()\n", + ")\n", + "\n", + "print(graph_chain.invoke(query))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can try running this generated code to see if it works:" + ] + }, + { + "cell_type": "code", + "execution_count": 60, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "from astrapy.client import DataAPIClient\n", + "from astrapy.collection import Collection\n", + "\n", + "\n", + "def connect_and_retrieve_rows(num_rows):\n", + " api_endpoint = os.getenv(\"ASTRA_DB_API_ENDPOINT\")\n", + " application_token = os.getenv(\"ASTRA_DB_APPLICATION_TOKEN\")\n", + " keyspace = os.getenv(\"ASTRA_DB_KEYSPACE\")\n", + " collection_name = os.getenv(\"ASTRA_DB_COLLECTION\")\n", + "\n", + " client = DataAPIClient(token=application_token)\n", + " database = client.get_database(api_endpoint)\n", + " collection = Collection(database=database, name=collection_name, keyspace=keyspace)\n", + "\n", + " rows = collection.find(limit=num_rows)\n", + " return list(rows)" + ] + }, + { + "cell_type": "code", + "execution_count": 61, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "{'_id': 'astrapy.info.EmbeddingProviderAuthentication', 'content': 'A representation of an authentication mode for using an embedding model,\\nmodeling the corresponding part of the response returned by the\\n\\'findEmbeddingProviders\\' Data API endpoint (namely \"supportedAuthentication\").', 'metadata': {'kind': 'class', 'name': 'EmbeddingProviderAuthentication', 'path': 'astrapy.info.EmbeddingProviderAuthentication', 'parameters': [{'name': 'enabled', 'type': 'bool'}, {'name': 'tokens', 'type': 'list[EmbeddingProviderToken]'}], 'attributes': [{'name': 'enabled', 'type': 'bool', 'description': 'whether this authentication mode is available for a given model.'}, {'name': 'tokens', 'type': 'list[EmbeddingProviderToken]', 'description': 'a list of `EmbeddingProviderToken` objects,\\ndetailing the secrets required for the authentication mode.'}], 'gathered_types': ['EmbeddingProviderToken'], 'parent': 'astrapy.info'}}\n", + "{'_id': 'astrapy.defaults.DEV_OPS_RESPONSE_HTTP_CREATED', 'content': '', 'metadata': {'kind': 'attribute', 'name': 'DEV_OPS_RESPONSE_HTTP_CREATED', 'path': 'astrapy.defaults.DEV_OPS_RESPONSE_HTTP_CREATED', 'value': 'DEV_OPS_RESPONSE_HTTP_CREATED = 201', 'parent': 'astrapy.defaults'}}\n", + "{'_id': 'astrapy.info.CollectionInfo.full_name', 'content': '', 'metadata': {'kind': 'attribute', 'name': 'full_name', 'path': 'astrapy.info.CollectionInfo.full_name', 'value': 'full_name: str', 'parent': 'astrapy.info.CollectionInfo'}}\n", + "{'_id': 'astrapy.collection.Collection.full_name', 'content': 'The fully-qualified collection name within the database,\\nin the form \"keyspace.collection_name\".', 'metadata': {'kind': 'attribute', 'name': 'full_name', 'path': 'astrapy.collection.Collection.full_name', 'value': 'full_name: str', 'example': \">>> my_coll.full_name\\n'default_keyspace.my_v_collection'\", 'parent': 'astrapy.collection.Collection'}}\n", + "{'_id': 'astrapy.exceptions.DataAPIErrorDescriptor', 'content': 'An object representing a single error returned from the Data API,\\ntypically with an error code and a text message.\\nAn API request would return with an HTTP 200 success error code,\\nbut contain a nonzero amount of these.\\n\\nA single response from the Data API may return zero, one or more of these.\\nMoreover, some operations, such as an insert_many, may partally succeed\\nyet return these errors about the rest of the operation (such as,\\nsome of the input documents could not be inserted).', 'metadata': {'kind': 'class', 'name': 'DataAPIErrorDescriptor', 'path': 'astrapy.exceptions.DataAPIErrorDescriptor', 'parameters': [{'name': 'error_dict', 'type': 'dict[str, str]'}], 'attributes': [{'name': 'error_code', 'type': 'str | None', 'description': 'a string code as found in the API \"error\" item.'}, {'name': 'message', 'type': 'str | None', 'description': 'the text found in the API \"error\" item.'}, {'name': 'attributes', 'type': 'dict[str, Any]', 'description': 'a dict with any further key-value pairs returned by the API.'}], 'parent': 'astrapy.exceptions'}}\n" + ] + } + ], + "source": [ + "for row in connect_and_retrieve_rows(5):\n", + " print(row)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Conclusion\n", + "\n", + "The code generated by GraphRAG isn't perfect, but it works. It's a good starting point for the LLM to generate code. The LLM used the information in the documentation and code examples to generate functional code.\n", + "\n", + "In the Appendix, you can see examples of attempting this query with just an LLM and with Standard (non-graph) RAG. In both cases, the LLM was unable to generate usable code." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Appendix" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### LLM Alone\n", + "\n", + "Here we show how to use the LLM alone to generate code for the query. We will use the same query as before, but modify the prompt to not include any context." + ] + }, + { + "cell_type": "code", + "execution_count": 68, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "```python\n", + "import os\n", + "from astra import AstraClient\n", + "\n", + "def fetch_rows_from_astra_db(num_rows):\n", + " # Retrieve environment variables\n", + " api_endpoint = os.getenv(\"ASTRA_DB_API_ENDPOINT\")\n", + " application_token = os.getenv(\"ASTRA_DB_APPLICATION_TOKEN\")\n", + " keyspace = os.getenv(\"ASTRA_DB_KEYSPACE\")\n", + " collection = os.getenv(\"ASTRA_DB_COLLECTION\")\n", + " \n", + " # Initialize the Astra DB client\n", + " client = AstraClient(api_endpoint, application_token)\n", + " \n", + " # Retrieve rows from the specified collection\n", + " query = f'SELECT * FROM {keyspace}.{collection} LIMIT {num_rows}'\n", + " response = client.execute_statement(query)\n", + " \n", + " # Return the rows retrieved\n", + " return response['rows']\n", + "```\n" + ] + } + ], + "source": [ + "llm_only_prompt = ChatPromptTemplate.from_template(\n", + " \"\"\"Generate a block of runnable python code. Return only the code.\n", + " Don't include any example usage.\n", + "\n", + " Question: {question}\n", + " \"\"\"\n", + ")\n", + "\n", + "llm_only_chain = (\n", + " {\"question\": RunnablePassthrough()} | llm_only_prompt | llm | StrOutputParser()\n", + ")\n", + "\n", + "print(llm_only_chain.invoke(query))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This code is not functional. The package `astra` and the class `AstraClient` do not exist." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Standard RAG\n", + "\n", + "Here we show how to use the LLM with standard RAG to generate code for the query. We will use the same query and prompt as we did with GraphRAG." + ] + }, + { + "cell_type": "code", + "execution_count": 67, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "```python\n", + "import os\n", + "from astra import AstraClient\n", + "\n", + "def fetch_rows_from_astradb(num_rows):\n", + " endpoint = os.getenv('ASTRA_DB_API_ENDPOINT')\n", + " token = os.getenv('ASTRA_DB_APPLICATION_TOKEN')\n", + " keyspace = os.getenv('ASTRA_DB_KEYSPACE')\n", + " collection = os.getenv('ASTRA_DB_COLLECTION')\n", + "\n", + " client = AstraClient(\n", + " endpoint=endpoint,\n", + " token=token\n", + " )\n", + "\n", + " query = f'SELECT * FROM {keyspace}.{collection} LIMIT {num_rows}'\n", + " response = client.execute(query)\n", + " return response['data']\n", + "```\n" + ] + } + ], + "source": [ + "rag_chain = (\n", + " {\n", + " \"context\": store.as_retriever(k=6) | format_docs,\n", + " \"question\": RunnablePassthrough(),\n", + " }\n", + " | prompt\n", + " | llm\n", + " | StrOutputParser()\n", + ")\n", + "\n", + "print(rag_chain.invoke(query))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This code is also not functional. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Converting AstraPy Documentation\n", + "\n", + "The AstraPy documentation was converted into a JSONL format via some custom code that is not included in this notebook. However, the code is available in the `graph-rag-example-helpers` package [here](https://github.com/datastax/graph-rag/blob/main/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": ".venv", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.8" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples/index.md b/docs/examples/index.md index ba11008d..5f7ad65c 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -10,4 +10,20 @@ It loads Wikipedia articles and traverses based on links ("mentions") and named entities (extracted from the content). It retrieves a large number of articles, groups them by community, and extracts claims from each community. The best claims are used to answer the question. [:material-fast-forward: Lazy Graph RAG Example](lazy-graph-rag.ipynb) - \ No newline at end of file + +- :material-code-braces-box:{ .lg .middle } __Code Generation__ + + --- + This example notebook shows how to load documentation for python packages into a + vector store so that it can be used to provide context to an LLM for code generation. + + It uses LangChain and `langchain-graph-retriever` with a custom traversal Strategy + to in order to improve LLM generated code output. It shows that using GraphRAG can + provide a significant increase in quality over using either a LLM alone or standard + RAG. + + GraphRAG is traverses through the documentation in a way similar to how a + software engineer would, in order to determine how to solve a coding problem. + + [:material-fast-forward: Code Generation Example](code-generation.ipynb) + diff --git a/docs/examples/lazy-graph-rag.ipynb b/docs/examples/lazy-graph-rag.ipynb index 218e1b31..5fa7c5a4 100644 --- a/docs/examples/lazy-graph-rag.ipynb +++ b/docs/examples/lazy-graph-rag.ipynb @@ -71,6 +71,13 @@ "The last package -- `graph-rag-example-helpers` -- includes some helpers for setting up environment helpers and allowing the loading of wikipedia data to be restarted if it fails." ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "code", "execution_count": null, diff --git a/packages/graph-rag-example-helpers/pyproject.toml b/packages/graph-rag-example-helpers/pyproject.toml index 82a77c89..12a33d34 100644 --- a/packages/graph-rag-example-helpers/pyproject.toml +++ b/packages/graph-rag-example-helpers/pyproject.toml @@ -42,6 +42,7 @@ dependencies = [ "astrapy>=1.5.2", "backoff>=2.2.1", "graph-retriever", + "griffe>=1.5.7", "httpx>=0.28.1", "langchain-core>=0.3.29", "python-dotenv>=1.0.1", @@ -54,6 +55,7 @@ dependencies = [ astrapy = "astrapy" backoff = "backoff" graph-retriever = "graph_retriever" +griffe = "griffe" httpx = "httpx" langchain-core = "langchain_core" mypy = "mypy" diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py new file mode 100644 index 00000000..e283bdbf --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py @@ -0,0 +1,9 @@ +from ...examples.code_generation.format import add_tabs, format_docs, format_document +from .fetch import fetch_documents + +__all__ = [ + "fetch_documents", + "add_tabs", + "format_document", + "format_docs", +] diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py new file mode 100644 index 00000000..57182b2e --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py @@ -0,0 +1,40 @@ +import json + +import requests +from langchain_core.documents import Document + +# TODO: revert to main branch before code generation is merged +# ASTRAPY_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/main/data/astrapy.jsonl" +ASTRAPY_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/code_generation/data/astrapy.jsonl" + + +def fetch_documents() -> list[Document]: + """ + Download and parse a list of Documents for use with Graph Retriever. + + This dataset contains the documentation for the AstraPy project as of version 1.5.2. + + This method downloads the dataset each time -- generally it is preferable + to invoke this only once and store the documents in memory or a vector + store. + + Returns + ------- + : + The fetched astra-py documentation Documents. + + Notes + ----- + - The dataset is setup in a way where the path of the item is the `id`, the pydoc + description is the `page_content`, and the items other attributes are stored in the + `metadata`. + - There are many documents that contain an id and metadata, but no page_content. + """ + response = requests.get(ASTRAPY_JSONL_URL) + response.raise_for_status() # Ensure we got a valid response + + return [ + Document(id=data["id"], page_content=data["text"], metadata=data["metadata"]) + for line in response.text.splitlines() + if (data := json.loads(line)) + ] diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py new file mode 100644 index 00000000..d10cfc30 --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py @@ -0,0 +1,7 @@ +from .format import add_tabs, format_docs, format_document + +__all__ = [ + "add_tabs", + "format_document", + "format_docs", +] diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py new file mode 100644 index 00000000..6d65985f --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py @@ -0,0 +1,450 @@ +import ast +import json +import os +import typing +from typing import Any + +import griffe + +from graph_rag_example_helpers.utils import add_tabs + + +def convert( + package_name: str, + search_paths: list[str], + docstring_parser: griffe.DocstringStyle, + output_path: str, +) -> None: + """ + Load and convert a package's objects and documentation into a JSONL file. + + This method converts the internal documentation of modules, classes, functions, and + attributes of a package into a format that is better suited for RAG (and GraphRAG + in particular). + + The code uses the `griffe` library, which is a Python code analysis tool that + extracts information from Python code and docstrings. + + The JSONL file contains one JSON object per line, with the following structure: + id: the path to the object in the package + text: the description of the object (if any, can be empty) + metadata: Always includes `name`, `path`, `kind` keys. + The remaining keys below are included when available. + name: the name of the object + path: the path to the object in the package + kind: either `module`, `class`, `function`, or `attribute` + parameters: the parameters for a class or function. Includes type + information, default values, and descriptions + attributes: the attributes on a class or module. Includes type + information and descriptions + gathered_types: list of non-standard types in the parameters and attributes + imports: list of non-standard types imported by the class or module + exports: list of non-standard types exported by the module + properties: list of boolean properties about the module + example: any code examples for the class, function, or module + references: list of any non-standard types used in the example code + returns: the return type and description + yields: the yield type and description + bases: list of base types inherited by the class + implemented_by: list of types that implement the a base class + + + Parameters + ---------- + package_name : + The name of the package to convert. + search_paths : + The paths to search for the package. + docstring_parser : + The docstring parser to use. + output_path : + The path to save the JSONL file. + + + Examples + -------- + from graph_rag_example_helpers.examples.code_generation.converter import convert + convert("astrapy", [".venv/lib/python3.12/site-packages"], "google", "data") + + + Notes + ----- + - This code was written the `code-generation` example and `astrapy==1.5.2`. It will + probably need tweaking for use with other python packages. Use at your own risk. + """ + my_package = griffe.load( + package_name, search_paths=search_paths, docstring_parser=docstring_parser + ) + + converter = _Converter() + items = converter._convert(package_name, my_package) + + with open(os.path.join(output_path, f"{package_name}.jsonl"), "w") as f: + for item in items: + text = item.pop("text", "") + id = item.get("path") + metadata = item + for key, value in metadata.items(): + if isinstance(value, set): + metadata[key] = list(value) + f.write(json.dumps({"id": id, "text": text, "metadata": metadata})) + f.write("\n") + + +class _Converter: + """Converts griffe objects into .""" + + def __init__(self) -> None: + self._alias_lookup: dict[str, str] = {} + self._items: dict[str, dict[str, Any]] = {} + self._bases: dict[str, set[str]] = {} + self._used: bool = False + + self._typing_type_names: set[str] = { + name for name in dir(typing) if not name.startswith("_") + } + """All standard-type names from the typing module.""" + + def _check_first_use(self): + assert not self._used, "Converters cannot be re-used." + self._used = True + + def _extract_alias(self, name, alias: griffe.Alias): + try: + self._alias_lookup[name] = alias.final_target.path + except Exception: + pass + + def _is_first_letter_lowercase(self, s: str) -> bool: + return s[:1].islower() + + def _extract_expr( + self, annotation: str | griffe.Expr | None, gathered_types: set[str] + ) -> str | None: + if isinstance(annotation, griffe.Expr): + annotation = annotation.modernize() + for expr in annotation.iterate(flat=True): + if isinstance(expr, griffe.ExprName): + if ( + self._is_first_letter_lowercase(expr.name) + or expr.name in self._typing_type_names + ): + continue + gathered_types.add(expr.name) + return annotation.__str__() + else: + return annotation + + def _extract_named_element( + self, + el: griffe.DocstringNamedElement, + gathered_types: set[str], + annotation_key: str = "type", + ): + stuff = {} + if el.name != "": + stuff["name"] = el.name + anno = self._extract_expr(el.annotation, gathered_types=gathered_types) + if anno is not None: + stuff[annotation_key] = anno + if el.description != "": + stuff["description"] = el.description + if el.value is not None: + value = self._extract_expr(el.value, gathered_types=gathered_types) + if value is not None: + stuff["value"] = value + return stuff + + def _format_parameter(self, el: dict[str, str]) -> str: + text = el["name"] + if "value" in el and "default" in el: + assert el["value"] == el["default"] + + if "type" in el: + text += f": {el['type']}" + if "default" in el: + text += f" = {el['default']}" + if "description" in el: + desc = add_tabs(el["description"]) + text += f"\n\t{desc}" + return text + + def _format_return(self, el: dict[str, str]) -> str: + items = [] + if "type" in el: + items.append(el["type"]) + if "description" in el: + items.append(add_tabs(el["description"])) + return "\n\t".join(items) + + def _extract_common(self, obj: griffe.Object) -> dict[str, Any]: + common: dict[str, Any] = { + "kind": obj.kind.value, + "name": obj.name, + "path": obj.path, + } + if len(obj.imports) > 0: + common["imports"] = obj.imports + + exports = obj.exports + if isinstance(exports, set): + common["exports"] = list(exports) + elif isinstance(exports, list): + common["exports"] = [] + for export in exports: + if isinstance(export, str): + common["exports"].append(export) + elif isinstance(export, griffe.ExprName): + common["exports"].append(export.name) + + return common + + def _extract_module( + self, obj: griffe.Module, gathered_types: set[str] + ) -> dict[str, Any]: + item = self._extract_common(obj) + item["properties"] = { + "is_init_module": obj.is_init_module, + "is_package": obj.is_package, + "is_subpackage": obj.is_subpackage, + "is_namespace_package": obj.is_namespace_package, + "is_namespace_subpackage": obj.is_namespace_subpackage, + } + if obj.is_init_module: + for export in item.get("exports", []): + if export in item["imports"]: + # add exported items to alias lookup so references can be found + self._alias_lookup[f"{item['path']}.{export}"] = item["imports"][ + export + ] + return item + + def _extract_class( + self, obj: griffe.Class, gathered_types: set[str] + ) -> dict[str, Any]: + item = self._extract_common(obj) + params = [] + for param in obj.parameters: + if param.name == "self": + continue + el = {"name": param.name} + default = self._extract_expr(param.default, gathered_types=gathered_types) + if default is not None: + el["default"] = default + annotation = self._extract_expr( + param.annotation, gathered_types=gathered_types + ) + if annotation is not None: + el["type"] = annotation + params.append(el) + if len(params) > 0: + item["parameters"] = params + + bases = [ + self._extract_expr(b, gathered_types=gathered_types) for b in obj.bases + ] + if len(bases) > 0: + item["bases"] = bases + return item + + def _extract_function( + self, obj: griffe.Function, gathered_types: set[str] + ) -> dict[str, Any]: + item = self._extract_common(obj) + params = [] + for param in obj.parameters: + if param.name == "self": + continue + el = {"name": param.name} + default = self._extract_expr(param.default, gathered_types=gathered_types) + if default is not None: + el["default"] = default + annotation = self._extract_expr( + param.annotation, gathered_types=gathered_types + ) + if annotation is not None: + el["type"] = annotation + params.append(el) + if len(params) > 0: + item["parameters"] = params + + item["returns"] = [ + {"type": self._extract_expr(obj.returns, gathered_types=gathered_types)} + ] + return item + + def _extract_attribute( + self, obj: griffe.Attribute, gathered_types: set[str] + ) -> dict[str, Any]: + item = self._extract_common(obj) + el = {"name": obj.name} + value = self._extract_expr(obj.value, gathered_types=gathered_types) + if value is not None: + el["default"] = value + annotation = self._extract_expr(obj.annotation, gathered_types=gathered_types) + if annotation is not None: + el["type"] = annotation + item["value"] = self._format_parameter(el) + return item + + def _extract_object(self, name, obj: griffe.Object): + assert name == obj.name + + if not obj.name.startswith("_"): + gathered_types: set[str] = set() + references: set[str] = set() + if isinstance(obj, griffe.Attribute): + item = self._extract_attribute(obj, gathered_types=gathered_types) + elif isinstance(obj, griffe.Function): + item = self._extract_function(obj, gathered_types=gathered_types) + elif isinstance(obj, griffe.Class): + item = self._extract_class(obj, gathered_types=gathered_types) + elif isinstance(obj, griffe.Module): + item = self._extract_module(obj, gathered_types=gathered_types) + else: + raise TypeError(f"Unknown obj type: {obj}") + + if obj.docstring is not None: + for section in obj.docstring.parsed: + # TODO: merge this stuff with those from above if already existing. + if isinstance(section, griffe.DocstringSectionText): + item["text"] = section.value + elif isinstance(section, griffe.DocstringSectionAdmonition): + admonition_label = self._extract_expr( + section.value.annotation, gathered_types=gathered_types + ) + if admonition_label is not None: + item[admonition_label] = section.value.description + if admonition_label == "example": + references.update( + self._extract_imported_objects( + section.value.description + ) + ) + elif isinstance(section, griffe.DocstringSectionParameters): + params = [] + for param in section.value: + named_element = self._extract_named_element( + param, gathered_types=gathered_types + ) + named_element["default"] = self._extract_expr( + param.default, gathered_types=gathered_types + ) + params.append(named_element) + item["parameters"] = params + elif isinstance(section, griffe.DocstringSectionAttributes): + item["attributes"] = [ + self._extract_named_element( + e, gathered_types=gathered_types + ) + for e in section.value + ] + elif isinstance(section, griffe.DocstringSectionYields): + item["yields"] = [ + self._extract_named_element( + e, gathered_types=gathered_types + ) + for e in section.value + ] + elif isinstance(section, griffe.DocstringSectionReturns): + item["returns"] = [ + self._extract_named_element( + e, gathered_types=gathered_types + ) + for e in section.value + ] + elif isinstance(section, griffe.DocstringSectionExamples): + for example in section.value: + references.update( + self._extract_imported_objects(example[1]) + ) + item["example"] = "/n/n/n".join( + [example[1] for example in section.value] + ) + else: + raise TypeError( + f"Unknown section type: {section} of kind: {section.kind}" + ) + + if item["path"] in references: + references.remove(item["path"]) + if len(references) > 0: + item["references"] = list(references) + + if len(gathered_types) > 0: + item["gathered_types"] = list(gathered_types) + + if obj.path in self._items: + raise Exception(f"{obj.path} was already found") + self._items[obj.path] = item + + for _name, _obj in obj.members.items(): + self._extract_object_or_alias(_name, _obj) + + def _extract_object_or_alias(self, name: str, obj: griffe.Object | griffe.Alias): + if isinstance(obj, griffe.Object): + self._extract_object(name, obj) + elif isinstance(obj, griffe.Alias): + self._extract_alias(name, obj) + + def _extract_imported_objects(self, code: str) -> set[str]: + """ + Extract the fully qualified names of imported objects from a given code snippet. + + If an error occurs, it removes the code from the error and beyond, and retries. + + Returns + ------- + The set of imported types + """ + code = ( + code.replace("\n>>>", "\n") + .replace("\n...", "\n") + .replace(">>> ", "") + .replace("\n ", "\n") + .replace("imort", "import") + ) + imported_objects = set() + + while code: + try: + tree = ast.parse(code) + for node in ast.walk(tree): + if isinstance(node, ast.ImportFrom) and node.module: + for alias in node.names: + imported_objects.add(f"{node.module}.{alias.name}") + break # Stop retrying if parsing succeeds + except SyntaxError as e: + # Trim code before the error line and retry + error_line = e.lineno + if error_line is None or error_line <= 1: + break # If error is at the first line, there's nothing to salvage + code = "\n".join(code.splitlines()[: error_line - 1]) + + return imported_objects + + def _update_item_paths(self, item: dict[str, Any]): + """Update types to full paths for item attributes.""" + for key in ["gathered_types", "bases", "references"]: + if key in item: + updated = [self._alias_lookup.get(k, k) for k in item[key]] + item[key] = updated + + if "bases" in item: + for base in item["bases"]: + self._bases.setdefault(base, set()).add(item["path"]) + + def _convert( + self, package_name: str, package: griffe.Object | griffe.Alias + ) -> list[dict[str, Any]]: + self._check_first_use() + self._extract_object_or_alias(package_name, package) + + for item in self._items.values(): + self._update_item_paths(item) + + for base, implemented_by in self._bases.items(): + if base in self._items: + self._items[base]["implemented_by"] = implemented_by + + return list(self._items.values()) diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py new file mode 100644 index 00000000..7d6195be --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py @@ -0,0 +1,103 @@ +from langchain_core.documents import Document + +from graph_rag_example_helpers.utils import add_tabs + + +def _format_parameter(el: dict[str, str]) -> str: + text = el["name"] + if "value" in el and "default" in el: + assert el["value"] == el["default"] + + if "type" in el: + text += f": {el['type']}" + if "default" in el: + text += f" = {el['default']}" + if "description" in el: + desc = add_tabs(el["description"]) + text += f"\n\t{desc}" + return text + + +def _format_return(el: dict[str, str]) -> str: + items = [] + if "type" in el: + items.append(el["type"]) + if "description" in el: + items.append(add_tabs(el["description"])) + return "\n\t".join(items) + + +def format_document(doc: Document, debug: bool = False) -> str: + """Format a document as documentation for including as context in a LLM query.""" + metadata = doc.metadata + text = f"{metadata['name']} ({metadata['kind']})\n\n" + + text += f"path: \n\t{metadata['path']}\n\n" + + if "bases" in metadata: + text += f"bases: \n\t{add_tabs('\n'.join(metadata['bases']))}\n\n" + + if "exports" in metadata: + text += f"exports: \n\t{add_tabs('\n'.join(metadata['exports']))}\n\n" + + if "implemented_by" in metadata: + text += ( + f"implemented_by: \n\t{add_tabs('\n'.join(metadata['implemented_by']))}\n\n" + ) + + if "properties" in metadata: + props = [f"{k}: {v}" for k, v in metadata["properties"].items()] + text += f"properties: \n\t{add_tabs('\n'.join(props))}\n\n" + + if doc.page_content != "": + text += f"description: \n\t{add_tabs(doc.page_content)}\n\n" + elif "value" in metadata: + text += f"{metadata['value']}\n\n" + + if "attributes" in metadata: + attributes = [_format_parameter(a) for a in metadata["attributes"]] + text += f"attributes: \n\t{add_tabs('\n\n'.join(attributes))}\n\n" + + if "parameters" in metadata: + parameters = [_format_parameter(p) for p in metadata["parameters"]] + text += f"parameters: \n\t{add_tabs('\n\n'.join(parameters))}\n\n" + + if "returns" in metadata: + returns = [_format_return(r) for r in metadata["returns"]] + text += f"returns: \n\t{add_tabs('\n\n'.join(returns))}\n\n" + + if "yields" in metadata: + yields = [_format_return(y) for y in metadata["yields"]] + text += f"yields: \n\t{add_tabs('\n\n'.join(yields))}\n\n" + + if "note" in metadata: + text += f"note: \n\t{add_tabs(metadata['note'])}\n\n" + + if "example" in metadata: + text += f"example: \n\t{add_tabs(metadata['example'])}\n\n" + + if debug: + if "imports" in metadata: + imports = [] + for as_name, real_name in metadata["imports"].items(): + if real_name == as_name: + imports.append(real_name) + else: + imports.append(f"{real_name} as {as_name}") + text += f"imports: \n\t{add_tabs('\n'.join(imports))}\n\n" + + if "references" in metadata: + text += f"references: \n\t{add_tabs('\n'.join(metadata['references']))}\n\n" + + if "gathered_types" in metadata: + text += f"gathered_types: \n\t{add_tabs('\n'.join(metadata['gathered_types']))}\n\n" # noqa: E501 + + if "parent" in metadata: + text += f"parent: {metadata['parent']}\n\n" + + return text + + +def format_docs(docs: list[Document]) -> str: + """Format documents as documentation for including as context in a LLM query.""" + return "\n---\n".join(format_document(doc) for doc in docs) diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py new file mode 100644 index 00000000..4b647af6 --- /dev/null +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py @@ -0,0 +1,3 @@ +def add_tabs(text: str) -> str: + """Add a tab character to the start of each line in the text.""" + return "\n\t".join(text.split("\n")) diff --git a/packages/graph-retriever/pyproject.toml b/packages/graph-retriever/pyproject.toml index c1f437db..f27b512c 100644 --- a/packages/graph-retriever/pyproject.toml +++ b/packages/graph-retriever/pyproject.toml @@ -59,6 +59,7 @@ testing = [ ] [tool.deptry.package_module_name_map] +immutabledict = "immutabledict" numpy = "numpy" pytest = "pytest" simsimd = "simsimd" diff --git a/packages/langchain-graph-retriever/pyproject.toml b/packages/langchain-graph-retriever/pyproject.toml index 1c31d197..879186f5 100644 --- a/packages/langchain-graph-retriever/pyproject.toml +++ b/packages/langchain-graph-retriever/pyproject.toml @@ -63,6 +63,7 @@ chromadb = "chromadb" gliner = "gliner" graph-retriever = "graph_retriever" httpx = "httpx" +immutabledict = "immutabledict" keybert = "keybert" langchain-astradb = "langchain_astradb" langchain-chroma = "langchain_chroma" diff --git a/uv.lock b/uv.lock index 411f0e19..1e08ba0f 100644 --- a/uv.lock +++ b/uv.lock @@ -1,4 +1,5 @@ version = 1 +revision = 1 requires-python = ">=3.10" resolution-markers = [ "python_full_version >= '3.12.4'", @@ -1248,6 +1249,7 @@ dependencies = [ { name = "astrapy" }, { name = "backoff" }, { name = "graph-retriever" }, + { name = "griffe" }, { name = "httpx" }, { name = "langchain-core" }, { name = "python-dotenv" }, @@ -1271,6 +1273,7 @@ requires-dist = [ { name = "astrapy", specifier = ">=1.5.2" }, { name = "backoff", specifier = ">=2.2.1" }, { name = "graph-retriever", editable = "packages/graph-retriever" }, + { name = "griffe", specifier = ">=1.5.7" }, { name = "httpx", specifier = ">=0.28.1" }, { name = "langchain-core", specifier = ">=0.3.29" }, { name = "python-dotenv", specifier = ">=1.0.1" }, @@ -1322,6 +1325,7 @@ requires-dist = [ { name = "simsimd", marker = "extra == 'simsimd'", specifier = ">=6.2.1" }, { name = "typing-extensions", specifier = ">=4.12.2" }, ] +provides-extras = ["simsimd", "testing"] [package.metadata.requires-dev] dev = [{ name = "pytest", specifier = ">=8.3.4" }] @@ -1444,14 +1448,14 @@ wheels = [ [[package]] name = "griffe" -version = "1.5.5" +version = "1.6.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "colorama" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/5c/74/cd35a98cb11f79de0581e8e1e6fbd738aeeed1f2d90e9b5106728b63f5f7/griffe-1.5.5.tar.gz", hash = "sha256:35ee5b38b93d6a839098aad0f92207e6ad6b70c3e8866c08ca669275b8cba585", size = 391124 } +sdist = { url = "https://files.pythonhosted.org/packages/a0/1a/d467b93f5e0ea4edf3c1caef44cfdd53a4a498cb3a6bb722df4dd0fdd66a/griffe-1.6.0.tar.gz", hash = "sha256:eb5758088b9c73ad61c7ac014f3cdfb4c57b5c2fcbfca69996584b702aefa354", size = 391819 } wheels = [ - { url = "https://files.pythonhosted.org/packages/1f/88/52c9422bc853cd7c2b6122090e887d17b5fad29b67f930e4277c9c557357/griffe-1.5.5-py3-none-any.whl", hash = "sha256:2761b1e8876c6f1f9ab1af274df93ea6bbadd65090de5f38f4cb5cc84897c7dd", size = 128221 }, + { url = "https://files.pythonhosted.org/packages/bf/02/5a22bc98d0aebb68c15ba70d2da1c84a5ef56048d79634e5f96cd2ba96e9/griffe-1.6.0-py3-none-any.whl", hash = "sha256:9f1dfe035d4715a244ed2050dfbceb05b1f470809ed4f6bb10ece5a7302f8dd1", size = 128470 }, ] [[package]] @@ -2270,6 +2274,7 @@ requires-dist = [ { name = "spacy", marker = "extra == 'spacy'", specifier = ">=3.8.4" }, { name = "typing-extensions", specifier = ">=4.12.2" }, ] +provides-extras = ["astra", "html", "cassandra", "chroma", "gliner", "keybert", "opensearch", "spacy"] [package.metadata.requires-dev] dev = [ @@ -3281,7 +3286,6 @@ name = "nvidia-nccl-cu12" version = "2.20.5" source = { registry = "https://pypi.org/simple" } wheels = [ - { url = "https://files.pythonhosted.org/packages/c1/bb/d09dda47c881f9ff504afd6f9ca4f502ded6d8fc2f572cacc5e39da91c28/nvidia_nccl_cu12-2.20.5-py3-none-manylinux2014_aarch64.whl", hash = "sha256:1fc150d5c3250b170b29410ba682384b14581db722b2531b0d8d33c595f33d01", size = 176238458 }, { url = "https://files.pythonhosted.org/packages/4b/2a/0a131f572aa09f741c30ccd45a8e56316e8be8dfc7bc19bf0ab7cfef7b19/nvidia_nccl_cu12-2.20.5-py3-none-manylinux2014_x86_64.whl", hash = "sha256:057f6bf9685f75215d0c53bf3ac4a10b3e6578351de307abad9e18a99182af56", size = 176249402 }, ] @@ -3291,7 +3295,6 @@ version = "12.6.85" source = { registry = "https://pypi.org/simple" } wheels = [ { url = "https://files.pythonhosted.org/packages/9d/d7/c5383e47c7e9bf1c99d5bd2a8c935af2b6d705ad831a7ec5c97db4d82f4f/nvidia_nvjitlink_cu12-12.6.85-py3-none-manylinux2010_x86_64.manylinux_2_12_x86_64.whl", hash = "sha256:eedc36df9e88b682efe4309aa16b5b4e78c2407eac59e8c10a6a47535164369a", size = 19744971 }, - { url = "https://files.pythonhosted.org/packages/31/db/dc71113d441f208cdfe7ae10d4983884e13f464a6252450693365e166dcf/nvidia_nvjitlink_cu12-12.6.85-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:cf4eaa7d4b6b543ffd69d6abfb11efdeb2db48270d94dfd3a452c24150829e41", size = 19270338 }, ] [[package]] From 5f9c9c7de7835aec86cafdda5490d5edb246a672 Mon Sep 17 00:00:00 2001 From: Eric Pinzur Date: Tue, 18 Mar 2025 11:22:12 -0500 Subject: [PATCH 2/3] fix for python 3.10 and 3.11' --- .../examples/code_generation/format.py | 55 +++++++------------ 1 file changed, 20 insertions(+), 35 deletions(-) diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py index 7d6195be..09880e49 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py @@ -34,16 +34,10 @@ def format_document(doc: Document, debug: bool = False) -> str: text += f"path: \n\t{metadata['path']}\n\n" - if "bases" in metadata: - text += f"bases: \n\t{add_tabs('\n'.join(metadata['bases']))}\n\n" - - if "exports" in metadata: - text += f"exports: \n\t{add_tabs('\n'.join(metadata['exports']))}\n\n" - - if "implemented_by" in metadata: - text += ( - f"implemented_by: \n\t{add_tabs('\n'.join(metadata['implemented_by']))}\n\n" - ) + for key in ["bases", "exports", "implemented_by"]: + if key in metadata: + values = '\n'.join(metadata[key]) + text += f"{key}: \n\t{add_tabs(values)}\n\n" if "properties" in metadata: props = [f"{k}: {v}" for k, v in metadata["properties"].items()] @@ -54,27 +48,18 @@ def format_document(doc: Document, debug: bool = False) -> str: elif "value" in metadata: text += f"{metadata['value']}\n\n" - if "attributes" in metadata: - attributes = [_format_parameter(a) for a in metadata["attributes"]] - text += f"attributes: \n\t{add_tabs('\n\n'.join(attributes))}\n\n" - - if "parameters" in metadata: - parameters = [_format_parameter(p) for p in metadata["parameters"]] - text += f"parameters: \n\t{add_tabs('\n\n'.join(parameters))}\n\n" + for key in ["attributes", "parameters"]: + if key in metadata: + values = '\n\n'.join([_format_parameter(v) for v in metadata[key]]) + text += f"{key}: \n\t{add_tabs(values)}\n\n" - if "returns" in metadata: - returns = [_format_return(r) for r in metadata["returns"]] - text += f"returns: \n\t{add_tabs('\n\n'.join(returns))}\n\n" + for key in ["returns", "yields"]: + if key in metadata: + values = '\n\n'.join([_format_return(v) for v in metadata[key]]) + text += f"{key}: \n\t{add_tabs(values)}\n\n" - if "yields" in metadata: - yields = [_format_return(y) for y in metadata["yields"]] - text += f"yields: \n\t{add_tabs('\n\n'.join(yields))}\n\n" - - if "note" in metadata: - text += f"note: \n\t{add_tabs(metadata['note'])}\n\n" - - if "example" in metadata: - text += f"example: \n\t{add_tabs(metadata['example'])}\n\n" + for key in ["note", "example"]: + text += f"{key}: \n\t{add_tabs(metadata[key])}\n\n" if debug: if "imports" in metadata: @@ -84,13 +69,13 @@ def format_document(doc: Document, debug: bool = False) -> str: imports.append(real_name) else: imports.append(f"{real_name} as {as_name}") - text += f"imports: \n\t{add_tabs('\n'.join(imports))}\n\n" - - if "references" in metadata: - text += f"references: \n\t{add_tabs('\n'.join(metadata['references']))}\n\n" + values = "\n".join(imports) + text += f"imports: \n\t{add_tabs(values)}\n\n" - if "gathered_types" in metadata: - text += f"gathered_types: \n\t{add_tabs('\n'.join(metadata['gathered_types']))}\n\n" # noqa: E501 + for key in ["references", "gathered_types"]: + if key in metadata: + values = "\n".join(metadata[key]) + text += f"{key}: \n\t{add_tabs(values)}\n\n" if "parent" in metadata: text += f"parent: {metadata['parent']}\n\n" From 757c9acedbbc825fafecd8e19d43f2e0f6ef747c Mon Sep 17 00:00:00 2001 From: Eric Pinzur Date: Tue, 18 Mar 2025 11:44:56 -0500 Subject: [PATCH 3/3] fixes --- data/astrapy.README.md | 37 ++++ docs/examples/code-generation.ipynb | 202 +++++++++++------- docs/examples/index.md | 8 +- docs/examples/lazy-graph-rag.ipynb | 7 - docs/styles.css | 7 +- mkdocs.yml | 1 + .../datasets/astrapy/__init__.py | 4 - .../datasets/astrapy/fetch.py | 4 +- .../examples/code_generation/__init__.py | 3 +- .../examples/code_generation/converter.py | 7 +- .../examples/code_generation/format.py | 34 +-- .../src/graph_rag_example_helpers/utils.py | 3 - 12 files changed, 192 insertions(+), 125 deletions(-) create mode 100644 data/astrapy.README.md delete mode 100644 packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py diff --git a/data/astrapy.README.md b/data/astrapy.README.md new file mode 100644 index 00000000..b5db15b3 --- /dev/null +++ b/data/astrapy.README.md @@ -0,0 +1,37 @@ +# AstraPy Documentation + +This data file contains the AstraPy documentation in a specialized format for use +in the GraphRAG `code_generation` example. + +## Generation + +The file was generated using `astrapy` version `1.5.2` via the `convert` method in +`graph_rag_example_helpers.examples.code_generation.converter`. See the help on the +method for more information about how to use it. + +## Structure + +The JSONL file contains one JSON object per line, with the following structure: + +id: the path to the object in the package +text: the description of the object (if any, can be empty) + +metadata: Always includes `name`, `path`, `kind` keys. + The remaining keys below are included when available. + name: the name of the object + path: the path to the object in the package + kind: either `module`, `class`, `function`, or `attribute` + parameters: the parameters for a class or function. Includes type + information, default values, and descriptions + attributes: the attributes on a class or module. Includes type + information and descriptions + gathered_types: list of non-standard types in the parameters and attributes + imports: list of non-standard types imported by the class or module + exports: list of non-standard types exported by the module + properties: list of boolean properties about the module + example: any code examples for the class, function, or module + references: list of any non-standard types used in the example code + returns: the return type and description + yields: the yield type and description + bases: list of base types inherited by the class + implemented_by: list of types that implement the a base class diff --git a/docs/examples/code-generation.ipynb b/docs/examples/code-generation.ipynb index c25c3fb2..c7ee3c79 100644 --- a/docs/examples/code-generation.ipynb +++ b/docs/examples/code-generation.ipynb @@ -5,7 +5,7 @@ "execution_count": null, "metadata": { "tags": [ - "hide_input" + "hide_cell" ] }, "outputs": [], @@ -17,22 +17,31 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", - "\n", "# Code Generation with GraphRAG\n", "\n", "## Introduction\n", "\n", - "In this notebook we will show how GraphRAG can be used to traverse through python library documentation in order to provide help to an LLM that is generating code.\n", + "In this notebook, we demonstrate that **GraphRAG significantly outperforms standard vector-based retrieval** for generating working code from documentation. While traditional vector search retrieves relevant snippets, it often lacks the structured understanding needed to produce executable results. In contrast, **GraphRAG enables the LLM to follow logical relationships within documentation, leading to functional code generation**.\n", + "\n", + "We achieve this by leveraging a custom traversal strategy, selecting nodes that contain both **code examples and descriptive text**, allowing the LLM to assemble more complete responses.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Getting Started\n", "\n", - "We'll use a custom Strategy to traverse through the documents and select nodes that contain code examples and/or descriptive text.\n", + "Below we will experiment with the AstraPy documentation to evaluate how well GraphRAG can generate working code. \n", "\n", + "Using AstraDB as the vector store, we compare GraphRAG’s structured retrieval with standard vector search to solve a specific coding task. \n", "The query we will be sending to the LLM is the following:" ] }, { "cell_type": "code", - "execution_count": 9, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -54,8 +63,6 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Environment Setup\n", - "\n", "The following block will configure the environment from the Colab Secrets.\n", "To run it, you should have the following Colab Secrets defined and accessible to this notebook:\n", "\n", @@ -63,7 +70,9 @@ "- `ASTRA_DB_API_ENDPOINT`: The Astra DB API endpoint.\n", "- `ASTRA_DB_APPLICATION_TOKEN`: The Astra DB Application token.\n", "- `LANGCHAIN_API_KEY`: Optional. If defined, will enable LangSmith tracing.\n", - "- `ASTRA_DB_KEYSPACE`: Optional. If defined, will specify the Astra DB keyspace. If not defined, will use the default." + "- `ASTRA_DB_KEYSPACE`: Optional. If defined, will specify the Astra DB keyspace. If not defined, will use the default.\n", + "\n", + "If you don't yet have access to an AstraDB database, or need to check your credentials, see the help [here](https://python.langchain.com/docs/integrations/vectorstores/astradb/#credentials)." ] }, { @@ -91,7 +100,7 @@ }, { "cell_type": "code", - "execution_count": 49, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -145,58 +154,58 @@ "id: astrapy.client.DataAPIClient\n", "\n", "page_content: |\n", - " A client for using the Data API. This is the main entry point and sits\n", - " at the top of the conceptual \"client -> database -> collection\" hierarchy.\n", + " A client for using the Data API. This is the main entry point and sits\n", + " at the top of the conceptual \"client -> database -> collection\" hierarchy.\n", "\n", - " A client is created first, optionally passing it a suitable Access Token.\n", - " Starting from the client, then:\n", - " - databases (Database and AsyncDatabase) are created for working with data\n", - " - AstraDBAdmin objects can be created for admin-level work\n", + " A client is created first, optionally passing it a suitable Access Token.\n", + " Starting from the client, then:\n", + " - databases (Database and AsyncDatabase) are created for working with data\n", + " - AstraDBAdmin objects can be created for admin-level work\n", "\n", "metadata:\n", - " name: DataAPIClient\n", - " kind: class\n", - " path: astrapy.client.DataAPIClient\n", - " parameters: \n", - " token: |\n", - " str | TokenProvider | None = None\n", - " an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\n", - " This can be either a literal token string or a subclass of\n", - " `astrapy.authentication.TokenProvider`.\n", + " name: DataAPIClient\n", + " kind: class\n", + " path: astrapy.client.DataAPIClient\n", + " parameters: \n", + " token: |\n", + " str | TokenProvider | None = None\n", + " an Access Token to the database. Example: `\"AstraCS:xyz...\"`.\n", + " This can be either a literal token string or a subclass of\n", + " `astrapy.authentication.TokenProvider`.\n", + " \n", + " environment: |\n", + " str | None = None\n", + " a string representing the target Data API environment.\n", + " It can be left unspecified for the default value of `Environment.PROD`;\n", + " other values include `Environment.OTHER`, `Environment.DSE`.\n", " \n", - " environment: |\n", - " str | None = None\n", - " a string representing the target Data API environment.\n", - " It can be left unspecified for the default value of `Environment.PROD`;\n", - " other values include `Environment.OTHER`, `Environment.DSE`.\n", - " \n", - " callers: |\n", - " Sequence[CallerType] = []\n", - " a list of caller identities, i.e. applications, or frameworks,\n", - " on behalf of which Data API and DevOps API calls are performed.\n", - " These end up in the request user-agent.\n", - " Each caller identity is a (\"caller_name\", \"caller_version\") pair.\n", - "\n", - " example: |\n", - " >>> from astrapy import DataAPIClient\n", - " >>> my_client = DataAPIClient(\"AstraCS:...\")\n", - " >>> my_db0 = my_client.get_database(\n", - " ... \"https://01234567-....apps.astra.datastax.com\"\n", - " ... )\n", - " >>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n", - " >>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.1, 0.3]})\n", - " >>> my_db1 = my_client.get_database(\"01234567-...\")\n", - " >>> my_db2 = my_client.get_database(\"01234567-...\", region=\"us-east1\")\n", - " >>> my_adm0 = my_client.get_admin()\n", - " >>> my_adm1 = my_client.get_admin(token=more_powerful_token_override)\n", - " >>> database_list = my_adm0.list_databases()\n", - "\n", - " references: \n", - " astrapy.client.DataAPIClient\n", - "\n", - " gathered_types: \n", - " astrapy.constants.CallerType\n", - " astrapy.authentication.TokenProvider\n", + " callers: |\n", + " Sequence[CallerType] = []\n", + " a list of caller identities, i.e. applications, or frameworks,\n", + " on behalf of which Data API and DevOps API calls are performed.\n", + " These end up in the request user-agent.\n", + " Each caller identity is a (\"caller_name\", \"caller_version\") pair.\n", + "\n", + " example: |\n", + " >>> from astrapy import DataAPIClient\n", + " >>> my_client = DataAPIClient(\"AstraCS:...\")\n", + " >>> my_db0 = my_client.get_database(\n", + " ... \"https://01234567-....apps.astra.datastax.com\"\n", + " ... )\n", + " >>> my_coll = my_db0.create_collection(\"movies\", dimension=2)\n", + " >>> my_coll.insert_one({\"title\": \"The Title\", \"$vector\": [0.1, 0.3]})\n", + " >>> my_db1 = my_client.get_database(\"01234567-...\")\n", + " >>> my_db2 = my_client.get_database(\"01234567-...\", region=\"us-east1\")\n", + " >>> my_adm0 = my_client.get_admin()\n", + " >>> my_adm1 = my_client.get_admin(token=more_powerful_token_override)\n", + " >>> database_list = my_adm0.list_databases()\n", + "\n", + " references: \n", + " astrapy.client.DataAPIClient\n", + "\n", + " gathered_types: \n", + " astrapy.constants.CallerType\n", + " astrapy.authentication.TokenProvider\n", "```\n", "\n", "\n", @@ -242,7 +251,7 @@ }, { "cell_type": "code", - "execution_count": 50, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -289,8 +298,12 @@ }, { "cell_type": "code", - "execution_count": 7, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -303,9 +316,7 @@ "\n", "callers = callers_param\n", "\n", - "parent: astrapy.admin.AstraDBAdmin\n", - "\n", - "\n" + "parent: astrapy.admin.AstraDBAdmin\n" ] } ], @@ -350,7 +361,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -376,8 +387,12 @@ }, { "cell_type": "code", - "execution_count": 37, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -425,7 +440,7 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -478,8 +493,12 @@ }, { "cell_type": "code", - "execution_count": 39, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -515,14 +534,17 @@ "\n", "We now use the `CodeExamples` strategy inside a Langchain pipeline to generate code snippets.\n", "\n", - "We will also use a custom document formatter, which will format the document in a way that makes it look like standard documentation. In particular, it will format all the extra details stored in the metadata in a way that is easy to read. This will help the LLM use the information in the documents to generate code.\n", - "\n" + "We will also use a custom document formatter, which will format the document in a way that makes it look like standard documentation. In particular, it will format all the extra details stored in the metadata in a way that is easy to read. This will help the LLM use the information in the documents to generate code.\n" ] }, { "cell_type": "code", - "execution_count": 59, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -593,7 +615,7 @@ }, { "cell_type": "code", - "execution_count": 60, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -619,8 +641,12 @@ }, { "cell_type": "code", - "execution_count": 61, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -645,9 +671,11 @@ "source": [ "## Conclusion\n", "\n", - "The code generated by GraphRAG isn't perfect, but it works. It's a good starting point for the LLM to generate code. The LLM used the information in the documentation and code examples to generate functional code.\n", + "The results clearly demonstrate that **GraphRAG leads to functional code generation, while standard vector-based retrieval fails**. \n", + "\n", + "In contrast, attempts using **only an LLM** or **standard vector-based RAG** resulted in **incomplete or non-functional outputs**. The appendix includes examples illustrating these limitations.\n", "\n", - "In the Appendix, you can see examples of attempting this query with just an LLM and with Standard (non-graph) RAG. In both cases, the LLM was unable to generate usable code." + "By structuring document relationships effectively, **GraphRAG improves retrieval quality, enabling more reliable LLM-assisted code generation**." ] }, { @@ -668,8 +696,12 @@ }, { "cell_type": "code", - "execution_count": 68, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", @@ -733,8 +765,12 @@ }, { "cell_type": "code", - "execution_count": 67, - "metadata": {}, + "execution_count": null, + "metadata": { + "tags": [ + "keep_output" + ] + }, "outputs": [ { "name": "stdout", diff --git a/docs/examples/index.md b/docs/examples/index.md index 5f7ad65c..27e35c08 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -18,12 +18,12 @@ vector store so that it can be used to provide context to an LLM for code generation. It uses LangChain and `langchain-graph-retriever` with a custom traversal Strategy - to in order to improve LLM generated code output. It shows that using GraphRAG can - provide a significant increase in quality over using either a LLM alone or standard + in order to improve LLM generated code output. It shows that using GraphRAG can + provide a significant increase in quality over using either an LLM alone or standard RAG. - GraphRAG is traverses through the documentation in a way similar to how a - software engineer would, in order to determine how to solve a coding problem. + GraphRAG traverses cross references in the documentation like a software engineer + would, in order to determine how to solve a coding problem. [:material-fast-forward: Code Generation Example](code-generation.ipynb) diff --git a/docs/examples/lazy-graph-rag.ipynb b/docs/examples/lazy-graph-rag.ipynb index 5fa7c5a4..218e1b31 100644 --- a/docs/examples/lazy-graph-rag.ipynb +++ b/docs/examples/lazy-graph-rag.ipynb @@ -71,13 +71,6 @@ "The last package -- `graph-rag-example-helpers` -- includes some helpers for setting up environment helpers and allowing the loading of wikipedia data to be restarted if it fails." ] }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - }, { "cell_type": "code", "execution_count": null, diff --git a/docs/styles.css b/docs/styles.css index fb7f475d..834a5e9d 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -12,4 +12,9 @@ } .colab { color: #F9AB00; -} \ No newline at end of file +} + +/* hide cell tags */ +.jp-Cell .celltoolbar { + display: none !important; +} diff --git a/mkdocs.yml b/mkdocs.yml index d6e29919..c090c75b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -129,6 +129,7 @@ nav: - Examples: - examples/index.md - examples/lazy-graph-rag.ipynb + - examples/code-generation.ipynb - Reference: - reference/index.md - graph-retriever: diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py index e283bdbf..a7041172 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/__init__.py @@ -1,9 +1,5 @@ -from ...examples.code_generation.format import add_tabs, format_docs, format_document from .fetch import fetch_documents __all__ = [ "fetch_documents", - "add_tabs", - "format_document", - "format_docs", ] diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py index 57182b2e..183d8c03 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/datasets/astrapy/fetch.py @@ -3,9 +3,7 @@ import requests from langchain_core.documents import Document -# TODO: revert to main branch before code generation is merged -# ASTRAPY_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/main/data/astrapy.jsonl" -ASTRAPY_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/code_generation/data/astrapy.jsonl" +ASTRAPY_JSONL_URL = "https://raw.githubusercontent.com/datastax/graph-rag/refs/heads/main/data/astrapy.jsonl" def fetch_documents() -> list[Document]: diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py index d10cfc30..b1ac8db7 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/__init__.py @@ -1,7 +1,6 @@ -from .format import add_tabs, format_docs, format_document +from .format import format_docs, format_document __all__ = [ - "add_tabs", "format_document", "format_docs", ] diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py index 6d65985f..b2c4b02b 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/converter.py @@ -2,12 +2,11 @@ import json import os import typing +from textwrap import indent from typing import Any import griffe -from graph_rag_example_helpers.utils import add_tabs - def convert( package_name: str, @@ -165,7 +164,7 @@ def _format_parameter(self, el: dict[str, str]) -> str: if "default" in el: text += f" = {el['default']}" if "description" in el: - desc = add_tabs(el["description"]) + desc = indent(el["description"], "\t") text += f"\n\t{desc}" return text @@ -174,7 +173,7 @@ def _format_return(self, el: dict[str, str]) -> str: if "type" in el: items.append(el["type"]) if "description" in el: - items.append(add_tabs(el["description"])) + items.append(indent(el["description"], "\t")) return "\n\t".join(items) def _extract_common(self, obj: griffe.Object) -> dict[str, Any]: diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py index 09880e49..5450f744 100644 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py +++ b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/examples/code_generation/format.py @@ -1,6 +1,10 @@ +from textwrap import indent + from langchain_core.documents import Document -from graph_rag_example_helpers.utils import add_tabs + +def _add_tabs(text: str) -> str: + return indent(text, "\t") def _format_parameter(el: dict[str, str]) -> str: @@ -13,7 +17,7 @@ def _format_parameter(el: dict[str, str]) -> str: if "default" in el: text += f" = {el['default']}" if "description" in el: - desc = add_tabs(el["description"]) + desc = _add_tabs(el["description"]) text += f"\n\t{desc}" return text @@ -23,7 +27,7 @@ def _format_return(el: dict[str, str]) -> str: if "type" in el: items.append(el["type"]) if "description" in el: - items.append(add_tabs(el["description"])) + items.append(_add_tabs(el["description"])) return "\n\t".join(items) @@ -36,30 +40,32 @@ def format_document(doc: Document, debug: bool = False) -> str: for key in ["bases", "exports", "implemented_by"]: if key in metadata: - values = '\n'.join(metadata[key]) - text += f"{key}: \n\t{add_tabs(values)}\n\n" + values = "\n".join(metadata[key]) + text += f"{key}: \n\t{_add_tabs(values)}\n\n" if "properties" in metadata: props = [f"{k}: {v}" for k, v in metadata["properties"].items()] - text += f"properties: \n\t{add_tabs('\n'.join(props))}\n\n" + values = "\n".join(props) + text += f"properties: \n\t{_add_tabs(values)}\n\n" if doc.page_content != "": - text += f"description: \n\t{add_tabs(doc.page_content)}\n\n" + text += f"description: \n\t{_add_tabs(doc.page_content)}\n\n" elif "value" in metadata: text += f"{metadata['value']}\n\n" for key in ["attributes", "parameters"]: if key in metadata: - values = '\n\n'.join([_format_parameter(v) for v in metadata[key]]) - text += f"{key}: \n\t{add_tabs(values)}\n\n" + values = "\n\n".join([_format_parameter(v) for v in metadata[key]]) + text += f"{key}: \n\t{_add_tabs(values)}\n\n" for key in ["returns", "yields"]: if key in metadata: - values = '\n\n'.join([_format_return(v) for v in metadata[key]]) - text += f"{key}: \n\t{add_tabs(values)}\n\n" + values = "\n\n".join([_format_return(v) for v in metadata[key]]) + text += f"{key}: \n\t{_add_tabs(values)}\n\n" for key in ["note", "example"]: - text += f"{key}: \n\t{add_tabs(metadata[key])}\n\n" + if key in metadata: + text += f"{key}: \n\t{_add_tabs(metadata[key])}\n\n" if debug: if "imports" in metadata: @@ -70,12 +76,12 @@ def format_document(doc: Document, debug: bool = False) -> str: else: imports.append(f"{real_name} as {as_name}") values = "\n".join(imports) - text += f"imports: \n\t{add_tabs(values)}\n\n" + text += f"imports: \n\t{_add_tabs(values)}\n\n" for key in ["references", "gathered_types"]: if key in metadata: values = "\n".join(metadata[key]) - text += f"{key}: \n\t{add_tabs(values)}\n\n" + text += f"{key}: \n\t{_add_tabs(values)}\n\n" if "parent" in metadata: text += f"parent: {metadata['parent']}\n\n" diff --git a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py b/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py deleted file mode 100644 index 4b647af6..00000000 --- a/packages/graph-rag-example-helpers/src/graph_rag_example_helpers/utils.py +++ /dev/null @@ -1,3 +0,0 @@ -def add_tabs(text: str) -> str: - """Add a tab character to the start of each line in the text.""" - return "\n\t".join(text.split("\n"))