redis-lua-py 0.6.0__tar.gz → 0.7.0__tar.gz

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

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

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ 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.7.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.6.0...v0.7.0) (2026-09-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* a + b where neither side is known to be a number or a string now joins two strings instead of adding them as numbers, as Python does, so wrap a side in int to add. Integer keys of a dict the compiler knows to be one are no longer shifted by one, and a lambda or helper function that reads a loop variable is refused.
+
+### Added
+
+* compile lambdas, chained comparisons and slice steps, and tell dicts from lists ([6024009](https://github.com/IgnaceMaes/redis-lua-py/commit/6024009eaefeb20ccb743225c609799aa332f7c2))
+* support coredis clients ([#22](https://github.com/IgnaceMaes/redis-lua-py/issues/22)) ([3d07a89](https://github.com/IgnaceMaes/redis-lua-py/commit/3d07a89f5b4c55eddca3a1f3bae5f45b41fd4156))
+
+
+### Changed
+
+* split the compiler into a package of modules ([#20](https://github.com/IgnaceMaes/redis-lua-py/issues/20)) ([5f67766](https://github.com/IgnaceMaes/redis-lua-py/commit/5f67766f015c038086894f3b61fa76d6f9deef12))
+
 ## [0.6.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.5.1...v0.6.0) (2026-09-12)
 
 

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.6.0
+Version: 0.7.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/
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   Write Redis Lua scripts as real Python functions, not as strings.<br>
-  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py.
+  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py, and coredis.
 </p>
 
 <p align="center">
@@ -141,7 +141,7 @@ script cache is cold once per script rather than once per environment.
   a script is a `CompiledScript[R]`, and an async client gives you
   `Awaitable[R]`.
 - **[Sync and async](https://ignacemaes.com/redis-lua-py/guide/async/)** from
-  the same script object, and
+  the same script object, with redis-py or coredis, and
   **[`bind`](https://ignacemaes.com/redis-lua-py/guide/binding-a-client/)** when
   passing the client every time gets repetitive.
 - **[Build-time generation](https://ignacemaes.com/redis-lua-py/guide/build-time/)**

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">
   Write Redis Lua scripts as real Python functions, not as strings.<br>
-  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py.
+  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py, and coredis.
 </p>
 
 <p align="center">
@@ -115,7 +115,7 @@ script cache is cold once per script rather than once per environment.
   a script is a `CompiledScript[R]`, and an async client gives you
   `Awaitable[R]`.
 - **[Sync and async](https://ignacemaes.com/redis-lua-py/guide/async/)** from
-  the same script object, and
+  the same script object, with redis-py or coredis, and
   **[`bind`](https://ignacemaes.com/redis-lua-py/guide/binding-a-client/)** when
   passing the client every time gets repetitive.
 - **[Build-time generation](https://ignacemaes.com/redis-lua-py/guide/build-time/)**

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/guide/async.md

@@ -27,3 +27,31 @@ own script machinery, which this defers to rather than reimplementing.
 
 [`bind`](binding-a-client.md) works on async clients just as well, and carries
 the awaitable through.
+
+## coredis
+
+[coredis](https://github.com/alisaifee/coredis), which is async only, works
+the same way. A script, a bound script and a
+[library function](redis-functions.md) each return an awaitable, and the
+overloads type it as `Awaitable[R]`:
+
+```python
+import coredis
+
+async with coredis.Redis() as client:
+    remaining = await rate_limit(client, key="user:42", limit=10, ttl=60)
+```
+
+Script caching is coredis's own `register_script`, which reloads a script the
+server has dropped. In a coredis pipeline a call is queued like any other
+command, and coredis loads the pipeline's scripts before running it; await
+each call once the `async with` block has run the pipeline:
+
+```python
+async with client.pipeline() as pipe:
+    queued = rate_limit(pipe, key="user:42", limit=10, ttl=60)
+remaining = await queued
+```
+
+As with redis-py, a client created with `decode_responses=True` decodes
+replies, so a script annotated `bytes` returns `str` from it.

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/guide/redis-functions.md

@@ -34,7 +34,8 @@ peek(client, key="user:42")  # FCALL_RO peek 1 user:42
 
 A function is called like a script: pass a sync client and you get a value,
 an async one and you get an awaitable, and [`bind`](binding-a-client.md)
-works the same way.
+works the same way. With a [coredis](async.md#coredis) client, the call goes
+through its `fcall` or `fcall_ro`, and loading through its `function_load`.
 
 ## Loading
 
@@ -51,10 +52,11 @@ limits.load(client)
 
     A call queued in a pipeline cannot load the library halfway through
     `execute()`. Call `load()` before queueing calls to a library the server
-    may not have yet.
+    may not have yet. The same goes for a coredis pipeline, which runs when its
+    `async with` block ends: `await limits.load(client)` before entering it.
 
-On Redis Cluster, redis-py sends `FUNCTION LOAD` to every primary, and routes
-`FCALL` on the function's keys, as it does a script.
+On Redis Cluster, redis-py and coredis send `FUNCTION LOAD` to every primary,
+and route `FCALL` on the function's keys, as they do a script.
 
 ## What the library looks like
 

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/index.md

@@ -6,7 +6,7 @@ hide:
 # redis-lua-py
 
 Write Redis Lua scripts as real Python functions, not as strings. Compiled at
-import, checked by `mypy`, sent with `EVALSHA`. Sync and async redis-py.
+import, checked by `mypy`, sent with `EVALSHA`. Sync and async redis-py, and coredis.
 
 ```python
 from redis_lua_py import Key, redis, script
@@ -68,7 +68,8 @@ requirements, or go straight to the [Quickstart](quickstart.md).
 - **Typed on the caller's side.** A script is a `CompiledScript[R]`, so
   `rate_limit(...)` returns an `int` rather than `Any`, and an async client
   gives you `Awaitable[R]`. See [What the caller gets](guide/return-values.md).
-- **Sync and async from the same script object.** See [Async](guide/async.md).
+- **Sync and async from the same script object**, with redis-py or coredis.
+  See [Async](guide/async.md).
 - **Binary-safe throughout.** Nothing here decodes. See
   [Binary values](guide/binary-values.md).
 

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/installation.md

@@ -21,6 +21,10 @@ own script machinery, which this library defers to rather than reimplementing.
 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).
+
 ## For testing
 
 [fakeredis](https://github.com/cunla/fakeredis-py) embeds a real Lua

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/reference/errors.md

@@ -4,11 +4,11 @@ Every error this package raises carries a caret under the line at fault, and a
 hint saying what to write instead.
 
 ```
-chained comparisons are not supported
+math.log() with a base is not supported
   File "/srv/app/limits.py", line 12
-    if 0 < n < limit:
-       ^
-  hint: Split 'a < b < c' into 'a < b and b < c'.
+    buckets = math.log(n, 2)
+              ^
+  hint: Lua 5.1's math.log takes no base; divide by math.log(base) instead.
 ```
 
 ## The hierarchy

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/reference/lua-vs-python.md

@@ -23,22 +23,27 @@ Lua tables are 1-based. `items[0]` compiles to `items[1]`. Write Python indices
 and let the compiler shift them.
 
 A dict key must not be shifted, and Lua cannot tell a list from a dict. So the
-compiler looks at the subscript:
+compiler looks first at what is subscripted. A dict is indexed by its keys as
+they are, integer keys included, and a list's index is shifted by one. When
+that is not known, it looks at the subscript:
 
 - a string literal, or a value known to be a string, is used as it is;
 - an integer literal, or a value known to be a number, is shifted by one;
 - anything else goes through a small `__key` helper, which shifts numbers and
   leaves everything else alone, at runtime.
 
-A value is known to be a string or a number from its annotation, a literal,
-the builtin or method that produced it, a `range()` or `enumerate()` loop
-variable, or every assignment to the name agreeing. Integer keys in a dict
-are treated as positions; use string keys.
+A value's type is known from its annotation, a literal, the builtin, method or
+operator that produced it, a `range()` or `enumerate()` loop variable, or
+every assignment to the name agreeing. So after `counts = {}`, `counts[0]` is
+the key `0`. A table that comes from elsewhere -- a Redis reply,
+`cjson.decode`, a helper's parameter -- is not known, and an integer subscript
+on it is taken to be a position.
 
 `items[-1]` compiles to `items[#items]`, which needs a name to count back from.
 Indexing a string gives a one-character string, as it does in Python, through
-`string.sub`. Slices, `v[i:j]`, work on lists and strings, with negative and
-missing bounds; a slice with a step is refused.
+`string.sub`. Slices, `v[i:j]` and `v[i:j:k]`, work on lists and strings, with
+negative and missing bounds, and bounds are clamped exactly as Python clamps
+them. A negative step walks backwards, so `word[::-1]` reverses.
 
 ## Assignment scope is closed
 
@@ -50,8 +55,10 @@ the top of the script, so it does not silently read back `nil`.
 
 Lua's `+` is only arithmetic. It will add `"1" + "2"` to `3`. So `+`
 compiles to Lua's `..` wherever either side is known to be a string, as
-above, and `"=" * n` to `string.rep`. Where neither side is known, `+` stays
-arithmetic; use an f-string to concatenate two values of unknown type.
+above, to Lua's `+` wherever either side is known to be a number, and
+`"=" * n` to `string.rep`. Where neither side is known, as with two Redis
+replies, a small `__add` helper decides at runtime: two strings are joined,
+two lists are joined into a new list, and anything else is added.
 
 The string methods compile to Lua's string library, and to small helpers where
 Python means something Lua's own functions do not:
@@ -60,7 +67,9 @@ Python means something Lua's own functions do not:
   substring. `string.find` would read `.` as a pattern.
 - **`strip`, `lstrip` and `rstrip`** strip whitespace, and take no argument.
 - **`x in s`** is a substring test on a string. On a list it is an element test;
-  on a dict it is a key test.
+  on a dict it is a key test. A table whose type is not known, such as a
+  decoded JSON value, is taken to be a dict when any of its keys is not a list
+  position, and a list otherwise.
 
 `"%s: %d" % (name, n)` and f-string format specs such as `{price:8.2f}` compile
 to `string.format`. Width, precision, sign and zero padding are supported. A
@@ -88,8 +97,10 @@ becomes the same kind of function, because `c and a or b` is wrong whenever
 `.items()`, `.keys()` and `.values()` compile to Lua's `pairs()`, which visits
 entries in no fixed order. Sort the result if the order reaches the caller.
 
-Iterating a dict directly with `for k in d` walks its array part, which a dict
-does not have, so the loop never runs. Say `.keys()`.
+`for k in d` walks the keys of a dict the compiler knows to be one, as
+`.keys()` does, and `len(d)` counts them. On a table whose type is not known,
+say `.keys()`: there, `for k in d` and `len(d)` see only list positions, which
+a dict does not have.
 
 ## Redis replies are flat lists, not dicts
 
@@ -149,7 +160,10 @@ kept, whether or not something catches it.
 
 ## A loop variable does not outlive its loop
 
-Unlike in Python.
+Unlike in Python. Lua also gives each step of a loop a variable of its own,
+which a function defined inside the loop would keep, where in Python every
+step shares one. So a `lambda` or a helper function that reads a loop variable
+is refused; pass the value in as a parameter instead.
 
 ## A nil inside a returned table truncates the reply
 

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/docs/reference/supported-subset.md

@@ -13,12 +13,14 @@ language with a faithful Lua meaning is accepted.
   `assert`.
 - **Loops:** `for ... in` over a table, `range()`, `enumerate()`, or a dict's
   `.items()`, `.keys()` and `.values()`, binding a name or a tuple of names.
-- **Helper functions** defined with `def` at the top level of the body. They
-  can call each other and themselves.
-- **Expressions:** comparisons; arithmetic; `in` and `not in`; `and`/`or`, and
-  `a if c else b`, both as values; list and dict literals.
-- **Subscripts:** indices, dict keys, negative literal indices on a name, and
-  slices without a step, of lists and strings.
+- **Helper functions** defined with `def` at the top level of the body, and
+  `lambda` wherever an expression can go. They can call each other and
+  themselves, and be passed to a helper that calls them.
+- **Expressions:** comparisons, chained ones such as `0 < n <= limit`
+  included; arithmetic; `in` and `not in`; `and`/`or`, and `a if c else b`,
+  both as values; list and dict literals.
+- **Subscripts:** indices, dict keys of any type, negative literal indices on
+  a name, and slices of lists and strings, with a step or without.
 - **Strings:** f-strings with format specs; `%` formatting; `+` and `*` on a
   string; `str.join`, `upper`, `lower`, `strip`, `lstrip`, `rstrip`,
   `startswith`, `endswith`, `find`, `split` and `replace`.
@@ -37,11 +39,11 @@ Everything else raises
 with a caret under the line at fault:
 
 ```
-chained comparisons are not supported
+math.log() with a base is not supported
   File "/srv/app/limits.py", line 12
-    if 0 < n < limit:
-       ^
-  hint: Split 'a < b < c' into 'a < b and b < c'.
+    buckets = math.log(n, 2)
+              ^
+  hint: Lua 5.1's math.log takes no base; divide by math.log(base) instead.
 ```
 
 Failing at import, loudly, is deliberate. A body that looks like Python but is

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "redis-lua-py"
-version = "0.6.0"
+version = "0.7.0"
 description = "Write Redis Lua scripts as real Python functions, not strings."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -41,6 +41,9 @@ dev = [
     "zensical>=0.0.61",
     # typing.assert_type, for tests/test_typing.py, arrived in Python 3.11.
     "typing_extensions>=4.2; python_version < '3.11'",
+    # Tested against, never required: coredis shapes a command differently
+    # from redis-py, and tests/test_coredis.py runs the same scripts through it.
+    "coredis>=6.9",
 ]
 
 [build-system]

{redis_lua_py-0.6.0 → redis_lua_py-0.7.0}/src/redis_lua_py/__init__.py

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

redis_lua_py-0.7.0/src/redis_lua_py/_compile/__init__.py

@@ -0,0 +1,181 @@
+"""Turn a Python function into Lua.
+
+The supported subset is deliberately small. Anything outside it raises
+:class:`UnsupportedSyntax` pointing at the offending line, because a script
+body that *looks* like Python but is never executed by Python is exactly the
+place where a silent mistranslation would be most expensive.
+
+The compiler itself is in layers, described in ``base``.
+"""
+
+from __future__ import annotations
+
+import ast
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from .. import _lua as lua
+from .._script import CompiledScript
+from ..errors import CompileError, NilTruncationWarning, render_location
+from .analysis import unassigned_in_returns
+from .helpers import helper_order, helper_source
+from .source import parse_function, provenance
+from .statements import Compiler
+
+__all__ = [
+    "SCRIPT_FLAGS",
+    "CompiledBody",
+    "check_flags",
+    "compile_body",
+    "compile_function",
+    "helper_order",
+    "helper_source",
+    "provenance",
+]
+
+R = TypeVar("R")
+
+
+#: The flags Redis 7 defines, for a script's `#!lua` line and for a function.
+SCRIPT_FLAGS = frozenset(
+    {"no-writes", "allow-oom", "allow-stale", "no-cluster", "allow-cross-slot-keys"}
+)
+
+
+def check_flags(flags: tuple[str, ...], *, owner: str) -> tuple[str, ...]:
+    """Refuse a flag Redis does not define, where the mistake is made."""
+    for flag in flags:
+        if flag not in SCRIPT_FLAGS:
+            raise CompileError(
+                f"{owner}: unknown flag {flag!r}; Redis defines {', '.join(sorted(SCRIPT_FLAGS))}"
+            )
+    return flags
+
+
+@dataclass(frozen=True)
+class CompiledBody:
+    """A function compiled to Lua, before it is framed as a script or a library function."""
+
+    name: str
+    #: The prelude binding KEYS and ARGV, and the statements; no helpers.
+    body: str
+    #: The helpers the body calls, in the order they must be emitted.
+    helpers: tuple[str, ...]
+    params: tuple[str, ...]
+    keys: tuple[str, ...]
+    args: tuple[str, ...]
+    variadic_key: str | None
+    variadic_arg: str | None
+    doc: str | None
+    filename: str
+    first_lineno: int
+    #: Each parameter's annotation as written, in the order of ``params``.
+    param_annotations: tuple[str | None, ...] = ()
+    return_annotation: str | None = None
+    keyword_only: tuple[str, ...] = ()
+
+    @property
+    def provenance(self) -> str:
+        return f"{provenance(self.filename)}:{self.first_lineno}"
+
+
+def compile_function(
+    func: Callable[..., R],
+    *,
+    name: str | None = None,
+    header: bool = True,
+    flags: tuple[str, ...] = (),
+) -> CompiledScript[R]:
+    compiled = compile_body(func, name=name)
+    parts: list[str] = []
+    if flags:
+        # Redis only reads a script's flags from a shebang on its first line.
+        parts.append(f"#!lua flags={','.join(flags)}")
+    if header:
+        parts.append(
+            f"-- {compiled.name}\n"
+            f"-- Generated by redis-lua-py from {compiled.provenance}. Do not edit."
+        )
+    parts.extend(helper_source(helper) for helper in compiled.helpers)
+    parts.append(compiled.body)
+
+    return CompiledScript(
+        name=compiled.name,
+        lua="\n".join(parts) + "\n",
+        params=compiled.params,
+        keys=compiled.keys,
+        args=compiled.args,
+        variadic_key=compiled.variadic_key,
+        variadic_arg=compiled.variadic_arg,
+        doc=compiled.doc,
+        source=f"{compiled.filename}:{compiled.first_lineno}",
+        param_annotations=compiled.param_annotations,
+        return_annotation=compiled.return_annotation,
+        keyword_only=compiled.keyword_only,
+    )
+
+
+def compile_body(func: Callable[..., Any], *, name: str | None = None) -> CompiledBody:
+    node, filename, first_lineno, lines = parse_function(func)
+    compiler = Compiler(
+        node,
+        filename=filename,
+        first_lineno=first_lineno,
+        lines=lines,
+        # Receivers are resolved against the defining module, so the namespace
+        # is recognised under whatever name it was imported as.
+        globalns=getattr(func, "__globals__", {}),
+    )
+
+    prelude = compiler.compile_signature()
+    compiler.collect_assigned()
+
+    body = node.body
+    doc = ast.get_docstring(node)
+    if doc is not None:
+        body = body[1:]
+
+    statements = compiler.block(body)
+    if compiler.hoisted:
+        prelude.append(lua.Local(sorted(set(compiler.hoisted)), []))
+
+    for element, unassigned in unassigned_in_returns(body, set(compiler.params), compiler.known):
+        warnings.warn_explicit(
+            render_location(
+                f"{unassigned!r} is not assigned on every path to this return, and a nil "
+                "in a returned table truncates the reply there",
+                filename=filename,
+                lineno=first_lineno + element.lineno - 1,
+                col=element.col_offset,
+                source_line=lines[element.lineno - 1] if element.lineno <= len(lines) else None,
+                hint="Give it a value before the branch, so that every branch returns a "
+                "table of the same shape.",
+            ),
+            NilTruncationWarning,
+            filename,
+            first_lineno + element.lineno - 1,
+        )
+
+    return CompiledBody(
+        name=name or func.__name__,
+        body=lua.emit(prelude + statements).rstrip(),
+        helpers=tuple(helper_order(compiler.helpers)),
+        params=tuple(compiler.params),
+        keys=tuple(compiler.keys),
+        args=tuple(compiler.args),
+        variadic_key=compiler.variadic_key,
+        variadic_arg=compiler.variadic_arg,
+        doc=doc,
+        filename=filename,
+        first_lineno=first_lineno,
+        # Kept as source text: the compiler does not need them, but a generated
+        # function repeats them in its signature.
+        param_annotations=tuple(
+            None if arg.annotation is None else ast.unparse(arg.annotation)
+            for arg in [*node.args.args, *node.args.kwonlyargs]
+        ),
+        return_annotation=None if node.returns is None else ast.unparse(node.returns),
+        keyword_only=tuple(arg.arg for arg in node.args.kwonlyargs),
+    )