The Twisted interface is for use with the Twisted Python event and networking library which may be found at http://www.twistedmatrix.com. This documentation contains the API reference for how to use the txcouchbase module with Twisted.
For the most part, the txcouchbase API functions like its synchronous counterpart, Connection, except for its asynchronous nature. Where the synchronous API returns a Result object, the txcouchbase API returns a Deferred which will have its callback invoked with a result.
As such, we will omit the mentions of the normal key value operations, which function identially to their synchronous conterparts documented in the Connection class.
The Connection interface for Twisted is subclassed from the lower-level TxAsyncConnection which returns AsyncResult objects rather than Deferred objects. This is largely due to performance reasons (Deferreds result in a 3x performance slowdown).
Connection subclass for Twisted. This inherits from the ‘Async’ class, but also adds some twisted-specific logic for hooking on a connection.
Register a defer to be fired at the firing of a specific event.
| Parameters: |
|
|---|
If this event has already fired, the deferred will be triggered asynchronously.
Example:
def on_connect(*args):
print("I'm connected")
def on_connect_err(*args):
print("Connection failed")
d = Deferred()
cb.registerDeferred('connect', d)
d.addCallback(on_connect)
d.addErrback(on_connect_err)
| Raise: | ValueError if the event name is unrecognized |
|---|
Short-hand for the following idiom:
d = Deferred()
cb.registerDeferred('connect', d)
return d
| Returns: | A Deferred |
|---|
Converts a raw couchbase.results.AsyncResult object into a Deferred.
This is shorthand for the following “non-idiom”:
d = Deferred()
opres = cb.set("foo", "bar")
opres.callback = d.callback
def d_err(res, ex_type, ex_val, ex_tb):
d.errback(opres, ex_type, ex_val, ex_tb)
opres.errback = d_err
return d
| Parameters: | opres (couchbase.results.AsyncResult) – The operation to wrap |
|---|---|
| Returns: | a Deferred object. |
Example:
opres = cb.set("foo", "bar")
d = cb.defer(opres)
def on_ok(res):
print("Result OK. Cas: {0}".format(res.cas))
d.addCallback(opres)
Boolean read only property indicating whether this instance has been connected.
Note that this will still return true even if it is subsequently closed via _close()
This class inherits from TxAsyncConnection. In addition to the connection methods, this class’ data access methods return Deferreds instead of AsyncResult objects.
Operations such as get() or set() will invoke the Deferred.callback with the result object when the result is complete, or they will invoke the Deferred.errback with an exception (or Failure) in case of an error. The rules of the quiet attribute for raising exceptions apply to the invocation of the errback. This means that in the case where the synchronous client would raise an exception, the Deferred API will have its errback invoked. Otherwise, the result’s success field should be inspected.
Likewise multi operations will be invoked with a MultiResult compatible object.
Some examples:
Using single items:
d_set = cb.set("foo", "bar")
d_get = cb.get("foo")
def on_err_common(*args):
print("Got an error: {0}".format(args)),
def on_set_ok(res):
print("Successfuly set key with CAS {0}".format(res.cas))
def on_get_ok(res):
print("Successfuly got key with value {0}".format(res.value))
d_set.addCallback(on_set_ok).addErrback(on_err_common)
d_get.addCallback(on_get_ok).addErrback(on_get_common)
# Note that it is safe to do this as operations performed on the
# same key are *always* performed in the order they were scheduled.
Using multiple items:
d_get = cb.get_multi(("Foo", "bar", "baz))
def on_mres(mres):
for k, v in mres.items():
print("Got result for key {0}: {1}".format(k, v.value))
d.addCallback(mres)
Returns a Deferred object which will have its callback invoked with a BatchedView when the results are complete.
Parameters follow conventions of query().
Example:
d = cb.queryAll("beer", "brewery_beers")
def on_all_rows(rows):
for row in rows:
print("Got row {0}".format(row))
d.addCallback(on_all_rows)
Query a view, with the viewcls instance receiving events of the query as they arrive.
| Parameters: | viewcls (type) – A class (derived from AsyncViewBase) to instantiate |
|---|
Other arguments are passed to the standard query method.
This functions exactly like the query() method, except it automatically schedules operations if the connection has not yet been negotiated.
Iterator/Container object for a single-call view result.
This functions as an iterator over all results of the query, once the query has been completed.
Additional metadata may be obtained by examining the object. See Views for more details.
You will normally not need to construct this object manually.