{"id":5117,"library":"astrapy","title":"Astrapy Python Client","description":"Astrapy is a Python client library for interacting with the Data API on DataStax Astra DB. It provides a straightforward interface for working with both document collections (JSON) and tables. Currently at version 2.2.1, the library sees active development with frequent minor releases introducing new features and improvements.","status":"active","version":"2.2.1","language":"en","source_language":"en","source_url":"https://github.com/datastax/astrapy","tags":["database","datastax","astra-db","vector-database","nosql","document-store"],"install":[{"cmd":"pip install astrapy","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"AstraDB","correct":"from astrapy.db import AstraDB"},{"note":"In recent versions (2.x), Collection is directly exposed via astrapy.db for unified access. While astrapy.collections might still work, astrapy.db is preferred for consistency.","wrong":"from astrapy.collections import Collection","symbol":"Collection","correct":"from astrapy.db import Collection"}],"quickstart":{"code":"import os\nfrom astrapy.db import AstraDB\n\n# Get credentials from environment variables\nASTRA_DB_API_ENDPOINT = os.environ.get('ASTRA_DB_API_ENDPOINT', '')\nASTRA_DB_APPLICATION_TOKEN = os.environ.get('ASTRA_DB_APPLICATION_TOKEN', '')\nASTRA_DB_KEYSPACE = os.environ.get('ASTRA_DB_KEYSPACE', None) # Optional\n\nif not ASTRA_DB_API_ENDPOINT or not ASTRA_DB_APPLICATION_TOKEN:\n    raise ValueError(\n        \"Please set ASTRA_DB_API_ENDPOINT and ASTRA_DB_APPLICATION_TOKEN \"\n        \"environment variables.\"\n    )\n\n# Initialize Astra DB client\nastradb = AstraDB(\n    api_endpoint=ASTRA_DB_API_ENDPOINT,\n    token=ASTRA_DB_APPLICATION_TOKEN,\n    namespace=ASTRA_DB_KEYSPACE,\n)\n\nprint(f\"Connected to Astra DB: {astradb.api_endpoint}\")\n\n# Get or create a collection\ncollection = astradb.collection(\"my_test_collection\")\n\n# Insert a document\ndocument_id = \"doc1\"\ninserted_document = collection.insert_one({\"_id\": document_id, \"item\": \"apple\", \"price\": 1.0})\nprint(f\"Inserted document with ID: {inserted_document['inserted_id']}\")\n\n# Find a document\nfound_document = collection.find_one({\"_id\": document_id})\nprint(f\"Found document: {found_document}\")\n\n# Clean up (optional)\n# collection.delete_one({\"_id\": document_id})\n# print(f\"Deleted document with ID: {document_id}\")","lang":"python","description":"This quickstart demonstrates how to connect to DataStax Astra DB, get a collection, insert a document, and retrieve it. It relies on environment variables for secure credential management."},"warnings":[{"fix":"Consult the migration guide and new API Reference for 2.x. Key changes include how `Database` and `Collection` objects are initialized and used, as well as new data type handling.","message":"Version 2.0.0 introduced significant API changes, including full support for Tables, a major revision of the overall interface, and new astrapy-specific data types (e.g., `DataAPIVector`, `DataAPIDate`). Code written for 1.x versions will likely require substantial updates.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Python environment to 3.9 or newer before installing or upgrading to astrapy 2.2.0+.","message":"Python 3.8 support was dropped in version 2.2.0. The library now requires Python 3.9 or higher.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Ensure you are on the latest stable version of `astrapy` to benefit from fixes related to `$vector: null` handling. Always test vector operations carefully, especially when explicitly setting vectors to null.","message":"Handling `'$vector': null` for inserts or updates to collections has seen several fixes across versions 2.0.1 and 2.1.0. While intended to allow setting a vector field to null (removing its vector), users might encounter unexpected behavior if not on the latest patch or if the API behavior shifts.","severity":"gotcha","affected_versions":"<2.2.0"},{"fix":"Replace `cursor.alive` with `cursor.state != CursorState.CLOSED` in your code.","message":"The `alive` property on cursor objects was removed. Instead of `cursor.alive`, you should now check `cursor.state != CursorState.CLOSED`.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}