RESP3 connection examples

README.md

@@ -45,7 +45,8 @@ The table below higlights version compatibility of the most-recent library versi
 | Library version | Supported redis versions |
 |-----------------|-------------------|
 | 3.5.3 | <= 6.2 Family of releases |
-| >= 4.1.0 | Version 5.0 to current |
+| >= 4.5.0 | Version 5.0 to 7.0 |
+| >= 5.0.0 | Versiond 5.0 to current |
 
 
 ## Usage
@@ -63,6 +64,15 @@ b'bar'
 
 The above code connects to localhost on port 6379, sets a value in Redis, and retrieves it. All responses are returned as bytes in Python, to receive decoded strings, set *decode_responses=True*. For this, and more connection options, see [these examples](https://redis.readthedocs.io/en/stable/examples.html).
 
+
+#### RESP3 Support
+To enable support for RESP3, ensure you have at least version 5.0 of the client, and change your connection object to include *protocol=3*
+
+``` python
+>>> import redis
+>>> r = redis.Redis(host='localhost', port=6379, db=0, protocol=3)
+```
+
 ### Connection Pools
 
 By default, redis-py uses a connection pool to manage connections. Each instance of a Redis class receives its own connection pool. You can however define your own [redis.ConnectionPool](https://redis.readthedocs.io/en/stable/connections.html#connection-pools).

docs/examples/asyncio_examples.ipynb

@@ -21,6 +21,12 @@
  {
  "cell_type": "code",
  "execution_count": 1,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [
  {
  "name": "stdout",
@@ -36,29 +42,29 @@
  "connection = redis.Redis()\n",
  "print(f\"Ping successful: {await connection.ping()}\")\n",
  "await connection.close()"
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%%\n"
- }
- }
+ ]
  },
  {
  "cell_type": "markdown",
- "source": [
- "If you supply a custom `ConnectionPool` that is supplied to several `Redis` instances, you may want to disconnect the connection pool explicitly. Disconnecting the connection pool simply disconnects all connections hosted in the pool."
- ],
  "metadata": {
  "collapsed": false,
  "pycharm": {
  "name": "#%% md\n"
  }
- }
+ },
+ "source": [
+ "If you supply a custom `ConnectionPool` that is supplied to several `Redis` instances, you may want to disconnect the connection pool explicitly. Disconnecting the connection pool simply disconnects all connections hosted in the pool."
+ ]
  },
  {
  "cell_type": "code",
  "execution_count": 2,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [],
  "source": [
  "import redis.asyncio as redis\n",
@@ -67,16 +73,36 @@
  "await connection.close()\n",
  "# Or: await connection.close(close_connection_pool=False)\n",
  "await connection.connection_pool.disconnect()"
- ],
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "By default, this library uses version 2 of the RESP protocol. To enable RESP version 3, you will want to set `protocol` to 3"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import redis.asyncio as redis\n",
+ "\n",
+ "connection = redis.Redis(protocol=3)\n",
+ "await connection.close()\n",
+ "await connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
  "metadata": {
  "collapsed": false,
  "pycharm": {
- "name": "#%%\n"
+ "name": "#%% md\n"
  }
- }
- },
- {
- "cell_type": "markdown",
+ },
  "source": [
  "## Transactions (Multi/Exec)\n",
  "\n",
@@ -85,17 +111,17 @@
  "The commands will not be reflected in Redis until execute() is called & awaited.\n",
  "\n",
  "Usually, when performing a bulk operation, taking advantage of a “transaction” (e.g., Multi/Exec) is to be desired, as it will also add a layer of atomicity to your bulk operation."
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%% md\n"
- }
- }
+ ]
  },
  {
  "cell_type": "code",
  "execution_count": 3,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [],
  "source": [
  "import redis.asyncio as redis\n",
@@ -105,31 +131,31 @@
  " ok1, ok2 = await (pipe.set(\"key1\", \"value1\").set(\"key2\", \"value2\").execute())\n",
  "assert ok1\n",
  "assert ok2"
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%%\n"
- }
- }
+ ]
  },
  {
  "cell_type": "markdown",
- "source": [
- "## Pub/Sub Mode\n",
- "\n",
- "Subscribing to specific channels:"
- ],
  "metadata": {
  "collapsed": false,
  "pycharm": {
  "name": "#%% md\n"
  }
- }
+ },
+ "source": [
+ "## Pub/Sub Mode\n",
+ "\n",
+ "Subscribing to specific channels:"
+ ]
  },
  {
  "cell_type": "code",
  "execution_count": 4,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [
  {
  "name": "stdout",
@@ -170,29 +196,29 @@
  " await r.publish(\"channel:1\", STOPWORD)\n",
  "\n",
  " await future"
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%%\n"
- }
- }
+ ]
  },
  {
  "cell_type": "markdown",
- "source": [
- "Subscribing to channels matching a glob-style pattern:"
- ],
  "metadata": {
  "collapsed": false,
  "pycharm": {
  "name": "#%% md\n"
  }
- }
+ },
+ "source": [
+ "Subscribing to channels matching a glob-style pattern:"
+ ]
  },
  {
  "cell_type": "code",
  "execution_count": 5,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [
  {
  "name": "stdout",
@@ -234,16 +260,16 @@
  " await r.publish(\"channel:1\", STOPWORD)\n",
  "\n",
  " await future"
- ],
+ ]
+ },
+ {
+ "cell_type": "markdown",
  "metadata": {
  "collapsed": false,
  "pycharm": {
- "name": "#%%\n"
+ "name": "#%% md\n"
  }
- }
- },
- {
- "cell_type": "markdown",
+ },
  "source": [
  "## Sentinel Client\n",
  "\n",
@@ -252,17 +278,17 @@
  "Calling aioredis.sentinel.Sentinel.master_for or aioredis.sentinel.Sentinel.slave_for methods will return Redis clients connected to specified services monitored by Sentinel.\n",
  "\n",
  "Sentinel client will detect failover and reconnect Redis clients automatically."
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%% md\n"
- }
- }
+ ]
  },
  {
  "cell_type": "code",
  "execution_count": null,
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
  "outputs": [],
  "source": [
  "import asyncio\n",
@@ -277,13 +303,61 @@
  "assert ok\n",
  "val = await r.get(\"key\")\n",
  "assert val == b\"value\""
- ],
- "metadata": {
- "collapsed": false,
- "pycharm": {
- "name": "#%%\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to Redis instances by specifying a URL scheme.\n",
+ "Parameters are passed to the following schems, as parameters to the url scheme.\n",
+ "\n",
+ "Three URL schemes are supported:\n",
+ "\n",
+ "- `redis://` creates a TCP socket connection. <https://www.iana.org/assignments/uri-schemes/prov/redis>\n",
+ "- `rediss://` creates a SSL wrapped TCP socket connection. <https://www.iana.org/assignments/uri-schemes/prov/rediss>\n",
+ "- ``unix://``: creates a Unix Domain Socket connection.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
  }
- }
+ ],
+ "source": [
+ "import redis.asyncio as redis\n",
+ "url_connection = redis.from_url(\"redis://localhost:6379?decode_responses=True\")\n",
+ "url_connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "To enable the RESP 3 protocol, append `protocol=3` to the URL."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import redis.asyncio as redis\n",
+ "\n",
+ "url_connection = redis.from_url(\"redis://localhost:6379?decode_responses=Trueprotocol=3\")\n",
+ "url_connection.ping()"
+ ]
  }
  ],
  "metadata": {
@@ -307,4 +381,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}