summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordvora-h <67596500+dvora-h@users.noreply.github.com>2021-12-30 11:40:48 +0200
committerGitHub <noreply@github.com>2021-12-30 11:40:48 +0200
commitdeaaa536568e50b6ce958de0dd6306392e98f13e (patch)
tree7dae1abd2e5759a15520342911b90cf46b07e754
parent1b7d5bbac89d1dc65154e52360af43373d45ebc6 (diff)
downloadredis-py-deaaa536568e50b6ce958de0dd6306392e98f13e.tar.gz
Connection examples (#1835)
Co-authored-by: Chayim I. Kirshen <c@kirshen.com>
-rw-r--r--docs/conf.py4
-rw-r--r--docs/examples.rst8
-rw-r--r--docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb180
-rw-r--r--docs/examples/README.md (renamed from examples/README.md)0
-rw-r--r--docs/examples/connection_example.ipynb254
-rw-r--r--docs/index.rst1
-rw-r--r--docs/requirements.txt3
-rw-r--r--tasks.py1
-rw-r--r--tox.ini4
9 files changed, 452 insertions, 3 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 7e83e42..0f11442 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,6 +27,8 @@ sys.path.append(os.path.abspath(os.path.pardir))
# 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 @@ release = redis.__version__
# 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.
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..1a82182
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,8 @@
+Examples
+########
+
+.. toctree::
+ :maxdepth: 3
+ :glob:
+
+ examples/connection_example
diff --git a/docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb b/docs/examples/.ipynb_checkpoints/connection_example-checkpoint.ipynb
new file mode 100644
index 0000000..04de8fe
--- /dev/null
+++ b/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
+}
diff --git a/examples/README.md b/docs/examples/README.md
index ca6d5dc..ca6d5dc 100644
--- a/examples/README.md
+++ b/docs/examples/README.md
diff --git a/docs/examples/connection_example.ipynb b/docs/examples/connection_example.ipynb
new file mode 100644
index 0000000..af5193e
--- /dev/null
+++ b/docs/examples/connection_example.ipynb
@@ -0,0 +1,254 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Connection Examples"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import redis"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to a default Redis instance, running locally."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 2,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "connection = redis.Redis()\n",
+ "connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### by default Redis return binary responses, to decode them use decode_responses=True"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "decode_connection = redis.Redis(decode_responses=True)\n",
+ "connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to a redis instance, specifying a host and port with credentials."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "user_connection = redis.Redis(host='localhost', port=6380, username='dvora', password='redis', decode_responses=True)\n",
+ "user_connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to a Redis instance via SSL."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 5,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "ssl_connection = redis.Redis(host='localhost', port=6666, ssl=True, ssl_cert_reqs=\"none\")\n",
+ "ssl_connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to a Redis instance via SSL, while specifying a self-signed SSL certificate."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import os\n",
+ "\n",
+ "ROOT = os.path.join(os.getcwd(), \"..\", \"..\")\n",
+ "CERT_DIR = os.path.abspath(os.path.join(ROOT, \"docker\", \"stunnel\", \"keys\"))\n",
+ "ssl_certfile=os.path.join(CERT_DIR, \"server-cert.pem\")\n",
+ "ssl_keyfile=os.path.join(CERT_DIR, \"server-key.pem\")\n",
+ "ssl_ca_certs=os.path.join(CERT_DIR, \"server-cert.pem\")\n",
+ "\n",
+ "ssl_cert_conn = redis.Redis(\n",
+ " host=\"localhost\",\n",
+ " port=6666,\n",
+ " ssl=True,\n",
+ " ssl_certfile=ssl_certfile,\n",
+ " ssl_keyfile=ssl_keyfile,\n",
+ " ssl_cert_reqs=\"required\",\n",
+ " ssl_ca_certs=ssl_ca_certs,\n",
+ ")\n",
+ "ssl_cert_conn.ping()"
+ ]
+ },
+ {
+ "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": 7,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "True"
+ ]
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "url_connection = redis.from_url(\"rediss://localhost:6666?ssl_cert_reqs=none&decode_responses=True&health_check_interval=2\")\n",
+ "\n",
+ "url_connection.ping()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Connecting to a Sentinel instance"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from redis.sentinel import Sentinel\n",
+ "sentinel = Sentinel([('localhost', 26379)], socket_timeout=0.1)\n",
+ "sentinel.discover_master(\"redis-py-test\")"
+ ]
+ }
+ ],
+ "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.8.12"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/index.rst b/docs/index.rst
index d088708..cbf5115 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -71,6 +71,7 @@ Module Documentation
exceptions
lock
retry
+ examples
Contributing
*************
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 6dc905f..bbb7dc6 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,6 @@
sphinx<2
docutils<0.18
sphinx-rtd-theme
+nbsphinx
+sphinx_gallery
+ipython
diff --git a/tasks.py b/tasks.py
index 0fbb5e8..313986d 100644
--- a/tasks.py
+++ b/tasks.py
@@ -29,6 +29,7 @@ def devenv(c):
@task
def build_docs(c):
"""Generates the sphinx documentation."""
+ _generate_keys()
run("tox -e docs")
diff --git a/tox.ini b/tox.ini
index 0da66ed..3ca4533 100644
--- a/tox.ini
+++ b/tox.ini
@@ -131,7 +131,7 @@ skipsdist = true
skip_install = true
deps = -r {toxinidir}/dev_requirements.txt
docker = {[testenv]docker}
-commands = /usr/bin/echo
+commands = /usr/bin/echo docker_up
run_before = {[testenv]run_before}
[testenv:linters]
@@ -147,7 +147,7 @@ skipsdist = true
skip_install = true
[testenv:docs]
-deps_files = docs/requirements.txt
+deps = -r docs/requirements.txt
docker =
changedir = {toxinidir}/docs
allowlist_externals = make