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

acouchbase.analytics.AnalyticsQuery

Nothing: internal to the SDK

acouchbase.n1ql.N1QLQuery

Nothing: internal to the SDK

acouchbase.options.forward_args

Nothing: internal to the SDK

acouchbase.options.get_valid_args

Nothing: internal to the SDK

acouchbase.options.get_valid_multi_args

Nothing: internal to the SDK

acouchbase.search.SearchQueryBuilder

Nothing: internal to the SDK

acouchbase.subdocument.ArrayValues

Nothing: internal to the SDK

acouchbase.subdocument.SubDocOp

Nothing: internal to the SDK

acouchbase.views.ViewQuery

Nothing: internal to the SDK

couchbase.analytics.AnalyticsOptions

couchbase.options.AnalyticsOptions

couchbase.analytics.AnalyticsQuery

Nothing: internal to the SDK

couchbase.bucket.PingOptions

couchbase.options.PingOptions

couchbase.bucket.ViewErrorMode

couchbase.views.ViewErrorMode

couchbase.bucket.ViewOptions

couchbase.options.ViewOptions

couchbase.bucket.ViewOrdering

couchbase.views.ViewOrdering

couchbase.bucket.ViewScanConsistency

couchbase.views.ViewScanConsistency

couchbase.cluster.ClusterOptions

couchbase.options.ClusterOptions

couchbase.cluster.ClusterTimeoutOptions

couchbase.options.ClusterTimeoutOptions

couchbase.cluster.ClusterTracingOptions

couchbase.options.ClusterTracingOptions

couchbase.cluster.Compression

couchbase.options.Compression

couchbase.cluster.DiagnosticsOptions

couchbase.options.DiagnosticsOptions

couchbase.cluster.QueryOptions

couchbase.options.QueryOptions

couchbase.cluster.QueryProfile

couchbase.n1ql.QueryProfile

couchbase.cluster.QueryScanConsistency

couchbase.n1ql.QueryScanConsistency

couchbase.collection.AppendOptions

couchbase.options.AppendOptions

couchbase.collection.CBCollection

couchbase.collection.Collection

couchbase.collection.ConstrainedInt

couchbase.options.ConstrainedInt

couchbase.collection.DecrementOptions

couchbase.options.DecrementOptions

couchbase.collection.DeltaValue

couchbase.options.DeltaValue

couchbase.collection.ExistsOptions

couchbase.options.ExistsOptions

couchbase.collection.GetAllReplicasOptions

couchbase.options.GetAllReplicasOptions

couchbase.collection.GetAndLockOptions

couchbase.options.GetAndLockOptions

couchbase.collection.GetAndTouchOptions

couchbase.options.GetAndTouchOptions

couchbase.collection.GetAnyReplicaOptions

couchbase.options.GetAnyReplicaOptions

couchbase.collection.GetOptions

couchbase.options.GetOptions

couchbase.collection.IncrementOptions

couchbase.options.IncrementOptions

couchbase.collection.InsertOptions

couchbase.options.InsertOptions

couchbase.collection.LookupInOptions

couchbase.options.LookupInOptions

couchbase.collection.PrependOptions

couchbase.options.PrependOptions

couchbase.collection.RemoveOptions

couchbase.options.RemoveOptions

couchbase.collection.ReplaceOptions

couchbase.options.ReplaceOptions

couchbase.collection.Scope

couchbase.scope.Scope

couchbase.collection.SignedInt64

couchbase.options.SignedInt64

couchbase.collection.TouchOptions

couchbase.options.TouchOptions

couchbase.collection.UnlockOptions

couchbase.options.UnlockOptions

couchbase.collection.UpsertOptions

couchbase.options.UpsertOptions

couchbase.metrics.CouchbaseMeter

couchbase.observability.metrics.Meter

couchbase.metrics.CouchbaseValueRecorder

couchbase.observability.metrics.ValueRecorder

couchbase.mutation_state.MutationToken

couchbase.result.MutationToken

couchbase.n1ql.N1QLQuery

Nothing: internal to the SDK

couchbase.options.DefaultJsonSerializer

couchbase.serializer.DefaultJsonSerializer

couchbase.options.DurabilityParser

Nothing: internal to the SDK

couchbase.options.InvalidArgumentException

couchbase.exceptions.InvalidArgumentException

couchbase.options.Supportability

Nothing: internal to the SDK

couchbase.options.forward_args

Nothing: internal to the SDK

couchbase.options.get_valid_args

Nothing: internal to the SDK

couchbase.options.get_valid_multi_args

Nothing: internal to the SDK

couchbase.options.timedelta_as_milliseconds

Nothing: internal to the SDK

couchbase.options.timedelta_as_timestamp

Nothing: internal to the SDK

couchbase.options.validate_int

Nothing: internal to the SDK

couchbase.result.HttpResult

Nothing: nothing in the SDK returns one

couchbase.search.NoChildrenException

couchbase.exceptions.NoChildrenException

couchbase.search.SearchOptions

couchbase.options.SearchOptions

couchbase.search.SearchQueryBuilder

Nothing: internal to the SDK

couchbase.subdocument.ArrayValues

Nothing: internal to the SDK

couchbase.subdocument.MutateInOptions

couchbase.options.MutateInOptions

couchbase.subdocument.SubDocOp

Nothing: internal to the SDK

couchbase.tracing.CouchbaseSpan

couchbase.observability.tracing.RequestSpan

couchbase.tracing.CouchbaseTracer

couchbase.observability.tracing.RequestTracer

couchbase.transcoder.DefaultJsonSerializer

couchbase.serializer.DefaultJsonSerializer

couchbase.transcoder.FMT_BYTES

couchbase.constants.FMT_BYTES

couchbase.transcoder.FMT_COMMON_MASK

couchbase.constants.FMT_COMMON_MASK

couchbase.transcoder.FMT_JSON

couchbase.constants.FMT_JSON

couchbase.transcoder.FMT_LEGACY_MASK

couchbase.constants.FMT_LEGACY_MASK

couchbase.transcoder.FMT_PICKLE

couchbase.constants.FMT_PICKLE

couchbase.transcoder.FMT_UTF8

couchbase.constants.FMT_UTF8

couchbase.views.ViewQuery

Nothing: internal to the SDK

txcouchbase.options.forward_args

Nothing: internal to the SDK

txcouchbase.options.get_valid_args

Nothing: internal to the SDK

txcouchbase.options.get_valid_multi_args

Nothing: internal to the SDK

txcouchbase.subdocument.ArrayValues

Nothing: internal to the SDK

txcouchbase.subdocument.SubDocOp

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_core package has been removed. The 4.x SDK provides appropriate import paths within the couchbase package (or the acouchbase and txcouchbase packages, 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 _libcouchbase C 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 ClassicAuthenticator class.

      • Key-value operations are no longer available with a bucket instance. Use a collection instance for key-value operations.

      • A cluster and bucket instance do not inherit from the same base class.

      • The Client class.

      • The Items API.

      • The Admin cluster.

    • Key items that have been deprecated:

  • 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_core package; the ones that are deprecated are listed under Import paths.

  • Changes to the async APIs (acouchbase and txcouchbase):

    • The multi-document operations (get_multi, upsert_multi and the rest) exist only in the couchbase API. Each async API is built on a library with its own way to run operations together: asyncio.gather() for asyncio, and DeferredList for Twisted.

    • The txcouchbase API runs on Twisted’s asyncioreactor, which importing txcouchbase installs. So txcouchbase has to be imported before the reactor is:

      import txcouchbase
      
      from twisted.internet import reactor