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

{redis_lua_py-0.5.0 → redis_lua_py-0.6.0}/.github/workflows/ci.yml

@@ -37,6 +37,17 @@ jobs:
   oldest:
     name: Tests (oldest supported Python and redis-py)
     runs-on: ubuntu-latest
+    # A real server as well, since what fakeredis cannot run -- Redis Functions
+    # and script flags -- is exactly what old redis-py spells differently.
+    services:
+      redis:
+        image: redis:7
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
@@ -46,8 +57,11 @@ jobs:
       # The floor in pyproject.toml is only a claim until something runs on it.
       # fakeredis declares redis>=4.3 but works on 4.2, the first release with
       # redis.asyncio, so the pin goes in after the resolver is done.
-      - run: uv pip install --no-deps "redis==4.2.0" async-timeout deprecated
+      - run: uv pip install --no-deps "redis==4.2.0" async-timeout deprecated packaging
       - run: uv run --no-sync pytest
+      - run: uv run --no-sync pytest
+        env:
+          REDIS_URL: redis://localhost:6379/0
 
   live:
     name: Tests against a real Redis

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

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

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

@@ -7,6 +7,20 @@ 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.6.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.5.1...v0.6.0) (2026-09-12)
+
+
+### Added
+
+* generate typed functions that call scripts the way `@script` does ([#18](https://github.com/IgnaceMaes/redis-lua-py/issues/18)) ([8f602f7](https://github.com/IgnaceMaes/redis-lua-py/commit/8f602f7bdf4afaa22c83c63e215ef5d965fbc584))
+
+## [0.5.1](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.5.0...v0.5.1) (2026-09-12)
+
+
+### Fixed
+
+* load redis functions libraries on redis-py 4.2 ([#16](https://github.com/IgnaceMaes/redis-lua-py/issues/16)) ([85c2ba2](https://github.com/IgnaceMaes/redis-lua-py/commit/85c2ba20056224af7b2c9720176f799cf54b163f))
+
 ## [0.5.0](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.4.0...v0.5.0) (2026-09-12)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-lua-py
-Version: 0.5.0
+Version: 0.6.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/
@@ -145,8 +145,9 @@ script cache is cold once per script rather than once per environment.
   **[`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`
+  for libraries — `python -m redis_lua_py generate` writes your scripts to a
+  module of typed functions that needs only the standard library, called just
+  like the `@script`, so your users never depend on this package. `--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`

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

@@ -119,8 +119,9 @@ script cache is cold once per script rather than once per environment.
   **[`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`
+  for libraries — `python -m redis_lua_py generate` writes your scripts to a
+  module of typed functions that needs only the standard library, called just
+  like the `@script`, so your users never depend on this package. `--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`

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

@@ -0,0 +1,196 @@
+# 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 a module from them while you
+develop. What you ship is that module: plain Python that needs only the
+standard library, with a typed function per script, called exactly the way
+the `@script` would be.
+
+## Generate a module
+
+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
+```
+
+Your library calls the generated functions the way it would call the scripts
+themselves:
+
+```python
+from redis import Redis
+
+from ._lua import rate_limit
+
+
+def hit(client: Redis, key: str, limit: int, ttl: int) -> int:
+    return rate_limit(client, key=key, limit=limit, ttl=ttl)
+```
+
+Moving from `@script` to generated code, or back, is a change of import. A sync
+client gets a value and an async one an awaitable, `EVALSHA` falls back to
+`EVAL` when the server has dropped the script, and a cluster pipeline is sent
+the source: the generated module carries a copy of the code the package itself
+calls scripts with.
+
+## What the module holds
+
+For each script, its Lua as a constant named after it in capitals, and a
+function with the signature it was written with:
+
+```python
+# 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
+"""
+_RATE_LIMIT_CLIENTS: WeakKeyDictionary[Any, Any] = WeakKeyDictionary()
+
+
+@overload
+def rate_limit(
+    client: _AsyncClient,
+    /,
+    key: _Key,
+    limit: int,
+    ttl: int,
+) -> Awaitable[int]: ...
+@overload
+def rate_limit(client: Any, /, key: _Key, limit: int, ttl: int) -> int: ...
+def rate_limit(client: Any, /, key: _Key, limit: int, ttl: int) -> Any:
+    return _run(
+        RATE_LIMIT,
+        _RATE_LIMIT_CLIENTS,
+        client,
+        [key],
+        [_encode("limit", limit), _encode("ttl", ttl)],
+    )
+```
+
+Because it is a real signature, Python itself refuses a missing, misspelled or
+duplicated argument, and your type checker sees every call, including what it
+returns from a sync client and from an async one. Parameter names, their
+order, keyword-only parameters and the docstring all come from the script.
+
+The types come from the script's annotations, as far as a module that imports
+nothing of yours can repeat them:
+
+| Parameter | Accepts |
+| --- | --- |
+| annotated `Key` | `str \| bytes \| memoryview`, as redis-py does for a key |
+| `list[Key]`, or `list[...]` of arguments | any iterable of those, as `@script` does |
+| an argument annotated with builtins only, such as `int` or `str \| bytes` | exactly that |
+| an argument annotated with anything else | `str \| bytes \| memoryview \| int \| float` |
+
+A return annotation made only of builtins, such as `list[bytes] | None`, is kept
+as written; anything else becomes `Any`. A value Redis has no representation
+for, such as `None`, raises `TypeError`, as does a string passed where a list
+belongs.
+
+Above the scripts sits that copied call path, about a hundred lines, every name
+in it private. A script or parameter named like one of them would shadow it, so
+generation refuses one and names it.
+
+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. It is laid out the way black and ruff
+format code, and passes strict mypy.
+
+If you would rather call redis-py yourself, the constants are there for that:
+`client.register_script(RATE_LIMIT)`, with `keys` and `args` in the order the
+comment above each one records.
+
+## 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, and the
+call path is the same code. What differs is at the edges:
+
+- **Errors.** A bad argument raises `TypeError`, not
+  [`ScriptArgumentError`](../reference/errors.md#scriptargumenterror), which
+  lives in this package.
+- **`bind`.** A generated function takes the client on every call. Wrap it in a
+  function of your own if that gets repetitive.
+- **Your own types.** An annotation that names a type from your module is
+  widened, as in the table above.
+- **Redis Functions.** Only `@script` functions are generated, not a
+  [`Library`](redis-functions.md).
+
+Keep testing the scripts against
+[fakeredis](testing.md#run-the-behaviour-without-a-server), through the
+generated module or through `@script`: both run the same Lua.
+
+The script module itself is ordinary Python, so point your type checker and
+linter at it along with the rest of the project.

{redis_lua_py-0.5.0 → redis_lua_py-0.6.0}/docs/reference/api.md

@@ -112,6 +112,9 @@ script(client, /, *positional, **keyword) -> Awaitable[R]   # async client
 | `args` | `tuple[str, ...]` | everything else, in `ARGV` order |
 | `variadic_key` | `str \| None` | the `list[Key]` parameter, which fills the rest of `KEYS` |
 | `variadic_arg` | `str \| None` | the list parameter that fills the rest of `ARGV` |
+| `param_annotations` | `tuple[str \| None, ...]` | each parameter's annotation as written, in `params` order |
+| `return_annotation` | `str \| None` | the return annotation as written |
+| `keyword_only` | `tuple[str, ...]` | the parameters declared after a bare `*` |
 | `doc` | `str \| None` | the function's docstring |
 | `source` | `str` | where it was defined, repo-relative |
 
@@ -227,8 +230,9 @@ package at runtime. See
 [Shipping without the dependency](../guide/build-time.md). Every function takes
 the module as a module object or a dotted name, and `out` as a path:
 
-- ending in `.py`, for one module holding every script as a string constant
-  and importing nothing
+- ending in `.py`, for one module importing only the standard library, with a
+  typed function per script, called the way the `@script` is, and its Lua as a
+  string constant
 - anything else, for a directory with one `.lua` file per script
 
 ### `codegen.generate`

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

@@ -1,6 +1,6 @@
 [project]
 name = "redis-lua-py"
-version = "0.5.0"
+version = "0.6.0"
 description = "Write Redis Lua scripts as real Python functions, not strings."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -77,8 +77,9 @@ select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "N", "C4", "PT"]
 python_version = "3.10"
 strict = true
 # test_typing.py carries assert_type() claims about what a call returns, which
-# are only worth anything if mypy actually reads them.
-files = ["src", "tests/test_typing.py"]
+# are only worth anything if mypy actually reads them. generated_scripts.py is
+# codegen output, checked in so that strict mode reads what adopters ship.
+files = ["src", "tests/test_typing.py", "tests/generated_scripts.py"]
 mypy_path = "tests"
 
 # A script body returns Lua-side values, whose Python type is Any by

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

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

{redis_lua_py-0.5.0 → redis_lua_py-0.6.0}/src/redis_lua_py/_compile.py

@@ -2353,6 +2353,10 @@ class CompiledBody:
     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:
@@ -2389,6 +2393,9 @@ def compile_function(
         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,
     )
 
 
@@ -2454,4 +2461,12 @@ def compile_body(func: Callable[..., Any], *, name: str | None = None) -> Compil
         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),
     )

{redis_lua_py-0.5.0 → redis_lua_py-0.6.0}/src/redis_lua_py/_library.py

@@ -43,6 +43,23 @@ def _function_missing(error: BaseException) -> bool:
     return "Function not found" in str(error)
 
 
+def _modern_function_load(client: object) -> Any:
+    """The client's function_load, if it takes the library code first.
+
+    Early redis-py releases, 4.2.0 among them, still have the Redis 7
+    release-candidate signature, function_load(engine, library, code), which
+    no released Redis accepts.
+    """
+    function_load = getattr(client, "function_load", None)
+    if function_load is None:
+        return None
+    try:
+        parameters = list(inspect.signature(function_load).parameters)
+    except (TypeError, ValueError):  # a callable without an inspectable signature
+        return None
+    return function_load if parameters[:1] == ["code"] else None
+
+
 class Library:
     """A Redis Functions library, built from Python functions.
 
@@ -130,8 +147,10 @@ class Library:
         is only needed ahead of a pipeline, or to load at deploy time. Returns
         what the client returns: an awaitable for an async client.
         """
-        function_load = getattr(client, "function_load", None)
+        function_load = _modern_function_load(client)
         if function_load is not None:
+            # Preferred where it exists, since redis-py routes it to every
+            # primary of a cluster.
             return function_load(self.lua, replace=True)
         return client.execute_command("FUNCTION", "LOAD", "REPLACE", self.lua)
 

redis_lua_py-0.6.0/src/redis_lua_py/_portable.py

@@ -0,0 +1,116 @@
+"""Calling a compiled script: the part that has to work without this package.
+
+Everything below the imports is copied, verbatim, into every module that
+:mod:`redis_lua_py.codegen` generates, and :mod:`._script` calls the same
+functions at runtime. That is how a generated wrapper and a ``CompiledScript``
+stay in step: there is only one copy of this code to get right.
+
+So this module imports only the standard library, and nothing from the
+package, and every name it defines starts with an underscore, to stay out of
+the way of the scripts in a generated module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+from weakref import WeakKeyDictionary
+
+#: What a generated signature accepts for a key, the same as redis-py does.
+_Key = str | bytes | memoryview
+
+#: What a generated signature accepts for an argument it has no better type for.
+_Arg = str | bytes | memoryview | int | float
+
+
+class _AsyncClient(Protocol):
+    """Enough of an async redis-py client to tell it from a sync one.
+
+    Only used to type the two shapes of call. ``__aenter__`` is the
+    discriminator because every async client has one and no sync client does,
+    on every supported redis-py -- ``aclose`` only arrived in redis-py 5.
+    """
+
+    async def __aenter__(self) -> Any: ...
+
+    def register_script(self, script: str) -> Any: ...
+
+
+def _encode(
+    name: str, value: object, error: type[Exception] = TypeError
+) -> str | bytes | memoryview:
+    """Render a Python value as a Redis argument.
+
+    Redis has no argument types: everything on the wire is a byte string. This
+    only accepts values whose string form is unambiguous, so that a stray None
+    or object fails here rather than arriving in Lua as something surprising.
+    """
+    if isinstance(value, bool):
+        return "1" if value else "0"
+    if isinstance(value, str | bytes | memoryview):
+        return value
+    if isinstance(value, int | float):
+        return repr(value) if isinstance(value, float) else str(value)
+    raise error(
+        f"argument {name!r} is a {type(value).__name__}, which has no Redis representation. "
+        "Pass a str, bytes, int, float or bool."
+    )
+
+
+def _items(name: str, value: object, error: type[Exception] = TypeError) -> list[Any]:
+    """The elements passed for a list parameter.
+
+    A string is iterable too, and splitting a key into characters is never
+    what was meant, so it is refused rather than spread.
+    """
+    if isinstance(value, str | bytes | memoryview) or not isinstance(value, Iterable):
+        raise error(
+            f"argument {name!r} takes a list, got a {type(value).__name__}. "
+            "Wrap a single value in a list."
+        )
+    return list(value)
+
+
+def _encode_all(
+    name: str, value: object, error: type[Exception] = TypeError
+) -> list[str | bytes | memoryview]:
+    """The elements passed for a list of arguments, each rendered for Redis."""
+    return [_encode(name, item, error) for item in _items(name, value, error)]
+
+
+def _is_cluster_pipeline(client: object) -> bool:
+    cls = type(client)
+    return cls.__name__ == "ClusterPipeline" and cls.__module__.startswith("redis.")
+
+
+def _registered(lua: str, registry: WeakKeyDictionary[Any, Any], client: Any) -> Any:
+    """The redis-py Script for this source on this client, registered once.
+
+    redis-py's own Script object already implements the EVALSHA-then-EVAL
+    dance and the NOSCRIPT retry, so this defers to it rather than
+    reimplementing script caching.
+    """
+    try:
+        registered = registry.get(client)
+    except TypeError:  # a client that does not support weak references
+        return client.register_script(lua)
+    if registered is None:
+        registered = client.register_script(lua)
+        registry[client] = registered
+    return registered
+
+
+def _run(
+    lua: str,
+    registry: WeakKeyDictionary[Any, Any],
+    client: Any,
+    keys: list[Any],
+    argv: list[Any],
+) -> Any:
+    """Run a script: a value from a sync client, an awaitable from an async one."""
+    if _is_cluster_pipeline(client):
+        # redis-py refuses EVALSHA on a cluster pipeline, and a queued
+        # EVALSHA could not recover from NOSCRIPT at execute time anyway,
+        # so the source travels with the command.
+        return client.eval(lua, len(keys), *keys, *argv)
+    return _registered(lua, registry, client)(keys=keys, args=argv, client=client)

{redis_lua_py-0.5.0 → redis_lua_py-0.6.0}/src/redis_lua_py/_script.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import difflib
-from collections.abc import Awaitable, Iterable
+from collections.abc import Awaitable
 from dataclasses import dataclass, field
 from typing import Any, Generic, Protocol, TypeVar, overload
 from weakref import WeakKeyDictionary
 
+from ._portable import _AsyncClient, _encode, _encode_all, _items, _registered, _run
 from .errors import ScriptArgumentError
 
 #: What a script's return annotation describes: the value the *caller* gets
@@ -17,56 +18,9 @@ R = TypeVar("R")
 #: What calling a bound script produces -- ``R``, or an awaitable of it.
 T = TypeVar("T")
 
-
-class AsyncClient(Protocol):
-    """Enough of an async redis-py client to tell it from a sync one.
-
-    Only used to type the two shapes of call. ``__aenter__`` is the
-    discriminator because every async client has one and no sync client does,
-    on every supported redis-py -- ``aclose`` only arrived in redis-py 5.
-    """
-
-    async def __aenter__(self) -> Any: ...  # pragma: no cover - a typing shape
-
-    def register_script(self, script: str) -> Any: ...  # pragma: no cover
-
-
-def encode(name: str, value: object) -> str | bytes | memoryview:
-    """Render a Python value as a Redis argument.
-
-    Redis has no argument types: everything on the wire is a byte string. This
-    only accepts values whose string form is unambiguous, so that a stray None
-    or object fails here rather than arriving in Lua as something surprising.
-    """
-    if isinstance(value, bool):
-        return "1" if value else "0"
-    if isinstance(value, str | bytes | memoryview):
-        return value
-    if isinstance(value, int | float):
-        return repr(value) if isinstance(value, float) else str(value)
-    raise ScriptArgumentError(
-        f"argument {name!r} is a {type(value).__name__}, which has no Redis representation. "
-        "Pass a str, bytes, int, float or bool."
-    )
-
-
-def _items(name: str, value: object) -> list[object]:
-    """The elements passed for a list parameter.
-
-    A string is iterable too, and splitting a key into characters is never
-    what was meant, so it is refused rather than spread.
-    """
-    if isinstance(value, str | bytes | memoryview) or not isinstance(value, Iterable):
-        raise ScriptArgumentError(
-            f"argument {name!r} takes a list, got a {type(value).__name__}. "
-            "Wrap a single value in a list."
-        )
-    return list(value)
-
-
-def _is_cluster_pipeline(client: object) -> bool:
-    cls = type(client)
-    return cls.__name__ == "ClusterPipeline" and cls.__module__.startswith("redis.")
+#: Enough of an async redis-py client to tell it from a sync one. It lives with
+#: the rest of the call path in ``_portable``, which generated modules copy.
+AsyncClient = _AsyncClient
 
 
 def resolve_arguments(
@@ -104,15 +58,15 @@ def resolve_arguments(
     resolved_keys: list[Any] = []
     for k in keys:
         if k == variadic_key:
-            resolved_keys.extend(_items(k, values[k]))
+            resolved_keys.extend(_items(k, values[k], ScriptArgumentError))
         else:
             resolved_keys.append(values[k])
     argv: list[Any] = []
     for a in args:
         if a == variadic_arg:
-            argv.extend(encode(a, item) for item in _items(a, values[a]))
+            argv.extend(_encode_all(a, values[a], ScriptArgumentError))
         else:
-            argv.append(encode(a, values[a]))
+            argv.append(_encode(a, values[a], ScriptArgumentError))
     return resolved_keys, argv
 
 
@@ -165,6 +119,13 @@ class CompiledScript(Generic[R]):
     variadic_key: str | None = None
     #: The list parameter whose elements fill the rest of ARGV.
     variadic_arg: str | None = None
+    #: Each parameter's annotation as written in the source, or None, in the
+    #: order of ``params``; what a generated function's signature is built from.
+    param_annotations: tuple[str | None, ...] = ()
+    #: The return annotation as written in the source, or None.
+    return_annotation: str | None = None
+    #: The parameters declared after a bare ``*``.
+    keyword_only: tuple[str, ...] = ()
     _registry: WeakKeyDictionary[Any, Any] = field(
         default_factory=WeakKeyDictionary, compare=False, repr=False
     )
@@ -179,12 +140,7 @@ class CompiledScript(Generic[R]):
 
     def __call__(self, client: Any, /, *positional: object, **keyword: object) -> Any:
         keys, argv = self.resolve(*positional, **keyword)
-        if _is_cluster_pipeline(client):
-            # redis-py refuses EVALSHA on a cluster pipeline, and a queued
-            # EVALSHA could not recover from NOSCRIPT at execute time anyway,
-            # so the source travels with the command.
-            return client.eval(self.lua, len(keys), *keys, *argv)
-        return self._for(client)(keys=keys, args=argv, client=client)
+        return _run(self.lua, self._registry, client, keys, argv)
 
     @overload
     def bind(self, client: AsyncClient) -> BoundScript[Awaitable[R]]: ...
@@ -215,20 +171,8 @@ class CompiledScript(Generic[R]):
         )
 
     def _for(self, client: Any) -> Any:
-        """Get the redis-py Script bound to this client, registering it once.
-
-        redis-py's own Script object already implements the EVALSHA-then-EVAL
-        dance and the NOSCRIPT retry, so this defers to it rather than
-        reimplementing script caching.
-        """
-        try:
-            registered = self._registry.get(client)
-        except TypeError:  # a client that does not support weak references
-            return client.register_script(self.lua)
-        if registered is None:
-            registered = client.register_script(self.lua)
-            self._registry[client] = registered
-        return registered
+        """Get the redis-py Script bound to this client, registering it once."""
+        return _registered(self.lua, self._registry, client)
 
     def __repr__(self) -> str:
         signature = ", ".join(self.params)