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

redis_lua_py-0.2.1/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  # A pull request only builds, so a broken link fails review rather than main.
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time, and never cancel one in flight.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      # Link validation is on in zensical.toml, so this fails on a dead link.
+      - run: uv run zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

{redis_lua_py-0.1.0 → redis_lua_py-0.2.1}/.gitignore

@@ -22,3 +22,6 @@ htmlcov/
 .idea/
 .vscode/
 .DS_Store
+
+# Docs site
+site/

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

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

redis_lua_py-0.2.1/CHANGELOG.md

@@ -0,0 +1,116 @@
+# 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.1](https://github.com/IgnaceMaes/redis-lua-py/compare/v0.2.0...v0.2.1) (2026-09-12)
+
+
+### Documentation
+
+* add a documentation site built with zensical ([#4](https://github.com/IgnaceMaes/redis-lua-py/issues/4)) ([f877f97](https://github.com/IgnaceMaes/redis-lua-py/commit/f877f97c0b7c8126ab62ef2324aff99106434ee4))
+
+## [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.1}/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.2.1/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: redis-lua-py
+Version: 0.2.1
+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/
+Project-URL: Repository, https://github.com/ignacemaes/redis-lua-py
+Project-URL: Issues, https://github.com/ignacemaes/redis-lua-py/issues
+Project-URL: Changelog, https://github.com/ignacemaes/redis-lua-py/blob/main/CHANGELOG.md
+Author: Ignace Maes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: eval,evalsha,lua,redis,scripting,transpiler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Lua
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: redis>=5.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/banner-dark.svg">
+    <img alt="redis-lua-py: Redis Lua scripts as real Python functions." src="./.github/assets/banner-light.svg" width="860">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/redis-lua-py/"><img alt="PyPI" src="https://img.shields.io/pypi/v/redis-lua-py?color=%230070F3&label=pypi"></a>
+  <a href="https://pypi.org/project/redis-lua-py/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/redis-lua-py?color=%230070F3"></a>
+  <a href="https://github.com/ignacemaes/redis-lua-py/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ignacemaes/redis-lua-py/ci.yml?branch=main&color=%230070F3&label=ci"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/pypi/l/redis-lua-py?color=%230070F3"></a>
+</p>
+
+<p align="center">
+  Write Redis Lua scripts as real Python functions, not as strings.<br>
+  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py.
+</p>
+
+<p align="center">
+  <b><a href="https://ignacemaes.com/redis-lua-py/">Documentation</a></b> ·
+  <a href="https://ignacemaes.com/redis-lua-py/quickstart/">Quickstart</a> ·
+  <a href="https://ignacemaes.com/redis-lua-py/reference/api/">API reference</a> ·
+  <a href="./CHANGELOG.md">Changelog</a>
+</p>
+
+```python
+from redis_lua_py import Key, redis, script
+
+
+@script
+def rate_limit(key: Key, limit: int, ttl: int) -> int:
+    current = redis.incr(key)
+    if current == 1:
+        redis.expire(key, ttl)
+    if current > limit:
+        return -1
+    return limit - current
+```
+
+The body is never executed by Python. It is read as source when the module is
+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
+
+client = Redis()
+remaining = rate_limit(client, key="user:42", limit=10, ttl=60)
+```
+
+Importing the client as `from redis import Redis` leaves the name `redis` free
+for the script namespace, so the two never collide.
+
+## Install
+
+```bash
+uv add redis-lua-py
+```
+
+Python 3.11+, and redis-py 5.0+ as the only dependency.
+
+## What it compiles to
+
+Nothing is hidden. Every script exposes the Lua it produced:
+
+```python
+>>> print(rate_limit.lua)
+```
+
+```lua
+-- rate_limit
+-- 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])
+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
+```
+
+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.
+
+## What else it does
+
+- **[Keys and arguments](https://ignacemaes.com/redis-lua-py/guide/keys-and-arguments/)** —
+  a parameter annotated `Key` becomes `KEYS`, which is what Redis Cluster
+  routes on; an `int` or `float` is wrapped in `tonumber` for you.
+- **[Command names are checked](https://ignacemaes.com/redis-lua-py/guide/calling-redis-commands/)**
+  at compile time against Redis' own command table, so `redis.expires(...)` is
+  refused where you can see it rather than raised inside a script whose whole
+  purpose was to be atomic.
+- **[Constants are folded](https://ignacemaes.com/redis-lua-py/guide/constants/)** —
+  a module-level `int`, `float`, `str`, `bytes` or `bool` is read once, at
+  import, and written into the script as a literal.
+- **[Binary values survive](https://ignacemaes.com/redis-lua-py/guide/binary-values/)** —
+  nothing here decodes, and `bytes` is a passthrough in both directions.
+- **[The caller's side is typed](https://ignacemaes.com/redis-lua-py/guide/return-values/)** —
+  a script is a `CompiledScript[R]`, and an async client gives you
+  `Awaitable[R]`.
+- **[Sync and async](https://ignacemaes.com/redis-lua-py/guide/async/)** from
+  the same script object, and
+  **[`bind`](https://ignacemaes.com/redis-lua-py/guide/binding-a-client/)** when
+  passing the client every time gets repetitive.
+- **[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.
+- **[Anything outside the supported subset](https://ignacemaes.com/redis-lua-py/reference/supported-subset/)**
+  raises at import, with a caret under the line at fault.
+
+Full documentation: **[ignacemaes.com/redis-lua-py](https://ignacemaes.com/redis-lua-py/)**.
+
+## Testing your scripts
+
+[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. `.lua` is the whole script, so a golden snapshot is a string
+comparison — see
+[Testing your scripts](https://ignacemaes.com/redis-lua-py/guide/testing/).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy
+```
+
+Tests run against [fakeredis](https://github.com/cunla/fakeredis-py), which
+executes real Lua, so `uv run pytest` needs no server. Set `REDIS_URL` to also
+run them against a live Redis:
+
+```bash
+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
+```
+
+The docs site is built with [Zensical](https://zensical.org); `uv run zensical
+serve` previews it with live reload.
+
+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
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

redis_lua_py-0.2.1/README.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/banner-dark.svg">
+    <img alt="redis-lua-py: Redis Lua scripts as real Python functions." src="./.github/assets/banner-light.svg" width="860">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/redis-lua-py/"><img alt="PyPI" src="https://img.shields.io/pypi/v/redis-lua-py?color=%230070F3&label=pypi"></a>
+  <a href="https://pypi.org/project/redis-lua-py/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/redis-lua-py?color=%230070F3"></a>
+  <a href="https://github.com/ignacemaes/redis-lua-py/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ignacemaes/redis-lua-py/ci.yml?branch=main&color=%230070F3&label=ci"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/pypi/l/redis-lua-py?color=%230070F3"></a>
+</p>
+
+<p align="center">
+  Write Redis Lua scripts as real Python functions, not as strings.<br>
+  Compiled at import, checked by <code>mypy</code>, sent with <code>EVALSHA</code>. Sync and async redis-py.
+</p>
+
+<p align="center">
+  <b><a href="https://ignacemaes.com/redis-lua-py/">Documentation</a></b> ·
+  <a href="https://ignacemaes.com/redis-lua-py/quickstart/">Quickstart</a> ·
+  <a href="https://ignacemaes.com/redis-lua-py/reference/api/">API reference</a> ·
+  <a href="./CHANGELOG.md">Changelog</a>
+</p>
+
+```python
+from redis_lua_py import Key, redis, script
+
+
+@script
+def rate_limit(key: Key, limit: int, ttl: int) -> int:
+    current = redis.incr(key)
+    if current == 1:
+        redis.expire(key, ttl)
+    if current > limit:
+        return -1
+    return limit - current
+```
+
+The body is never executed by Python. It is read as source when the module is
+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
+
+client = Redis()
+remaining = rate_limit(client, key="user:42", limit=10, ttl=60)
+```
+
+Importing the client as `from redis import Redis` leaves the name `redis` free
+for the script namespace, so the two never collide.
+
+## Install
+
+```bash
+uv add redis-lua-py
+```
+
+Python 3.11+, and redis-py 5.0+ as the only dependency.
+
+## What it compiles to
+
+Nothing is hidden. Every script exposes the Lua it produced:
+
+```python
+>>> print(rate_limit.lua)
+```
+
+```lua
+-- rate_limit
+-- 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])
+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
+```
+
+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.
+
+## What else it does
+
+- **[Keys and arguments](https://ignacemaes.com/redis-lua-py/guide/keys-and-arguments/)** —
+  a parameter annotated `Key` becomes `KEYS`, which is what Redis Cluster
+  routes on; an `int` or `float` is wrapped in `tonumber` for you.
+- **[Command names are checked](https://ignacemaes.com/redis-lua-py/guide/calling-redis-commands/)**
+  at compile time against Redis' own command table, so `redis.expires(...)` is
+  refused where you can see it rather than raised inside a script whose whole
+  purpose was to be atomic.
+- **[Constants are folded](https://ignacemaes.com/redis-lua-py/guide/constants/)** —
+  a module-level `int`, `float`, `str`, `bytes` or `bool` is read once, at
+  import, and written into the script as a literal.
+- **[Binary values survive](https://ignacemaes.com/redis-lua-py/guide/binary-values/)** —
+  nothing here decodes, and `bytes` is a passthrough in both directions.
+- **[The caller's side is typed](https://ignacemaes.com/redis-lua-py/guide/return-values/)** —
+  a script is a `CompiledScript[R]`, and an async client gives you
+  `Awaitable[R]`.
+- **[Sync and async](https://ignacemaes.com/redis-lua-py/guide/async/)** from
+  the same script object, and
+  **[`bind`](https://ignacemaes.com/redis-lua-py/guide/binding-a-client/)** when
+  passing the client every time gets repetitive.
+- **[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.
+- **[Anything outside the supported subset](https://ignacemaes.com/redis-lua-py/reference/supported-subset/)**
+  raises at import, with a caret under the line at fault.
+
+Full documentation: **[ignacemaes.com/redis-lua-py](https://ignacemaes.com/redis-lua-py/)**.
+
+## Testing your scripts
+
+[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. `.lua` is the whole script, so a golden snapshot is a string
+comparison — see
+[Testing your scripts](https://ignacemaes.com/redis-lua-py/guide/testing/).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+uv run mypy
+```
+
+Tests run against [fakeredis](https://github.com/cunla/fakeredis-py), which
+executes real Lua, so `uv run pytest` needs no server. Set `REDIS_URL` to also
+run them against a live Redis:
+
+```bash
+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
+```
+
+The docs site is built with [Zensical](https://zensical.org); `uv run zensical
+serve` previews it with live reload.
+
+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
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

redis_lua_py-0.2.1/docs/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="redis-lua-py">
+  <rect width="64" height="64" rx="14" fill="#000000"/>
+  <g transform="translate(7.6 7.6) scale(0.76)"><defs><mask id="l"><rect width="64" height="64" fill="#fff"/><path d="M40 15.8 L64.2 40 L40 64.2 L15.8 40 Z" fill="#000"/></mask></defs><g fill="none" stroke="#FFFFFF" stroke-width="6.0" stroke-linejoin="miter"><path mask="url(#l)" d="M8 8 H36 V36 H8 Z"/><path d="M40 20 L60 40 L40 60 L20 40 Z"/></g></g>
+</svg>

redis_lua_py-0.2.1/docs/contributing.md

@@ -0,0 +1,67 @@
+# Contributing
+
+## Getting set up
+
+```bash
+uv sync --dev
+uv run pytest && uv run ruff check && uv run ruff format --check && uv run mypy
+```
+
+See [Development](development.md) for running the suite against a live Redis
+and for regenerating the command table.
+
+## Commit messages
+
+Pull requests are squash-merged, so **the PR title becomes the commit subject
+on `main`**, and that subject is the only thing the release tooling reads. It
+must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: compile `pcall` into a protected call
+fix: hoist names assigned in both arms of an if
+docs: document the Key annotation
+```
+
+| Prefix | Changelog section | Version bump |
+| --- | --- | --- |
+| `feat:` | Added | minor |
+| `fix:` | Fixed | patch |
+| `perf:` | Performance | patch |
+| `refactor:` | Changed | patch |
+| `deps:` | Dependencies | patch |
+| `docs:` | Documentation | patch |
+| `chore:` `test:` `ci:` `build:` `style:` | omitted | none |
+
+A `!` after the prefix (`feat!:`) or a `BREAKING CHANGE:` paragraph in the PR
+body marks a breaking change. While the version is below 1.0 that bumps the
+minor, not the major — `0.1.0` becomes `0.2.0`, never `1.0.0`. Promoting the
+project to 1.0 is a deliberate act: set `"release-as": "1.0.0"` once in
+`release-please-config.json`, or land a commit with a `Release-As: 1.0.0`
+footer.
+
+The subject is copied verbatim into the changelog, so write it as a lowercase
+phrase with no trailing period. `.github/workflows/pr-title.yml` enforces this
+on every pull request.
+
+## Releasing
+
+Releases are cut by merging a pull request; nobody edits a version by hand.
+
+1. Land your PR on `main`.
+2. `.github/workflows/release.yml` runs
+   [release-please](https://github.com/googleapis/release-please), which keeps
+   **one open PR** titled something like `chore(main): release 0.2.0`. Each
+   merge to `main` refreshes it. The PR bumps `version` in `pyproject.toml`,
+   `__version__` in `src/redis_lua_py/__init__.py`, and prepends the new
+   section to `CHANGELOG.md`. Review it like any other PR — the changelog body
+   is editable before you merge.
+3. Merge the release PR. That tags `vX.Y.Z`, publishes a GitHub release, and
+   the same workflow then builds the sdist and wheel and uploads them to PyPI
+   via [trusted publishing](https://docs.pypi.org/trusted-publishers/) — no API
+   token is stored anywhere.
+
+`.release-please-manifest.json` records the last released version and is
+updated by the release PR. Don't edit it by hand.
+
+The full text lives in
+[CONTRIBUTING.md](https://github.com/ignacemaes/redis-lua-py/blob/main/CONTRIBUTING.md).