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 a dict like interface for working with the Key/Value service. Simply use items on the consulate.Session like you would with a dict to get, set, or delete values in the key/value store.

Additionally, KV acts as an iterator, providing methods to iterate over keys, values, keys and values, etc.

Should you need access to get or set the flag value, the get_record, set_record, and records 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
__delitem__(item)

Delete an item from the Key/Value service

Parameters:item (str) – The key name
__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:
  • item (str) – The item in the Consul KV database
  • session (str) – The session value for the lock
  • value (mixed) – An optional value to set for the lock
  • cas (int) – Optional Check-And-Set index value
  • flags (int) – User defined flags to set
Returns:

bool

delete(item, recurse=False)

Delete an item from the Key/Value service

Parameters:
  • item (str) – The item key
  • recurse (bool) – Remove keys prefixed with the item pattern
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:
  • item (str) – The item key
  • default (mixed) – A default value to return if the get fails
  • raw (bool) – Return the raw value from Consul
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:
  • item (str) – The item in the Consul KV database
  • session (str) – The session value for the lock
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

set_record(item, flags=0, value=None, replace=True)

Set a full record, including the item flag

Parameters:
  • item (str) – The key to set
  • value (mixed) – The value to set
  • replace – If True existing value will be overwritten:
values()

Return a list of all of the values in the Key/Value service

Example:

>>> consul.kv.values()
[True, 'bar', 'baz']
Return type:list