redis-lua-py 0.8.0__tar.gz → 0.10.0__tar.gz

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/.github/workflows/ci.yml

@@ -54,7 +54,7 @@ jobs:
         with:
           enable-cache: true
       - run: uv sync --dev --python 3.10
-      # The floor in pyproject.toml is only a claim until something runs on it.
+      # The redis-py floor the docs name is only a claim until something runs on it.
       # fakeredis declares redis>=4.3 but works on 4.2, the first release with
       # redis.asyncio, so the pin goes in after the resolver is done.
       - run: uv pip install --no-deps "redis==4.2.0" async-timeout deprecated packaging

redis_lua_py-0.10.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.10.0"
+}

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ are written by [release-please](https://github.com/googleapis/release-please)
 from the conventional commit subjects on `main`; see
 [CONTRIBUTING.md](CONTRIBUTING.md) for how a release is cut.
 
+## [0.10.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.9.0...v0.10.0) (2026-09-14)
+
+
+### Added
+
+* document every redis command on hover in editors ([#28](https://github.com/IgnaceMaes/redis-lua-py/issues/28)) ([5d86e35](https://github.com/IgnaceMaes/redis-lua-py/commit/5d86e355c97d9a597cfc59985feaa88bc3a6fc17))
+
+## [0.9.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.8.0...v0.9.0) (2026-09-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* installing redis-lua-py no longer installs redis-py. Add redis-py or coredis to your own dependencies.
+
+### Added
+
+* drop the redis-py dependency ([#26](https://github.com/IgnaceMaes/redis-lua-py/issues/26)) ([e6e40e9](https://github.com/IgnaceMaes/redis-lua-py/commit/e6e40e914afb4043468d9b5b15f970940effcd63))
+
 ## [0.8.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.7.0...v0.8.0) (2026-09-13)
 
 

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/CONTRIBUTING.md

@@ -12,8 +12,9 @@ Redis.
 
 `src/redis_lua_py/_commands.py` is generated, not written. It is the table
 command names are checked against, and it comes from the command definitions
-in the Redis source. Refresh it when a Redis release adds commands, and commit
-the result:
+in the Redis source. The same run writes `src/redis_lua_py/_command_stubs.py`,
+the typed method per command that editors show on hover. Refresh both when a
+Redis release adds commands, and commit the result:
 
 ```sh
 uv run python scripts/generate_commands.py 8.10.1

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.8.0
+Version: 0.10.0
 Summary: Write Redis Lua scripts as real Python functions, not strings.
 Project-URL: Homepage, https://ignacemaes.com/redis-lua-py/
 Project-URL: Documentation, https://ignacemaes.com/redis-lua-py/
@@ -21,7 +21,6 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: redis>=4.2
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -89,7 +88,7 @@ for the script namespace, so the two never collide.
 uv add redis-lua-py
 ```
 
-Python 3.10+, and redis-py 4.2+ as the only dependency.
+Python 3.10+, and no dependencies: bring your own client, redis-py 4.2+ or coredis.
 
 ## What it compiles to
 

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/README.md

@@ -63,7 +63,7 @@ for the script namespace, so the two never collide.
 uv add redis-lua-py
 ```
 
-Python 3.10+, and redis-py 4.2+ as the only dependency.
+Python 3.10+, and no dependencies: bring your own client, redis-py 4.2+ or coredis.
 
 ## What it compiles to
 

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/docs/development.md

@@ -24,8 +24,9 @@ part you would most want a real server for.
 
 `src/redis_lua_py/_commands.py` is generated, not written. It is the table
 command names are checked against, and it comes from the command definitions
-in the Redis source. Refresh it when a Redis release adds commands, and commit
-the result:
+in the Redis source. The same run writes `src/redis_lua_py/_command_stubs.py`,
+the typed method per command that editors show on hover. Refresh both when a
+Redis release adds commands, and commit the result:
 
 ```bash
 uv run python scripts/generate_commands.py 8.10.1

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/docs/guide/calling-redis-commands.md

@@ -58,6 +58,22 @@ commands are checked down to the subcommand, and a hyphenated one is reached
 through its underscores — `redis.client_no_evict("on")` compiles to
 `redis.call('CLIENT', 'NO-EVICT', 'on')`.
 
+## In your editor
+
+Type checkers see every command as a method, generated from the same command
+definitions as the table, so hovering `redis.hset` shows what the command does,
+its syntax, its reply and its complexity, with a link to its page on redis.io.
+The Lua API's own functions, such as `redis.pcall` and `redis.log`, and
+`cjson.encode` / `cjson.decode`, are documented the same way.
+
+The leading plain arguments are named, so a call with too few or too many is
+flagged before the compiler sees it. Past the first option the order depends on
+which options are given, so the rest is `*args` and the syntax in the hover says
+what goes there. Every return type is `Any`: what a reply looks like inside Lua
+is not something Python can know. A spelling that is not one method per
+command, such as `redis.debug_object(k)`, still type-checks, and is left to the
+compiler.
+
 ## The escape hatch
 
 `redis.call(...)` is deliberately never checked. It is the escape hatch for

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/docs/installation.md

@@ -13,8 +13,12 @@ pip install redis-lua-py
 ## Requirements
 
 - Python 3.10 or newer
-- [redis-py](https://github.com/redis/redis-py) 4.2 or newer — the only
-  dependency, and installed with the package
+- A Redis client: [redis-py](https://github.com/redis/redis-py) 4.2 or newer,
+  or [coredis](https://github.com/alisaifee/coredis)
+
+The package has no dependencies of its own. It only calls the client you pass
+it, so it never installs one: add redis-py or coredis yourself, as you would
+to talk to Redis at all.
 
 Script caching, `EVALSHA` and the `NOSCRIPT` reload are handled by redis-py's
 own script machinery, which this library defers to rather than reimplementing.
@@ -22,8 +26,7 @@ Anything redis-py can talk to, this can run against: a standalone server, a
 cluster, Sentinel, or an in-process [fakeredis](guide/testing.md).
 
 [coredis](https://github.com/alisaifee/coredis) clients work as well, and are
-tested against, but coredis is not a dependency: install it yourself. See
-[Async](guide/async.md#coredis).
+tested against. See [Async](guide/async.md#coredis).
 
 ## For testing
 

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/docs/reference/api.md

@@ -79,6 +79,10 @@ Names are checked at compile time against Redis' own command table;
 The compiler identifies the namespace by value rather than by the name it is
 imported under, so every alias works and nothing is reserved.
 
+Type checkers see a method per command, documented from Redis' own command
+definitions, so an editor shows each command's syntax on hover. See
+[In your editor](../guide/calling-redis-commands.md#in-your-editor).
+
 ## `call`
 
 An alias of [`redis`](#redis), for modules that would rather not rename

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "redis-lua-py"
-version = "0.8.0"
+version = "0.10.0"
 description = "Write Redis Lua scripts as real Python functions, not strings."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -19,7 +19,7 @@ classifiers = [
     "Topic :: Database",
     "Typing :: Typed",
 ]
-dependencies = ["redis>=4.2"]
+dependencies = []
 
 [project.urls]
 Homepage = "https://ignacemaes.com/redis-lua-py/"
@@ -33,6 +33,9 @@ redis-lua-py = "redis_lua_py.__main__:main"
 
 [dependency-groups]
 dev = [
+    # The client every test runs through. Not a dependency of the package, which
+    # only calls the client it is handed: that client's library is already installed.
+    "redis>=4.2",
     "pytest>=8.3",
     "pytest-asyncio>=1.0",
     "fakeredis[lua]>=2.30",

redis_lua_py-0.10.0/scripts/generate_commands.py

@@ -0,0 +1,329 @@
+"""Regenerate the command table and its typed stubs from the Redis source tree.
+
+The compiler refuses a command Redis does not have, which means it needs to
+know what Redis has. The authority for that is ``src/commands/*.json`` in the
+Redis repository — the same files the server itself is built from — so this
+downloads a tagged release and reads them rather than transcribing a list.
+
+    uv run python scripts/generate_commands.py [version]
+
+Two files come out of it. ``src/redis_lua_py/_commands.py`` is the table the
+compiler checks names against. ``src/redis_lua_py/_command_stubs.py`` is a class
+with one method per command, carrying the summary, syntax and complexity from
+the same JSON, which type checkers see in place of the namespace so that an
+editor can show them on hover.
+
+Run it when a Redis release adds commands, and commit the result. The command
+table only gates the ``redis.<name>()`` spelling: ``redis.call('NEW.CMD', ...)``
+is deliberately never checked, so a stale table can never block a caller.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import keyword
+import re
+import subprocess
+import sys
+import tarfile
+import textwrap
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from redis_lua_py._compile.tables import COMMAND_ALIASES, REDIS_DIRECT
+
+DEFAULT_VERSION = "8.10.1"
+SOURCE = "https://github.com/redis/redis/archive/refs/tags/{version}.tar.gz"
+PACKAGE = Path(__file__).resolve().parent.parent / "src" / "redis_lua_py"
+TABLE = PACKAGE / "_commands.py"
+STUBS = PACKAGE / "_command_stubs.py"
+
+Spec = dict[str, Any]
+
+#: Argument types that are a single value, and so can be a named parameter.
+VALUE_TYPES = frozenset({"key", "string", "integer", "double", "unix-time", "pattern"})
+
+#: Docstring text is wrapped to this, inside a method eight spaces deep.
+WIDTH = 88
+
+
+def fetch(version: str) -> tuple[dict[str, Spec], dict[str, dict[str, Spec]]]:
+    """Read every command definition out of a released Redis tarball.
+
+    A subcommand's file names it bare -- ``hotkeys-get.json`` defines ``GET``
+    with ``"container": "HOTKEYS"`` -- so entries are separated as they are
+    read. Collecting them into one dict first would let ``HOTKEYS GET`` quietly
+    displace plain ``GET``.
+    """
+    url = SOURCE.format(version=version)
+    print(f"fetching {url}", file=sys.stderr)
+    with urllib.request.urlopen(url) as response:
+        payload = response.read()
+
+    commands: dict[str, Spec] = {}
+    subcommands: dict[str, dict[str, Spec]] = {}
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+        for member in archive.getmembers():
+            parts = Path(member.name).parts
+            if parts[1:3] != ("src", "commands") or not member.name.endswith(".json"):
+                continue
+            handle = archive.extractfile(member)
+            if handle is None:  # pragma: no cover - directories were filtered out
+                continue
+            for name, spec in json.loads(handle.read()).items():
+                container = spec.get("container")
+                if isinstance(container, str):
+                    subcommands.setdefault(container.upper(), {})[name.upper()] = spec
+                else:
+                    commands[name.upper()] = spec
+    if not commands:
+        raise SystemExit(f"no command definitions found in {url}")
+    return commands, subcommands
+
+
+def render_table(version: str, commands: set[str], subcommands: dict[str, set[str]]) -> str:
+    lines = [
+        '"""The commands Redis accepts, by name.',
+        "",
+        f"Generated by scripts/generate_commands.py from Redis {version}. Do not edit.",
+        "",
+        "``COMMANDS`` holds every command that is not a subcommand; ``SUBCOMMANDS``",
+        "maps each container command to the subcommands it takes. Together they are",
+        "what ``redis.<name>()`` is checked against, so that a name Redis does not",
+        "have is refused at import rather than at the first execution of a branch.",
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        f'REDIS_VERSION = "{version}"',
+        "",
+        "COMMANDS: frozenset[str] = frozenset(",
+        "    {",
+    ]
+    lines += [f'        "{name}",' for name in sorted(commands)]
+    lines += ["    }", ")", "", "SUBCOMMANDS: dict[str, frozenset[str]] = {"]
+    for container in sorted(subcommands):
+        lines.append(f'    "{container}": frozenset(')
+        lines.append("        {")
+        lines += [f'            "{name}",' for name in sorted(subcommands[container])]
+        lines += ["        }", "    ),"]
+    lines += ["}", ""]
+    return "\n".join(lines)
+
+
+def syntax(arg: Spec) -> str:
+    """Render one argument the way the Redis documentation writes it."""
+    kind = arg["type"]
+    token = arg.get("token")
+    if kind == "pure-token":
+        text = token or arg.get("display_text") or arg["name"].upper()
+    else:
+        if kind == "oneof":
+            text = " | ".join(syntax(child) for child in arg["arguments"])
+            if not arg.get("optional") or token or arg.get("multiple"):
+                text = f"<{text}>"
+        elif kind == "block":
+            text = " ".join(syntax(child) for child in arg["arguments"])
+        else:
+            text = arg.get("display", arg["name"])
+        if arg.get("multiple"):
+            if token and arg.get("multiple_token"):
+                text = f"{token} {text} [{token} {text} ...]"
+            else:
+                text = f"{text} [{text} ...]"
+                if token:
+                    text = f"{token} {text}"
+        elif token:
+            text = f"{token} {text}"
+    return f"[{text}]" if arg.get("optional") else text
+
+
+def identifier(name: str, taken: set[str]) -> str:
+    base = re.sub(r"\W", "_", name.lower())
+    if keyword.iskeyword(base) or base in {"self", "args"} or base[0].isdigit():
+        base += "_"
+    candidate, n = base, 2
+    while candidate in taken:
+        candidate, n = f"{base}{n}", n + 1
+    taken.add(candidate)
+    return candidate
+
+
+def parameters(tokens: tuple[str, ...], spec: Spec) -> tuple[list[str], bool]:
+    """The named parameters a command takes, and whether more may follow.
+
+    Only the leading run of plain required values is named. Past the first
+    token, option or group, the order and count depend on which options are
+    given, so the rest is left to ``*args`` and the syntax in the docstring.
+    Redis' own arity settles the count: a signature that disagrees with it is
+    widened to ``*args`` rather than trusted.
+    """
+    arguments = spec.get("arguments", [])
+    names: list[str] = []
+    taken: set[str] = set()
+    rest = False
+    for arg in arguments:
+        if arg["type"] not in VALUE_TYPES or arg.get("token") or arg.get("optional"):
+            rest = True
+            break
+        names.append(identifier(arg["name"], taken))
+        if arg.get("multiple"):
+            rest = True
+            break
+
+    arity = spec["arity"]
+    fixed = len(tokens) + len(names)
+    if arity < 0:
+        if fixed > -arity:
+            names = names[: -arity - len(tokens)]
+        return names, True
+    if rest or fixed != arity:
+        return names[: max(arity - len(tokens), 0)], True
+    return names, False
+
+
+def plain(text: str) -> str:
+    """Turn the JSON's Markdown code spans into reST ones: `!GET` -> ``GET``."""
+    return re.sub(r"`!?([^`]+)`", r"``\1``", " ".join(text.split()))
+
+
+def replies(schema: Spec) -> list[str]:
+    if "description" in schema:
+        return [schema["description"]]
+    for key in ("oneOf", "anyOf"):
+        if key in schema:
+            return [option["description"] for option in schema[key] if "description" in option]
+    return []
+
+
+def docstring(tokens: tuple[str, ...], spec: Spec, has_args: bool) -> list[str]:
+    paragraphs: list[list[str]] = [textwrap.wrap(plain(spec["summary"]), WIDTH)]
+
+    if "deprecated_since" in spec:
+        note = f"Deprecated since Redis {spec['deprecated_since']}"
+        if "replaced_by" in spec:
+            note += f", replaced by {plain(spec['replaced_by'])}"
+        paragraphs.append(textwrap.wrap(note + ".", WIDTH))
+
+    usage = " ".join([*tokens, *(syntax(arg) for arg in spec.get("arguments", []))])
+    wrapped = textwrap.wrap(
+        usage,
+        WIDTH - 4,
+        subsequent_indent="    ",
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+    paragraphs.append(["Syntax::"])
+    paragraphs.append(["    " + line for line in wrapped])
+
+    reply = [plain(text) for text in replies(spec.get("reply_schema", {}))]
+    if len(reply) == 1:
+        paragraphs.append(textwrap.wrap(f"Reply: {reply[0]}", WIDTH))
+    elif reply:
+        bullets = ["Reply, one of:", ""]
+        for text in reply:
+            bullets += textwrap.wrap(text, WIDTH, initial_indent="- ", subsequent_indent="  ")
+        paragraphs.append(bullets)
+
+    if "complexity" in spec:
+        paragraphs.append(textwrap.wrap(f"Time complexity: {plain(spec['complexity'])}", WIDTH))
+
+    call = ", ".join([*(f"'{token}'" for token in tokens), *(["..."] if has_args else [])])
+    paragraphs.append(
+        textwrap.wrap(
+            f"Available since Redis {spec['since']}. Compiles to ``redis.call({call})``.", WIDTH
+        )
+    )
+    if spec["group"] != "sentinel":  # Sentinel commands have no page of their own.
+        page = "-".join(tokens).lower()
+        paragraphs.append([f"https://redis.io/docs/latest/commands/{page}/"])
+
+    lines: list[str] = []
+    for paragraph in paragraphs:
+        if lines:
+            lines.append("")
+        lines += paragraph
+    return lines
+
+
+def method(name: str, tokens: tuple[str, ...], spec: Spec) -> list[str]:
+    names, rest = parameters(tokens, spec)
+    params = ["self", *(f"{param}: Any" for param in names)]
+    if names:
+        params.append("/")
+    if rest:
+        params.append("*args: Any")
+
+    doc = [line.replace("\\", "\\\\") for line in docstring(tokens, spec, bool(names) or rest)]
+    lines = [f"    def {name}({', '.join(params)}) -> Any:"]
+    lines.append(f'        """{doc[0]}')
+    lines += [f"        {line}".rstrip() for line in doc[1:]]
+    lines.append('        """')
+    return lines
+
+
+def render_stubs(
+    version: str, commands: dict[str, Spec], subcommands: dict[str, dict[str, Spec]]
+) -> str:
+    entries: dict[str, tuple[tuple[str, ...], Spec]] = {}
+    for command, spec in commands.items():
+        if command in subcommands:
+            continue  # A container needs a subcommand; it is not callable bare.
+        if "-" in command and command.split("-")[0] in commands:
+            # redis.restore_asking reaches RESTORE with an ASKING argument, not
+            # RESTORE-ASKING, so a stub under that name would describe the wrong command.
+            continue
+        entries[command.lower().replace("-", "_")] = ((command,), spec)
+    for container, members in subcommands.items():
+        for sub, spec in members.items():
+            entries[f"{container}_{sub}".lower().replace("-", "_")] = ((container, sub), spec)
+    for alias, tokens in COMMAND_ALIASES.items():
+        entries[alias] = (tokens, commands[tokens[0]])
+    for name in [*entries]:
+        if keyword.iskeyword(name) or name in REDIS_DIRECT:
+            del entries[name]
+
+    lines = [
+        '"""A typed method for every Redis command a script body can call.',
+        "",
+        f"Generated by scripts/generate_commands.py from Redis {version}. Do not edit.",
+        "",
+        "Nothing imports this at runtime. Type checkers see the ``redis`` namespace as",
+        "a subclass of ``RedisCommands``, so an editor can show each command's syntax",
+        "and documentation on hover, while the compiler goes on resolving the",
+        "namespace by value.",
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "from typing import Any",
+        "",
+        "",
+        "class RedisCommands:",
+        '    """The Redis commands, as ``redis.<name>(...)`` spells them."""',
+    ]
+    for name in sorted(entries):
+        lines.append("")
+        lines += method(name, *entries[name])
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    version = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_VERSION
+    commands, subcommands = fetch(version)
+    names = {container: set(members) for container, members in subcommands.items()}
+    TABLE.write_text(render_table(version, set(commands), names))
+    STUBS.write_text(render_stubs(version, commands, subcommands))
+    subprocess.run([sys.executable, "-m", "ruff", "format", str(STUBS)], check=True)
+    print(
+        f"wrote {TABLE.relative_to(Path.cwd())} and {STUBS.relative_to(Path.cwd())}: "
+        f"{len(commands)} commands, {len(subcommands)} containers",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()

{redis_lua_py-0.8.0 → redis_lua_py-0.10.0}/src/redis_lua_py/__init__.py

@@ -67,7 +67,7 @@ __all__ = [
     "script",
 ]
 
-__version__ = "0.8.0"  # x-release-please-version
+__version__ = "0.10.0"  # x-release-please-version
 
 
 @overload