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

你可能感兴趣的:(redis)