Choosing an API

    +
    The Couchbase Python SDK offers both asyncio and Twisted APIs for async operation.

    We will cover the asyncio API here initially. Twisted documentation will be added shortly.

    For asyncio: All operations return a Future[T] where T is the return type, with T generally being the same type as the synchronous equivalent. (Note, this genericisation of the Future type is not supported widely, yet, but the object returned is indeed a Future the value of which is of type T) This is equivalent to the operation being marked async fn(…​)→T, and await ing the result will wait for the operation to complete or fail.

    Future s are evaluated asynchronously using the familiar await keyword, and run in a blocking method. If a Future is awaited, the method awaiting the task must have the async keyword in its signature. More information can be found in Python’s asyncio documentation.

    Note: All examples on this page start with initiating a Cluster object and then opening the default Bucket and Collection:

    import acouchbase.cluster
    import couchbase.cluster
    import couchbase.auth
    cluster = acouchbase.cluster.Cluster("couchbase://localhost", couchbase.cluster.ClusterOptions(couchbase.auth.PasswordAuthenticator("user", "password")))
    cluster.bucket("travel-sample")
    
    bucket = cluster.bucket("default")
    await bucket.on_connect()
    collection = bucket.default_collection()

    Asynchronous Programming using await

    This is the most common and basic way for consuming Couchbase operations asynchronously via asyncio:

    upsert_result = await collection.upsert("doc1", dict(name="Ted", age=80))
    get_result = await collection.get("doc1")
    person = get_result.content

    Note that in the upsert method above, an exception will be thrown if the operation fails; if it succeeds then the result will be an MutationResult that contains the CAS value for reuse, otherwise it can be ignored. get returns a GetResult if it succeeds, you’ll then have to use content or content_as to read the returned value.