New in version 1.1.0.
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
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
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
Item objects may be created simply by calling the zero-arg constructor:
from couchbase_core.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
from couchbase_core.items import ItemOptionDict itmdict = ItemOptionDict() # Need to add the value: it.value = "some string" itmdict.add(it, format=couchbase_core.FMT_UTF8)
To actually store the item, you pass the collection to the
upsert_multi() method, and it will function as
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
New in version 1.1.0.
- class couchbase_core.items.Item(key=None, value=None)¶
Construct a new Item object.
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.
As the item build-in properties (such as
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
propertyor 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_core.client.ClientAPI methods, you must take care to:
Use only the
Convenience method to return an instance of a
ItemCollectioncontaining only this item. This would then be used like so:
Or use it with options:
kwargs – Extra operation-specific options.
- class couchbase_core.items.ItemCollection¶
The base class for a collection of Items.
- class couchbase_core.items.ItemOptionDict(d=None)¶
A simple mapping of
Itemobjects 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
d (dict) – A dictionary of item -> option, or None.
- add(itm, **options)¶
Convenience method to add an item together with a series of options.
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
dictinstead to update options
- create_and_add(key, value=None, cas=0, **options)¶
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
- property dict¶
Return the actual dict object