NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #953 most downloaded on PyPI
Microsoft Azure Cosmos Client Library for Python
Last release 17 days ago
16 Sep 2026
Ships fairly regularly
a new release about every 3 weeks
Most releases are documented
notes for 28 of 35 stable releases
1 version withdrawn
withdrawn after publishing
8 years old
77 releases · first in 2018
Added deprecation warning for "lazy" indexing mode. The backend no longer allows creating containers with this mode and will set them to consistent in…
New features
Bug fixes
Breaking changes: New API design
One column per quarter.
access_condition, if_match, if_none_match) have been deprecated in favor of separate match_condition and etag parameters.__repr__ support for Cosmos entity objects.timeout keyword argument to all operations to specify an absolute timeout in seconds
within which the operation must be completed. If the timeout value is exceeded, a azure.cosmos.errors.CosmosClientTimeoutError will be raised.ConnectionRetryPolicy to manage retry behaviour during HTTP connection errors.retry_total - Maximum retry attempts.retry_backoff_max - Maximum retry wait time in seconds.retry_fixed_interval - Fixed retry interval in milliseconds.retry_read - Maximum number of socket read retry attempts.retry_connect - Maximum number of connection error retry attempts.retry_status - Maximum number of retry attempts on error status codes.retry_on_status_codes - A list of specific status codes to retry on.retry_backoff_factor - Factor to calculate wait time between retry attempts.create_database_if_not_exists() and create_container_if_not_exists functionalities to CosmosClient and Database respectively.Version 4.0.0b2 is the second iteration in our efforts to build a more Pythonic client library.
Breaking changes
azure.core.pipeline.Database -> DatabaseProxyUser -> UserProxyContainer -> ContainerProxyScripts -> ScriptsProxyCosmosClient has been updated:
auth parameter has been renamed to credential and will now take an authentication type directly. This means the master key value, a dictionary of resource tokens, or a list of permissions can be passed in. However the old dictionary format is still supported.connection_policy parameter has been made a keyword only parameter, and while it is still supported, each of the individual attributes of the policy can now be passed in as explicit keyword arguments:
request_timeoutmedia_request_timeoutconnection_modemedia_read_modeproxy_configenable_endpoint_discoverypreferred_locationsmultiple_write_locationsCosmosClient to enable creation via a connection string retrieved from the Azure portal.read_all operations have been renamed to list operations:
CosmosClient.read_all_databases -> CosmosClient.list_databasesContainer.read_all_conflicts -> ContainerProxy.list_conflictsDatabase.read_all_containers -> DatabaseProxy.list_containersDatabase.read_all_users -> DatabaseProxy.list_usersUser.read_all_permissions -> UserProxy.list_permissionsrequest_options or feed_options parameters, these have been moved to keyword only parameters. In addition, while these options dictionaries are still supported, each of the individual options within the dictionary are now supported as explicit keyword arguments.azure.core.AzureError instead of CosmosError which has been removed.
HTTPFailure has been renamed to CosmosHttpResponseErrorJSONParseFailure has been removed and replaced by azure.core.DecodeErrorCosmosResourceNotFoundError for status 404CosmosResourceExistsError for status 409CosmosAccessConditionFailedError for status 412CosmosClient can now be run in a context manager to handle closing the client connection.azure.core.paging.ItemPaged. The method fetch_next_block has been replaced by a secondary iterator, accessed by the by_page method.Version 4.0.0b1 is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Cosmos. For more information about this, and preview releases of other Azure SDK libraries, please visit https://aka.ms/azure-sdk-preview1-python.
Breaking changes: New API design
Operations are now scoped to a particular client:
CosmosClient: This client handles account-level operations. This includes managing service properties and listing the databases within an account.Database: This client handles database-level operations. This includes creating and deleting containers, users and stored procedures. It can be accessed from a CosmosClient instance by name.Container: This client handles operations for a particular container. This includes querying and inserting items and managing properties.User: This client handles operations for a particular user. This includes adding and deleting permissions and managing user properties.These clients can be accessed by navigating down the client hierarchy using the get_<child>_client method. For full details on the new API, please see the reference documentation.
Clients are accessed by name rather than by Id. No need to concatenate strings to create links.
No more need to import types and methods from individual modules. The public API surface area is available directly in the azure.cosmos package.
Individual request properties can be provided as keyword arguments rather than constructing a separate RequestOptions instance.
Added retry policy support for throttled requests. (Throttled requests receive a request rate too large exception, error code 429.) By default, DocumentDB retries nine times for each request when error code 429 is encountered, honoring the retryAfter time in the response header. A fixed retry interval time can now be set as part of the RetryOptions property on the ConnectionPolicy object if you want to ignore the retryAfter time returned by server between the retries. DocumentDB now waits for a maximum of 30 seconds for each request that is being throttled (irrespective of retry count) and returns the response with error code 429. This time can also be overridden in the RetryOptions property on ConnectionPolicy object.
DocumentDB now returns x-ms-throttle-retry-count and x-ms-throttle-retry-wait-time-ms as the response headers in every request to denote the throttle retry count and the cumulative time the request waited between the retries.
Removed the RetryPolicy class and the corresponding property (retry_policy) exposed on the document_client class and instead introduced a RetryOptions class exposing the RetryOptions property on ConnectionPolicy class that can be used to override some of the default retry options.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →