Home

Welcome to the redisun-py wiki!

This project aims to make Redis munipulations easy, by using lua scripts to encapsulate Redis commands together.

Most of the lua scripts could deal with multiple keys.

First we need to make sure what the lua scripts should do before they manipulate keys.

Before calling a command that only support a certain data type, the script shoud check the key's type first. The command would execute only if the type is compatible with the command.

Then we need to make sure what the lua scripts should return

the key to manipulate
a code that indicates manipulation status (likes http status code), such as ok or error happened
the return value of the command if it is compatible with the key's type
the error message if encounter any unexpected error

At last, we need to make sure what the Python client should do

decode bytes to string
decode hash in format of list to dict
decode zset in format of list to dict
transform integer string returned by TTL, ZRANK to integer
transform float string returned by ZSCORE to float

Status codes

0 - Everything is OK
1 - Command not compatible with key's type
2 - Redis server error
3 - Existence not satisfied

How to query

Let's start with introducing QueryBuilder who takes the job to compose query keys for you.

QueryBuilder has three properties

all fields, ['user','id','score'] e.g.
dynamic fields, ['id'] e.g.
delimiter, ':' e.g.

Support two methods to bind value(s) with dynamic field

where(field, value)
where_in(field, values)

Take the example above to explain how to make query keys

where - bind single value to a dynamic field

Use where('id', 1) to make query key 'user:1:score'

where_in - bind multiple values to a dynamic fields

Use where_in('id', [1,2]) to make query keys 'user:1:score' and 'user:2:score'

QueryBuilder also supports multiple dynamic fields. For example

all fields: ['greeting', 'username', 'date']
dynamic fields: ['username', 'date']
delimiter: ':'

where('username', 'Alice').where_in('date', ['0901', '0902']) would produce two keys

greeting:Alice:0901
greeting:Alice:0902

where_in('username', ['Alice', 'Bob']).where_in('date', ['0901', '0902']) would produce four keys

greeting:Alice:0901
greeting:Alice:0902
greeting:Bob:0901
greeting:Bob:0902

Wrapped Redis commands

create

Create multiple keys with a value and modify the keys' ttl if wanted.

Default to keep current ttl.

Returns

ok keys - a list contains the keys create successfully
ok keys value - a dict holds the Redis command return of the ok keys
failed keys status - a dict holds the status codes of the failed keys
failed keys hint - a dict holds NOT OK messages returned by Redis after execute commands on keys

create_nx

Create only if the key not already exists.

Returns Same as create

create_xx

Create only if the key already exists.

Retuens same as create

first

Retrieve the first existed key among the query keys.

Returns None if existed key not found, else

key
value
ttl if wanted

last

Retrieve the last existed key among the query keys.

Returns Same as first

randone

Retrieve one randomly from the exsited keys.

Returns Same as first

all

Retrieve all existed keys among the query keys.

Returns Similar to create

getset_one

Get a key's current value and set it with a new value.

Returns

key
status code
value
error msg

getset_all

Get keys's current values and set them with a new value.