阅读 94

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"

  • dbint) - 连接时切换到的Redis数据库索引。

  • passwordstrNone) - 如果redis服务器实例需要授权,则使用密码。

  • sslssl.SSLContext或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()

  • encodingstrNone) - 用于响应解码的编解码器。

  • 解析器可调用**或) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面hiredis.Reader

  • loopEventLoop) - 可选的事件循环实例(asyncio.get_event_loop()如果未指定则使用)。

  • timeoutfloat大于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 等待结果。

    参数:

    • commandstrbytesbytearray) - 要执行的命令
    • encodingstrNone) - 用于覆盖响应解码的仅关键字参数。默认情况下,将使用连接范围的编码。可以设置为None以跳过响应解码。

    Rasies:

    返回:返回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索引更改为新索引。

    参数: dbint) - 新的redis数据库索引。

    Rasies:

    返回True:始终返回True或引发异常。

  • auth(密码)

    发送AUTH命令。

    参数: passwordstr) - 纯文本密码

    返回 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"
  • dbint) - 连接时切换到的Redis数据库索引。
  • passwordstrNone) - 如果redis服务器实例需要授权,则使用密码。
  • sslssl.SSLContext或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
  • encodingstrNone) - 用于响应解码的编解码器。
  • minsizeint) - 要在池中创建的最小可用连接数。 1默认情况下。
  • maxsizeint) - 要保留在池中的最大连接数。 10默认情况下。必须大于0None是不被允许的。
  • 解析器可调用**或) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面hiredis.Reader
  • loopEventLoop) - 可选的事件循环实例(asyncio.get_event_loop()如果未指定则使用)。
  • create_connection_timeoutfloat大于0 None) - 打开连接的最长时间,否则引发连接asyncio.TimeoutErrorNone默认情况下。
  • pool_clsaioredis.abc.AbcPool) - 可用于实例化自定义池类。该参数必须是子类AbcPool
  • connection_clsaioredis.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索引。

    参数: dbint) - 新数据库索引。

  • 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 表示该频道已取消订阅且不再接收消息。

    参数:

    • encodingstr) - 如果不是 None 用于解码生成的字节消息。
    • decodercallable) - 如果指定用于解码消息,例如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接口实例(没有自动重新连接)。

参数:

  • addresstuplestr) - 连接的地址。可以是(主机,端口)元组,unix域套接字路径字符串或Redis URI字符串。
  • dbint) - 连接时切换到的Redis数据库索引。
  • passwordstrbytesNone) - Redis服务器实例需要授权时使用的密码。
  • sslssl.SSLContext或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
  • encodingstrNone) - 用于响应解码的编解码器。
  • commands_factorycallable) - 接受单个参数的工厂 - 实现AbcConnection 并返回为Redis提供高级接口的实例的对象。Redis默认情况下。
  • 解析器可调用**或) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面hiredis.Reader
  • timeoutfloat大于0 None) - 打开连接的最长时间,否则引发asyncio.TimeoutError异常。 None默认情况下
  • connection_clsaioredis.abc.AbcConnection) - 可用于实例化自定义连接类。该参数必须是子类 AbcConnection
  • loopEventLoop) - 可选的事件循环实例(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参数说明。

参数:

  • addresstuplestr) - 连接的地址。可以是(主机,端口)元组,unix域套接字路径字符串或Redis URI字符串。
  • dbint) - 连接时切换到的Redis数据库索引。
  • passwordstrbytesNone) - Redis服务器实例需要授权时使用的密码。
  • sslssl.SSLContext或True或None) - 传递给的SSL上下文asyncio.BaseEventLoop.create_connection()
  • encodingstrNone) - 用于响应解码的编解码器。
  • commands_factorycallable) - 接受单个参数的工厂 - 实现AbcConnection接口的对象,并返回一个为Redis提供高级接口的实例。Redis默认情况下。
  • minsizeint) - 初始化和保留在池中的最小连接数。默认值为1。
  • maxsizeint) - 可在池中创建的最大连接数。默认值为10。
  • 解析器可调用**或) - 协议解析器类。可用于设置自定义协议阅读器; 预期相同的界面hiredis.Reader
  • timeoutfloat大于0 None) - 打开连接的最长时间,否则引发asyncio.TimeoutError异常。 None默认情况下
  • pool_clsaioredis.abc.AbcPool) - 可用于实例化自定义池类。该参数必须是子类AbcPool
  • connection_clsaioredis.abc.AbcConnection) - 可用于使池实例化自定义连接类。该参数必须是子类 AbcConnection
  • loopEventLoop) - 可选的事件循环实例(asyncio.get_event_loop()如果未指定则使用)。

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

关注下面的标签,发现更多相似文章
评论