KV¶
The KV
class provides both high and low level access
to the Consul Key/Value service. To use the KV
class,
access the consulate.Consul.kv()
attribute of the
Session
class.
For high-level operation, the KV
class behaves
like a standard Python dict
. You can get, set, and delete items in
the Key/Value service just as you would with a normal dictionary.
If you need to have access to the full record associated with an item, there are
lower level methods such as KV.set_record
and KV.set_record
. These two methods
provide access to the other fields associated with the item in Consul, including
the flag
and various index related fields.
Examples of Use¶
Here’s a big blob of example code that uses most of the functionality in the
KV
class. Check the comments in the code to see what
part of the class it is demonstrating.
import consulate session = consulate.Session() # Set the key named release_flag to True session.kv['release_flag'] = True # Get the value for the release_flag, if not set, raises AttributeError try: should_release_feature = session.kv['release_flag'] except AttributeError: should_release_feature = False # Delete the release_flag key del session.kv['release_flag'] # Fetch how many rows are set in the KV store print(len(self.session.kv)) # Iterate over all keys in the kv store for key in session.kv: print('Key "{0}" set'.format(key)) # Iterate over all key/value pairs in the kv store for key, value in session.kv.iteritems(): print('{0}: {1}'.format(key, value)) # Iterate over all keys in the kv store for value in session.kv.values: print(value) # Find all keys that start with "fl" for key in session.kv.find('fl'): print('Key "{0}" found'.format(key)) # Check to see if a key called "foo" is set if "foo" in session.kv: print 'Already Set' # Return all of the items in the key/value store session.kv.items()
API¶
-
class
consulate.api.kv.
KV
(uri, adapter, datacenter=None, token=None)¶ The
consul.api.KV
class implements adict
like interface for working with the Key/Value service. Simply use items on theconsulate.Session
like you would with adict
toget
,set
, ordelete
values in the key/value store.Additionally,
KV
acts as aniterator
, providing methods to iterate overkeys
,values
,keys and values
, etc.Should you need access to get or set the flag value, the
get_record
,set_record
, andrecords
provide a way to access the additional fields exposed by the KV service.-
__contains__
(item)¶ Return True if there is a value set in the Key/Value service for the given key.
Parameters: item (str) – The key to check for Return type: bool
-
__getitem__
(item)¶ Get a value from the Key/Value service, returning it fully decoded if possible.
Parameters: item (str) – The item name Return type: mixed Raises: KeyError
-
__iter__
()¶ Iterate over all the keys in the Key/Value service
Return type: iterator
-
__len__
()¶ Return the number if items in the Key/Value service
Returns: int
-
__setitem__
(item, value)¶ Set a value in the Key/Value service, using the CAS mechanism to ensure that the set is atomic. If the value passed in is not a string, an attempt will be made to JSON encode the value prior to setting it.
Parameters: - item (str) – The key to set
- value (mixed) – The value to set
Raises: KeyError
-
acquire_lock
(item, session, value=None, cas=None, flags=None)¶ Use Consul for locking by specifying the item/key to lock with and a session value for removing the lock.
Parameters: Returns: bool
-
delete
(item, recurse=False)¶ Delete an item from the Key/Value service
Parameters: Raises: KeyError
-
find
(prefix, separator=None)¶ Find all keys with the specified prefix, returning a dict of matches.
Example:
>>> consul.kv.find('b') {'baz': 'qux', 'bar': 'baz'}
Parameters: prefix (str) – The prefix to search with Return type: dict
-
get
(item, default=None, raw=False)¶ Get a value from the Key/Value service, returning it fully decoded if possible.
Parameters: Return type: mixed
Raises: KeyError
-
get_record
(item)¶ Get the full record from the Key/Value service, returning all fields including the flag.
Parameters: item (str) – The item key Return type: dict Raises: KeyError
-
items
()¶ Return a dict of all of the key/value pairs in the Key/Value service
Example:
>>> consul.kv.items() {'foo': 'bar', 'bar': 'baz', 'quz': True, 'corgie': 'dog'}
Return type: dict
-
iteritems
()¶ Iterate over the dict of key/value pairs in the Key/Value service
Example:
>>> for key, value in consul.kv.iteritems(): ... print(key, value) ... (u'bar', 'baz') (u'foo', 'bar') (u'quz', True)
Return type: iterator
-
keys
()¶ Return a list of all of the keys in the Key/Value service
Example:
>>> consul.kv.keys() [u'bar', u'foo', u'quz']
Return type: list
-
records
(key=None)¶ Return a list of tuples for all of the records in the Key/Value service
Example:
>>> consul.kv.records() [(u'bar', 0, 'baz'), (u'corgie', 128, 'dog'), (u'foo', 0, 'bar'), (u'quz', 0, True)]
Return type: list of (Key, Flags, Value)
-
release_lock
(item, session)¶ Release an existing lock from the Consul KV database.
Parameters: Returns: bool
-
set
(item, value)¶ Set a value in the Key/Value service, using the CAS mechanism to ensure that the set is atomic. If the value passed in is not a string, an attempt will be made to JSON encode the value prior to setting it.
Parameters: - item (str) – The key to set
- value (mixed) – The value to set
Raises: KeyError
-