Merge branch 'master' into patch-1

willfrey · web-flow · commit f0d79210a325 · 2024-05-16T16:04:05.000+09:00
diff --git a/.github/wordlist.txt b/.github/wordlist.txt
@@ -74,6 +74,8 @@ bysource
 charset
 del
 dev
+docstring
+docstrings
 eg
 exc
 firsttimersonly
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -81,6 +81,19 @@ using `invoke standalone-tests`; similarly, RedisCluster tests can be run by usi
 Each run of tests starts and stops the various dockers required. Sometimes
 things get stuck, an `invoke clean` can help.
 
+## Documentation
+
+If relevant, update the code documentation, via docstrings, or in `/docs`.
+
+You can check how the documentation looks locally by running `invoke build-docs`
+and loading the generated HTML files in a browser.
+
+Historically there is a mix of styles in the docstrings, but the preferred way
+of documenting code is by applying the
+[Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+Type hints should be added according to PEP484, and should not be repeated in
+the docstrings.
+
 ### Docker Tips
 
 Following are a few tips that can help you work with the Docker-based
diff --git a/docs/conf.py b/docs/conf.py
@@ -10,6 +10,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
 import sys
 
@@ -30,19 +31,23 @@
     "nbsphinx",
     "sphinx_gallery.load_style",
     "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
-    "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
 ]
 
+# Napoleon settings. We only accept Google-style docstrings.
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
 # AutosectionLabel settings.
 # Uses a <page>:<label> schema which doesn't work for duplicate sub-section
 # labels, so set max depth.
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 
 # AutodocTypehints settings.
+autodoc_typehints = 'description'
 always_document_param_types = True
 typehints_defaults = "comma"
 
@@ -60,7 +65,8 @@
 
 # General information about the project.
 project = "redis-py"
-copyright = "2023, Redis Inc"
+current_year = datetime.datetime.now().year
+copyright = f"{current_year}, Redis Inc"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/docs/examples/redis-stream-example.ipynb b/docs/examples/redis-stream-example.ipynb
@@ -108,7 +108,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "[[b'skey', [(b'1657571033115-0', {b'ts': b'1657571033.1128936', b'v': b'0'}), (b'1657571033117-0', {b'ts': b'1657571033.1176307', b'v': b'1'})]]]\n"
+      "[[b'skey', [(b'1710790167982-0', {b'ts': b'1710790167.9824948', b'v': b'0'}), (b'1710790167983-0', {b'ts': b'1710790167.9830241', b'v': b'1'})]]]\n"
      ]
     }
    ],
@@ -135,8 +135,8 @@
      "output_type": "stream",
      "text": [
       "got data from stream: b'skey'\n",
-      "id: b'1657571033115-0' value: b'0'\n",
-      "id: b'1657571033117-0' value: b'1'\n"
+      "id: b'1710790167982-0' value: b'0'\n",
+      "id: b'1710790167983-0' value: b'1'\n"
      ]
     }
    ],
@@ -165,8 +165,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "id: b'1657571033115-0' value: b'0'\n",
-      "id: b'1657571033117-0' value: b'1'\n"
+      "id: b'1710790167982-0' value: b'0'\n",
+      "id: b'1710790167983-0' value: b'1'\n"
      ]
     }
    ],
@@ -192,8 +192,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "id: b'1657571033118-0' value: b'2'\n",
-      "id: b'1657571033119-0' value: b'3'\n"
+      "id: b'1710790167983-1' value: b'2'\n",
+      "id: b'1710790167983-2' value: b'3'\n"
      ]
     }
    ],
@@ -213,8 +213,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "id: b'1657571033119-1' value: b'4'\n",
-      "id: b'1657571033121-0' value: b'5'\n"
+      "id: b'1710790167983-3' value: b'4'\n",
+      "id: b'1710790167983-4' value: b'5'\n"
      ]
     }
    ],
@@ -255,6 +255,34 @@
     "print( f\"stream length: {r.xlen( stream_key )}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "to get the last entry in the stream"
+   ],
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[[b'skey', [(b'1710790167984-0', {b'ts': b'1710790167.9839962', b'v': b'9'})]]]\n",
+      "stream length: 10\n"
+     ]
+    }
+   ],
+   "source": [
+    "# read the last available message\n",
+    "l = r.xread( count=1, streams={stream_key: '+'} )\n",
+    "print(l)\n",
+    "print( f\"stream length: {r.xlen( stream_key )}\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -298,8 +326,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got from b'skey' the entry [(b'1657571033115-0', {b'ts': b'1657571033.1128936', b'v': b'0'})]\n",
-      "got from b's2key' the entry [(b'1657571042111-0', {b'v': b'1000'})]\n"
+      "got from b'skey' the entry [(b'1710790167982-0', {b'ts': b'1710790167.9824948', b'v': b'0'})]\n",
+      "got from b's2key' the entry [(b'1710790173142-0', {b'v': b'1000'})]\n"
      ]
     }
    ],
