redis-lua-py 0.3.0__tar.gz → 0.5.0__tar.gz

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

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

{redis_lua_py-0.3.0 → redis_lua_py-0.5.0}/CHANGELOG.md

@@ -7,6 +7,28 @@ 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.5.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.4.0...v0.5.0) (2026-09-12)
+
+
+### Added
+
+* compile continue, try/except/else/finally, raise and assert ([#11](https://github.com/IgnaceMaes/redis-lua-py/issues/11)) ([aeca575](https://github.com/IgnaceMaes/redis-lua-py/commit/aeca5757fffe42e88b49b18fa4d3fe91897fad2e))
+* compile membership, slicing, string methods and formatting, and key variables ([#13](https://github.com/IgnaceMaes/redis-lua-py/issues/13)) ([4880c81](https://github.com/IgnaceMaes/redis-lua-py/commit/4880c8156d849755259dea9a8c29cf69392ecd7e))
+* compile redis functions libraries, and script flags ([#15](https://github.com/IgnaceMaes/redis-lua-py/issues/15)) ([5980f03](https://github.com/IgnaceMaes/redis-lua-py/commit/5980f0317acbe9a7a96ffaff029f2d76143b7e32))
+* generate lua ahead of time for code that ships without redis-lua-py ([#14](https://github.com/IgnaceMaes/redis-lua-py/issues/14)) ([83d6b9d](https://github.com/IgnaceMaes/redis-lua-py/commit/83d6b9da0b540cefc0be9ec51fbead54c4d0fade))
+
+## [0.4.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.3.0...v0.4.0) (2026-09-12)
+
+
+### Added
+
+* compile variable keys, splat calls, and/or values, helper functions and dict loops ([#10](https://github.com/IgnaceMaes/redis-lua-py/issues/10)) ([271f3f6](https://github.com/IgnaceMaes/redis-lua-py/commit/271f3f6be23d78246d91cde5de4fec05cee28832))
+
+
+### Fixed
+
+* stop silently mistranslating reassigned parameters, infinity, == None and set_repl ([#8](https://github.com/IgnaceMaes/redis-lua-py/issues/8)) ([930c382](https://github.com/IgnaceMaes/redis-lua-py/commit/930c38283f366fd9042c4cc20cdf7eeb34e2d8a5))
+
 ## [0.3.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.2.1...v0.3.0) (2026-09-12)
 
 

{redis_lua_py-0.3.0 → redis_lua_py-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.3.0
+Version: 0.5.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/
@@ -144,6 +144,14 @@ script cache is cold once per script rather than once per environment.
   the same script object, 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/)**
+  for libraries — `python -m redis_lua_py generate` writes the Lua to a module
+  of plain strings, so your users never depend on this package, and `--check`
+  keeps it current in CI.
+- **[Redis Functions](https://ignacemaes.com/redis-lua-py/guide/redis-functions/)** —
+  the same Python compiles into a function library, loaded with `FUNCTION LOAD`
+  on first use and called with `FCALL`, and scripts take Redis 7 flags such as
+  `no-writes`.
 - **[The gaps between Lua and Python](https://ignacemaes.com/redis-lua-py/reference/lua-vs-python/)**
   are closed or refused — truthiness, 1-based indexing, `false` versus `nil`,
   block scope, and the nil that truncates a returned table.

{redis_lua_py-0.3.0 → redis_lua_py-0.5.0}/README.md

@@ -118,6 +118,14 @@ script cache is cold once per script rather than once per environment.
   the same script object, 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/)**
+  for libraries — `python -m redis_lua_py generate` writes the Lua to a module
+  of plain strings, so your users never depend on this package, and `--check`
+  keeps it current in CI.
+- **[Redis Functions](https://ignacemaes.com/redis-lua-py/guide/redis-functions/)** —
+  the same Python compiles into a function library, loaded with `FUNCTION LOAD`
+  on first use and called with `FCALL`, and scripts take Redis 7 flags such as
+  `no-writes`.
 - **[The gaps between Lua and Python](https://ignacemaes.com/redis-lua-py/reference/lua-vs-python/)**
   are closed or refused — truthiness, 1-based indexing, `false` versus `nil`,
   block scope, and the nil that truncates a returned table.

redis_lua_py-0.5.0/docs/guide/build-time.md

@@ -0,0 +1,152 @@
+# Shipping without the dependency
+
+Calling a script needs redis-lua-py at runtime: it compiles the body when the
+module is imported, and resolves keys and arguments on every call. In an
+application that is a dependency you chose. In a library it is a dependency
+every one of your users inherits, along with the import-time compile, for Lua
+that never changes between your releases.
+
+So a library can compile ahead of time instead. You write the scripts with
+`@script`, as anywhere else, and generate plain Lua from them while you
+develop. What you ship is that Lua: no import of this package, no compile
+step, nothing added to your dependencies.
+
+## Generate a module of strings
+
+Keep the scripts outside the package you ship, and redis-lua-py in your
+development dependencies:
+
+```bash
+uv add --dev redis-lua-py
+```
+
+```
+myproj/
+├── pyproject.toml
+├── redis_scripts/
+│   └── limits.py      # the @script functions; never shipped
+└── src/myproj/
+    ├── _lua.py        # generated, checked in, shipped
+    └── limits.py      # the code that runs them
+```
+
+Then, from the project root:
+
+```bash
+python -m redis_lua_py generate redis_scripts.limits --out src/myproj/_lua.py
+```
+
+The output imports nothing. Each script is a string constant, named after the
+function in capitals, with a comment recording the order its keys and
+arguments go in:
+
+```python
+"""Redis Lua scripts compiled by redis-lua-py from redis_scripts.limits. Do not edit.
+
+Regenerate with:
+
+    python -m redis_lua_py generate redis_scripts.limits --out src/myproj/_lua.py
+"""
+
+__all__ = [
+    "RATE_LIMIT",
+]
+
+# rate_limit -- KEYS: key; ARGV: limit, ttl
+RATE_LIMIT = """\
+-- rate_limit
+-- Generated by redis-lua-py from redis_scripts/limits.py:6. Do not edit.
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local ttl = tonumber(ARGV[2])
+local current = redis.call('INCR', key)
+if current == 1 then
+  redis.call('EXPIRE', key, ttl)
+end
+if current > limit then
+  return -1
+end
+return limit - current
+"""
+```
+
+Your library runs it the way it would run any Lua, through redis-py:
+
+```python
+from redis import Redis
+
+from ._lua import RATE_LIMIT
+
+
+class Limiter:
+    def __init__(self, client: Redis) -> None:
+        self._rate_limit = client.register_script(RATE_LIMIT)
+
+    def hit(self, key: str, limit: int, ttl: int) -> int:
+        return self._rate_limit(keys=[key], args=[limit, ttl])
+```
+
+Every path in the file is relative to the project root, so it comes out
+byte-for-byte the same on every machine, and regenerating it without a change
+to the scripts leaves it untouched.
+
+## Or one `.lua` file per script
+
+Pass a directory instead of a `.py` path:
+
+```bash
+python -m redis_lua_py generate redis_scripts.limits --out src/myproj/lua/
+```
+
+That writes `rate_limit.lua` and a file for every other script, for a library
+that already loads its Lua from files. When a script is renamed or removed, its
+old file is deleted. Only files carrying the generated header are ever
+deleted, so hand-written Lua in the same directory is safe. The flip side is
+that a script compiled with `header=False` leaves its old file behind when it
+is renamed.
+
+## Keep it current
+
+Checking generated code in only works if something notices when it goes stale.
+`--check` writes nothing, and exits 1 with a diff if the output no longer
+matches the scripts. Run it in CI:
+
+```yaml
+- run: uv run python -m redis_lua_py generate redis_scripts.limits --out src/myproj/_lua.py --check
+```
+
+Or as a test, which fails with the same diff:
+
+```python
+from redis_lua_py import codegen
+
+
+def test_generated_lua_is_current():
+    codegen.check("redis_scripts.limits", "src/myproj/_lua.py")
+```
+
+A test imports `redis_scripts.limits` like any other module, so the project
+root has to be on the path. With pytest, set `pythonpath = ["."]` under
+`[tool.pytest.ini_options]`.
+
+## What you give up
+
+The generated Lua is identical to what a `@script` call would send, so the
+behaviour inside Redis is the same. What stays behind is the caller's side:
+
+- **Argument checking.** A call through `CompiledScript` refuses a missing,
+  misspelled or duplicated argument, and a value such as `None` that has no
+  Redis representation. With a plain string, you pass `keys` and `args` in the
+  order the comment records, and nothing checks them.
+- **Booleans.** A `CompiledScript` sends `True` as `1`. redis-py refuses a
+  `bool` outright, so convert it yourself.
+- **Cluster pipelines.** A `CompiledScript` switches to `EVAL` on a redis-py
+  cluster pipeline, which refuses `EVALSHA`. A registered string does not.
+
+Keep writing tests that call the scripts through `@script` against
+[fakeredis](testing.md#run-the-behaviour-without-a-server) as well: those run
+the same Lua, with the checks still in place.
+
+The script module itself is ordinary Python, so point your type checker and
+linter at it along with the rest of the project. Lines in the generated file
+are as long as the Lua's, so leave that one file out of any line-length rule.

{redis_lua_py-0.3.0 → redis_lua_py-0.5.0}/docs/guide/calling-redis-commands.md

@@ -5,8 +5,33 @@ split into subcommand tokens, so `redis.script_load(x)` compiles to
 `redis.call('SCRIPT', 'LOAD', x)`.
 
 `redis.pcall`, `redis.error_reply`, `redis.status_reply`, `redis.sha1hex`,
-`redis.log` and `cjson.encode` / `cjson.decode` pass through under their own
-names.
+`redis.log`, `redis.set_repl`, `redis.acl_check_cmd` and `cjson.encode` /
+`cjson.decode` pass through under their own names. So do the constants they
+take: `redis.LOG_WARNING` and the other log levels, `redis.REPL_ALL` and the
+other replication modes, and `redis.REDIS_VERSION`.
+
+## Splatting a list into a command
+
+A starred argument compiles to `unpack`, which is how a list becomes the
+arguments of a command:
+
+```python
+@script
+def push_all(queue: Key, jobs: list[str]) -> int:
+    return redis.rpush(queue, *jobs)
+```
+
+```lua
+return redis.call('RPUSH', queue, unpack(jobs))
+```
+
+It has to be the last argument, because Lua's `unpack` only expands there.
+
+!!! warning "unpack has a limit"
+
+    `unpack` puts every element on Lua's stack at once, and Redis' Lua refuses
+    past roughly eight thousand values with "too many results to unpack".
+    Split a list that can grow that large into chunks, one command per chunk.
 
 ## Names are checked, not just uppercased
 

{redis_lua_py-0.3.0 → redis_lua_py-0.5.0}/docs/guide/keys-and-arguments.md

@@ -46,6 +46,42 @@ 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`.
 
+## A variable number of keys or arguments
+
+Annotate a parameter `list[Key]` to take any number of keys, or `list[str]`,
+`list[int]` and so on to take any number of arguments. Its elements fill
+whatever is left of `KEYS` or `ARGV` after the fixed parameters, wherever the
+list is declared, and arrive in the body as a table:
+
+```python
+@script
+def delete_tagged(tag: Key, keys: list[Key], stamp: int) -> int:
+    redis.set(tag, stamp)
+    return redis.delete(*keys)
+
+
+delete_tagged(client, tag="purged", keys=["a", "b", "c"], stamp=1700000000)
+```
+
+```lua
+local tag = KEYS[1]
+local stamp = tonumber(ARGV[1])
+local keys = {}
+for __i1 = 2, #KEYS do
+  keys[#keys + 1] = KEYS[__i1]
+end
+redis.call('SET', tag, stamp)
+return redis.call('DEL', unpack(keys))
+```
+
+A script can take one list of keys and one list of arguments, since `KEYS`
+and `ARGV` only have positions to tell them apart. Every element of a
+`list[Key]` is a declared key, so Redis Cluster routes on all of them. An
+element annotation of `int` or `float` converts each element, as it would a
+single argument. Passing a string where a list is expected raises
+[`ScriptArgumentError`](../reference/errors.md#scriptargumenterror) rather
+than spreading it into characters.
+
 ## Positional or keyword
 
 Scripts accept either; keyword is clearer at the call site and is what the

redis_lua_py-0.5.0/docs/guide/redis-functions.md

@@ -0,0 +1,139 @@
+# Redis Functions
+
+A script is sent with `EVALSHA`, and lives in a cache the server is free to
+drop. Since Redis 7 there is an alternative: a **function library**. It is
+loaded once with `FUNCTION LOAD`, persists and replicates with the data, and
+each function in it is called by name with `FCALL`.
+
+The same Python compiles to either. A body follows exactly the rules of a
+script's.
+
+```python
+from redis_lua_py import Key, Library, redis
+
+limits = Library("limits")
+
+
+@limits.function
+def hit(key: Key, ttl: int) -> int:
+    current = redis.incr(key)
+    if current == 1:
+        redis.expire(key, ttl)
+    return current
+
+
+@limits.function(flags=["no-writes"])
+def peek(key: Key) -> int:
+    return int(redis.get(key) or 0)
+```
+
+```python
+hit(client, key="user:42", ttl=60)  # FCALL hit 1 user:42 60
+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.
+
+## Loading
+
+There is nothing to do up front. When a call finds that the server does not
+have the library, it loads it with `FUNCTION LOAD REPLACE` and tries again.
+
+To load it explicitly, at deploy time for instance:
+
+```python
+limits.load(client)
+```
+
+!!! warning "Load before a pipeline"
+
+    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.
+
+On Redis Cluster, redis-py sends `FUNCTION LOAD` to every primary, and routes
+`FCALL` on the function's keys, as it does a script.
+
+## What the library looks like
+
+`limits.lua` is the whole library, exactly as `FUNCTION LOAD` receives it:
+
+```lua
+#!lua name=limits
+-- Generated by redis-lua-py. Do not edit.
+-- Python truthiness: 0, '', empty tables and nil are all false.
+local function __truthy(v)
+  if v == nil or v == false then return false end
+  if v == 0 or v == '' then return false end
+  if type(v) == 'table' and next(v) == nil then return false end
+  return true
+end
+-- Python's `a or b`: a when it is truthy by Python's rules, otherwise b.
+local function __or(a, b)
+  if __truthy(a) then return a end
+  return b
+end
+-- hit, from limits.py:6
+redis.register_function{
+  function_name = 'hit',
+  callback = function(KEYS, ARGV)
+    local key = KEYS[1]
+    local ttl = tonumber(ARGV[1])
+    local current = redis.call('INCR', key)
+    if current == 1 then
+      redis.call('EXPIRE', key, ttl)
+    end
+    return current
+  end,
+}
+-- peek, from limits.py:14
+redis.register_function{
+  function_name = 'peek',
+  callback = function(KEYS, ARGV)
+    local key = KEYS[1]
+    return tonumber(__or(redis.call('GET', key), 0))
+  end,
+  flags = {'no-writes'},
+}
+```
+
+A helper any function needs is emitted once, at the top, where every callback
+can see it. The callback names its parameters `KEYS` and `ARGV`, so a function
+body compiles to exactly what the same body would as a script.
+
+Library and function names take letters, digits and underscores, which is all
+Redis accepts. Function names are global on the server, so two libraries
+cannot both define a `hit`.
+
+## Flags
+
+`flags` takes the flags Redis defines: `no-writes`, `allow-oom`,
+`allow-stale`, `no-cluster` and `allow-cross-slot-keys`. A `no-writes`
+function is called with `FCALL_RO`, which a replica accepts.
+
+Scripts take the same flags. Redis 7 reads them from a `#!lua` line at the very
+top of the script, which is where they go:
+
+```python
+@script(flags=["no-writes"])
+def read(key: Key) -> bytes:
+    return redis.get(key)
+```
+
+```lua
+#!lua flags=no-writes
+-- read
+-- Generated by redis-lua-py from app/cache.py:12. Do not edit.
+local key = KEYS[1]
+return redis.call('GET', key)
+```
+
+A misspelled flag is refused at import, like everything else.
+
+## Testing
+
+fakeredis has neither `FUNCTION` nor script flags. Test a library against a
+real server, or check its source as a golden file: `limits.lua` is the whole
+of it, as [a script's `.lua` is](testing.md#snapshot-the-lua).