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 aproperty
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:- Use only the
*_multi
methods - Pass one of the
ItemCollection
objects to these methods. This will let the API know to enable special handling for theItem
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.
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
objectParameters: seq (An iterable or a single item) – A sequence containing the items