Azure DocumentDB Python SDK (Legacy)

2.3.5 · abandoned · verified Thu Apr 16

This is the legacy Python SDK for Azure DocumentDB, which was rebranded to Azure Cosmos DB. This `pydocumentdb` package is no longer maintained and has been superseded by the `azure-cosmos` package. Users should migrate to `azure-cosmos` for current development. The last stable version released under this name was 2.3.5.

Common errors

```
ModuleNotFoundError: No module named 'pydocumentdb'
```
cause Attempting to import `pydocumentdb` without installing it, or trying to use `pydocumentdb` code after installing only `azure-cosmos`.

fix If you intend to use the legacy SDK, run `pip install pydocumentdb`. If you intend to use the modern SDK (recommended), install `azure-cosmos` (`pip install azure-cosmos`) and update your imports and code accordingly.
```
AttributeError: module 'pydocumentdb' has no attribute 'DocumentClient'
```
cause Incorrect import statement for the `DocumentClient` class, or trying to use `azure-cosmos` import patterns with the `pydocumentdb` package.

fix Ensure your import statement is `from pydocumentdb.document_client import DocumentClient`. For modern Cosmos DB, use `from azure.cosmos import CosmosClient` from the `azure-cosmos` package.
```
pydocumentdb.errors.DocumentDBClientException: {"code":"Unauthorized","message":"The input authorization token can't serve the request. Please check the authorization token and retry."...}
```
cause Likely attempting to connect to a modern Azure Cosmos DB account using the legacy `pydocumentdb` SDK, which uses outdated authentication methods, or an incorrect master key/connection details for an old DocumentDB account.

fix First, verify your master key and host URL are correct for the legacy DocumentDB account. More importantly, consider migrating to the `azure-cosmos` package, as `pydocumentdb` is not compatible with all modern Cosmos DB features and authentication, and its connection details may differ.

Warnings

breaking The `pydocumentdb` library is officially abandoned and has been replaced by `azure-cosmos`. No new features, bug fixes, or security updates are being released for `pydocumentdb`.
Fix: Migrate your code to use the `azure-cosmos` package. Refer to Azure Cosmos DB documentation for migration guides and updated APIs (e.g., `CosmosClient` instead of `DocumentClient`).
gotcha Connecting to modern Azure Cosmos DB accounts using `pydocumentdb` will likely fail or have limited functionality, as the API versions, authentication methods, and underlying protocols have evolved significantly.
Fix: Use the `azure-cosmos` package to connect to Azure Cosmos DB accounts. Ensure your connection strings and authentication methods align with the current Azure SDK for Python.
deprecated While `pydocumentdb` might have worked with Python 2, modern Azure SDKs (including `azure-cosmos`) only support Python 3.7+. Attempting to use `pydocumentdb` with Python 2 is unsupported and discouraged.
Fix: Upgrade your Python environment to 3.7+ and use the `azure-cosmos` SDK for current Azure Cosmos DB interactions.

Install

pip install pydocumentdb Install legacy pydocumentdb
pip install azure-cosmos Install modern Azure Cosmos DB SDK (recommended)

Imports

DocumentClient

from pydocumentdb.document_client import DocumentClient

documents (enums)
```
from pydocumentdb import documents
```

Quickstart

Shows how to initialize the legacy DocumentDB client. This code is for the `pydocumentdb` package, which is no longer maintained. Users are strongly advised to migrate to `azure-cosmos` for any new development or existing applications connecting to Azure Cosmos DB.

import os
from pydocumentdb.document_client import DocumentClient

# These environment variables would be for an *old* DocumentDB account.
# Modern Azure Cosmos DB accounts use the azure-cosmos SDK.
HOST = os.environ.get("DOCUMENTDB_HOST", "https://your-old-documentdb-account.documents.azure.com:443/")
MASTER_KEY = os.environ.get("DOCUMENTDB_MASTER_KEY", "YOUR_OLD_MASTER_KEY")

if not HOST or not MASTER_KEY or HOST == "https://your-old-documentdb-account.documents.azure.com:443/":
    print("Warning: Skipping DocumentDB client init. Please set DOCUMENTDB_HOST and DOCUMENTDB_MASTER_KEY for an *old* DocumentDB account.")
else:
    try:
        client = DocumentClient(HOST, {'masterKey': MASTER_KEY})
        print(f"Successfully initialized legacy DocumentDB client for host: {HOST}")
        # Example: Read databases (requires an active old DocumentDB account)
        # databases = list(client.ReadDatabases())
        # print(f"Found {len(databases)} databases.")
    except Exception as e:
        print(f"Error initializing legacy DocumentDB client: {e}")

view raw JSON →