PyRelukko¶
PyRelukko is the official Python client library for the Relukko resource-locking backend. It provides a simple, distributed locking mechanism for coordinating access to shared resources across multiple Python processes or services.
Relukko is intentionally lightweight: it is designed for collaborative environments. The system assumes clients behave cooperatively, and by design it does not enforce protection against misbehaving clients.
Documentation¶
Full API documentation can be found at:
Features¶
Simple, Pythonic API for acquiring and releasing locks.
Centralized lock management via the Relukko backend.
Lightweight and dependency-minimal.
Useful for distributed systems, CI pipelines, automated testing and shared-resource orchestration.
Important Design Note¶
Relukko and PyRelukko are built for trusted, collaborative clients.
⚠️ No client-side trust guarantees¶
A client that connects to the Relukko backend can forcibly release any lock, including those owned by another client. There is no protection against malicious manipulation of locks.
This is an intentional design decision to keep the system simple and lightweight.
If you require secure, adversarial-resistant locking, you should consider using a system built upon consensus algorithms (e.g., etcd, Consul, Zookeeper).
Ecosystem¶
The Relukko ecosystem consists of the following components:
1. Relukko Backend (Rust)¶
The backend is responsible for storing and arbitrating lock states.
Repository: https://gitlab.com/relukko/relukko
2. PyRelukko Client (Python)¶
This Python package communicates with the backend, providing user-friendly locking primitives.
Repository: https://gitlab.com/relukko/pyrelukko
3. Robotframework-Relukko (Python)¶
Robot Framework keyword library that enables acquiring and releasing locks directly from Robot Framework test suites. Depends on PyRelukko.
Repository: https://gitlab.com/relukko/robotframework-relukko
Installation¶
Install via pip:
pip install pyrelukko
Requires Python 3.11+.
Quick Start¶
Basic Example¶
from pyrelukko import RelukkoClient
relukko = RelukkoClient(
base_url="http://localhost:3000",
api_key="api-key",
)
lock = relukko.acquire_relukko("LockName", "Creator", 300)
lock_id = lock.get('id')
# Perform work while holding the lock
relukko.delete_relukko(lock_id)
When to Use PyRelukko¶
PyRelukko is ideal for:
Distributed test harnesses
CI/CD job coordination
Server orchestration scripts
Managing exclusive access to hardware devices or simulation environments
Any cooperative environment where multiple workers need a shared mutex
It is not designed for untrusted environments or where mutual exclusion must be strongly enforced.
Limitations¶
❗ A malicious or buggy client can release locks it doesn’t own.
❗ No cryptographic guarantees or client identity.
❗ Requires a running Relukko backend server.
❗ Not fault-tolerant like consensus-based systems.
These limitations are intentional, in exchange for simplicity and minimal overhead.
Running the Backend¶
The backend is written in Rust and provides a simple HTTP API. See the backend repository for instructions:
Contributing¶
Contributions to both the Python client and Rust backend are welcome! Feel free to open issues or merge requests in the relevant GitLab repository.
License¶
MIT License.
See LICENSE for details.