redis-lua-py 0.9.0__tar.gz → 0.11.0__tar.gz

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

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

{redis_lua_py-0.9.0 → redis_lua_py-0.11.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ 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.11.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.10.0...v0.11.0) (2026-09-25)
+
+
+### Added
+
+* compile isinstance and cjson.null in script bodies ([373c4b7](https://github.com/IgnaceMaes/redis-lua-py/commit/373c4b79d58994e7a67ada0db9572496839af8da))
+
+
+### Fixed
+
+* rename locals that would shadow the Lua globals scripts rely on ([373c4b7](https://github.com/IgnaceMaes/redis-lua-py/commit/373c4b79d58994e7a67ada0db9572496839af8da))
+* type a client wrapper with getattr forwarding as sync, not async ([373c4b7](https://github.com/IgnaceMaes/redis-lua-py/commit/373c4b79d58994e7a67ada0db9572496839af8da))
+
+## [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)
 
 

{redis_lua_py-0.9.0 → redis_lua_py-0.11.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.9.0 → redis_lua_py-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.9.0
+Version: 0.11.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/

{redis_lua_py-0.9.0 → redis_lua_py-0.11.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.9.0 → redis_lua_py-0.11.0}/docs/guide/async.md

@@ -22,6 +22,11 @@ a = rate_limit(sync_client, key="u:1", limit=10, ttl=60)  # int
 b = rate_limit(async_client, key="u:1", limit=10, ttl=60)  # Awaitable[int]
 ```
 
+A client is typed as sync when it has `__enter__`, as every redis-py sync
+client does, and as async when it has `__aenter__`. The sync overload comes
+first, so a wrapper of your own that forwards attributes through `__getattr__`,
+which mypy takes to provide both, is typed as the sync client it wraps.
+
 Script caching, `EVALSHA`, and the `NOSCRIPT` reload are handled by redis-py's
 own script machinery, which this defers to rather than reimplementing.
 

{redis_lua_py-0.9.0 → redis_lua_py-0.11.0}/docs/guide/build-time.md

@@ -81,6 +81,8 @@ return limit - current
 _RATE_LIMIT_CLIENTS: WeakKeyDictionary[Any, Any] = WeakKeyDictionary()
 
 
+@overload
+def rate_limit(client: _SyncClient, /, key: _Key, limit: int, ttl: int) -> int: ...
 @overload
 def rate_limit(
     client: _AsyncClient,

{redis_lua_py-0.9.0 → redis_lua_py-0.11.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.9.0 → redis_lua_py-0.11.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
@@ -88,6 +92,8 @@ anything.
 
 The JSON library Redis exposes to scripts: `cjson.encode` and `cjson.decode`,
 which pass through under their own names.
+`cjson.null` is JSON `null`, which `None` is not: a field set to `None` is
+dropped from an encoded object.
 
 ## `CompiledScript`
 

{redis_lua_py-0.9.0 → redis_lua_py-0.11.0}/docs/reference/lua-vs-python.md

@@ -19,6 +19,24 @@ never runs. `x is None` compiles to a helper accepting both, which also takes
 twice. `x == None` and `x != None` compile to the same helper, since that is
 plainly what they mean.
 
+`cjson.decode` gives JSON `null` as `cjson.null`, which is neither: compare
+with `== cjson.null`. Setting a field to `None` removes it, so write
+`cjson.null` where the encoded object should keep the field as `null`.
+
+## `isinstance` has Lua's types
+
+`isinstance(x, dict)` compiles to `type(x) == 'table'`, the usual guard on a
+decoded JSON value before reading its fields. Lua has fewer types than Python,
+so some tests answer for more than their name says:
+
+- `int` and `float` both test for a number, which may have a fraction;
+- `dict` and `list` both test for a table;
+- `str` and `bytes` both test for a string;
+- `bool` is not a number, so `isinstance(True, int)` is false.
+
+A tuple or a `|` union of types tests for any of them. A class of your own has
+no Lua counterpart, and is refused.
+
 ## Indexing is closed
 
 Lua tables are 1-based. `items[0]` compiles to `items[1]`. Write Python indices
@@ -53,6 +71,15 @@ Python scopes a name to the whole function; Lua's `local` scopes it to the
 enclosing block. A name assigned inside an `if` and read after it is hoisted to
 the top of the script, so it does not silently read back `nil`.
 
+## Names Lua already uses are closed
+
+The generated Lua calls globals such as `type`, `error`, `tostring` and
+`pairs`, and reads `KEYS` and `ARGV`. A local of the same name would shadow
+them for the rest of the script, so a parameter named `error` would break
+every `raise` after it. Such a name is renamed with a trailing underscore
+instead: `local error_ = ARGV[1]`. The keyword argument on the Python side
+keeps its name.
+
 ## Strings are closed
 
 Lua's `+` is only arithmetic. It will add `"1" + "2"` to `3`. So `+`

{redis_lua_py-0.9.0 → redis_lua_py-0.11.0}/docs/reference/supported-subset.md

@@ -27,10 +27,12 @@ language with a faithful Lua meaning is accepted.
   `decode()` in UTF-8, which leave the bytes as they are.
 - **Builtins and methods:** `len()`, `int()`, which truncates toward zero,
   `float()`, `str()`, `min()`, `max()`, `abs()`, `ord()`, `chr()`, `.append()`,
-  `.insert()`, `.pop()` and `dict.get()`.
+  `.insert()`, `.pop()` and `dict.get()`; `isinstance()` against `str`,
+  `bytes`, `int`, `float`, `bool`, `dict` and `list`.
 - **The `math` module:** `floor`, `ceil`, `sqrt`, `fabs`, `fmod`, `exp`,
   `log`, `log10` and `pow`, imported either way.
-- **Calls:** into `redis` and `cjson`, with `*xs` allowed as the last argument.
+- **Calls:** into `redis` and `cjson`, with `*xs` allowed as the last argument,
+  and `cjson.null` for a JSON null.
 - **Parameters:** `list[Key]` and `list[...]`, for a variable number of keys
   and arguments.
 - **Module-level constants.**

{redis_lua_py-0.9.0 → redis_lua_py-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "redis-lua-py"
-version = "0.9.0"
+version = "0.11.0"
 description = "Write Redis Lua scripts as real Python functions, not strings."
 readme = "README.md"
 requires-python = ">=3.10"

redis_lua_py-0.11.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.9.0 → redis_lua_py-0.11.0}/src/redis_lua_py/__init__.py

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