aioredis - API中文参考文档
asyncio (PEP 3156) Redis客户端库。
该库旨在基于asyncio为Redis提供简单而清晰的接口。译者:桑葚ICE
Connection
连接使用示例:
import asyncio
import aioredis
async def connect_uri():
conn = await aioredis.create_connection(
'redis://localhost/0')
val = await conn.execute('GET', 'my-key')
async def connect_tcp():
conn = await aioredis.create_connection(
('localhost', 6379))
val = await conn.execute('GET', 'my-key')
async def connect_unixsocket():
conn = await aioredis.create_connection(
'/path/to/redis/socket')
# or uri 'unix:///path/to/redis/socket?db=1'
val = await conn.execute('GET', 'my-key')
asyncio.get_event_loop().run_until_complete(connect_tcp())
asyncio.get_event_loop().run_until_complete(connect_unixsocket())
创建Redis连接(create_connection)
coroutine aioredis.create_connection(address,*,db = 0,password = None,ssl = None,encoding = None,parser = None,loop = None,timeout = None)
参数:
-
地址(元组或str) -
-
一个地址连接。可以是以下之一:
-
Redis URI -
"redis://host:6379/0?encoding=utf-8"
;"redis://:password@host:6379/0?encoding=utf-8"`;
-
a(主机,端口)元组 - ;
('localhost', 6379)
-
或者是unix域套接字路径字符串 -
"/path/to/redis.sock"
。
-
-
db(int) - 连接时切换到的Redis数据库索引。
-
ssl(
ssl.SSLContext
或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
。 -
解析器(可调用**或无) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面
hiredis.Reader
。 -
loop(EventLoop) - 可选的事件循环实例(
asyncio.get_event_loop()
如果未指定则使用)。 -
timeout(float大于0 或None) - 打开连接的最长时间,否则引发
asyncio.TimeoutError
异常。None
默认情况下
返回:RedisConnection
实例。
class aioredis.RedisConnection
接口类:abc.AbcConnection
方法:
-
address
Redis服务器地址; IP端口元组或unix socket str(只读)。
IP是IPv4或IPv6,具体取决于初始地址中已解析的主机部分。
-
db
当前数据库索引(只读)。
-
encoding
用于响应解码的当前编解码器(只读)。
-
closed
True 如果连接已关闭(只读),则设置为。
-
in_transaction
设置为 True 发出MULTI命令时(只读)。
-
pubsub_channels
具有订阅频道的只读字典。键是字节,值是
Channel
实例。 -
pubsub_patterns
具有订阅模式的只读字典。键是字节,值是
Channel
实例。 -
in_pubsub
表示连接处于PUB / SUB模式。提供订阅频道的数量。只读。
-
execute(command,args,encoding = _NOTSET)
执行Redis命令。
该方法本身不是协程,而是写入底层传输并返回
asyncio.Future
等待结果。参数:
- command(str,bytes,bytearray) - 要执行的命令
- encoding(str或None) - 用于覆盖响应解码的仅关键字参数。默认情况下,将使用连接范围的编码。可以设置为None以跳过响应解码。
Rasies:
- TypeError - 当任何参数为None或无法编码为字节时。
- aioredis.ReplyError - 对于redis错误回复。
- aioredis.ProtocolError - 无法解码响应和/或连接断开。
返回:返回bytes或int reply(如果设置了编码,则返回str)
-
execute_pubsub(command,channels_or_patterns)
执行Pub / Sub命令的方法。该方法本身不是协程,而是返回
asyncio.gather()
协程。方法还接受aioredis.Channel
实例作为命令参数:>>> ch1 = Channel('A', is_pattern=False, loop=loop) >>> await conn.execute_pubsub('subscribe', ch1) [[b'subscribe', b'A', 1]]
-
closed()
关闭连接。
将连接标记为已关闭和计划清理过程。
所有待处理的命令都将被取消
ConnectionForcedCloseError
。 -
wait_closed()
将当前db索引更改为新索引。
参数: db(int) - 新的redis数据库索引。
Rasies:
- TypeError - 当
db
参数不是int时。 - ValueError - 当
db
参数小于0时。
返回True:始终返回True或引发异常。
- TypeError - 当
-
auth(密码)
发送AUTH命令。
参数: password(str) - 纯文本密码
返回 bool: 如果redis回复 OK ,则为 True 。
Connections Pool
基本用法示例:
import aioredis
async def sample_pool():
pool = await aioredis.create_pool('redis://localhost')
val = await pool.execute('get', 'my-key')
创建Redis连接池(create_pool)
aioredis.create_pool(address,*,db = 0,password = None,ssl = None,encoding = None,minsize = 1,maxsize = 10,parser = None,loop = None,create_connection_timeout = None,pool_cls = None,connection_cls = None)
参数:
- 地址(或) -
- Redis URI -
"redis://host:6379/0?encoding=utf-8"
; - a(主机,端口)元组 - ;
('localhost', 6379)
- 或者是unix域套接字路径字符串 -
"/path/to/redis.sock"
。
- Redis URI -
- db(int) - 连接时切换到的Redis数据库索引。
- password(str或None) - 如果redis服务器实例需要授权,则使用密码。
- ssl(
ssl.SSLContext
或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
。 - encoding(str或None) - 用于响应解码的编解码器。
- minsize(int) - 要在池中创建的最小可用连接数。
1
默认情况下。 - maxsize(int) - 要保留在池中的最大连接数。
10
默认情况下。必须大于0
。None
是不被允许的。 - 解析器(可调用**或无) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面
hiredis.Reader
。 - loop(EventLoop) - 可选的事件循环实例(
asyncio.get_event_loop()
如果未指定则使用)。 - create_connection_timeout(float大于0 或None) - 打开连接的最长时间,否则引发连接
asyncio.TimeoutError
。None
默认情况下。 - pool_cls(aioredis.abc.AbcPool) - 可用于实例化自定义池类。该参数必须是子类
AbcPool
。 - connection_cls(aioredis.abc.AbcConnection) - 可用于使池实例化自定义连接类。该参数必须是子类
AbcConnection
。
返回:ConnectionsPool
实例。
class aioredis.ConnectionsPool
接口类:abc.AbcPool
方法:
-
minsize
池的最小大小(只读)。
-
maxsize
池的最大大小(只读)。
-
size
当前池大小 - 空闲和已使用连接的数量(只读)。
-
freesize
当前的空闲连接数(只读)。
-
db
当前选择的db索引(只读)。
-
encoding
用于响应解码的当前编解码器(只读)。
-
closed
True 如果游泳池关闭。
-
execute(command, args, kwargs)
在空闲连接中执行Redis命令并返回 asyncio.Future等待结果。
此方法尝试从池中选择一个空闲连接并立即通过它发送命令 (保持由提供的流水线功能aioredis.RedisConnection.execute())。如果没有找到连接 - 返回coroutine等待执行命令的自由连接。
-
execute_pubsub(command, channels)
执行Redis(p)subscribe /(p)unsubscribe命令。
ConnectionsPool 为pub / sub选择单独的免费连接并使用它直到池关闭或连接断开(取消订阅所有频道/模式将保持连接被锁定以供pub / sub使用)。
Pub / Sub连接没有自动重新连接,因为这将隐藏用户消息丢失。
与execute()行为类似,即:尝试从池中选择自由连接并将其切换到pub / sub模式; 或者回退到coroutine等待自由连接和重复操作。
-
get_connection(command, args=())
从池返回 tuple (connection, address) 获取空闲连接。
如果未找到空闲连接 - 则返回None以代替连接。
返回类型: tuple(RedisConnection or None, str)
-
coroutine clear()
关闭并删除池中的所有空闲连接。
-
coroutine select(db)
更改池中所有空闲连接的db索引。
参数: db(int) - 新数据库索引。
-
coroutine acquire(command=None, args=())
从空闲池获取连接。如果需要,创建新的连接。
参数:
- command - 为将来保留。
- args - 为将来保留。
Rasies: aioredis.PoolClosedError - 如果池已经关闭
-
release(conn)
将已使用的连接返回到池中。
当返回的连接的db索引与池中的索引不同时,将断开连接。当空闲连接队列已满时,将断开连接。
注意:这种方法不是协程
参数: conn (aioredis.RedisConnection) – A RedisConnection 实例.
-
close()
关闭所有可用和正在进行的连接,并将池标记为已关闭。
-
coroutine wait_closed()
等待池关闭(当所有连接都关闭时)。
Pub/Sub Channel object
Channel对象是用于存储接收的发布/订阅消息的队列包装器。
class aioredis.Channel(name, is_pattern, loop=None)
接口类: abc.AbcChannel
表示发布/订阅消息队列的对象。它基本上是一个包装器asyncio.Queue。
-
name
保存编码的通道/模式名称。
-
is_pattern
模式通道设置为True。
-
is_active
如果队列中有消息并且仍然订阅了此通道,则设置为True。
-
coroutine get(*, encoding=None, decoder=None)
Coroutine等待并返回消息。
返回值是收到的消息或 None 表示该频道已取消订阅且不再接收消息。
参数:
- encoding(str) - 如果不是 None 用于解码生成的字节消息。
- decoder(callable) - 如果指定用于解码消息,例如
json.loads()
Rasies: aioredis.ChannelClosedError - 如果频道已取消订阅且没有更多消息。
-
get_json(*, encoding="utf-8")
Shortcut to
get(encoding="utf-8", decoder=json.loads)
-
coroutine wait_message()
关闭(取消订阅)等待消息在频道或频道中可用的等待消息。
主要思想是在循环中使用它:
>>> ch = redis.channels['channel:1'] >>> while await ch.wait_message(): ... msg = await ch.get()
返回类型: bool
-
coroutine async-for iter(*, encoding=None, decoder=None)
与get()方法相同,但它是一个本地协程。
用法示例:
>>> async for msg in ch.iter(): ... print(msg)
Commands Interface
该库提供了高级API,实现了Redis命令的简单接口。
用法示例:
import aioredis
# Create Redis client bound to single non-reconnecting connection.
async def single_connection():
redis = await aioredis.create_redis(
'redis://localhost')
val = await redis.get('my-key')
# Create Redis client bound to connections pool.
async def pool_of_connections():
redis = await aioredis.create_redis_pool(
'redis://localhost')
val = await redis.get('my-key')
# we can also use pub/sub as underlying pool
# has several free connections:
ch1, ch2 = await redis.subscribe('chan:1', 'chan:2')
# publish using free connection
await redis.publish('chan:1', 'Hello')
await ch1.get()
有关命令参考 - 请参阅命令mixins参考。
aioredis.create_redis
coroutine aioredis.create_redis(address, *, db=0, password=None, ssl=None, encoding=None, commands_factory=Redis, parser=None, timeout=None, connection_cls=None, loop=None)
此协程创建绑定到单个Redis连接的高级Redis接口实例(没有自动重新连接)。
参数:
- address(tuple或str) - 连接的地址。可以是(主机,端口)元组,unix域套接字路径字符串或Redis URI字符串。
- db(int) - 连接时切换到的Redis数据库索引。
- password(str或bytes或None) - Redis服务器实例需要授权时使用的密码。
- ssl(
ssl.SSLContext
或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
。 - encoding(str或None) - 用于响应解码的编解码器。
- commands_factory(callable) - 接受单个参数的工厂 - 实现
AbcConnection
并返回为Redis提供高级接口的实例的对象。Redis
默认情况下。 - 解析器(可调用**或无) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面
hiredis.Reader
。 - timeout(float大于0 或None) - 打开连接的最长时间,否则引发
asyncio.TimeoutError
异常。None
默认情况下 - connection_cls(aioredis.abc.AbcConnection) - 可用于实例化自定义连接类。该参数必须是子类
AbcConnection
。 - loop(EventLoop) - 可选的事件循环实例(
asyncio.get_event_loop()
如果未指定则使用)。
返回:Redis 客户端 (commands_factory 调用的结果), 默认情况下。
aioredis.create_redis_pool
coroutine aioredis.create_redis_pool(address, *, db=0, password=None, ssl=None, encoding=None, commands_factory=Redis, minsize=1, maxsize=10, parser=None, timeout=None, pool_cls=None, connection_cls=None, loop=None)
此协程创建绑定到连接池的高级Redis客户端实例(这允许自动重新连接和简单的发布/订阅使用)。
另请参阅ConnectionsPool
参数说明。
参数:
- address(tuple或str) - 连接的地址。可以是(主机,端口)元组,unix域套接字路径字符串或Redis URI字符串。
- db(int) - 连接时切换到的Redis数据库索引。
- password(str或bytes或None) - Redis服务器实例需要授权时使用的密码。
- ssl(
ssl.SSLContext
或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
。 - encoding(str或None) - 用于响应解码的编解码器。
- commands_factory(callable) - 接受单个参数的工厂 - 实现
AbcConnection
接口的对象,并返回一个为Redis提供高级接口的实例。Redis
默认情况下。 - minsize(int) - 初始化和保留在池中的最小连接数。默认值为1。
- maxsize(int) - 可在池中创建的最大连接数。默认值为10。
- 解析器(可调用**或无) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面
hiredis.Reader
。 - timeout(float大于0 或None) - 打开连接的最长时间,否则引发
asyncio.TimeoutError
异常。None
默认情况下 - pool_cls(aioredis.abc.AbcPool) - 可用于实例化自定义池类。该参数必须是子类
AbcPool
。 - connection_cls(aioredis.abc.AbcConnection) - 可用于使池实例化自定义连接类。该参数必须是子类
AbcConnection
。 - loop(EventLoop) - 可选的事件循环实例(
asyncio.get_event_loop()
如果未指定则使用)。