Redis-py官方文档翻译
官网：
https://github.com/andymccurd…
当前版本：2.10.5
注：这不是完整翻译，只提取了关键信息。省略了部分内容，如lua脚本支持。
pip install redis
pip install hiredis（解析器，可选。windows下好像不行。）
>>> import redis
>>> r = redis.StrictRedis(host='localhost', port=6379, db=0)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
'bar'
redis-py采取两种client class实现redis命令：
其一、StrictRedis类尽量坚持官方语法，但是以下除外：
- SELECT: 没有实现，应该是线程安全的原因。
- DEL: 由于del是python语法关键字，所用delete来代替。
- CONFIG GET|SET: 分开用 config_get or config_set来代替
- MULTI/EXEC:
事务作为Pipeline类的其中一部分的实现。Pipeline默认保证了MULTI,EXEC声明。但是你可以指定transaction=False来禁用这一行为。 - SUBSCRIBE/LISTEN:PubSub作为一个独立的类来实现发布订阅机制。
- SCAN/SSCAN/HSCAN/ZSCAN:每个命令都对应一个等价的迭代器方法
- scan_iter/sscan_iter/hscan_iter/zscan_iter methods for this behavior.
其二、Redis类是StrictRedis的子类，提供redis-py版本向后的兼容性。
关于StrictRedis与Redis的区别：(官方推荐使用StrictRedis.)
以下几个方法在StrictRedis和Redis类中的参数顺序不同。
- LREM: Order of ‘num’ and ‘value’ arguments reversed such that ‘num’
can provide a default value of zero. 在Redis类中是这样的： lrem(self, name,
value, num=0) 在StrictRedis类中是这样的： lrem(self, name, count, value) - ZADD: Redis specifies the ‘score’ argument before ‘value’. These were
swapped accidentally when being implemented and not discovered until
after people were already using it. The Redis class expects *args in
the form of: name1, score1, name2, score2, … 在Redis类中是这样的：
redis.zadd(‘my-key’, ‘name1’, 1.1, ‘name2’, 2.2, name3=3.3,
name4=4.4) 在StrictRedis中是这样的： redis.zadd(‘my-key’, 1.1, ‘name1’, 2.2,
‘name2’, name3=3.3, name4=4.4) - SETEX: Order of ‘time’ and ‘value’ arguments reversed. 在Redis类中是这样的：
setex(self, name, value, time) 而在StrictRedis中是这样的： setex(self, name,
time, value)
连接池
>>> pool = redis.ConnectionPool(host='localhost', port=6379, db=0)
>>> r = redis.Redis(connection_pool=pool)
Connections：redis-py提供两种类型的连接：基于TCP端口的，基于Unix
socket文件的（需要redis服务器开启配置）。
>>> r = redis.Redis(unix_socket_path='/tmp/redis.sock')
如果你需要，自定义连接类，需要告知连接池。
>>> pool = redis.ConnectionPool(connection_class=YourConnectionClass,
your_arg='...', ...)
释放连接回到连接池：
- 可以使用Redis类的reset()方法，或者使用with上下文管理语法。
解析器：
- 解析器控制如何解析Redis-server的响应内容，redis-py提供两种方式的解析器类支持：PythonParser和HiredisParser(需要单独安装)。它优先选用HiredisParser,如果不存在，则选用PythonParser.
Hiredis是redis核心团队开发的一个高性能c库，能够提高10x的解析速度。
响应回调：
- The client class使用一系列的callbacks来完成响应到对应python类型的映射。这些响应回调，定义在 Redis
client class中的RESPONSE_CALLBACKS字典中。你可以使用set_response_callback
方法来添加自定义回调类。这个方法接受两个参数：一个命令名字，一个回调类。回调类接受至少一个参数：响应内容，关键字参数作为命令调用时的参数。
线程安全性：
Redis client instances是线程安全的。由于线程安全原因，不提供select实现，因为它会导致数据库的切换。
在不同线程间传递PubSub or Pipeline对象也是不安全的。
Pipelines
- Pipelines是Redis类的一个子类，支持缓存多个命令，然后作为单个请求发送。通过减少TCP请求次数来达到提供性能的目的。
>>> r = redis.Redis(...)
>>> r.set('bing', 'baz')
>>> # Use the pipeline() method to create a pipeline instance
>>> pipe = r.pipeline()
>>> # The following SET commands are buffered
>>> pipe.set('foo', 'bar')
>>> pipe.get('bing')
>>> # the EXECUTE call sends all buffered commands to the server, returning
>>> # a list of responses, one for each command.
>>> pipe.execute()
[True, 'baz']
Pipelines的实现采用流式API，故而你可以采用以下链式调用的方式：
>>> pipe.set('foo', 'bar').sadd('faz', 'baz').incr('auto_number').execute()
[True, True, 6]
Pipelines默认以原子性(事务)的形式执行所有缓存的命令,你也可以禁用这一行为：
>>> pipe = r.pipeline(transaction=False)
WATCH命令提供了在事务之前检测一个或多个key值的变化。一旦在事务执行之前，某个值发生了变化，那么事务将被取消然后抛出WatchError 异常。
利用watch我们可以实现client-side incr命令：
>>> with r.pipeline() as pipe:
... while 1:
... try:
... # put a WATCH on the key that holds our sequence value
... pipe.watch('OUR-SEQUENCE-KEY')
... # after WATCHing, the pipeline is put into immediate execution
... # mode until we tell it to start buffering commands again.
... # this allows us to get the current value of our sequence
... current_value = pipe.get('OUR-SEQUENCE-KEY')
... next_value = int(current_value) + 1
... # now we can put the pipeline back into buffered mode with MULTI
... pipe.multi()
... pipe.set('OUR-SEQUENCE-KEY', next_value)
... # and finally, execute the pipeline (the set command)
... pipe.execute()
... # if a WatchError wasn't raised during execution, everything
... # we just did happened atomically.
... break
... except WatchError:
... # another client must have changed 'OUR-SEQUENCE-KEY' between
... # the time we started WATCHing it and the pipeline's execution.
... # our best bet is to just retry.
... continue
不过你可以使用transaction方法来简化这一操作：它包含handling and retrying watch errors的样板代码。第一参数为callable(这个callable只能接受一个Pipeline参数),及多个需要被WATCH的keys
>>> def client_side_incr(pipe):
... current_value = pipe.get('OUR-SEQUENCE-KEY')
... next_value = int(current_value) + 1
... pipe.multi()
... pipe.set('OUR-SEQUENCE-KEY', next_value)
>>>
>>> r.transaction(client_side_incr, 'OUR-SEQUENCE-KEY')
[True]
Publish / Subscribe
PubSub对象subscribes to channels and listens for new messages。
>>> r = redis.StrictRedis(...)
>>> p = r.pubsub()
>>> p.subscribe('my-first-channel', 'my-second-channel', ...)
>>> p.psubscribe('my-*', ...)
>>> p.get_message()
{'pattern': None, 'type': 'subscribe', 'channel': 'my-second-channel', 'data': 1L}
>>> p.get_message()
{'pattern': None, 'type': 'subscribe', 'channel': 'my-first-channel', 'data': 2L}
>>> p.get_message()
{'pattern': None, 'type': 'psubscribe', 'channel': 'my-*', 'data': 3L}
通过PubSub获取消息时返回的是一个字典，字典key有如下几个：
-
type:其中一个， ‘subscribe’, ‘unsubscribe’, ‘psubscribe’, ‘punsubscribe’,
‘message’, ‘pmessage’ -
channel: The channel [un]subscribed to or the channel a message was
published to -
pattern: The pattern that matched a published message’s channel. Will
be None in all cases except for ‘pmessage’ types. -
data: The message data. With [un]subscribe messages, this value will
be the number of channels and patterns the connection is currently
subscribed to. With [p]message messages, this value will be the
actual published message.
现在来发布消息：
# the publish method returns the number matching channel and pattern
# subscriptions. 'my-first-channel' matches both the 'my-first-channel'
# subscription and the 'my-*' pattern subscription, so this message will
# be delivered to 2 channels/patterns
>>> r.publish('my-first-channel', 'some data')
2
>>> p.get_message()
{'channel': 'my-first-channel', 'data': 'some data', 'pattern': None, 'type': 'message'}
>>> p.get_message()
{'channel': 'my-first-channel', 'data': 'some data', 'pattern': 'my-*', 'type': 'pmessage'}
取消订阅：如果没有传递任何参数，那么这个PubSub订阅的所有的channels or patterns都会被取消。
>>> p.unsubscribe()
>>> p.punsubscribe('my-*')
>>> p.get_message()
{'channel': 'my-second-channel', 'data': 2L, 'pattern': None, 'type': 'unsubscribe'}
>>> p.get_message()
{'channel': 'my-first-channel', 'data': 1L, 'pattern': None, 'type': 'unsubscribe'}
>>> p.get_message()
{'channel': 'my-*', 'data': 0L, 'pattern': None, 'type': 'punsubscribe'}
回调的方式处理发布的消息
redis-py还允许你通过回调的方式处理发布的消息。
Message handlers接受一个参数，the message,是一个字典对象。just like the examples above.
以回调形式订阅：subscribe接受关键字参数，键为channels or patterns,值为回调函数。
>>> def my_handler(message):
... print 'MY HANDLER: ', message['data']
>>> p.subscribe(**{'my-channel': my_handler})
在你注册了回调处理的情况下， get_message()会返回None。
默认情况下除了发布消息之外，还会传递 subscribe/unsubscribe成功的确认消息，如果你不想接收它们：ignore_subscribe_messages=True
>>> p = r.pubsub(ignore_subscribe_messages=True)
>>> p.subscribe('my-channel')
>>> p.get_message() # hides the subscribe message and returns None
>>> r.publish('my-channel')
1
>>> p.get_message()
{'channel': 'my-channel', 'data': 'my data', 'pattern': None, 'type': 'message'}
三种读取消息的方式
第一种：无限循环通过PubSub对象的get_message()读取消息
>>> while True:
>>> message = p.get_message()
>>> if message:
>>> # do something with the message
>>> time.sleep(0.001) # be nice to the system :)
第二种，通过阻塞方法listen()来读取：p.listen()返回一个generator，阻塞直到有消息可获取。
>>> for message in p.listen():
... # do something with the message
第三种，开启一个事件循环线程pubsub.run_in_thread()方法 creates a new thread and starts the event loop. 并返回线程对象。
但是需要注意的是：如果你没有注册消息处理函数，那么调用run_in_thread()将会抛出异常redis.exceptions.PubSubError
>>> p.subscribe(**{'my-channel': my_handler})
>>> thread = p.run_in_thread(sleep_time=0.001)
# the event loop is now running in the background processing messages
# when it's time to shut it down...
>>> thread.stop()
关于字符编码：
默认情况下，publish的消息会被编码，当你获取消息时得到的是编码后的字节，如果你需要它自动解码，创建Redis
client实例时需要指定decode_responses=True,(译者注：不建议使用该选项，因为当存在pickle序列化的值时，client.get(key)时会出现解码失败的错误UnicodeDecodeError)
关闭释放资源：
PubSub.close() method to shutdown the connection.
>>> p = r.pubsub()
>>> ...
>>> p.close()
Sentinel support与节点发现：
Redis Sentinel用于发现Redis节点。请确保至少一个Sentinel daemon 进程在运行。
你可以使用Sentinel connection to discover the master and slaves network addresses:
>>> from redis.sentinel import Sentinel
>>> sentinel = Sentinel([('localhost', 26379)], socket_timeout=0.1)
>>> sentinel.discover_master('mymaster')
('127.0.0.1', 6379)
>>> sentinel.discover_slaves('mymaster')
[('127.0.0.1', 6380)]
>>> master = sentinel.master_for('mymaster', socket_timeout=0.1)
>>> slave = sentinel.slave_for('mymaster', socket_timeout=0.1)
>>> master.set('foo', 'bar')
>>> slave.get('foo')
'bar'
上面的master and slave对象就是一个普通的StrictRedis对象实例。如果Sentinel配置了连接池的话，它们还会使用这个连接池。
可能抛出的异常：MasterNotFoundError ，SlaveNotFoundError 它们都是ConnectionError的子类
Scan Iterators
Redis 2.8之后有了*SCAN命令。redis-py also exposes the following methods that return Python iterators for convenience: scan_iter, hscan_iter, sscan_iter and zscan_iter.
>>> for key, value in (('A', '1'), ('B', '2'), ('C', '3')):
... r.set(key, value)
>>> for key in r.scan_iter():
... print key, r.get(key)
A 1
B 2
C 3