def rget(self, key, replica_index=None, quiet=None):
"""
Get a key from a replica
:param string key: The key to fetch
:param int replica_index: The replica index to fetch.
If this is ``None`` then this method will return once any replica
responds. Use :attr:`configured_replica_count` to figure out the
upper bound for this parameter.
The value for this parameter must be a number between 0 and the
value of :attr:`configured_replica_count`-1.
:param boolean quiet: Whether to suppress errors when the key is not
found
This function (if `replica_index` is not supplied) functions like
the :meth:`get` method that has been passed the `replica` parameter::
c.get(key, replica=True)
.. seealso::
:meth:`get` :meth:`rget_multi`
"""
if replica_index is not None:
return _Base._rgetix(self, key, replica=replica_index, quiet=quiet)
else:
return _Base._rget(self, key, quiet=quiet)
def rget(self, key, replica_index=None, quiet=None):
"""
Get a key from a replica
:param string key: The key to fetch
:param int replica_index: The replica index to fetch.
If this is ``None`` then this method will return once any replica
responds. Use :attr:`configured_replica_count` to figure out the
upper bound for this parameter.
The value for this parameter must be a number between 0 and the
value of :attr:`configured_replica_count`-1.
:param boolean quiet: Whether to suppress errors when the key is not
found
This function (if `replica_index` is not supplied) functions like
the :meth:`get` method that has been passed the `replica` parameter::
c.get(key, replica=True)
.. seealso::
:meth:`get` :meth:`rget_multi`
"""
if replica_index is not None:
return _Base._rgetix(self, key, replica=replica_index, quiet=quiet)
else:
return _Base._rget(self, key, quiet=quiet)
def endure_multi(self, keys, persist_to=-1, replicate_to=-1,
timeout=5.0,
interval=0.010,
check_removed=False):
"""
.. versionadded:: 1.1.0
Check durability requirements for multiple keys
:param keys: The keys to check
The type of keys may be one of the following:
* Sequence of keys
* A :class:`~couchbase.result.MultiResult` object
* A ``dict`` with CAS values as the dictionary value
* A sequence of :class:`~couchbase.result.Result` objects
:return: A :class:`~couchbase.result.MultiResult` object of
:class:`~couchbase.result.OperationResult` items.
.. seealso:: :meth:`endure`
"""
return _Base.endure_multi(self, keys, persist_to, replicate_to,
timeout=timeout,
interval=interval,
check_removed=check_removed)
def touch_multi(self, keys, ttl=0):
"""Touch multiple keys
Multi variant of :meth:`touch`
:param keys: the keys to touch
:type keys: :ref:`iterable<argtypes>`
``keys`` can also be a dictionary with values being integers, in
whic case the value for each key will be used as the TTL instead
of the global one (i.e. the one passed to this function)
:param int ttl: The new expiration time
:return: A :class:`~couchbase.libcouchbase.MultiResult` object
Update three keys to expire in 10 seconds ::
cb.touch_multi(("key1", "key2", "key3"), ttl=10)
Update three keys with different expiration times ::
cb.touch_multi({"foo" : 1, "bar" : 5, "baz" : 10})
.. seealso::
:meth:`touch`
"""
return _Base.touch_multi(self, keys, ttl=ttl)
def set(self, key, value, cas=0, ttl=0, format=None):
"""Unconditionally store the object in Couchbase.
:param key: The key to set the value with. By default, the key must be
either a :class:`bytes` or :class:`str` object encodable as UTF-8.
If a custom `transcoder` class is used (see :meth:`__init__`), then
the key object is passed directly to the transcoder, which may
serialize it how it wishes.
:type key: string or bytes
:param value: The value to set for the key. The type for `value`
follows the same rules as for `key`
:param int cas: The _CAS_ value to use. If supplied, the value will only
be stored if it already exists with the supplied CAS
:param int ttl: If specified, the key will expire after this many
seconds
:param int format: If specified, indicates the `format` to use when
encoding the value. If none is specified, it will use the
`default_format`
For more info see
:attr:`~couchbase.libcouchbase.Connection.default_format`
:raise: :exc:`couchbase.exceptions.ArgumentError` if an
argument is supplied that is not applicable in this context.
For example setting the CAS as a string.
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection closed
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the key
already exists on the server with a different CAS value.
:raise: :exc:`couchbase.exceptions.ValueFormatError` if the
value cannot be serialized with chosen encoder, e.g. if you
try to store a dictionaty in plain mode.
:return: :class:`~couchbase.libcouchbase.Result`
Simple set::
cb.set('key', 'value')
Force JSON document format for value::
cb.set('foo', {'bar': 'baz'}, format=couchbase.FMT_JSON)
Perform optimistic locking by specifying last known CAS version::
cb.set('foo', 'bar', cas=8835713818674332672)
Several sets at the same time (mutli-set)::
cb.set_multi({'foo': 'bar', 'baz': 'value'})
.. seealso::
:meth:`set_multi`
"""
return _Base.set(self, key, value, cas, ttl, format)
def append(self, key, value, cas=0, ttl=0, format=None):
"""
Append a string to an existing value in Couchbase.
This follows the same conventions as
:meth:`~couchbase.libcouchbase.Connection.set`.
The `format` argument must be one of :const:`~couchbase.FMT_UTF8` or
:const:`~couchbase.FMT_BYTES`. If not specified, it will be
:const:`~couchbase.FMT_UTF8`
(overriding the :attr:`default_format` attribute).
This is because JSON or Pickle formats will be nonsensical when
random data is appended to them. If you wish to modify a JSON or
Pickle encoded object, you will need to retrieve it (via :meth:`get`),
modify it, and then store it again (using :meth:`set`).
Additionally, you must ensure the value (and flags) for the current
value is compatible with the data to be appended. For an example,
you may append a :const:`~couchbase.FMT_BYTES` value to an existing
:const:`~couchbase.FMT_JSON` value, but an error will be thrown when
retrieving the value using
:meth:`get` (you may still use the :attr:`data_passthrough` to
overcome this).
:raise: :exc:`couchbase.exceptions.NotStoredError` if the key does
not exist
.. seealso::
:meth:`set`
:meth:`append_multi`
"""
return _Base.append(self, key, value, ttl=ttl, cas=cas, format=format)
def unlock_multi(self, keys):
"""Unlock multiple keys
Multi variant of :meth:`unlock`
:param dict keys: the keys to unlock
:return: a :class:`MultiResult` object
The value of the ``keys`` argument should be either the CAS, or a
previously returned :class:`Result` object from a :meth:`lock` call.
Effectively, this means you may pass a :class:`MultiResult` as the
``keys`` argument.
Thus, you can do something like ::
keys = (....)
rvs = cb.lock_multi(keys, ttl=5)
# do something with rvs
cb.unlock_multi(rvs)
.. seealso::
:meth:`unlock`
"""
return _Base.unlock_multi(self, keys)
def touch(self, key, ttl=0):
"""Update a key's expiration time
:param string key: The key whose expiration time should be modified
:param int ttl: The new expiration time. If the expiration time is ``0``
then the key never expires (and any existing expiration is removed)
:return: :class:`OperationResult`
Update the expiration time of a key ::
cb.set("key", ttl=100)
# expires in 100 seconds
cb.touch("key", ttl=0)
# key should never expire now
:raise: The same things that :meth:`get` does
.. seealso::
:meth:`get` - which can be used to get *and* update the expiration
:meth:`touch_multi`
"""
return _Base.touch(self, key, ttl=ttl)
def append(self, key, value, cas=0, ttl=0, format=None):
"""
Append a string to an existing value in Couchbase.
This follows the same conventions as
:meth:`~couchbase.connection.Connection.set`.
The `format` argument must be one of :const:`~couchbase.FMT_UTF8` or
:const:`~couchbase.FMT_BYTES`. If not specified, it will be
:const:`~couchbase.FMT_UTF8`
(overriding the :attr:`default_format` attribute).
This is because JSON or Pickle formats will be nonsensical when
random data is appended to them. If you wish to modify a JSON or
Pickle encoded object, you will need to retrieve it (via :meth:`get`),
modify it, and then store it again (using :meth:`set`).
Additionally, you must ensure the value (and flags) for the current
value is compatible with the data to be appended. For an example,
you may append a :const:`~couchbase.FMT_BYTES` value to an existing
:const:`~couchbase.FMT_JSON` value, but an error will be thrown when
retrieving the value using
:meth:`get` (you may still use the :attr:`data_passthrough` to
overcome this).
:raise: :exc:`couchbase.exceptions.NotStoredError` if the key does
not exist
.. seealso::
:meth:`set`, :meth:`append_multi`
"""
return _Base.append(self, key, value, ttl=ttl, cas=cas, format=format)
def unlock(self, key, cas):
"""Unlock a Locked Key in Couchbase.
:param key: The key to unlock
:param cas: The cas returned from
:meth:`lock`'s :class:`couchbase.result.Result` object.
Unlock a previously-locked key in Couchbase. A key is
locked by a call to :meth:`lock`.
See :meth:`lock` for an example.
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the CAS
supplied does not match the CAS on the server (possibly because
it was unlocked by previous call).
.. seealso::
:meth:`lock`
:meth:`unlock_multi`
"""
return _Base.unlock(self, key, cas=cas)
def set_multi(self, keys, ttl=0, format=None):
"""Set multiple keys
This follows the same semantics as
:meth:`~couchbase.connection.Connection.set`
:param dict keys: A dictionary of keys to set. The keys are the keys
as they should be on the server, and the values are the values for
the keys to be stored
:param int ttl: If specified, sets the expiration value for all
keys
:param int format:
If specified, this is the conversion format which will be used for
_all_ the keys.
:return: A :class:`~couchbase.result.MultiResult` object, which
is a `dict` subclass.
The multi methods are more than just a convenience, they also save on
network performance by batch-scheduling operations, reducing latencies.
This is especially noticeable on smaller value sizes.
.. seealso:: :meth:`set`
"""
return _Base.set_multi(self, keys, ttl=ttl, format=format)
def set(self, key, value, cas=0, ttl=0, format=None):
"""Unconditionally store the object in Couchbase.
:param key: The key to set the value with. By default, the key must be
either a :class:`bytes` or :class:`str` object encodable as UTF-8.
If a custom `transcoder` class is used (see :meth:`__init__`), then
the key object is passed directly to the transcoder, which may
serialize it how it wishes.
:type key: string or bytes
:param value: The value to set for the key. The type for `value`
follows the same rules as for `key`
:param int cas: The _CAS_ value to use. If supplied, the value will only
be stored if it already exists with the supplied CAS
:param int ttl: If specified, the key will expire after this many
seconds
:param int format: If specified, indicates the `format` to use when
encoding the value. If none is specified, it will use the
`default_format`
For more info see
:attr:`~couchbase.libcouchbase.Connection.default_format`
:raise: :exc:`couchbase.exceptions.ArgumentError` if an
argument is supplied that is not applicable in this context.
For example setting the CAS as a string.
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection closed
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the key
already exists on the server with a different CAS value.
:raise: :exc:`couchbase.exceptions.ValueFormatError` if the
value cannot be serialized with chosen encoder, e.g. if you
try to store a dictionaty in plain mode.
:return: :class:`~couchbase.libcouchbase.Result`
Simple set::
cb.set('key', 'value')
Force JSON document format for value::
cb.set('foo', {'bar': 'baz'}, format=couchbase.FMT_JSON)
Perform optimistic locking by specifying last known CAS version::
cb.set('foo', 'bar', cas=8835713818674332672)
Several sets at the same time (mutli-set)::
cb.set_multi({'foo': 'bar', 'baz': 'value'})
.. seealso::
:meth:`set_multi`
"""
return _Base.set(self, key, value, cas, ttl, format)
def set_multi(self, keys, ttl=0, format=None):
"""Set multiple keys
This follows the same semantics as
:meth:`~couchbase.libcouchbase.Connection.set`
:param dict keys: A dictionary of keys to set. The keys are the keys
as they should be on the server, and the values are the values for
the keys to be stored
:param int ttl: If specified, sets the expiration value for all
keys
:param int format:
If specified, this is the conversion format which will be used for
_all_ the keys.
:return: A :class:`~couchbase.libcouchbase.MultiResult` object, which
is a `dict` subclass.
The multi methods are more than just a convenience, they also save on
network performance by batch-scheduling operations, reducing latencies.
This is especially noticeable on smaller value sizes.
.. seealso::
:meth:`set`
"""
return _Base.set_multi(self, keys, ttl=ttl, format=format)
def get_multi(self,
keys,
ttl=0,
quiet=None,
replica=False,
no_format=False):
"""Get multiple keys
Multi variant of :meth:`get`
:param keys: keys the keys to fetch
:type keys: :ref:`iterable<argtypes>`
:param int ttl: Set the expiration for all keys when retrieving
:param boolean replica:
Whether the results should be obtained from a replica instead of the
master. See :meth:`get` for more information about this parameter.
:return: A :class:`~couchbase.result.MultiResult` object.
This object is a subclass of dict and contains the keys (passed as)
`keys` as the dictionary keys, and
:class:`~couchbase.result.Result` objects as values
"""
return _Base.get_multi(self,
keys,
ttl=ttl,
quiet=quiet,
replica=replica,
no_format=no_format)
def touch_multi(self, keys, ttl=0):
"""Touch multiple keys
Multi variant of :meth:`touch`
:param keys: the keys to touch
:type keys: :ref:`iterable<argtypes>`
``keys`` can also be a dictionary with values being integers, in
whic case the value for each key will be used as the TTL instead
of the global one (i.e. the one passed to this function)
:param int ttl: The new expiration time
:return: A :class:`~couchbase.result.MultiResult` object
Update three keys to expire in 10 seconds ::
cb.touch_multi(("key1", "key2", "key3"), ttl=10)
Update three keys with different expiration times ::
cb.touch_multi({"foo" : 1, "bar" : 5, "baz" : 10})
.. seealso:: :meth:`touch`
"""
return _Base.touch_multi(self, keys, ttl=ttl)
def unlock_multi(self, keys):
"""Unlock multiple keys
Multi variant of :meth:`unlock`
:param dict keys: the keys to unlock
:return: a :class:`~couchbase.result.MultiResult` object
The value of the ``keys`` argument should be either the CAS, or a
previously returned :class:`Result` object from a :meth:`lock` call.
Effectively, this means you may pass a
:class:`~couchbase.result.MultiResult` as the ``keys`` argument.
Thus, you can do something like ::
keys = (....)
rvs = cb.lock_multi(keys, ttl=5)
# do something with rvs
cb.unlock_multi(rvs)
.. seealso:: :meth:`unlock`
"""
return _Base.unlock_multi(self, keys)
def touch(self, key, ttl=0):
"""Update a key's expiration time
:param string key: The key whose expiration time should be modified
:param int ttl: The new expiration time. If the expiration time is ``0``
then the key never expires (and any existing expiration is removed)
:return: :class:`OperationResult`
Update the expiration time of a key ::
cb.set("key", ttl=100)
# expires in 100 seconds
cb.touch("key", ttl=0)
# key should never expire now
:raise: The same things that :meth:`get` does
.. seealso::
:meth:`get` - which can be used to get *and* update the expiration
:meth:`touch_multi`
"""
return _Base.touch(self, key, ttl=ttl)
def unlock(self, key, cas):
"""Unlock a Locked Key in Couchbase.
:param key: The key to unlock
:param cas: The cas returned from
:meth:`lock`'s :class:`Result` object.
Unlock a previously-locked key in Couchbase. A key is
locked by a call to :meth:`lock`.
See :meth:`lock` for an example.
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the CAS
supplied does not match the CAS on the server (possibly because
it was unlocked by previous call).
.. seealso::
:meth:`lock`
:meth:`unlock_multi`
"""
return _Base.unlock(self, key, cas=cas)
def delete(self, key, cas=0, quiet=None):
"""Remove the key-value entry for a given key in Couchbase.
:param key: A string which is the key to delete. The format and type
of the key follows the same conventions as in :meth:`set`
:type key: string, dict, or tuple/list
:param int cas: The CAS to use for the removal operation.
If specified, the key will only be deleted from the server if
it has the same CAS as specified. This is useful to delete a
key only if its value has not been changed from the version
currently visible to the client.
If the CAS on the server does not match the one specified,
an exception is thrown.
:param boolean quiet:
Follows the same semantics as `quiet` in :meth:`get`
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist on the bucket
:raise: :exc:`couchbase.exceptions.KeyExistsError` if a CAS
was specified, but the CAS on the server had changed
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection was closed
:return: A :class:`~couchbase.libcouchbase.Result` object.
Simple delete::
ok = cb.delete("key").success
Don't complain if key does not exist::
ok = cb.delete("key", quiet=True)
Only delete if CAS matches our version::
rv = cb.get("key")
cb.delete("key", cas=rv.cas)
Remove multiple keys::
oks = cb.delete_multi(["key1", "key2", "key3"])
Remove multiple keys with CAS::
oks = cb.delete({
"key1" : cas1,
"key2" : cas2,
"key3" : cas3
})
.. seealso::
:meth:`delete_multi`
"""
return _Base.delete(self, key, cas, quiet)
def delete(self, key, cas=0, quiet=None):
"""Remove the key-value entry for a given key in Couchbase.
:param key: A string which is the key to delete. The format and type
of the key follows the same conventions as in :meth:`set`
:type key: string, dict, or tuple/list
:param int cas: The CAS to use for the removal operation.
If specified, the key will only be deleted from the server if
it has the same CAS as specified. This is useful to delete a
key only if its value has not been changed from the version
currently visible to the client.
If the CAS on the server does not match the one specified,
an exception is thrown.
:param boolean quiet:
Follows the same semantics as `quiet` in :meth:`get`
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist on the bucket
:raise: :exc:`couchbase.exceptions.KeyExistsError` if a CAS
was specified, but the CAS on the server had changed
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection was closed
:return: A :class:`~couchbase.libcouchbase.Result` object.
Simple delete::
ok = cb.delete("key").success
Don't complain if key does not exist::
ok = cb.delete("key", quiet=True)
Only delete if CAS matches our version::
rv = cb.get("key")
cb.delete("key", cas=rv.cas)
Remove multiple keys::
oks = cb.delete_multi(["key1", "key2", "key3"])
Remove multiple keys with CAS::
oks = cb.delete({
"key1" : cas1,
"key2" : cas2,
"key3" : cas3
})
.. seealso::
:meth:`delete_multi`
"""
return _Base.delete(self, key, cas, quiet)
def prepend_multi(self, keys, ttl=0, format=None):
"""Prepend to multiple keys.
Multi variant of :meth:`prepend`
.. seealso:: :meth:`prepend`, :meth:`set_multi`, :meth:`set`
"""
return _Base.prepend_multi(self, keys, ttl=ttl, format=format)
def replace_multi(self, keys, ttl=0, format=None):
"""Replace multiple keys.
Multi variant of :meth:`replace`
.. seealso:: :meth:`replace`, :meth:`set_multi`, :meth:`set`
"""
return _Base.replace_multi(self, keys, ttl=ttl, format=format)
def replace_multi(self, keys, ttl=0, format=None):
"""Replace multiple keys.
Multi variant of :meth:`replace`
.. seealso:: :meth:`replace`, :meth:`set_multi`, :meth:`set`
"""
return _Base.replace_multi(self, keys, ttl=ttl, format=format)
def prepend_multi(self, keys, ttl=0, format=None):
"""Prepend to multiple keys.
Multi variant of :meth:`prepend`
.. seealso:: :meth:`prepend`, :meth:`set_multi`, :meth:`set`
"""
return _Base.prepend_multi(self, keys, ttl=ttl, format=format)
def add_multi(self, keys, ttl=0, format=None):
"""Add multiple keys.
Multi variant of :meth:`~couchbase.connection.Connection.add`
.. seealso:: :meth:`add`, :meth:`set_multi`, :meth:`set`
"""
return _Base.add_multi(self, keys, ttl=ttl, format=format)
def add_multi(self, keys, ttl=0, format=None):
"""Add multiple keys.
Multi variant of :meth:`~couchbase.connection.Connection.add`
.. seealso:: :meth:`add`, :meth:`set_multi`, :meth:`set`
"""
return _Base.add_multi(self, keys, ttl=ttl, format=format)
def get(self, key, ttl=0, quiet=None):
"""Obtain an object stored in Couchbase by given key.
:param string key: The key to fetch. The type of key is the same
as mentioned in :meth:`set`
:param int ttl:
If specified, indicates that the key's expiration time should be
*modified* when retrieving the value.
:param boolean quiet: causes `get` to return None instead of
raising an exception when the key is not found. It defaults
to the value set by
:attr:`~couchbase.libcouchbase.Connection.quiet` on the instance.
In `quiet` mode, the error may still be obtained by inspecting
the :attr:`~couchbase.libcouchbase.Result.rc` attribute of the
:class:`Result` object, or checking :attr:`Result.success`.
Note that the default value is `None`, which means to use
the :attr:`quiet`. If it is a boolean (i.e. `True` or `False) it will
override the `Connection`-level `quiet` attribute.
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
is missing in the bucket
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection closed
:raise: :exc:`couchbase.exceptions.ValueFormatError` if the
value cannot be deserialized with chosen decoder, e.g. if you
try to retreive an object stored with an unrecognized format
:return: A :class:`~couchbase.libcouchbase.Result` object
Simple get::
value = cb.get('key').value
Get multiple values::
cb.get_multi(['foo', 'bar'])
# { 'foo' : <Result(...)>, 'bar' : <Result(...)> }
Inspect the flags::
rv = cb.get("key")
value, flags, cas = rv.value, rv.flags, rv.cas
Update the expiration time::
rv = cb.get("key", ttl=10)
# Expires in ten seconds
.. seealso::
:meth:`get_multi`
"""
return _Base.get(self, key, ttl, quiet)
def get(self, key, ttl=0, quiet=None):
"""Obtain an object stored in Couchbase by given key.
:param string key: The key to fetch. The type of key is the same
as mentioned in :meth:`set`
:param int ttl:
If specified, indicates that the key's expiration time should be
*modified* when retrieving the value.
:param boolean quiet: causes `get` to return None instead of
raising an exception when the key is not found. It defaults
to the value set by
:attr:`~couchbase.libcouchbase.Connection.quiet` on the instance.
In `quiet` mode, the error may still be obtained by inspecting
the :attr:`~couchbase.libcouchbase.Result.rc` attribute of the
:class:`Result` object, or checking :attr:`Result.success`.
Note that the default value is `None`, which means to use
the :attr:`quiet`. If it is a boolean (i.e. `True` or `False) it will
override the `Connection`-level `quiet` attribute.
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
is missing in the bucket
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection closed
:raise: :exc:`couchbase.exceptions.ValueFormatError` if the
value cannot be deserialized with chosen decoder, e.g. if you
try to retreive an object stored with an unrecognized format
:return: A :class:`~couchbase.libcouchbase.Result` object
Simple get::
value = cb.get('key').value
Get multiple values::
cb.get_multi(['foo', 'bar'])
# { 'foo' : <Result(...)>, 'bar' : <Result(...)> }
Inspect the flags::
rv = cb.get("key")
value, flags, cas = rv.value, rv.flags, rv.cas
Update the expiration time::
rv = cb.get("key", ttl=10)
# Expires in ten seconds
.. seealso::
:meth:`get_multi`
"""
return _Base.get(self, key, ttl, quiet)
def prepend(self, key, value, cas=0, ttl=0, format=None):
"""
Prepend a string to an existing value in Couchbase.
.. seealso::
:meth:`append`, :meth:`prepend_multi`
"""
return _Base.prepend(self, key, value, ttl=ttl, cas=cas, format=format)
def add_multi(self, keys, ttl=0, format=None, persist_to=0, replicate_to=0):
"""Add multiple keys.
Multi variant of :meth:`~couchbase.connection.Connection.add`
.. seealso:: :meth:`add`, :meth:`set_multi`, :meth:`set`
"""
return _Base.add_multi(self, keys, ttl=ttl, format=format,
persist_to=persist_to, replicate_to=replicate_to)
def decr(self, key, amount=1, initial=None, ttl=0):
"""
Like :meth:`incr`, but decreases, rather than increaes the
counter value
.. seealso:: :meth:`incr`, :meth:`decr_multi`
"""
return _Base.decr(self, key, amount, initial, ttl)
def prepend(self, key, value, cas=0, ttl=0, format=None):
"""
Prepend a string to an existing value in Couchbase.
.. seealso::
:meth:`append`, :meth:`prepend_multi`
"""
return _Base.prepend(self, key, value, ttl=ttl, cas=cas, format=format)
def decr(self, key, amount=1, initial=None, ttl=0):
"""
Like :meth:`incr`, but decreases, rather than increaes the
counter value
.. seealso:: :meth:`incr`, :meth:`decr_multi`
"""
return _Base.decr(self, key, amount, initial, ttl)
def incr(self, key, amount=1, initial=None, ttl=0):
"""
Increment the numeric value of a key.
:param string key: A key whose counter value is to be incremented
:param int amount: an amount by which the key should be
incremented
:param initial: The initial value for the key, if it does not
exist. If the key does not exist, this value is used, and
`amount` is ignored. If this parameter is `None` then no
initial value is used
:type initial: int or `None`
:param int ttl: The lifetime for the key, after which it will
expire
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist on the bucket (and `initial` was `None`)
:raise: :exc:`couchbase.exceptions.DeltaBadvalError` if the key
exists, but the existing value is not numeric
:return:
A :class:`couchbase.libcouchbase.Result` object. The current value
of the counter may be obtained by inspecting the return value's
`value` attribute.
Simple increment::
rv = cb.incr("key")
rv.value
# 42
Increment by 10::
ok = cb.incr("key", amount=10)
Increment by 20, set initial value to 5 if it does not exist::
ok = cb.incr("key", amount=20, initial=5)
Increment three keys::
kv = cb.incr_multi(["foo", "bar", "baz"])
for key, result in kv.items():
print "Key %s has value %d now" % (key, result.value)
.. seealso::
:meth:`decr`
:meth:`incr_multi`
"""
return _Base.incr(self, key, amount, initial, ttl)
def incr(self, key, amount=1, initial=None, ttl=0):
"""
Increment the numeric value of a key.
:param string key: A key whose counter value is to be incremented
:param int amount: an amount by which the key should be
incremented
:param initial: The initial value for the key, if it does not
exist. If the key does not exist, this value is used, and
`amount` is ignored. If this parameter is `None` then no
initial value is used
:type initial: int or `None`
:param int ttl: The lifetime for the key, after which it will
expire
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist on the bucket (and `initial` was `None`)
:raise: :exc:`couchbase.exceptions.DeltaBadvalError` if the key
exists, but the existing value is not numeric
:return:
A :class:`couchbase.libcouchbase.Result` object. The current value
of the counter may be obtained by inspecting the return value's
`value` attribute.
Simple increment::
rv = cb.incr("key")
rv.value
# 42
Increment by 10::
ok = cb.incr("key", amount=10)
Increment by 20, set initial value to 5 if it does not exist::
ok = cb.incr("key", amount=20, initial=5)
Increment three keys::
kv = cb.incr_multi(["foo", "bar", "baz"])
for key, result in kv.items():
print "Key %s has value %d now" % (key, result.value)
.. seealso::
:meth:`decr`
:meth:`incr_multi`
"""
return _Base.incr(self, key, amount, initial, ttl)
def replace_multi(self, keys, ttl=0, format=None,
persist_to=0, replicate_to=0):
"""Replace multiple keys.
Multi variant of :meth:`replace`
.. seealso:: :meth:`replace`, :meth:`set_multi`, :meth:`set`
"""
return _Base.replace_multi(self, keys, ttl=ttl, format=format,
persist_to=persist_to,
replicate_to=replicate_to)
def prepend_multi(self, keys, ttl=0, format=None,
persist_to=0, replicate_to=0):
"""Prepend to multiple keys.
Multi variant of :meth:`prepend`
.. seealso:: :meth:`prepend`, :meth:`set_multi`, :meth:`set`
"""
return _Base.prepend_multi(self, keys, ttl=ttl, format=format,
persist_to=persist_to,
replicate_to=replicate_to)
def append_multi(self, keys, ttl=0, format=None):
"""Append to multiple keys.
Multi variant of :meth:`append`
.. seealso::
:meth:`append`
:meth:`set_multi`
:meth:`set`
"""
return _Base.append_multi(self, keys, ttl=ttl, format=format)
def append_multi(self, keys, ttl=0, format=None):
"""Append to multiple keys.
Multi variant of :meth:`append`
.. seealso::
:meth:`append`
:meth:`set_multi`
:meth:`set`
"""
return _Base.append_multi(self, keys, ttl=ttl, format=format)
def lock_multi(self, keys, ttl=0):
"""Lock multiple keys
Multi variant of :meth:`lock`
:param keys: the keys to lock
:type keys: :ref:`iterable<argtypes>`
:param int ttl: The lock timeout for all keys
:return: a :class:`~couchbase.result.MultiResult` object
.. seealso:: :meth:`lock`
"""
return _Base.lock_multi(self, keys, ttl=ttl)
def lock_multi(self, keys, ttl=0):
"""Lock multiple keys
Multi variant of :meth:`lock`
:param keys: the keys to lock
:type keys: :ref:`iterable<argtypes>`
:param int ttl: The lock timeout for all keys
:return: a :class:`~couchbase.result.MultiResult` object
.. seealso:: :meth:`lock`
"""
return _Base.lock_multi(self, keys, ttl=ttl)
def replace(self, key, value, cas=0, ttl=0, format=None):
"""
Store an object in Couchbase only if it already exists.
Follows the same conventions as
:meth:`~couchbase.connection.Connection.set`, but the value is
stored only if a previous value already exists.
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist
.. seealso:: :meth:`set`, :meth:`replace_multi`
"""
return _Base.replace(self, key, value, ttl=ttl, cas=cas, format=format)
def replace(self, key, value, cas=0, ttl=0, format=None):
"""
Store an object in Couchbase only if it already exists.
Follows the same conventions as
:meth:`~couchbase.connection.Connection.set`, but the value is
stored only if a previous value already exists.
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
does not exist
.. seealso:: :meth:`set`, :meth:`replace_multi`
"""
return _Base.replace(self, key, value, ttl=ttl, cas=cas, format=format)
def get_multi(self, keys, ttl=0, quiet=None):
"""Get multiple keys
Multi variant of :meth:`get`
:param keys: keys the keys to fetch
:type keys: :ref:`iterable<argtypes>`
:param int ttl: Set the expiration for all keys when retrieving
:return: A `~couchbase.libcouchbase.MultiResult` object.
This object is a subclass of dict and contains the keys (passed as)
`keys` as the dictionary keys, and
:class:`~couchbase.libcouchbase.Result` objects as values
"""
return _Base.get_multi(self, keys, ttl=ttl, quiet=quiet)
def get_multi(self, keys, ttl=0, quiet=None):
"""Get multiple keys
Multi variant of :meth:`get`
:param keys: keys the keys to fetch
:type keys: :ref:`iterable<argtypes>`
:param int ttl: Set the expiration for all keys when retrieving
:return: A `~couchbase.libcouchbase.MultiResult` object.
This object is a subclass of dict and contains the keys (passed as)
`keys` as the dictionary keys, and
:class:`~couchbase.libcouchbase.Result` objects as values
"""
return _Base.get_multi(self, keys, ttl=ttl, quiet=quiet)
def set_multi(self, keys, ttl=0, format=None, persist_to=0, replicate_to=0):
"""Set multiple keys
This follows the same semantics as
:meth:`~couchbase.connection.Connection.set`
:param dict keys: A dictionary of keys to set. The keys are the keys
as they should be on the server, and the values are the values for
the keys to be stored.
From version 1.1.0, `keys` may also be a
:class:`~couchbase.items.ItemCollection`. If using a dictionary
variant for item collections, an additional `ignore_cas` parameter
may be supplied with a boolean value. If not specified, the operation
will fail if the CAS value on the server does not match the one
specified in the `Item`'s `cas` field.
:param int ttl: If specified, sets the expiration value for all
keys
:param int format:
If specified, this is the conversion format which will be used for
_all_ the keys.
:param int persist_to: Durability constraint for persistence.
Note that it is more efficient to use :meth:`endure_multi`
on the returned :class:`~couchbase.result.MultiResult` than
using these parameters for a high volume of keys. Using these
parameters however does save on latency as the constraint checking
for each item is performed as soon as it is successfully stored.
:param int replicate_to: Durability constraints for replication.
See notes on the `persist_to` parameter for usage.
:return: A :class:`~couchbase.result.MultiResult` object, which
is a `dict` subclass.
The multi methods are more than just a convenience, they also save on
network performance by batch-scheduling operations, reducing latencies.
This is especially noticeable on smaller value sizes.
.. seealso:: :meth:`set`
"""
return _Base.set_multi(self, keys, ttl=ttl, format=format,
persist_to=persist_to, replicate_to=replicate_to)
def append_multi(self, keys, ttl=0, format=None,
persist_to=0, replicate_to=0):
"""Append to multiple keys.
Multi variant of :meth:`append`.
.. warning::
If using the `Item` interface, use the :meth:`append_items`
and :meth:`prepend_items` instead, as those will automatically
update the :attr:`couchbase.items.Item.value` property upon
successful completion.
.. seealso:: :meth:`append`, :meth:`set_multi`, :meth:`set`
"""
return _Base.append_multi(self, keys, ttl=ttl, format=format,
persist_to=persist_to,
replicate_to=replicate_to)
def add(self, key, value, ttl=0, format=None):
"""
Store an object in Couchbase unless it already exists.
Follows the same conventions as
:meth:`~couchbase.connection.Connection.set` but the value is
stored only if it does not exist already. Conversely, the value
is not stored if the key already exists.
Notably missing from this method is the `cas` parameter, this is
because `add` will only succeed if a key does not already exist
on the server (and thus can have no CAS)
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the key
already exists
.. seealso:: :meth:`set`, :meth:`add_multi`
"""
return _Base.add(self, key, value, ttl=ttl, format=format)
def get_multi(self, keys, ttl=0, quiet=None, replica=False, no_format=False):
"""Get multiple keys
Multi variant of :meth:`get`
:param keys: keys the keys to fetch
:type keys: :ref:`iterable<argtypes>`
:param int ttl: Set the expiration for all keys when retrieving
:param boolean replica:
Whether the results should be obtained from a replica instead of the
master. See :meth:`get` for more information about this parameter.
:return: A :class:`~couchbase.result.MultiResult` object.
This object is a subclass of dict and contains the keys (passed as)
`keys` as the dictionary keys, and
:class:`~couchbase.result.Result` objects as values
"""
return _Base.get_multi(self, keys, ttl=ttl, quiet=quiet, replica=replica, no_format=no_format)
def add(self, key, value, ttl=0, format=None):
"""
Store an object in Couchbase unless it already exists.
Follows the same conventions as
:meth:`~couchbase.connection.Connection.set` but the value is
stored only if it does not exist already. Conversely, the value
is not stored if the key already exists.
Notably missing from this method is the `cas` parameter, this is
because `add` will only succeed if a key does not already exist
on the server (and thus can have no CAS)
:raise: :exc:`couchbase.exceptions.KeyExistsError` if the key
already exists
.. seealso:: :meth:`set`, :meth:`add_multi`
"""
return _Base.add(self, key, value, ttl=ttl, format=format)
def observe(self, key):
"""
Return storage information for a key.
The ``observe`` function maps to the low-level ``OBSERVE``
command.
It returns a :class:`couchbase.result.ValueResult`
object with the ``value`` field
set to a list of :class:`~couchbase.result.ObserveInfo`
objects. Each element in the list
responds to the storage status for the key on the given node. The
length of the list (and thus the number of
:class:`~couchbase.result.ObserveInfo` objects)
are equal to the number of online replicas plus the master for the
given key.
:param string key: The key to inspect
.. seealso:: :ref:`observe_info`
"""
return _Base.observe(self, key)
def observe(self, key):
"""
Return storage information for a key.
The ``observe`` function maps to the low-level ``OBSERVE``
command.
It returns a :class:`couchbase.result.ValueResult`
object with the ``value`` field
set to a list of :class:`~couchbase.result.ObserveInfo`
objects. Each element in the list
responds to the storage status for the key on the given node. The
length of the list (and thus the number of
:class:`~couchbase.result.ObserveInfo` objects)
are equal to the number of online replicas plus the master for the
given key.
:param string key: The key to inspect
.. seealso:: :ref:`observe_info`
"""
return _Base.observe(self, key)
def get(self, key, ttl=0, quiet=None, replica=False, no_format=False):
"""Obtain an object stored in Couchbase by given key.
:param string key: The key to fetch. The type of key is the same
as mentioned in :meth:`set`
:param int ttl:
If specified, indicates that the key's expiration time should be
*modified* when retrieving the value.
:param boolean quiet: causes `get` to return None instead of
raising an exception when the key is not found. It defaults
to the value set by
:attr:`~couchbase.connection.Connection.quiet` on the instance.
In `quiet` mode, the error may still be obtained by inspecting
the :attr:`~couchbase.result.Result.rc` attribute of the
:class:`couchbase.result.Result` object, or
checking :attr:`couchbase.result.Result.success`.
Note that the default value is `None`, which means to use
the :attr:`quiet`. If it is a boolean (i.e. `True` or `False) it will
override the :class:`Connection`-level :attr:`quiet` attribute.
:param bool replica: Whether to fetch this key from a replica
rather than querying the master server. This is primarily useful
when operations with the master fail (possibly due to a configuration
change). It should normally be used in an exception handler like so
Using the ``replica`` option::
try:
res = c.get("key", quiet=True) # suppress not-found errors
catch CouchbaseError:
res = c.get("key", replica=True, quiet=True)
:param bool no_format:
.. versionadded:: 1.1.0
If set to ``True``, then the value will always be
delivered in the :class:`~couchbase.result.Result` object as being of
:data:`~couchbase.FMT_BYTES`. This is a item-local equivalent of using
the :attr:`data_passthrough` option
:raise: :exc:`couchbase.exceptions.NotFoundError` if the key
is missing in the bucket
:raise: :exc:`couchbase.exceptions.ConnectError` if the
connection closed
:raise: :exc:`couchbase.exceptions.ValueFormatError` if the
value cannot be deserialized with chosen decoder, e.g. if you
try to retreive an object stored with an unrecognized format
:return: A :class:`~couchbase.result.Result` object
Simple get::
value = cb.get('key').value
Get multiple values::
cb.get_multi(['foo', 'bar'])
# { 'foo' : <Result(...)>, 'bar' : <Result(...)> }
Inspect the flags::
rv = cb.get("key")
value, flags, cas = rv.value, rv.flags, rv.cas
Update the expiration time::
rv = cb.get("key", ttl=10)
# Expires in ten seconds
.. seealso::
:meth:`get_multi`
"""
return _Base.get(self, key, ttl, quiet, replica, no_format)
def lock(self, key, ttl=0):
"""Lock and retrieve a key-value entry in Couchbase.
:param key: A string which is the key to lock.
:param int: a TTL for which the lock should be valid. If set to
`0` it will use the default lock timeout on the server.
While the lock is active, attempts to access the key (via
other :meth:`lock`, :meth:`set` or other mutation calls) will
fail with an :exc:`couchbase.exceptions.TemporaryFailError`
This function otherwise functions similarly to :meth:`get`;
specifically, it will return the value upon success.
Note the :attr:`~couchbase.result.Result.cas` value from the
:class:`couchbase.result.Result`
object. This will be needed to :meth:`unlock` the key.
Note the lock will also be implicitly released if modified by one
of the :meth:`set` family of functions when the valid CAS is
supplied
:raise: :exc:`couchbase.exceptions.TemporaryFailError` if the key
was already locked.
:raise: See :meth:`get` for possible exceptions
Lock a key ::
rv = cb.lock("locked_key", ttl=100)
# This key is now locked for the next 100 seconds.
# attempts to access this key will fail until the lock
# is released.
# do important stuff...
cb.unlock("locked_key", rv.cas)
Lock a key, implicitly unlocking with :meth:`set` with CAS ::
rv = self.cb.lock("locked_key", ttl=100)
new_value = rv.value.upper()
cb.set("locked_key", new_value, rv.cas)
Poll and Lock ::
rv = None
begin_time = time.time()
while time.time() - begin_time < 15:
try:
rv = cb.lock("key")
except TemporaryFailError:
print("Key is currently locked.. waiting")
time.sleep(0)
if not rv:
raise Exception("Waited too long..")
# Do stuff..
cb.unlock("key", rv.cas)
.. seealso::
:meth:`get`, :meth:`lock_multi`, :meth:`unlock`
"""
return _Base.lock(self, key, ttl=ttl)
def lock(self, key, ttl=0):
"""Lock and retrieve a key-value entry in Couchbase.
:param key: A string which is the key to lock.
:param int: a TTL for which the lock should be valid. If set to
`0` it will use the default lock timeout on the server.
While the lock is active, attempts to access the key (via
other :meth:`lock`, :meth:`set` or other mutation calls) will
fail with an :exc:`couchbase.exceptions.TemporaryFailError`
This function otherwise functions similarly to :meth:`get`;
specifically, it will return the value upon success.
Note the :attr:`~Result.cas` value from the :class:`Result`
object. This will be needed to :meth:`unlock` the key.
Note the lock will also be implicitly released if modified by one
of the :meth:`set` family of functions when the valid CAS is
supplied
:raise: :exc:`couchbase.exceptions.TemporaryFailError` if the key
was already locked.
:raise: See :meth:`get` for possible exceptions
Lock a key ::
rv = cb.lock("locked_key", ttl=100)
# This key is now locked for the next 100 seconds.
# attempts to access this key will fail until the lock
# is released.
# do important stuff...
cb.unlock("locked_key", rv.cas)
Lock a key, implicitly unlocking with :meth:`set` with CAS ::
rv = self.cb.lock("locked_key", ttl=100)
new_value = rv.value.upper()
cb.set("locked_key", new_value, rv.cas)
Poll and Lock ::
rv = None
begin_time = time.time()
while time.time() - begin_time < 15:
try:
rv = cb.lock("key")
except TemporaryFailError:
print("Key is currently locked.. waiting")
time.sleep(0)
if not rv:
raise Exception("Waited too long..")
# Do stuff..
cb.unlock("key", rv.cas)
.. seealso::
:meth:`get`
:meth:`lock_multi`
:meth:`unlock`
"""
return _Base.lock(self, key, ttl=ttl)
def observe_multi(self, keys):
"""
Multi-variant of :meth:`observe`
"""
return _Base.observe_multi(self, keys)
