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

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

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

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

@@ -7,6 +7,17 @@ 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.8.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.7.0...v0.8.0) (2026-09-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* a bool parameter is a boolean in the body rather than "1" or "0", and integer conversion of a non-number raises instead of giving nil.
+
+### Fixed
+
+* give bool arguments, int() and known booleans their python meaning ([#24](https://github.com/IgnaceMaes/redis-lua-py/issues/24)) ([27b3de8](https://github.com/IgnaceMaes/redis-lua-py/commit/27b3de8e7c12aea9076b940e6a7f369b054876f3))
+
 ## [0.7.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.6.0...v0.7.0) (2026-09-12)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.7.0
+Version: 0.8.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.7.0 → redis_lua_py-0.8.0}/docs/guide/keys-and-arguments.md

@@ -30,7 +30,7 @@ to it on the way in.
 | `Key` | `KEYS[n]`, and what the cluster routes on |
 | `int`, `float` | wrapped in `tonumber`, so it is a number by the time your comparison runs |
 | `str` | passed through as the string it already is |
-| `bool` | encoded as `"1"` or `"0"` |
+| `bool` | encoded as `"1"` or `"0"`, and a Lua boolean in the body |
 | `bytes`, `memoryview` | passed through untouched — see [Binary values](binary-values.md) |
 
 ### `float` carries a caveat
@@ -41,10 +41,15 @@ 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` deletes a conditional
+### `bool` is a boolean in the body
 
-`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`.
+`bool` travels as `"1"` or `"0"`, and arrives as `ARGV[n] == '1'`, so
+`if flag:` means what it says. `"0"` is a non-empty string, which both Lua and
+Python count as true, so passing the string through would make every flag set.
+
+A Lua boolean cannot be a command argument, as in redis-py. Write `int(flag)`
+where the body hands it to Redis, or annotate the parameter `int` instead:
+pass `True`, and the body gets `1`, with no `1 if flag else 0` at the call site.
 
 ## A variable number of keys or arguments
 

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/docs/guide/return-values.md

@@ -30,7 +30,9 @@ def preview(doc: Key) -> list[int | bytes]:
 
 `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.
+about the same thing. For a string built in the body, `str(n).encode()` does
+the same: Lua strings are already bytes, so `encode()` compiles to nothing, and
+the body type-checks against `-> bytes`.
 
 Return values follow Redis' own conversion rules: `True` becomes `1`, `False`
 and `None` become nil, floats are truncated to integers. Return a string, or

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

@@ -4,9 +4,11 @@ These are the gaps that matter. Most are closed for you; the rest are refused.
 
 ## Truthiness is closed
 
-Lua counts `0` and `''` as true. Any condition that is not already a boolean is
-routed through a generated `__truthy` helper, so `if count:` means what it
-means in Python.
+Lua counts `0` and `''` as true. Any condition that is not known to be a
+boolean is routed through a generated `__truthy` helper, so `if count:` means
+what it means in Python. A comparison, `not`, `startswith()`, `endswith()`, a
+`bool` parameter, and a name only ever assigned one of those are used as they
+are, and `and`/`or` between them compile to Lua's own operators.
 
 ## Missing values are closed
 

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

@@ -23,10 +23,11 @@ language with a faithful Lua meaning is accepted.
   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`.
-- **Builtins and methods:** `len()`, `int()`, `float()`, `str()`, `min()`,
-  `max()`, `abs()`, `ord()`, `chr()`, `.append()`, `.insert()`, `.pop()` and
-  `dict.get()`.
+  `startswith`, `endswith`, `find`, `split` and `replace`; `encode()` and
+  `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()`.
 - **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.

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

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

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

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

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/analysis.py

@@ -217,7 +217,7 @@ def without_finally(node: ast.Try) -> ast.Try:
 def value_kind(value: object) -> str | None:
     """The kind of a module-level constant, as folded into the script."""
     if isinstance(value, bool):
-        return None
+        return "bool"
     if isinstance(value, str | bytes):
         return "str"
     if isinstance(value, int | float):

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/base.py

@@ -242,16 +242,21 @@ class CompilerBase(ABC):
     def kind(self, node: ast.expr) -> str | None:
         """What an expression is statically known to be, or None.
 
-        One of "str", "num", "list", "dict" or "func". Lua does not care, but
-        several translations do: a subscript is shifted to 1-based for a list
-        and not for a dict, `+` joins strings and adds numbers, `in` searches a
-        list and looks up a dict's keys, and a format spec aligns a string and
-        a number differently. None means "only known at runtime", and the
-        translation then decides there, or refuses.
+        One of "str", "num", "bool", "list", "dict" or "func". Lua does not
+        care, but several translations do: a subscript is shifted to 1-based
+        for a list and not for a dict, `+` joins strings and adds numbers, `in`
+        searches a list and looks up a dict's keys, a format spec aligns a
+        string and a number differently, and a boolean needs no truthiness
+        helper. None means "only known at runtime", and the translation then
+        decides there, or refuses.
         """
         match node:
             case ast.Constant(value=bool()):
-                return None
+                return "bool"
+            case ast.Compare() | ast.UnaryOp(op=ast.Not()):
+                return "bool"
+            case ast.BoolOp(values=values):
+                return "bool" if all(self.kind(value) == "bool" for value in values) else None
             case ast.Constant(value=str() | bytes()):
                 return "str"
             case ast.Constant(value=int() | float()):
@@ -292,6 +297,10 @@ class CompilerBase(ABC):
                     return None
                 if attr in {"upper", "lower", "strip", "lstrip", "rstrip", "replace", "join"}:
                     return "str"
+                if attr in {"encode", "decode"}:
+                    return "str"
+                if attr in {"startswith", "endswith"}:
+                    return "bool"
                 if attr == "split":
                     return "list"
                 return "num" if attr == "find" else None

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/calls.py

@@ -42,6 +42,8 @@ class CallCompiler(ExpressionCompiler):
                     self.helpers.add("__dictlen")
                     return lua.Call(lua.Name("__dictlen"), args)
                 return lua.UnOp("#", args[0])
+            case ast.Name(id="int"):
+                return self.int_call(node, args)
             case ast.Name(id=name) if name in BUILTIN_FUNCS:
                 return lua.Call(lua.Name(BUILTIN_FUNCS[name]), args)
             case ast.Attribute(value=receiver, attr="join") if not self.is_namespace(receiver):
@@ -87,6 +89,17 @@ class CallCompiler(ExpressionCompiler):
                 args.append(self.expr(arg))
         return tuple(args)
 
+    def int_call(self, node: ast.Call, args: tuple[lua.Expr, ...]) -> lua.Expr:
+        """``int(x)``: truncated toward zero, which tonumber alone does not do."""
+        if len(args) != 1:
+            self.fail(
+                node, "int() takes exactly one argument", hint="int() with a base is not supported."
+            )
+        if self.kind(node.args[0]) == "bool":
+            return lua.BinOp("or", lua.BinOp("and", args[0], lua.Num(1)), lua.Num(0))
+        self.helpers.add("__int")
+        return lua.Call(lua.Name("__int"), args)
+
     def math_call(self, node: ast.Call, attr: str, args: tuple[lua.Expr, ...]) -> lua.Expr:
         if attr == "log":
             if len(args) != 1:
@@ -135,6 +148,16 @@ class CallCompiler(ExpressionCompiler):
     ) -> lua.Expr:
         """The str methods, and dict.get, over Lua's string library and helpers."""
         target = self.expr(receiver)
+        if attr in {"encode", "decode"}:
+            # Every Lua string is already bytes, so there is nothing to convert.
+            if len(node.args) > 1 or (node.args and not is_utf8(node.args[0])):
+                self.fail(
+                    node,
+                    f"{attr}() only supports UTF-8 inside a script",
+                    hint="Lua strings are bytes, so encode() and decode() leave them as they are; "
+                    "another encoding has no counterpart.",
+                )
+            return target
         allowed = {"get": (1, 2), "split": (0, 1), "replace": (2,)}.get(attr)
         if allowed is None:
             allowed = (0,) if attr in {"upper", "lower", "strip", "lstrip", "rstrip"} else (1,)
@@ -254,6 +277,13 @@ class CallCompiler(ExpressionCompiler):
         )
 
 
+def is_utf8(node: ast.expr) -> bool:
+    """Whether an encode()/decode() argument names UTF-8."""
+    if not isinstance(node, ast.Constant) or not isinstance(node.value, str):
+        return False
+    return node.value.lower().replace("_", "-") in {"utf-8", "utf8"}
+
+
 def listing(names: list[str], limit: int = 6) -> str:
     """A comma-separated sample, only trailing off when there is more."""
     shown = ", ".join(names[:limit])

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/expressions.py

@@ -393,6 +393,9 @@ class ExpressionCompiler(ScopeCompiler):
         that is a name or a literal goes through a helper; anything else is
         wrapped in a function, so it only runs when Python would run it.
         """
+        if self.kind(node) == "bool":
+            # Between booleans, Lua's and/or mean exactly what Python's do.
+            return self.condition(node)
         is_or = isinstance(node.op, ast.Or)
         self.helpers.add("__truthy")
         result = self.expr(node.values[0])
@@ -432,9 +435,11 @@ class ExpressionCompiler(ScopeCompiler):
     def condition(self, node: ast.expr) -> lua.Expr:
         """Compile an expression used for its truth value.
 
-        Lua treats 0 and '' as true, so anything that is not already a boolean
-        gets routed through the __truthy helper.
+        Lua treats 0 and '' as true, so anything that is not known to be a
+        boolean gets routed through the __truthy helper.
         """
+        if self.kind(node) == "bool" and not isinstance(node, ast.BoolOp | ast.UnaryOp):
+            return self.expr(node)
         match node:
             case ast.Compare():
                 return self.compare(node)

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/helpers.py

@@ -125,6 +125,15 @@ local function __add(a, b)
     return out
   end
   return a + b
+end""",
+    "__int": """\
+-- Python's int(): a number truncated toward zero, and an error rather than
+-- nil for anything that is not a number.
+local function __int(v)
+  local n = tonumber(v)
+  if n == nil then error('invalid literal for int(): ' .. tostring(v), 0) end
+  if n < 0 then return math.ceil(n) end
+  return math.floor(n)
 end""",
     "__startswith": """\
 local function __startswith(s, prefix)

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/scope.py

@@ -135,6 +135,10 @@ class ScopeCompiler(CompilerBase):
                     # is the author asking for the conversion.
                     self.numeric_args.add(name)
                     source = lua.Call(lua.Name("tonumber"), (source,))
+                elif self._annotation_name(arg.annotation) == "bool":
+                    # A bool arrives as "1" or "0", and "0" is a string Lua and
+                    # Python both count as true. Comparing makes it a boolean.
+                    source = lua.BinOp("==", source, lua.Str("1"))
             kind = self._annotation_kind(arg.annotation)
             if kind is not None:
                 self.kinds[name] = kind
@@ -182,8 +186,9 @@ class ScopeCompiler(CompilerBase):
         name = self._annotation_name(node)
         if name in {"int", "float"}:
             return "num"
-        # A bool arrives as the string "1" or "0", like every other ARGV.
-        if name in {"Key", "str", "bytes", "memoryview", "bool"}:
+        if name == "bool":
+            return "bool"
+        if name in {"Key", "str", "bytes", "memoryview"}:
             return "str"
         return None
 

{redis_lua_py-0.7.0 → redis_lua_py-0.8.0}/src/redis_lua_py/_compile/tables.py

@@ -119,8 +119,8 @@ MATH_BY_OBJECT: dict[object, str] = {getattr(math, name): name for name in [*MAT
 
 METHOD_HINT = (
     "Available: the redis and cjson namespaces; list append, insert and pop; str join, "
-    "upper, lower, strip, lstrip, rstrip, startswith, endswith, find, split and replace; "
-    "and dict get."
+    "upper, lower, strip, lstrip, rstrip, startswith, endswith, find, split, replace, "
+    "encode and decode; and dict get."
 )
 
 
@@ -139,6 +139,8 @@ STRING_METHODS = frozenset(
         "find",
         "split",
         "replace",
+        "encode",
+        "decode",
         "get",
     }
 )

redis_lua_py-0.8.0/tests/test_booleans_and_conversions.py

@@ -0,0 +1,162 @@
+"""Booleans, int() and str/bytes conversions, where Lua's meaning differs from Python's.
+
+Each test runs the script as well as inspecting it: a translation that reads
+well but answers differently is the failure being guarded against.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+from redis_lua_py import CompiledScript, Key, UnsupportedSyntax, redis, script
+
+Body = Callable[[CompiledScript[object]], str]
+
+
+class TestBoolArguments:
+    """A bool travels as "1" or "0", and "0" is a string Lua counts as true."""
+
+    def test_false_is_false_in_a_condition(self, client: Any) -> None:
+        @script
+        def s(flag: bool) -> str:
+            if flag:
+                return "yes"
+            return "no"
+
+        assert s(client, flag=True) == b"yes"
+        assert s(client, flag=False) == b"no"
+
+    def test_arrives_as_a_lua_boolean(self, body: Body) -> None:
+        @script
+        def s(flag: bool) -> int:
+            if not flag:
+                return 0
+            return 1
+
+        emitted = body(s)
+        assert "local flag = ARGV[1] == '1'" in emitted
+        assert "__truthy" not in emitted
+
+    def test_int_of_a_bool(self, client: Any, body: Body) -> None:
+        @script
+        def s(flag: bool) -> int:
+            return int(flag) + 1
+
+        assert "__int" not in body(s)
+        assert s(client, flag=True) == 2
+        assert s(client, flag=False) == 1
+
+
+class TestKnownBooleans:
+    """A value known to be a boolean needs no truthiness helper."""
+
+    def test_a_comparison_kept_in_a_name(self, client: Any, body: Body) -> None:
+        @script
+        def s(k: Key) -> int:
+            empty = redis.llen(k) == 0
+            if empty:
+                return 0
+            return 1
+
+        assert "__truthy" not in body(s)
+        assert s(client, k="list") == 0
+        client.rpush("list", "x")
+        assert s(client, k="list") == 1
+
+    def test_startswith_and_endswith(self, client: Any, body: Body) -> None:
+        @script
+        def s(k: Key, prefix: str, suffix: str) -> int:
+            value = redis.get(k)
+            if value is not None and value.startswith(prefix) and not value.endswith(suffix):
+                return 1
+            return 0
+
+        assert "__truthy" not in body(s)
+        client.set("k", "pointer:abc")
+        assert s(client, k="k", prefix="pointer:", suffix="xyz") == 1
+        assert s(client, k="k", prefix="inline:", suffix="xyz") == 0
+        assert s(client, k="k", prefix="pointer:", suffix="abc") == 0
+        assert s(client, k="missing", prefix="pointer:", suffix="xyz") == 0
+
+    def test_and_or_between_booleans_use_luas_operators(self, client: Any, body: Body) -> None:
+        @script
+        def s(a: int, b: int) -> list[int]:
+            both = a > 0 and b > 0
+            either = a > 0 or b > 0
+            return [int(both), int(either)]
+
+        emitted = body(s)
+        for helper in ("__truthy", "__and", "__or", "__int"):
+            assert helper not in emitted
+        assert s(client, a=1, b=0) == [0, 1]
+        assert s(client, a=1, b=1) == [1, 1]
+        assert s(client, a=0, b=0) == [0, 0]
+
+    def test_a_bool_constant(self, client: Any, body: Body) -> None:
+        @script
+        def s(n: int) -> int:
+            found = False
+            if n > 3:
+                found = True
+            if found:
+                return 1
+            return 0
+
+        assert "__truthy" not in body(s)
+        assert s(client, n=5) == 1
+        assert s(client, n=1) == 0
+
+
+class TestInt:
+    """int() truncates toward zero, where tonumber keeps the fraction."""
+
+    @pytest.mark.parametrize(
+        ("value", "expected"), [("7", 7), ("3.7", 3), ("-3.7", -3), ("-0.5", 0), ("12", 12)]
+    )
+    def test_truncates_toward_zero(self, client: Any, value: str, expected: int) -> None:
+        @script
+        def s(v: str) -> list[int]:
+            # Scaled, so Redis' own truncation of a numeric reply cannot hide ours.
+            return [int(v) * 10]
+
+        assert s(client, v=value) == [expected * 10]
+
+    def test_a_missing_value_raises(self, client: Any) -> None:
+        @script
+        def s(k: Key) -> int:
+            return int(redis.get(k))
+
+        with pytest.raises(Exception, match="invalid literal for int"):
+            s(client, k="missing")
+
+    def test_a_base_is_refused(self) -> None:
+        with pytest.raises(UnsupportedSyntax, match="int\\(\\) takes exactly one argument"):
+
+            @script
+            def s(v: str) -> int:
+                return int(v, 16)  # type: ignore[call-overload]
+
+
+class TestEncodeDecode:
+    """Lua strings are bytes, so encode() and decode() have nothing to convert."""
+
+    def test_pass_through(self, client: Any, body: Body) -> None:
+        @script
+        def s(k: Key, text: str) -> bytes:
+            redis.set(k, text.encode())
+            return str(redis.get(k).decode("utf-8")).encode("utf-8")
+
+        emitted = body(s)
+        assert "encode" not in emitted
+        assert "decode" not in emitted
+        assert s(client, k="k", text="héllo") == "héllo".encode()
+
+    def test_another_encoding_is_refused(self) -> None:
+        with pytest.raises(UnsupportedSyntax, match="only supports UTF-8"):
+
+            @script
+            def s(text: str) -> bytes:
+                return text.encode("latin-1")

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

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