aioredis - API中文参考文档

asyncio (PEP 3156) Redis客户端库。

该库旨在基于asyncio为Redis提供简单而清晰的接口。

译者：桑葚ICE

Connection

Redis Connection是库的核心功能。连接实例可以按原样使用，也可以通过 pool 或高级API。

连接使用示例：

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数据库索引。
password（str或None） - 如果redis服务器实例需要授权，则使用密码。
ssl（ssl.SSLContext或True或None） - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()。
encoding（str或None） - 用于响应解码的编解码器。
解析器（可调用**或无） - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面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或引发异常。
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"。
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()如果未指定则使用）。

aioredis - API中文参考文档

Connection

连接使用示例：

创建Redis连接(create_connection)

参数：

返回：RedisConnection实例。

class aioredis.RedisConnection

接口类：abc.AbcConnection

方法：

Connections Pool

基本用法示例：

创建Redis连接池(create_pool)

参数：

返回：ConnectionsPool 实例。

class aioredis.ConnectionsPool

接口类：abc.AbcPool

方法：

Pub/Sub Channel object

class aioredis.Channel(name, is_pattern, loop=None)

Commands Interface

用法示例：

aioredis.create_redis

参数：

返回：Redis 客户端 (commands_factory 调用的结果), 默认情况下。

aioredis.create_redis_pool

参数：

返回：Redis 客户端 (commands_factory 调用的结果), 默认情况下。

返回：`RedisConnection`实例。

接口类：`abc.AbcConnection`

返回：`ConnectionsPool` 实例。

接口类：`abc.AbcPool`