picoredis 0.1.1

Description:

picoredis 0.1.1

Overview
PicoRedis is a very minimal Redis client (not only) for MicroPython.

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.




Usage
>>> from picoredis import Redis
>>> redis = Redis() # server defaults to 127.0.0.1 port 6379
>>> redis.do_cmd('PING', 'Hello World!')
b'Hello World!'
Instead of using the do_cmd method, Redis instances can be
called directly:
>>> redis('SET', 'foo', 'bar')
b'OK'
>>> redis('GET', 'foo')
b'bar' # string responses are always byte strings
Or you can call arbitrary methods on the Redis instance, and the
method name will be used as the Redis command:
>>> redis.hset('myhash', 'key1', 42)
1
>>> redis.hkeys('myhash')
[b'key1']
You can use any method name consisting of only letters, except
connect, close, debug (and do_cmd), which are already
used as instance attribute or method names. If the name does not
correspond to a valid Redis command, the server will return an error and
a RedisError exception will be raised:
>>> redis.bogus('spam!')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "picoredis.py", line 72, in <lambda>
File "picoredis.py", line 66, in do_cmd
File "picoredis.py", line 82, in _read_response
RedisError: ('ERR', "unknown command 'bogus'")

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(host='192.168.1.100')
>>> redis = Redis(host='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.



Installation
On CPython and PyPy use pip to install as usual:
$ pip install picoredis
On MicroPython, just download the
picoredis.py
file from the repository and, for the unix port, put it into your
MICROPYPATH directory (normally ~/.micropython/lib), or for
base-metal ports (esp8266, stm32, wipy, etc.) upload it to the
flash storage of your MicroPython board, for example using
ampy:
$ curl -O https://raw.githubusercontent.com/SpotlightKid/picoredis/master/picoredis/picoredis.py
$ ampy -p /dev/ttyUSB0 put picoredis.py
You can also compile the picoredis.py module with
mpy-cross
and use the resulting picoredis.mpy file as a drop-in replacement
for the pure Python version. This will save you a good bit of memory on
your MicroPython board, because the byte-code compilation step, that
normally happens when you import the module, can be skipped:
$ mpy-cross picoredis.py
$ ampy -p /dev/ttyUSB0 put picoredis.mpy


License
PicoRedis was written and is copyrighted by Christopher Arndt, 2017.
It is distributed under the terms of the MIT
license, PicoRedis is free
and open source software.


Acknowledgements
Some inspiration and code ideas were taken from these projects:

micropython-redis
by Dwight Hubbard
redis_protocol by
Young King