@@ -425,8 +453,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got element b'1657571033115-0'from stream b'skey'\n",
-      "got element b'1657571033117-0'from stream b'skey'\n"
+      "got element b'1710790167982-0'from stream b'skey'\n",
+      "got element b'1710790167983-0'from stream b'skey'\n"
      ]
     }
    ],
@@ -453,8 +481,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got element b'1657571033118-0'from stream b'skey'\n",
-      "got element b'1657571033119-0'from stream b'skey'\n"
+      "got element b'1710790167983-1'from stream b'skey'\n",
+      "got element b'1710790167983-2'from stream b'skey'\n"
      ]
     }
    ],
@@ -484,10 +512,10 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got element b'1657571033115-0'from stream b'skey'\n",
-      "got element b'1657571033117-0'from stream b'skey'\n",
-      "got element b'1657571042111-0'from stream b's2key'\n",
-      "got element b'1657571042113-0'from stream b's2key'\n"
+      "got element b'1710790167982-0'from stream b'skey'\n",
+      "got element b'1710790167983-0'from stream b'skey'\n",
+      "got element b'1710790173142-0'from stream b's2key'\n",
+      "got element b'1710790173143-0'from stream b's2key'\n"
      ]
     }
    ],
@@ -546,8 +574,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got element b'1657571033118-0'from stream b'skey'\n",
-      "got element b'1657571033119-0'from stream b'skey'\n"
+      "got element b'1710790167983-1'from stream b'skey'\n",
+      "got element b'1710790167983-2'from stream b'skey'\n"
      ]
     }
    ],
@@ -593,22 +621,22 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "got element b'1657571033119-1'from stream b'skey'\n",
-      "got element b'1657571033121-0'from stream b'skey'\n",
-      "got element b'1657571033121-1'from stream b'skey'\n",
-      "got element b'1657571033121-2'from stream b'skey'\n",
-      "got element b'1657571033122-0'from stream b'skey'\n",
-      "got element b'1657571033122-1'from stream b'skey'\n",
-      "got element b'1657571049557-0'from stream b'skey'\n",
-      "got element b'1657571049557-1'from stream b'skey'\n",
-      "got element b'1657571049558-0'from stream b'skey'\n",
-      "got element b'1657571049559-0'from stream b'skey'\n",
-      "got element b'1657571049559-1'from stream b'skey'\n",
-      "got element b'1657571049559-2'from stream b'skey'\n",
-      "got element b'1657571049560-0'from stream b'skey'\n",
-      "got element b'1657571049562-0'from stream b'skey'\n",
-      "got element b'1657571049563-0'from stream b'skey'\n",
-      "got element b'1657571049563-1'from stream b'skey'\n",
+      "got element b'1710790167983-3'from stream b'skey'\n",
+      "got element b'1710790167983-4'from stream b'skey'\n",
+      "got element b'1710790167983-5'from stream b'skey'\n",
+      "got element b'1710790167983-6'from stream b'skey'\n",
+      "got element b'1710790167983-7'from stream b'skey'\n",
+      "got element b'1710790167984-0'from stream b'skey'\n",
+      "got element b'1710790173157-0'from stream b'skey'\n",
+      "got element b'1710790173158-0'from stream b'skey'\n",
+      "got element b'1710790173158-1'from stream b'skey'\n",
+      "got element b'1710790173158-2'from stream b'skey'\n",
+      "got element b'1710790173158-3'from stream b'skey'\n",
+      "got element b'1710790173158-4'from stream b'skey'\n",
+      "got element b'1710790173158-5'from stream b'skey'\n",
+      "got element b'1710790173159-0'from stream b'skey'\n",
+      "got element b'1710790173159-1'from stream b'skey'\n",
+      "got element b'1710790173159-2'from stream b'skey'\n",
       "2 pending messages on 'skey' for group 'grp1'\n"
      ]
     }
