Client objects¶

class aioriak.client.RiakClient(host='localhost', port=8087, loop=None)[source]¶

The RiakClient object holds information necessary to connect to Riak. Requests can be made to Riak directly through the client or by using the methods on related objects.

resolver¶

The sibling-resolution function for this client. Defaults to riak.resolver.default_resolver().

Client-level Operations¶

Some operations are not scoped by buckets or bucket types and can be performed on the client directly:

coroutine RiakClient.ping()[source]¶

Check if the Riak server for this RiakClient instance is alive.

Return type:	boolean

coroutine RiakClient.get_buckets(bucket_type=None)[source]¶

Get the list of buckets as Bucket instances.

Warning

Do not use this in production, as it requires traversing through all keys stored in a cluster.

Parameters:	bucket_type (BucketType) – the optional containing bucket type
Return type:	list of Bucket instances

Accessing Bucket Types and Buckets¶

Most client operations are on bucket type objects, the bucket objects they contain or keys within those buckets. Use the bucket_type or bucket methods for creating bucket types and buckets that will proxy operations to the called client.

RiakClient.bucket_type(name)[source]¶

Gets the bucket-type by the specified name. Bucket-types do not always exist (unlike buckets), but this will always return a BucketType object.

Parameters:	name (str) – the bucket name
Return type:	BucketType

RiakClient.bucket(name, bucket_type='default')[source]¶

Get the bucket by the specified name. Since buckets always exist, this will always return a Bucket. If you are using a bucket that is contained in a bucket type, it is preferable to access it from the bucket type object:

# Preferred:
client.bucket_type("foo").bucket("bar")
# Equivalent, but not preferred:
client.bucket("bar", bucket_type="foo")

Parameters:	name (str) – the bucket name bucket_type (BucketType or str) – the parent bucket-type
Return type:	Bucket

Bucket Type Operations¶

coroutine RiakClient.get_bucket_type_props(bucket_type)[source]¶

Fetches properties for the given bucket-type.

Parameters:	bucket_type (BucketType) – the bucket-type whose properties will be fetched
Return type:	dict

coroutine RiakClient.set_bucket_type_props(bucket_type, props)[source]¶

Sets properties for the given bucket-type.

Parameters:	bucket_type (BucketType) – the bucket-type whose properties will be set props (dict) – the properties to set

Bucket Operations¶

coroutine RiakClient.get_bucket_props(bucket)[source]¶

Fetches bucket properties for the given bucket.

Parameters:	bucket (Bucket) – the bucket whose properties will be fetched
Return type:	dict

coroutine RiakClient.set_bucket_props(bucket, props)[source]¶

Sets bucket properties for the given bucket.

Parameters:	bucket (Bucket) – the bucket whose properties will be set props (dict) – the properties to set

coroutine RiakClient.get_keys(bucket)[source]¶

Lists all keys in a bucket.

Warning

Do not use this in production, as it requires traversing through all keys stored in a cluster.

Parameters:	bucket (Bucket) – the bucket whose keys are fetched
Return type:	list

Key-level Operations¶

coroutine RiakClient.get(robj)[source]¶

Fetches the contents of a Riak object.

Parameters:	robj (RiakObject) – the object to fetch

coroutine RiakClient.put(robj, return_body)[source]¶

Stores an object in the Riak cluster.

Parameters:	return_body (boolean) – whether to return the resulting object after the write robj (RiakObject) – the object to store

coroutine RiakClient.delete(robj)[source]¶

Deletes an object from Riak.

Parameters:	robj (RiakObject) – the object to delete

coroutine RiakClient.fetch_datatype(bucket, key)[source]¶

Fetches the value of a Riak Datatype.

Parameters:	bucket (Bucket) – the bucket of the datatype, which must belong to a BucketType key (string) – the key of the datatype
Return type:	Datatype

coroutine RiakClient.update_datatype(datatype, **params)[source]¶

Sends an update to a Riak Datatype to the server.

Parameters:	datatype (Datatype) – the datatype with pending updates
Return type:	tuple of datatype, opaque value and opaque context

Serialization¶

The client supports automatic transformation of Riak responses into Python types if encoders and decoders are registered for the media-types. Supported by default are application/json and text/plain.

aioriak.client.default_encoder(obj)[source]¶

Default encoder for JSON datatypes, which returns UTF-8 encoded json instead of the default bloated backslash u XXXX escaped ASCII strings.

RiakClient.get_encoder(content_type)[source]¶

Get the encoding function for the provided content type.

Parameters:	content_type (str) – the requested media type
Return type:	function

RiakClient.set_encoder(content_type, encoder)[source]¶

Set the encoding function for the provided content type.

Parameters:	content_type (str) – the requested media type encoder (function) – an encoding function, takes a single object argument and returns encoded data

RiakClient.get_decoder(content_type)[source]¶

Get the decoding function for the provided content type.

Parameters:	content_type (str) – the requested media type
Return type:	function

RiakClient.set_decoder(content_type, decoder)[source]¶

Set the decoding function for the provided content type.

Parameters:	content_type (str) – the requested media type decoder (function) – a decoding function, takes encoded data and returns a Python type

Bucket objects¶

class aioriak.bucket.Bucket(client, name, bucket_type)[source]¶

The Bucket object allows you to access and change information about a Riak bucket, and provides async methods to create or retrieve objects within the bucket.

__init__(client, name, bucket_type)[source]¶

Returns a new Bucket instance.

Parameters:	client (RiakClient) – A RiakClient instance name (string) – The bucket name bucket_type (BucketType) – The parent bucket type of this bucket

name¶

The name of the bucket, a string.

bucket_type¶

The parent BucketType for the bucket.

resolver¶

The sibling-resolution function for this bucket. If the resolver is not set, the client’s resolver will be used.

Bucket properties¶

Bucket properties are flags and defaults that apply to all keys in the bucket.

coroutine Bucket.get_properties()[source]¶

Retrieve a dict of all bucket properties.

Return type:	dict

coroutine Bucket.set_properties(props)[source]¶

Set multiple bucket properties in one call.

Parameters:	props (dict) – A dictionary of properties

coroutine Bucket.get_property(key)[source]¶

Retrieve a bucket property.

Parameters:	key (string) – The property to retrieve.
Return type:	mixed

coroutine Bucket.set_property(key, value)[source]¶

Set a bucket property.

Parameters:	key (string) – Property to set. value (mixed) – Property value.

Working with keys¶

The primary purpose of buckets is to act as namespaces for keys. As such, you can use the bucket object to create, fetch and delete objects.

coroutine Bucket.new(key=None, data=None, content_type='application/json', encoded_data=None)[source]¶

A shortcut for manually instantiating a new RiakObject or a new Datatype, based on the presence and value of the datatype bucket property. When the bucket contains a Datatype, all arguments are ignored except key, otherwise they are used to initialize the RiakObject.

Parameters:	key (str) – Name of the key. Leaving this to be None (default) will make Riak generate the key on store. data (object) – The data to store in a RiakObject, see RiakObject.data. content_type (str) – The media type of the data stored in the RiakObject, see RiakObject.content_type. encoded_data (str) – The encoded data to store in a RiakObject, see RiakObject.encoded_data.
Return type:	RiakObject or Datatype

coroutine Bucket.get(key)[source]¶

Retrieve an RiakObject or Datatype, based on the presence and value of the datatype bucket property.

Parameters:	key (string) – Name of the key.
Return type:	RiakObject or Datatype

coroutine Bucket.delete(key, **kwargs)[source]¶

Deletes a key from Riak. Short hand for bucket.new(key).delete(). See RiakClient.delete() for options.

Parameters:	key (string) – The key for the object
Return type:	RiakObject

Serialization¶

Similar to RiakClient, buckets can register custom transformation functions for media-types. When undefined on the bucket, Bucket.get_encoder() and Bucket.get_decoder() will delegate to the client associated with the bucket.

Bucket.get_encoder(content_type)[source]¶

Get the encoding function for the provided content type for this bucket.

Parameters:	content_type (str) – the requested media type content_type – Content type requested

Bucket.set_encoder(content_type, encoder)[source]¶

Set the encoding function for the provided content type for this bucket.

Parameters:	content_type (str) – the requested media type encoder (function) – an encoding function, takes a single object argument and returns a string data as single argument.

Bucket.get_decoder(content_type)[source]¶

Get the decoding function for the provided content type for this bucket.

Parameters:	content_type (str) – the requested media type
Return type:	function

Bucket.set_decoder(content_type, decoder)[source]¶

Set the decoding function for the provided content type for this bucket.

Parameters:	content_type (str) – the requested media type decoder (function) – a decoding function, takes a string and returns a Python type

Listing keys¶

Shortcuts for RiakClient.get_keys() are exposed on the bucket object. The same admonitions for these operation apply.

coroutine Bucket.get_keys()[source]¶

Return all keys within the bucket.

Return type:	list of keys

Bucket Type objects¶

class aioriak.bucket.BucketType(client, name)[source]¶

The BucketType object allows you to access and change properties on a Riak bucket type and access buckets within its namespace.

Async implementation of riak.bucket.BucketType

__init__(client, name)[source]¶

Returns a new BucketType instance.

Parameters:	client (RiakClient) – A RiakClient instance name (string) – The bucket-type’s name

name¶

The name of the Bucket Type, a string.

BucketType.is_default()[source]¶

Whether this bucket type is the default type, or a user-defined type.

Return type:	bool

BucketType.bucket(name)[source]¶

Gets a bucket that belongs to this bucket-type.

Parameters:	name (str) – the bucket name
Return type:	Bucket

Bucket Type properties¶

Bucket Type properties are flags and defaults that apply to all buckets in the Bucket Type.

coroutine BucketType.get_properties()[source]¶

Retrieve a dict of all bucket-type properties.

Return type:	dict

coroutine BucketType.set_properties(props)[source]¶

Set multiple bucket-type properties in one call.

Parameters:	props (dict) – A dictionary of properties

coroutine BucketType.get_property(key)[source]¶

Retrieve a bucket-type property.

Parameters:	key (string) – The property to retrieve.
Return type:	mixed

coroutine BucketType.set_property(key, value)[source]¶

Set a bucket-type property.

Parameters:	key (string) – Property to set. value (mixed) – Property value.

BucketType.datatype¶

The assigned datatype for this bucket type, if present.

Listing buckets¶

Shortcut for RiakClient.get_buckets() is exposed on the bucket type object. This is similar to Listing keys on buckets.

coroutine BucketType.get_buckets()[source]¶

Get the list of buckets under this bucket-type as Bucket instances.

Warning

Do not use this in production, as it requires traversing through all keys stored in a cluster.

Return type:	list of Bucket instances

RiakObject¶

class aioriak.riak_object.RiakObject(client, bucket, key=None)[source]¶

The RiakObject holds meta information about a Riak object, plus the object’s data.

key¶

The key of this object, a string. If not present, the server will generate a key the first time this object is stored.

bucket¶

The bucket to which this object belongs.

resolver¶

The sibling-resolution function for this object. If the resolver is not set, the bucket’s resolver will be used.

vclock¶

The Vector clock for this object.

exists¶

Whether the object exists. This is only False when there are no siblings (the object was not found), or the solitary sibling is a tombstone.

Persistence¶

Fetching, storing, and deleting keys are the bread-and-butter of Riak.

coroutine RiakObject.store(return_body=True)[source]¶

Store the object in Riak. When this operation completes, the object could contain new metadata and possibly new data if Riak contains a newer version of the object according to the object’s vector clock.

Parameters:	return_body (bool) – if the newly stored object should be retrieved
Return type:	RiakObject

coroutine RiakObject.reload()[source]¶

Reload the object from Riak. When this operation completes, the object could contain new metadata and a new value, if the object was updated in Riak since it was last retrieved.

Note

Even if the key is not found in Riak, this will return a RiakObject. Check the exists property to see if the key was found.

Return type:	RiakObject

coroutine RiakObject.delete()[source]¶

Delete this object from Riak.

Return type:	RiakObject

Value and Metadata¶

