picoredis 0.1.0

What is does

• Support the REdis Serialization Protocol (RESP).

• Connect to a Redis server via TCP.

• Send Redis commands and receive and parse the response in a simple, blocking fashion.

• Support MicroPython (unix and bare-metal ports with usocket and uselect module), CPython and PyPy (3.4+, 2.7+ untested).

What it does not

• Parse the response beyond de-serialization of the basic RESP types (simple string, error, bulk string, integer and array).

• Decode response byte strings, except error messages.

• Support the subscribe / publish protocol.

• Support SSL / TLS (yet).

• Async I/O.

Connection

When you create a Redis instance, it immediatly tries to open a connecting to the Redis server. The default host and port are 127.0.0.1 and 6379 respectively.

You can set the host name or IP address and port number of the Redis server to connect with the host and port keyword arguments:

>>> redis = Redis('192.168.1.100')
>>> redis = Redis(port=6380)
>>> redis = Redis('192.168.1.100', 6380)
>>> redis = Redis(server='192.168.1.100')
>>> redis = Redis(server='192.168.1.100', port=6380)

You can set the TCP socket timeout with the timeout keyword argument in milliseconds (default 3000):

>>> redis = Redis(timeout=10000)

If a response is read from the server and the server doesn’t return any data within the timeout, a RedisTimeout exception is raised.

To close the connection to the server, use the close() method:

>>> redis.close()
>>> redis.ping()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "picoredis.py", line 89, in <lambda>
  File "picoredis.py", line 75, in do_cmd
RedisError: Not connected: use 'connect()' to connect to Redis server.

To open a new connection again, use the connect method. You can pass a different host name and / or port number and they will overwrite the ones given when the instance was created:

>>> redis.connect('redis.myserver.com')
>>> redis._host
'redis.myserver.com'

Debug Output

To turn on printing of raw messages sent to and received from the Redis server pass debug=True when creating the instance or set its debug attribute to True:

>>> redis = Redis(debug=True)
>>> redis.hkeys('myhash')
SEND: '*2\r\n$5\r\nhkeys\r\n$6\r\nmyhash\r\n'
RECV: b'*1\r\n'
RECV: b'$4\r\n'
RECV: b'key1\r\n'
[b'key1']

Tips

If you need to further parse the response to a Redis command regularly, just add a wrapper method in a sub-class. For example, here is how to get the list of commands supported by the Redis server as a list of strings:

>>> class MyRedis(Redis):
...     def command_list(self):
...         return sorted([cmd[0].decode('utf-8')
...                        for cmd in self.do_cmd('command')])
>>> redis = MyRedis()
>>> redis.command_list()
['append', 'asking', 'auth', 'bgrewriteaof', 'bgsave', 'bitcount', 'bitfield',
 ..., 'zunionstore']

Warning: The response to this command sent be the Redis server will be fairly big and probably cause a MemoryError, when you run it on a memory-constrained device like an ESP8266-based board.