Item Objects

New in version 1.1.0.

The Item class is a subclass of ValueResult. It differs from its parent in that it is instantiable by the user, and can also contain fields not originally defined in the superclass (i.e. it has a __dict__ field).

These objects may be passed (via either the couchbase.items.ItemOptionDict or couchbase.items.ItemSequence containers) to any of the _multi functions of the Bucket objects.

Since the Item structure is backwards-compatible (and therefore, interchangeable) with any of the key-value subtypes of the Result object, a new Result object is not created for each operation in the returned MultiResult dictionary.

This approach allows you to maintain a persistent object representing your data locally; periodically updating it from the Couchbase server.

Using the Item collections also allows per-item options for any of the _multi methods.

Creating Items

Item objects may be created simply by calling the zero-arg constructor:

from couchbase.items import Item
it = Item()

Before an Item object can be passed to any of the Bucket methods, it must have its key set. You can simply assign the key to the object’s key property:

it.key = "some_key"

In order to store the actual item, you should assign it a value, and place it inside one of the collections mentioned before. Here we’ll use the ItemOptionDict which can also contain per-item options:

from couchbase.items import ItemOptionDict
itmdict = ItemOptionDict()

# Need to add the value:
it.value = "some string"

itmdict.add(it, format=couchbase.FMT_UTF8)

To actually store the item, you pass the collection to the upsert_multi() method, and it will function as normally:

mres = cb.set_multi(itmdict)

mres is a MultiResult object. The value for each key will now contain the Item passed originally within the collection. The normal fields including cas, flags.

Class Reference

New in version 1.1.0.

class couchbase.items.Item(key=None, value=None)[source]

Construct a new Item object.

Parameters:
  • key (string) – The key to initialize this item with
  • value (object) – The value to initialize this item with

The Item class is a sublcass of a ValueResult. Its members are all writeable and accessible from this object.

Warning

As the item build-in properties (such as key, value, cas, etc.) are implemented directly in C and are not exposed in the item’s __dict__ field, you cannot override these fields in a subclass to be a property or some other custom data descriptor.

To confuse matters even more, if you do implement these properties as descriptors, they will be visible from your own code, but not from the implementation code. You have been warned.

In short, don’t override these properties.

Here’s an example of what you should not do:

class MyItem(Item):
    # ...
    @property
    def key(self):
        return self._key

    @key.setter
    def key(self, newkey):
        self._key = key

To use this class with the couchbase.bucket.Bucket API methods, you must take care to:

  1. Use only the *_multi methods
  2. Pass one of the ItemCollection objects to these methods. This will let the API know to enable special handling for the Item API.
as_itcoll(**kwargs)[source]

Convenience method to return an instance of a ItemCollection containing only this item. This would then be used like so:

cb.upsert_multi(itm.as_itcoll())

Or use it with options:

cb.upsert_multi(itm.as_itcoll(ignore_cas=True))
Parameters:kwargs – Extra operation-specific options.
Returns:An ItemCollection instance
class couchbase.items.ItemCollection[source]

The base class for a collection of Items.

class couchbase.items.ItemOptionDict(d=None)[source]

Bases: couchbase.items.ItemCollection

A simple mapping of Item objects to optional dictionaries of values.

The keys and values for the options dictionary depends on the command being used. See the appropriate command for more options

Parameters:d (dict) – A dictionary of item -> option, or None.
add(itm, **options)[source]

Convenience method to add an item together with a series of options.

Parameters:
  • itm – The item to add
  • options – keyword arguments which will be placed in the item’s option entry.

If the item already exists, it (and its options) will be overidden. Use dict instead to update options

create_and_add(key, value=None, cas=0, **options)[source]

Creates and adds an item. :param key: The key to use for the item :param value: The value to use for the item :param options: Additional operation-specific options

dict

Return the actual dict object

class couchbase.items.ItemSequence(obj)[source]

Bases: couchbase.items.ItemCollection

Create a new ItemSequence object

Parameters:seq (An iterable or a single item) – A sequence containing the items