redis-lua-py 0.1.0__tar.gz → 0.2.0__tar.gz

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

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

redis_lua_py-0.2.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries
+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.2.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.1.0...v0.2.0) (2026-09-12)
+
+Everything raised by the first adoption report of 0.1.0
+([#2](https://github.com/IgnaceMaes/redis-lua-py/pull/2),
+[0ef4ed2](https://github.com/IgnaceMaes/redis-lua-py/commit/0ef4ed23dd3cef8616ab5132d7a9089e38bb518a)).
+
+### ⚠ BREAKING CHANGES
+
+- A command name Redis does not have is now refused at import rather than
+  compiled, and a literal `None` inside a returned table is refused. Both
+  previously compiled to Lua that failed, or silently truncated, at runtime.
+- The generated header's source path is now relative to the project root,
+  which changes the SHA of every script — once.
+
+### Added
+
+- Command names are checked at compile time against a table generated from the
+  Redis source (`scripts/generate_commands.py`, tracking Redis 8.10), so a name
+  Redis does not have is refused with a caret and a suggestion rather than
+  raising the first time its branch runs.
+- The redis-py spellings that name exactly one command are translated instead
+  of refused: `redis.delete(k)` compiles to `redis.call('DEL', k)`.
+- Container 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')`.
+- Module-level `int`, `float`, `str`, `bytes` and `bool` constants are folded
+  into a script body, including through a dotted name such as an `IntEnum`
+  member or a settings attribute. A body no longer has to repeat a number its
+  own module already names.
+- The return annotation is carried to the caller: a script is a
+  `CompiledScript[R]`, `bind()` gives a `BoundScript`, and an async client
+  yields `Awaitable[R]` rather than `Any`.
+- `@script(header=False)` drops the provenance comment, for anyone who wants
+  the script body and nothing else.
+- `NilTruncationWarning` (and `RedisLuaWarning`) are raised when a name that is
+  not assigned on every path is returned inside a table, where it would
+  truncate the reply.
+
+### Fixed
+
+- The generated header recorded an absolute source path. Since the header is
+  part of the body, and the body is what `EVALSHA` hashes, the same script had
+  a different SHA on a laptop, in CI and in a container, and put build-machine
+  paths on the Redis server. The path is now relative to the project root.
+- A `bytes` literal in a body was decoded with `surrogateescape`, which could
+  not survive the script being sent to Redis as text. Bytes literals are now
+  emitted as numeric escapes, so they arrive exactly.
+- A NUL in a Lua string literal was written `\0`, which Lua reads together
+  with a following digit as a different byte. It is now `\000`.
+- `redis.sort_ro(...)` and the other `_RO` variants split into two tokens,
+  making the `RO` a stray argument. Their underscore is part of the wire name
+  and is now kept.
+
+### Documentation
+
+- Binary values through `ARGV` are now a stated guarantee with a test that
+  round-trips non-UTF-8 bytes through `ARGV`, a stored value and a returned
+  `GETRANGE`.
+- A returned table is truncated at the first genuine `nil` -- but a command
+  with nothing to return hands Lua `false`, which becomes a null *element* and
+  does not truncate. Both are written down, in "Where Lua differs from Python".
+- "Testing your scripts": snapshot `.lua` in a golden test, and run behaviour
+  against `fakeredis[lua]` without a server.
+- Scripts belong at module level, where they compile once at import.
+- `float` round-trips through Lua's `%.14g` number formatting; `bool` encodes
+  to `"1"` / `"0"`; `bytes` is a passthrough.
+
+## 0.1.0 (2026-09-12)
+
+First release.
+
+### Added
+
+- `@script`, which compiles a Python function to Redis Lua at import time.
+- `Key` annotation marking a parameter as `KEYS` rather than `ARGV`, so that
+  Redis Cluster can route the script correctly.
+- `int` and `float` annotations wrap their argument in `tonumber`, since `ARGV`
+  always arrives as a string.
+- One script object drives both sync and async redis-py clients, deferring to
+  redis-py for `EVALSHA`, script caching and the `NOSCRIPT` reload.
+- `redis.*` / `call.*` command calls, with underscores splitting into
+  subcommand tokens, plus `cjson.encode` / `cjson.decode`.
+- The generated Lua is exposed on `.lua` for review and golden testing.
+- `UnsupportedSyntax` reports the file, line and column of anything outside the
+  supported subset, with a hint for what to write instead.
+- The command namespace is resolved by value rather than by name, so it works
+  under any alias (`from redis_lua_py import redis as r`). A receiver that
+  turns out to be redis-py itself is refused with an explanation, instead of
+  being compiled against the client library.
+- `script.bind(client)` returns a callable with the client attached, for code
+  that would otherwise repeat it at every call site.
+
+### Semantics closed between Python and Lua
+
+- Truthiness: `0`, `''` and empty tables are falsy, as in Python.
+- Missing values: a Redis command returning nothing gives Lua `false`, not
+  `nil`, so `is None` accepts both and evaluates its operand once.
+- Indexing: Python's 0-based indices are translated to Lua's 1-based tables.
+- Scope: a name first assigned inside a block is hoisted, because Lua's `local`
+  is block-scoped where Python's assignment is function-scoped.

{redis_lua_py-0.1.0 → redis_lua_py-0.2.0}/CONTRIBUTING.md

@@ -10,6 +10,18 @@ uv run pytest && uv run ruff check && uv run ruff format --check && uv run mypy
 See the [README](README.md#development) for running the suite against a live
 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:
+
+```sh
+uv run python scripts/generate_commands.py 8.10.1
+```
+
+A stale table can never block a caller: `redis.call('NEW.CMD', ...)` is
+deliberately never checked.
+
 ## Commit messages
 
 Pull requests are squash-merged, so **the PR title becomes the commit subject

{redis_lua_py-0.1.0 → redis_lua_py-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.1.0
+Version: 0.2.0
 Summary: Write Redis Lua scripts as real Python functions, not strings.
 Project-URL: Homepage, https://github.com/ignacemaes/redis-lua-py
 Project-URL: Issues, https://github.com/ignacemaes/redis-lua-py/issues
@@ -58,6 +58,10 @@ imported, compiled to Lua, and sent to Redis with `EVALSHA`. Your editor
 highlights it, your linter sees it, and `mypy` checks the signature — none of
 which is true of a string.
 
+Define scripts at module level, where they compile once at import. A script
+defined inside a function recompiles on every call, and one defined through
+`exec` has no source to read and is refused.
+
 ```python
 from redis import Redis
 
@@ -84,7 +88,7 @@ Nothing is hidden. Every script exposes the Lua it produced:
 
 ```lua
 -- rate_limit
--- Generated by redis-lua-py from /srv/app/limits.py:6. Do not edit.
+-- Generated by redis-lua-py from src/limits.py:6. Do not edit.
 local key = KEYS[1]
 local limit = tonumber(ARGV[1])
 local ttl = tonumber(ARGV[2])
@@ -101,6 +105,12 @@ return limit - current
 Read it in review, paste it into `redis-cli`, check it into a golden test. The
 point of this library is to generate Lua you would have been willing to write.
 
+The header is part of the body, and the body is what `EVALSHA` hashes, so the
+path in it is relative to your project root rather than absolute — the same
+script has the same SHA on a laptop, in CI and in a container, and the server's
+script cache is cold once per script rather than once per environment. Pass
+`@script(header=False)` to drop the comment entirely.
+
 ## Keys and arguments
 
 A parameter annotated `Key` becomes `KEYS`, in declaration order. Everything
@@ -114,6 +124,17 @@ script will execute on the wrong node. Annotate every key.
 `float` wraps it in `tonumber` for you, so `limit` above is a number by the
 time your comparison runs.
 
+Annotate `float` for arithmetic, not for a value you mean to write back
+unchanged. `tonumber` makes it a Lua number, and Lua renders a number back to
+text with `%.14g`, so a value with more significant digits than that does not
+come back as it went in. Annotate `str` and call `str()` at the call site when
+the value is only being carried.
+
+`bool` encodes to `"1"` or `"0"`. Paired with an `int` annotation that deletes
+the `1 if flag else 0` from the call site: pass `True`, and the body gets `1`.
+
+`bytes` is passed through untouched — see [Binary values](#binary-values).
+
 Scripts accept positional or keyword arguments; keyword is clearer at the call
 site and is what the errors suggest.
 
@@ -157,6 +178,43 @@ split into subcommand tokens, so `redis.script_load(x)` compiles to
 `redis.log` and `cjson.encode` / `cjson.decode` pass through under their own
 names.
 
+### Names are checked, not just uppercased
+
+Uppercasing turns *any* attribute into a plausible command, which makes a name
+Redis does not have the one mistake with nothing standing in its way: it
+compiles, it survives review, and it raises the first time its branch runs —
+inside a script whose whole purpose was to be atomic.
+
+So command names are checked at compile time against Redis' own command table,
+and a miss is refused where you can see it:
+
+```
+Redis has no EXPIRES command
+  File "/srv/app/limits.py", line 14
+    redis.expires(key, 60)
+    ^
+  hint: Did you mean redis.expire()?
+```
+
+The handful of redis-py method names that do not match the wire name are
+translated rather than refused, because each names exactly one command and
+nothing else: `redis.delete(k)` compiles to `redis.call('DEL', k)`. Container
+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')`.
+
+`redis.call(...)` is deliberately never checked. It is the escape hatch for
+module commands, which are spelled with a dot anyway, and for anything a newer
+server has that the table does not:
+
+```python
+redis.call("JSON.SET", doc, "$.status", '"done"')
+```
+
+The table is generated from the command definitions in the Redis source — the
+same files the server is built from — and currently tracks Redis 8.10.
+Regenerate it with `uv run python scripts/generate_commands.py`.
+
 ### When the client is imported too
 
 Import the client *class* and nothing collides, because the name `redis` is
@@ -177,7 +235,7 @@ from redis_lua_py import redis as r  # the script namespace
 
 
 @script
-def claim(queue: Key, now: int) -> list[str]:
+def claim(queue: Key, now: int) -> list[bytes]:
     return r.zrangebyscore(queue, 0, now)
 
 
@@ -200,12 +258,123 @@ client library:
   redis as r), or the client under another name (import redis as redis_client).
 ```
 
+## Constants from the module
+
+A script has no closure: the body runs on the server, where nothing from your
+Python process exists. A module-level constant is the exception worth making,
+because it is already a literal and can simply be folded in.
+
+```python
+SESSION_TTL_SECONDS = 30 * 60
+
+
+@script
+def touch_session(session: Key) -> int:
+    hits = redis.incr(session)
+    redis.expire(session, SESSION_TTL_SECONDS)  # -> redis.call('EXPIRE', session, 1800)
+    return hits
+```
+
+`int`, `float`, `str`, `bytes` and `bool` are folded, including through a
+dotted name — an `IntEnum` member, or an attribute of a settings object.
+Anything else is refused with the same caret as everything else, because there
+is no literal to fold:
+
+```
+'SESSION_TTL' is a module-level timedelta, which has no Lua literal
+  File "/srv/app/sessions.py", line 18
+    redis.expire(session, SESSION_TTL)
+                          ^
+  hint: Only an int, float, str, bytes or bool constant is folded into the
+  script. Pass anything else as an argument, or name the literal it reduces to.
+```
+
+The value is read once, when the module is imported and the script compiles.
+A name rebound afterwards does not change the script — which is what "constant"
+means, but worth saying out loud.
+
+## Binary values
+
+Nothing here decodes. `KEYS`, `ARGV` and every Lua string are byte strings, so
+a `bytes` argument arrives in the script as exactly those bytes and comes back
+as exactly those bytes.
+
+```python
+import zlib
+
+
+@script
+def cache_compressed(key: Key, blob: bytes, ttl: int) -> int:
+    redis.set(key, blob)
+    redis.expire(key, ttl)
+    return len(blob)
+
+
+cache_compressed(client, key="report:42", blob=zlib.compress(report), ttl=300)
+```
+
+A `bytes` annotation is a passthrough: no `tonumber`, no decoding, no round
+trip through text. `memoryview` is accepted the same way. A `bytes` literal in
+a body is emitted as numeric escapes — `b"\x00\xff"` becomes `'\000\255'` —
+so it survives the journey to the server, where the script itself travels as
+text.
+
+This is a guarantee rather than an observation:
+[tests/test_binary.py](tests/test_binary.py) round-trips non-UTF-8 bytes
+through `ARGV`, through a stored value, and back out of a returned `GETRANGE`,
+against both fakeredis and a real server.
+
+## What the caller gets
+
+The return annotation describes the **caller's** side: the value that comes
+back from Redis, not the value the body hands to Lua. The compiler does not
+read it at all.
+
+It is carried through to the call, so a script is a `CompiledScript[R]` and
+`rate_limit` above returns an `int` rather than `Any`:
+
+```python
+remaining = rate_limit(client, key="user:42", limit=10, ttl=60)  # int
+```
+
+An async client gives you `Awaitable[R]`, so `await` gets you back to `R`.
+`bind` carries it too, on both.
+
+Redis renders every reply as bytes, which is what to annotate — and what to
+write in the body when a branch needs a placeholder:
+
+```python
+@script
+def preview(doc: Key) -> list[int | bytes]:
+    size = redis.strlen(doc)
+    if size == 0:
+        return [0, b""]
+    return [1, redis.getrange(doc, 0, 1023)]
+```
+
+`b""` and `""` compile to the same Lua string; only one of them also describes
+what the caller receives, which keeps the body and the signature agreeing
+about the same thing.
+
+Inside a body, every value that came from Redis is `Any` — nothing about
+`redis.get(k)` is knowable ahead of time. Under `mypy --strict` that makes
+`warn_return_any` fire on a body that returns a command result directly, on
+the one function whose body Python never runs. Turn it off for the module your
+scripts live in:
+
+```toml
+[[tool.mypy.overrides]]
+module = "myapp.scripts"
+warn_return_any = false
+```
+
 ## The supported subset
 
 Supported: assignment, augmented assignment, `if`/`elif`/`else`, `for ... in`
 over a table or `range()`, `while`, `break`, `return`, comparisons, arithmetic,
 f-strings, list and dict literals, `len()`, `.append()`, `int()`, `float()`,
-`str()`, `min()`, `max()`, `abs()`, and calls into `redis` and `cjson`.
+`str()`, `min()`, `max()`, `abs()`, module-level constants, and calls into
+`redis` and `cjson`.
 
 Everything else raises `UnsupportedSyntax` when the module is imported, with a
 caret under the line at fault:
@@ -257,6 +426,33 @@ nest the rest of the body.
 
 **A loop variable does not outlive its loop,** unlike in Python.
 
+**A nil inside a returned table truncates the reply.** Redis converts a
+returned array by walking it from the first element and stopping at the first
+`nil`, so the caller gets a shorter list rather than a null in the middle of
+one.
+
+Which values are actually nil is the part worth being exact about. A command
+with nothing to return hands Lua `false`, and `false` converts to a null
+*element* without ending the array — `return [1, redis.get(missing), 3]` really
+does reach the caller as `[1, None, 3]`. What truncates is a genuine nil, and
+in practice that means a name that was not assigned on this path. The compiler
+warns where it can see one:
+
+```
+'first' is not assigned on every path to this return, and a nil in a returned
+table truncates the reply there
+  File "/srv/app/queue.py", line 31
+    return [1, first, count]
+               ^
+  hint: Give it a value before the branch, so that every branch returns a
+  table of the same shape.
+```
+
+and refuses a `None` written out in the table, since that one is never what
+anybody meant. Silence the warning with
+`warnings.filterwarnings("ignore", category=NilTruncationWarning)` if your
+script really does mean to stop there.
+
 **Return values follow Redis' own conversion rules:** `True` becomes `1`,
 `False` and `None` become nil, floats are truncated to integers. Return a
 string, or `cjson.encode(...)`, when you need one preserved exactly.
@@ -265,7 +461,7 @@ string, or `cjson.encode(...)`, when you need one preserved exactly.
 
 ```python
 @script
-def claim_jobs(queue: Key, processing: Key, now: int, limit: int) -> list[str]:
+def claim_jobs(queue: Key, processing: Key, now: int, limit: int) -> list[bytes]:
     """Atomically move due jobs from a sorted set into a processing hash."""
     ids = redis.zrangebyscore(queue, 0, now, "LIMIT", 0, limit)
     claimed = []
@@ -293,6 +489,48 @@ end
 return claimed
 ```
 
+## Testing your scripts
+
+Replacing working Lua in a production path needs evidence. Two things supply
+most of it, and both are short.
+
+**Snapshot the Lua.** `.lua` is the whole script, so a golden test is a string
+comparison — and the diff against the Lua you are replacing is the review.
+
+```python
+from pathlib import Path
+
+GOLDEN = Path(__file__).parent / "golden" / "rate_limit.lua"
+
+
+def test_generated_lua_is_unchanged():
+    assert rate_limit.lua == GOLDEN.read_text()
+```
+
+The header path is repo-relative, so this is stable across machines and CI.
+Use `@script(header=False)` if you would rather compare the body alone.
+
+**Run the behaviour, without a server.**
+[fakeredis](https://github.com/cunla/fakeredis-py) embeds a real Lua
+interpreter, so your script executes for real against an in-process server:
+
+```python
+import fakeredis
+
+
+def test_rate_limit_refuses_past_the_limit():
+    client = fakeredis.FakeRedis()
+
+    assert rate_limit(client, key="u:42", limit=2, ttl=60) == 1
+    assert rate_limit(client, key="u:42", limit=2, ttl=60) == 0
+    assert rate_limit(client, key="u:42", limit=2, ttl=60) == -1
+```
+
+Install it with `uv add --dev "fakeredis[lua]"`; the `lua` extra is what brings
+the interpreter. This library's own suite runs that way and against a real
+Redis in CI, and the two agree — including on reply conversion, which is the
+part you would most want a real server for.
+
 ## Development
 
 ```bash
@@ -310,6 +548,13 @@ run them against a live Redis:
 REDIS_URL=redis://localhost:6379/0 uv run pytest
 ```
 
+`src/redis_lua_py/_commands.py` is generated from the Redis source. Refresh it
+when a Redis release adds commands:
+
+```bash
+uv run python scripts/generate_commands.py 8.10.1
+```
+
 Pull requests are squash-merged and their titles must follow
 [Conventional Commits](https://www.conventionalcommits.org/): the title becomes
 the changelog entry and decides the version bump. See