Connection examples (#1835)

Co-authored-by: Chayim I. Kirshen <c@kirshen.com>

docs/conf.py

@@ -27,6 +27,8 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "nbsphinx",
+    "sphinx_gallery.load_style",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
@@ -73,7 +75,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "**.ipynb_checkponts"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/examples.rst

@@ -0,0 +1,8 @@
+Examples
+########
+
+.. toctree::
+   :maxdepth: 3
+   :glob:
+
+   examples/connection_example

docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb

@@ -0,0 +1,180 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Connect to redis running locally with default parameters "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 40,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "import redis\n",
+    "r = redis.Redis()\n",
+    "print(r.ping())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Overwrite default parameters - connect to redis on specific host and port using username and password"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 39,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "import redis\n",
+    "r = redis.Redis(host='localhost', port=6380, username='dvora', password='redis')\n",
+    "print(r.ping())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Create a SSL wrapped TCP socket connection"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "import redis\n",
+    "r = redis.Redis(host='localhost', port=6666, ssl=True, ssl_cert_reqs=\"none\")\n",
+    "print(r.ping())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Add more parameters..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 37,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "import redis\n",
+    "\n",
+    "ROOT = os.path.join(os.getcwd(), \"..\")\n",
+    "CERT_DIR = os.path.abspath(os.path.join(ROOT, \"docker\", \"stunnel\", \"keys\"))\n",
+    "\n",
+    "r = redis.Redis(\n",
+    "    host=\"localhost\",\n",
+    "    port=6666,\n",
+    "    ssl=True,\n",
+    "    ssl_certfile=os.path.join(CERT_DIR, \"server-cert.pem\"),\n",
+    "    ssl_keyfile=os.path.join(CERT_DIR, \"server-key.pem\"),\n",
+    "    ssl_cert_reqs=\"required\",\n",
+    "    ssl_ca_certs=os.path.join(CERT_DIR, \"server-cert.pem\"),\n",
+    ")\n",
+    "print(r.ping())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Connect to redis client object configured from given URL\n",
+    "##### Three URL schemes are supported:\n",
+    "\n",
+    "##### - `redis://` creates a TCP socket connection. See more at:\n",
+    "##### <https://www.iana.org/assignments/uri-schemes/prov/redis>\n",
+    "##### - `rediss://` creates a SSL wrapped TCP socket connection. See more at:\n",
+    "##### <https://www.iana.org/assignments/uri-schemes/prov/rediss>\n",
+    "##### - ``unix://``: creates a Unix Domain Socket connection.\n",
+    "\n",
+    "##### Parameters are passed through querystring"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 36,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "True\n"
+     ]
+    }
+   ],
+   "source": [
+    "import redis\n",
+    "r = redis.from_url(\"rediss://localhost:6666?ssl_cert_reqs=none\")\n",
+    "print(r.ping())"
+   ]
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "d45c99ba0feda92868abafa8257cbb4709c97f1a0b5dc62bbeebdf89d4fad7fe"
+  },
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}