Unless you have enabled Siblings via the allow_mult bucket property, you can inspect and manipulate the value and metadata of an object directly using these properties and methods:

RiakObject.data¶

The data stored in this object, as Python objects. For the raw data, use the encoded_data property. If unset, accessing this property will result in decoding the encoded_data property into Python values. The decoding is dependent on the content_type property and the bucket’s registered decoders.

RiakObject.encoded_data¶

The raw data stored in this object, essentially the encoded form of the data property. If unset, accessing this property will result in encoding the data property into a string. The encoding is dependent on the content_type property and the bucket’s registered encoders.

RiakObject.content_type¶

The MIME media type of the encoded data as a string

RiakObject.charset¶

The character set of the encoded data as a string

RiakObject.content_encoding¶

The encoding (compression) of the encoded data. Valid values are identity, deflate, gzip

RiakObject.usermeta¶

Arbitrary user-defined metadata dict, mapping strings to strings.

RiakObject.links¶

A set of bucket/key/tag 3-tuples representing links to other keys.

RiakObject.indexes¶

The set of secondary index entries, consisting of index-name/value tuples

Siblings¶

Because Riak’s consistency model is “eventual” (and not linearizable), there is no way for it to disambiguate writes that happen concurrently. The Vector clock helps establish a “happens after” relationships so that concurrent writes can be detected, but with the exception of Data Types, Riak has no way to determine which write has the correct value.

Instead, when allow_mult is True, Riak keeps all writes that appear to be concurrent. Thus, the contents of a key’s value may, in fact, be multiple values, which are called “siblings”. Siblings are modeled in RiakContent objects, which contain all of the same Persistence methods and attributes as the parent object.

RiakObject.siblings = []¶

class aioriak.content.RiakContent(robject, data=None, encoded_data=None, charset=None, content_type='application/json', content_encoding=None, last_modified=None, etag=None, usermeta=None, links=None, indexes=None, exists=False)[source]¶

The RiakContent holds the metadata and value of a single sibling within a RiakObject. RiakObjects that have more than one sibling are considered to be in conflict.

You do not typically have to create RiakContent objects yourself, but they will be created for you when fetching objects from Riak.

Sending Operations¶

Riak Data Types provide a further departure from Riak’s usual operation, in that the API is operation-based. Rather than fetching the data structure, reconciling conflicts, mutating the result, and writing it back, you instead tell Riak what operations to perform on the Data Type. Here are some example operations:

• increment a Counter by 10
• add 'joe' to a Set
• remove the Set field called 'friends' from a Map
• enable the prepay Flag in a Map

Datatypes can be fetched and created just like RiakObject instances, using Bucket.get and Bucket.new, except that the bucket must belong to a bucket-type that has a valid datatype property. If we have a bucket-type named “social-graph” that has the datatype “set”, we would fetch a Set like so:

graph = client.bucket_type('social-graph')
graph.datatype  # => 'set'
backet = graph.bucket('followers')
myfollowers = await bucket.get('seancribbs')
# => a Set datatype

Once we have a datatype, we can stage operations against it and then send those operations to Riak:

myfollowers.add('javajolt')
myfollowers.discard('roach')
await myfollowers.update()

While this looks in code very similar to manipulating RiakObject instances, only mutations are enqueued locally, not the new value.

Context and Observed-Remove¶

In order for Riak Data Types to behave well, you must have an opaque context received from a read when you:

• disable a Flag (set it to false)
• remove a field from a Map
• remove an element from a Set

The basic rule is “you cannot remove something you haven’t seen”, and the context tells Riak what you’ve actually seen, similar to the Vector clock on RiakObject. The Python client handles opaque contexts for you transparently as long as you fetch before performing one of these actions.

Datatype abstract class¶

class aioriak.datatypes.Datatype(bucket=None, key=None, value=None, context=None)[source]¶

Base class for all convergent datatype wrappers. You will not use this class directly, but it does define some methods are common to all datatype wrappers.

value¶

The pure, immutable value of this datatype, as a Python value, which is unique for each datatype. NB: Do not use this property to mutate data, as it will not have any effect. Use the methods of the individual type to effect changes. This value is guaranteed to be independent of any internal data representation.

