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

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

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

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

@@ -7,6 +7,13 @@ 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.12.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.11.0...v0.12.0) (2026-09-25)
+
+
+### Added
+
+* str.isdigit, partition and annotated locals ([#32](https://github.com/IgnaceMaes/redis-lua-py/issues/32)) ([38e863c](https://github.com/IgnaceMaes/redis-lua-py/commit/38e863c96a89cd0c2a82d0bc59d73771f295d164))
+
 ## [0.11.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.10.0...v0.11.0) (2026-09-25)
 
 

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.11.0
+Version: 0.12.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.11.0 → redis_lua_py-0.12.0}/docs/installation.md

@@ -28,6 +28,31 @@ cluster, Sentinel, or an in-process [fakeredis](guide/testing.md).
 [coredis](https://github.com/alisaifee/coredis) clients work as well, and are
 tested against. See [Async](guide/async.md#coredis).
 
+### A client wrapper
+
+An application that wraps its client, to prefix keys per tenant for example,
+needs one method: `register_script(source)`. It returns a callable with the
+shape of redis-py's `Script`, `(keys=..., args=..., client=...)`, and a script
+runs through it:
+
+```python
+class PrefixedScript:
+    def __init__(self, owner: "PrefixedClient", script: Script) -> None:
+        self._owner, self._script = owner, script
+
+    def __call__(self, keys=(), args=(), client=None):
+        keys = [f"{self._owner.prefix}:{key}" for key in keys]
+        return self._script(keys=keys, args=args)
+
+
+class PrefixedClient:
+    def register_script(self, source: str) -> PrefixedScript:
+        return PrefixedScript(self, self._redis.register_script(source))
+```
+
+The wrapper's other methods never come into it, so an `eval` with its own
+signature is fine.
+
 ## For testing
 
 [fakeredis](https://github.com/cunla/fakeredis-py) embeds a real Lua

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

@@ -55,9 +55,17 @@ that is not known, it looks at the subscript:
 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,
+the key `0`. A value 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.
+on it is taken to be a table position. For a string, that reads `nil`, so
+annotate the local to say what it holds:
+
+```python
+text: str | None = redis.get(key)
+```
+
+An annotation on a local is a declaration, not a conversion: it decides how
+the value is indexed and added, and changes nothing at runtime.
 
 `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

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

@@ -5,8 +5,9 @@ language with a faithful Lua meaning is accepted.
 
 **Supported:**
 
-- **Statements:** assignment, including unpacking (`a, b = b, a`);
-  augmented assignment; `if`/`elif`/`else`; `while`; `break`; `continue`;
+- **Statements:** assignment, including unpacking (`a, b = b, a`) and
+  annotated assignment (`text: str = redis.get(key)`), whose annotation tells
+  the compiler the value's type; augmented assignment; `if`/`elif`/`else`; `while`; `break`; `continue`;
   `return`.
 - **Errors:** `try` with one `except` (bare or `Exception`), `else` and
   `finally`; `raise SomeError("message")`, and a bare `raise` inside `except`;
@@ -23,8 +24,10 @@ 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`; `encode()` and
-  `decode()` in UTF-8, which leave the bytes as they are.
+  `startswith`, `endswith`, `find`, `split`, `partition` and `replace`;
+  `isdigit`, `isalpha`, `isalnum` and `isspace`, which test ASCII as they do
+  on bytes; `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()`; `isinstance()` against `str`,

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

@@ -1,6 +1,6 @@
 [project]
 name = "redis-lua-py"
-version = "0.11.0"
+version = "0.12.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 → redis_lua_py-0.12.0}/src/redis_lua_py/__init__.py

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

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/base.py

@@ -26,7 +26,7 @@ from .. import _lua as lua
 from .._runtime import _Namespace
 from ..errors import UnsupportedSyntax
 from .analysis import UNBOUND, as_literal, binop_kind, dotted_name, value_kind
-from .tables import MATH_BY_OBJECT, RECEIVER_FALLBACK, REDIS_CONSTANTS
+from .tables import MATH_BY_OBJECT, RECEIVER_FALLBACK, REDIS_CONSTANTS, STRING_TESTS
 
 
 def is_redis_py(value: object) -> bool:
@@ -82,6 +82,9 @@ class CompilerBase(ABC):
         self.helpers: set[str] = set()
         # What a parameter or loop variable is known to be; see kind().
         self.kinds: dict[str, str] = {}
+        # Kinds that an annotation on a local declares. They are the author's
+        # word, so they win over what the assigned values suggest.
+        self.declared: dict[str, str] = {}
         # Every value assigned to each name, to work out what a local holds.
         self.values: dict[str, list[ast.expr]] = {}
         # Names bound in ways that say nothing about their type.
@@ -303,9 +306,9 @@ class CompilerBase(ABC):
                     return "str"
                 if attr in {"encode", "decode"}:
                     return "str"
-                if attr in {"startswith", "endswith"}:
+                if attr in {"startswith", "endswith", *STRING_TESTS}:
                     return "bool"
-                if attr == "split":
+                if attr in {"split", "partition"}:
                     return "list"
                 return "num" if attr == "find" else None
             case ast.Attribute():
@@ -321,6 +324,8 @@ class CompilerBase(ABC):
     def name_kind(self, name: str) -> str | None:
         if name not in self.known:
             return value_kind(self.globalns.get(name, UNBOUND))
+        if name in self.declared:
+            return self.declared[name]
         if name in self._resolving:
             # A name whose value depends on itself, as in `n += 1`, is whatever
             # its other assignments make it.

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/calls.py

@@ -18,6 +18,7 @@ from .tables import (
     METHOD_HINT,
     REDIS_DIRECT,
     STRING_METHODS,
+    STRING_TESTS,
 )
 
 
@@ -26,7 +27,12 @@ class CallCompiler(ExpressionCompiler):
 
     def call(self, node: ast.Call) -> lua.Expr:
         if node.keywords:
-            self.fail(node, "keyword arguments are not supported in a script body")
+            self.fail(
+                node,
+                "keyword arguments are not supported in a script body",
+                hint="Pass a Redis command's options positionally, as its syntax "
+                "writes them: redis.set(key, value, 'EX', ttl), not ex=ttl.",
+            )
         if (
             isinstance(node.func, ast.Name)
             and node.func.id == "isinstance"
@@ -205,7 +211,8 @@ class CallCompiler(ExpressionCompiler):
             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,)
+            no_args = {"upper", "lower", "strip", "lstrip", "rstrip", *STRING_TESTS}
+            allowed = (0,) if attr in no_args else (1,)
         if len(args) not in allowed:
             if attr in {"strip", "lstrip", "rstrip"}:
                 self.fail(
@@ -218,6 +225,9 @@ class CallCompiler(ExpressionCompiler):
 
         if attr in {"upper", "lower"}:
             return lua.Call(lua.Global(f"string.{attr}"), (target,))
+        if attr in STRING_TESTS:
+            found = lua.Call(lua.Global("string.find"), (target, lua.Str(STRING_TESTS[attr])))
+            return lua.BinOp("~=", found, lua.Nil())
         if attr in {"strip", "lstrip", "rstrip"}:
             pattern = {"strip": "^%s*(.-)%s*$", "lstrip": "^%s*(.*)$", "rstrip": "^(.-)%s*$"}
             return lua.Call(lua.Global("string.match"), (target, lua.Str(pattern[attr])))

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/helpers.py

@@ -149,6 +149,15 @@ local function __find(s, sub)
   local i = string.find(s, sub, 1, true)
   if i == nil then return -1 end
   return i - 1
+end""",
+    "__partition": """\
+-- str.partition: before, separator and after the first plain match, or the
+-- whole string and two empty strings when there is none.
+local function __partition(s, sep)
+  if sep == '' then error('empty separator', 0) end
+  local i, j = string.find(s, sep, 1, true)
+  if i == nil then return {s, '', ''} end
+  return {string.sub(s, 1, i - 1), sep, string.sub(s, j + 1)}
 end""",
     "__split": """\
 -- str.split: on a plain separator, or on runs of whitespace without one.

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/scope.py

@@ -44,6 +44,10 @@ class ScopeCompiler(CompilerBase):
                 node.target, ast.Name
             ):
                 record(node.target.id, node)
+                if isinstance(node, ast.AnnAssign):
+                    declared = self._annotation_kind(self._without_none(node.annotation))
+                    if declared is not None:
+                        self.declared.setdefault(node.target.id, declared)
                 if isinstance(node, ast.AugAssign):
                     value: ast.expr = ast.BinOp(left=node.target, op=node.op, right=node.value)
                     self.values.setdefault(node.target.id, []).append(value)
@@ -118,7 +122,12 @@ class ScopeCompiler(CompilerBase):
                     self.variadic_key = name
                 else:
                     if self.variadic_arg is not None:
-                        self.fail(arg, "only one list parameter of arguments is supported")
+                        self.fail(
+                            arg,
+                            "only one list parameter of arguments is supported",
+                            hint="Interleave the values in one list and index it "
+                            "with a stride, as in values[3 * i + 1].",
+                        )
                     self.variadic_arg = name
                     if self._is_numeric(item):
                         self.numeric_args.add(name)
@@ -192,6 +201,26 @@ class ScopeCompiler(CompilerBase):
             return "str"
         return None
 
+    @staticmethod
+    def _without_none(node: ast.expr | None) -> ast.expr | None:
+        """``X`` from ``X | None`` or ``Optional[X]``: None is no kind of its own."""
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            try:
+                node = ast.parse(node.value, mode="eval").body
+            except SyntaxError:
+                return None
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+            sides = [
+                side
+                for side in (node.left, node.right)
+                if not (isinstance(side, ast.Constant) and side.value is None)
+            ]
+            return sides[0] if len(sides) == 1 else None
+        name = ScopeCompiler._annotation_name(node)
+        if isinstance(node, ast.Subscript) and name == "Optional":
+            return node.slice
+        return node
+
     @staticmethod
     def _list_item(node: ast.expr | None) -> ast.expr | None:
         """The element annotation of a ``list[...]`` parameter, if it is one."""

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/statements.py

@@ -272,6 +272,7 @@ class Compiler(ControlFlowCompiler):
         # What the script's names hold is known inside the function too, except
         # for its parameters, which say nothing about their type.
         child.kinds = {k: v for k, v in self.kinds.items() if k not in params}
+        child.declared = {k: v for k, v in self.declared.items() if k not in params}
         child.values = {k: list(v) for k, v in self.values.items() if k not in params}
         child.opaque = self.opaque - set(params)
         child._temp = self._temp

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/src/redis_lua_py/_compile/tables.py

@@ -133,8 +133,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, replace, "
-    "encode and decode; and dict get."
+    "upper, lower, strip, lstrip, rstrip, startswith, endswith, find, split, partition, "
+    "replace, isdigit, isalpha, isalnum, isspace, encode and decode; and dict get."
 )
 
 
@@ -152,9 +152,24 @@ STRING_METHODS = frozenset(
         "endswith",
         "find",
         "split",
+        "partition",
         "replace",
+        "isdigit",
+        "isalpha",
+        "isalnum",
+        "isspace",
         "encode",
         "decode",
         "get",
     }
 )
+
+
+# The str.is* tests, as Lua patterns over the whole string. Lua's classes are
+# ASCII, which is exactly what the same methods on bytes test.
+STRING_TESTS: dict[str, str] = {
+    "isdigit": "^%d+$",
+    "isalpha": "^%a+$",
+    "isalnum": "^%w+$",
+    "isspace": "^%s+$",
+}

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/tests/test_errors.py

@@ -172,3 +172,25 @@ def test_an_except_name_that_is_a_lua_keyword_is_rejected() -> None:
             except Exception as end:
                 return len(end)
             return 0
+
+
+def test_keyword_arguments_hint_at_positional_options() -> None:
+    with pytest.raises(UnsupportedSyntax) as info:
+
+        @script
+        def put(key: Key, ttl: int) -> None:
+            redis.set(key, "v", ex=ttl)
+
+    assert info.value.hint is not None
+    assert "'EX', ttl" in info.value.hint
+
+
+def test_a_second_list_of_arguments_hints_at_a_stride() -> None:
+    with pytest.raises(UnsupportedSyntax) as info:
+
+        @script
+        def check(keys: list[Key], limits: list[int], ttls: list[int]) -> None:
+            pass
+
+    assert info.value.hint is not None
+    assert "3 * i" in info.value.hint

{redis_lua_py-0.11.0 → redis_lua_py-0.12.0}/tests/test_strings_and_indexing.py

@@ -303,6 +303,69 @@ class TestStringMethods:
 
         assert shifted(client, c="a") == b"b"
 
+    def test_character_class_tests(self, client: Any) -> None:
+        @script
+        def classes(text: str) -> list[bool]:
+            return [text.isdigit(), text.isalpha(), text.isalnum(), text.isspace()]
+
+        assert "__" not in classes.lua  # a pattern match inline, no helper
+        assert classes(client, text="0042") == [1, None, 1, None]
+        assert classes(client, text="abC") == [None, 1, 1, None]
+        assert classes(client, text=" \t\n") == [None, None, None, 1]
+        assert classes(client, text="") == [None, None, None, None]
+        assert classes(client, text="-1") == [None, None, None, None]
+
+    def test_partition(self, client: Any) -> None:
+        @script
+        def parts(text: str) -> list[list[bytes]]:
+            return [text.partition(":"), text.partition("?")]
+
+        assert parts(client, text="5:a:b") == [[b"5", b":", b"a:b"], [b"5:a:b", b"", b""]]
+
+    def test_partition_and_isdigit_parse_a_version_prefix(self, client: Any) -> None:
+        @script
+        def version_of(key: Key) -> int:
+            raw: str | None = redis.get(key)
+            if raw is None:
+                return 0
+            prefix, sep, _body = raw.partition(":")
+            if sep and prefix.isdigit() and len(prefix) <= 15:
+                return int(prefix)
+            return 0
+
+        cases = {b"12:[]": 12, b"x:[]": 0, b"12": 0, b":[]": 0, b"1e3:[]": 0, b"-1:[]": 0}
+        for stored, expected in cases.items():
+            client.set("v", stored)
+            assert version_of(client, key="v") == expected, stored
+        client.delete("v")
+        assert version_of(client, key="v") == 0
+
+
+class TestAnnotatedLocals:
+    def test_an_annotation_makes_a_reply_a_string(self, client: Any) -> None:
+        @script
+        def first_char(key: Key) -> bytes:
+            text: str = redis.get(key)
+            return text[0]
+
+        assert "string.sub" in first_char.lua
+        client.set("t", "hello")
+        assert first_char(client, key="t") == b"h"
+
+    def test_an_optional_annotation_declares_the_inner_kind(self, client: Any) -> None:
+        @script
+        def digits_of(key: Key) -> list[bytes]:
+            text: str | None = redis.get(key)
+            out = []
+            if text is not None:
+                for i in range(len(text)):
+                    out.append(text[i])
+            return out
+
+        assert "string.sub" in digits_of.lua
+        client.set("t", "42")
+        assert digits_of(client, key="t") == [b"4", b"2"]
+
 
 class TestFormatting:
     def test_percent_formatting(self, client: Any) -> None:

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

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