diff --git a/redis/commands/core.py b/redis/commands/core.py
@@ -199,69 +199,58 @@ def acl_setuser(
         """
         Create or update an ACL user.
 
-        Create or update the ACL for ``username``. If the user already exists,
+        Create or update the ACL for `username`. If the user already exists,
         the existing ACL is completely overwritten and replaced with the
         specified values.
 
-        ``enabled`` is a boolean indicating whether the user should be allowed
-        to authenticate or not. Defaults to ``False``.
-
-        ``nopass`` is a boolean indicating whether the can authenticate without
-        a password. This cannot be True if ``passwords`` are also specified.
-
-        ``passwords`` if specified is a list of plain text passwords
-        to add to or remove from the user. Each password must be prefixed with
-        a '+' to add or a '-' to remove. For convenience, the value of
-        ``passwords`` can be a simple prefixed string when adding or
-        removing a single password.
-
-        ``hashed_passwords`` if specified is a list of SHA-256 hashed passwords
-        to add to or remove from the user. Each hashed password must be
-        prefixed with a '+' to add or a '-' to remove. For convenience,
-        the value of ``hashed_passwords`` can be a simple prefixed string when
-        adding or removing a single password.
-
-        ``categories`` if specified is a list of strings representing category
-        permissions. Each string must be prefixed with either a '+' to add the
-        category permission or a '-' to remove the category permission.
-
-        ``commands`` if specified is a list of strings representing command
-        permissions. Each string must be prefixed with either a '+' to add the
-        command permission or a '-' to remove the command permission.
-
-        ``keys`` if specified is a list of key patterns to grant the user
-        access to. Keys patterns allow '*' to support wildcard matching. For
-        example, '*' grants access to all keys while 'cache:*' grants access
-        to all keys that are prefixed with 'cache:'. ``keys`` should not be
-        prefixed with a '~'.
-
-        ``reset`` is a boolean indicating whether the user should be fully
-        reset prior to applying the new ACL. Setting this to True will
-        remove all existing passwords, flags and privileges from the user and
-        then apply the specified rules. If this is False, the user's existing
-        passwords, flags and privileges will be kept and any new specified
-        rules will be applied on top.
-
-        ``reset_keys`` is a boolean indicating whether the user's key
-        permissions should be reset prior to applying any new key permissions
-        specified in ``keys``. If this is False, the user's existing
-        key permissions will be kept and any new specified key permissions
-        will be applied on top.
-
-        ``reset_channels`` is a boolean indicating whether the user's channel
-        permissions should be reset prior to applying any new channel permissions
-        specified in ``channels``.If this is False, the user's existing
-        channel permissions will be kept and any new specified channel permissions
-        will be applied on top.
-
-        ``reset_passwords`` is a boolean indicating whether to remove all
-        existing passwords and the 'nopass' flag from the user prior to
-        applying any new passwords specified in 'passwords' or
-        'hashed_passwords'. If this is False, the user's existing passwords
-        and 'nopass' status will be kept and any new specified passwords
-        or hashed_passwords will be applied on top.
-
-        For more information see https://redis.io/commands/acl-setuser
+        For more information, see https://redis.io/commands/acl-setuser
+
+        Args:
+            username: The name of the user whose ACL is to be created or updated.
+            enabled: Indicates whether the user should be allowed to authenticate.
+                     Defaults to `False`.
+            nopass: Indicates whether the user can authenticate without a password.
+                    This cannot be `True` if `passwords` are also specified.
+            passwords: A list of plain text passwords to add to or remove from the user.
+                       Each password must be prefixed with a '+' to add or a '-' to
+                       remove. For convenience, a single prefixed string can be used
+                       when adding or removing a single password.
+            hashed_passwords: A list of SHA-256 hashed passwords to add to or remove
+                              from the user. Each hashed password must be prefixed with
+                              a '+' to add or a '-' to remove. For convenience, a single
+                              prefixed string can be used when adding or removing a
+                              single password.
+            categories: A list of strings representing category permissions. Each string
+                        must be prefixed with either a '+' to add the category
+                        permission or a '-' to remove the category permission.
+            commands: A list of strings representing command permissions. Each string
+                      must be prefixed with either a '+' to add the command permission
+                      or a '-' to remove the command permission.
+            keys: A list of key patterns to grant the user access to. Key patterns allow
+                  '*' to support wildcard matching. For example, '*' grants access to
+                  all keys while 'cache:*' grants access to all keys that are prefixed
+                  with 'cache:'. `keys` should not be prefixed with a '~'.
+            reset: Indicates whether the user should be fully reset prior to applying
+                   the new ACL. Setting this to `True` will remove all existing
+                   passwords, flags, and privileges from the user and then apply the
+                   specified rules. If `False`, the user's existing passwords, flags,
+                   and privileges will be kept and any new specified rules will be
+                   applied on top.
+            reset_keys: Indicates whether the user's key permissions should be reset
+                        prior to applying any new key permissions specified in `keys`.
+                        If `False`, the user's existing key permissions will be kept and
+                        any new specified key permissions will be applied on top.
+            reset_channels: Indicates whether the user's channel permissions should be
+                            reset prior to applying any new channel permissions
+                            specified in `channels`. If `False`, the user's existing
+                            channel permissions will be kept and any new specified
+                            channel permissions will be applied on top.
+            reset_passwords: Indicates whether to remove all existing passwords and the
+                             `nopass` flag from the user prior to applying any new
+                             passwords specified in `passwords` or `hashed_passwords`.
+                             If `False`, the user's existing passwords and `nopass`
+                             status will be kept and any new specified passwords or
+                             hashed passwords will be applied on top.
         """
         encoder = self.get_encoder()
         pieces: List[EncodableT] = [username]