context¶

The opaque context for this type, if it was previously fetched.

Return type:	str

modified¶

Whether this datatype has staged local modifications.

Return type:	bool

Counter¶

class aioriak.datatypes.Counter(bucket=None, key=None, value=None, context=None)[source]¶

A convergent datatype that represents a counter which can be incremented or decremented. This type can stand on its own or be embedded within a Map.

Counter.value¶

The current value of the counter.

Counter.increment(amount=1)[source]¶

Increments the counter by one or the given amount.

Parameters:	amount (int) – the amount to increment the counter

Counter.decrement(amount=1)[source]¶

Decrements the counter by one or the given amount.

Parameters:	amount (int) – the amount to decrement the counter

Set¶

class aioriak.datatypes.Set(bucket=None, key=None, value=None, context=None)[source]¶

A convergent datatype representing a Set with observed-remove semantics. Currently strings are the only supported value type.

Example::

myset.add(‘barista’) myset.add(‘roaster’) myset.add(‘brewer’)

Likewise they can simply be removed::

myset.discard(‘barista’)

This datatype also implements the Set ABC, meaning it supports len(), in, and iteration.

Set.value¶

An immutable copy (frozenset) of the current value of the set.

Set.add(element)[source]¶

Adds an element to the set.

Parameters:	element (str) – the element to add

Set.discard(element)[source]¶

Removes an element from the set.

Parameters:	element (str) – the element to remove

Map¶

class aioriak.datatypes.Map(bucket=None, key=None, value=None, context=None)[source]¶

A convergent datatype that acts as a key-value datastructure. Keys are pairs of (name, datatype) where name is a string and datatype is the datatype name. Values are other convergent datatypes, represented by any concrete type in this module.

You cannot set values in the map directly (it does not implement __setitem__), but you may add new empty values or access non-existing values directly via bracket syntax. If a key is not in the original value of the map when accessed, fetching the key will cause its associated value to be created.:

map[('name', 'register')]

Keys and their associated values may be deleted from the map as you would in a dict:

del map[('emails', 'set')]

Convenience accessors exist that partition the map’s keys by datatype and implement the collections.Mapping behavior as well as supporting deletion:

map.sets['emails']
map.registers['name']
del map.counters['likes']

Map.value¶

Returns a copy of the original map’s value. Nested values are pure Python values as returned by Datatype.value from the nested types.

Return type:	dict

Map.counters¶

Filters keys in the map to only those of counter types. Example:

map.counters['views'].increment()
del map.counters['points']

Map.flags¶

Filters keys in the map to only those of flag types. Example:

map.flags['confirmed'].enable()
del map.flags['attending']

Map.maps¶

Filters keys in the map to only those of map types. Example:

map.maps['emails'].registers['home'].set("user@example.com")
del map.maps['spam']

Map.registers¶

Filters keys in the map to only those of register types. Example:

map.registers['username'].set_value("riak-user")
del map.registers['access_key']

Map.sets¶

Filters keys in the map to only those of set types. Example:

map.sets['friends'].add("brett")
del map.sets['favorites']

Map-only datatypes¶

Two of the new Data Types may only be embedded in Map objects (in addition to Map itself):

Register¶

class aioriak.datatypes.Register(bucket=None, key=None, value=None, context=None)[source]¶

A convergent datatype that represents an opaque string that is set with last-write-wins semantics, and may only be embedded in Map instances.

Register.value¶

Returns a copy of the original value of the register.

Return type:	str

Register.assign(new_value)[source]¶

Assigns a new value to the register.

Parameters:	new_value (str) – the new value for the register

Flag¶

class aioriak.datatypes.Flag(bucket=None, key=None, value=None, context=None)[source]¶

A convergent datatype that represents a boolean value that can be enabled or disabled, and may only be embedded in Map instances.

Flag.value¶

The current value of the flag.

Flag.enable()[source]¶

Turns the flag on, effectively setting its value to True.

Flag.disable()[source]¶

Turns the flag off, effectively setting its value to False.