Migration
Import paths
Every public name has one import path, the module its reference page documents. Some names can also still be imported from an older path, so that code written against it keeps working. Those paths are kept only for that code: new code should use the path in the right-hand column below, and none of the old paths will gain anything new.
Importing a name from an old path emits a CouchbaseDeprecationWarning that
points at the import and says what to use instead. The SDK’s type information leaves the old paths out,
so a type checker reports them too. To find them all in a test run, turn the warning into an error:
import warnings
from couchbase.warnings import CouchbaseDeprecationWarning
warnings.simplefilter('error', CouchbaseDeprecationWarning)
The table lists every old path the SDK still serves. “Nothing” marks a name that was never meant for applications, or one with no replacement.
Old path |
Import instead |
|---|---|
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
|
|
Nothing: internal to the SDK |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Nothing: internal to the SDK |
|
|
|
Nothing: internal to the SDK |
|
|
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: nothing in the SDK returns one |
|
|
|
|
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
|
|
Nothing: internal to the SDK |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
|
Nothing: internal to the SDK |
Migrating from 3.x to 4.x
The Python SDK 4.x implements the SDK API 3 spec, so all the steps outlined in the SDK 3 migration docs apply to a migration from a Python SDK 2.x directly to Python SDK 4.x.
Importantly, the Python SDK 4.x has been substantially reworked to use a new backend (Couchbase++ instead of libcouchbase). Though the API surfaces are intended to be compatible, any code that relies on undocumented or uncommitted internal details is not guaranteed to work. Key areas that have been reworked:
The
couchbase_corepackage has been removed. The 4.x SDK provides appropriate import paths within thecouchbasepackage (or theacouchbaseandtxcouchbasepackages, for the async APIs) for anything that is needed with respect to the APIs provided by the SDK.As there is a new backend, the previous
_libcouchbaseC extension has been removed.Remnants of the 2.x API in previous Python 3.x SDK versions have been removed or deprecated.
Key items that have been removed:
The
ClassicAuthenticatorclass.Key-value operations are no longer available with a
bucketinstance. Use acollectioninstance for key-value operations.A
clusterandbucketinstance do not inherit from the same base class.The
Clientclass.The
ItemsAPI.The
Admincluster.
Key items that have been deprecated:
The datastructure methods of a
collectioninstance, replaced byCouchbaseList,CouchbaseMap,CouchbaseQueueandCouchbaseSet.OperationResultandValueResult, still available fromcouchbase.result.
Import paths have been reorganized to follow consistent patterns. The paths that existed in the 3.x SDK are mostly still available, apart from the
couchbase_corepackage; the ones that are deprecated are listed under Import paths.Authenticators are imported from
couchbase.auth.Constants are imported from
couchbase.constants.Options are imported from
couchbase.options.Management options are imported from
couchbase.management.options.Results are imported from
couchbase.result.Exceptions are imported from
couchbase.exceptions.Enumerations and classes related to an operation are imported from that operation’s module. For example,
QueryScanConsistencyis imported fromcouchbase.n1ql.
Changes to the async APIs (
acouchbaseandtxcouchbase):The multi-document operations (
get_multi,upsert_multiand the rest) exist only in thecouchbaseAPI. Each async API is built on a library with its own way to run operations together:asyncio.gather()for asyncio, andDeferredListfor Twisted.The
txcouchbaseAPI runs on Twisted’sasyncioreactor, which importingtxcouchbaseinstalls. Sotxcouchbasehas to be imported before the reactor is:import txcouchbase from twisted.internet import reactor