pyrelukko 0.10.0__tar.gz

pyrelukko-0.10.0/.gitlab-ci.yml

@@ -0,0 +1,128 @@
+variables:
+  FF_TIMESTAMPS: true
+  RUN_PYLINT:
+    description: Used in rules, if "true" and web triggered run pylint.
+    value: "false"
+    options:
+    - "false"
+    - "true"
+  RUN_PYTEST:
+    description: Used in rules, if "true" and web triggered run the pytests.
+    value: "false"
+    options:
+    - "false"
+    - "true"
+  RELUKKO_HOSTNAME: relukko
+  RELUKKO_BIND_PORT: 3000
+  RELUKKO_API_KEY: "somerandomkey"
+  POSTGRES_USER: relukko
+  POSTGRES_PASSWORD: okkuler
+  POSTGRES_DB: relukko
+  POSTGRES_HOSTNAME: postgres
+
+
+run-pylint:
+  stage: test
+  image: "registry.gitlab.com/relukko/py-tox-images/py-3.14-tox"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+      changes:
+        - src/**/*.py
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      changes:
+        - src/**/*.py
+    - if: $CI_PIPELINE_SOURCE == "web" && $RUN_PYLINT == "true"
+      when: always
+  before_script:
+    - echo "Running PyLint."
+  script:
+    - ./cicd/run_pylint.sh
+  artifacts:
+    when: always
+    expire_in: 2 week
+    paths:
+      - pylint.out.*
+
+
+run-pytest:
+  stage: test
+  services:
+    - name: postgres:17
+      alias: postgres
+    - name: registry.gitlab.com/relukko/relukko:latest
+      alias: relukko
+      variables:
+        DATABASE_URL: "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
+        RELUKKO_USER: "relukko"
+        RELUKKO_PASSWORD: "relukko"
+        RELUKKO_BIND_ADDR: "0.0.0.0"
+        HEALTHCHECK_TCP_PORT: "${RELUKKO_BIND_PORT}"
+  variables:
+    FF_NETWORK_PER_BUILD: 1
+    CI_HAS_RELUKKO: true
+    CI_RELUKKO_BASE_URL: "http://${RELUKKO_HOSTNAME}:${RELUKKO_BIND_PORT}"
+    CI_RELUKKO_API_KEY: "${RELUKKO_API_KEY}"
+  parallel:
+    matrix:
+      - PIPELINE_PY_VERSION: ['3.11', '3.12', '3.13', '3.14']
+  image: "registry.gitlab.com/relukko/py-tox-images/py-$PIPELINE_PY_VERSION-tox"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+      changes:
+        - src/**/*.py
+        - tests/test_*.py
+        - tests/conftest.py
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      changes:
+        - src/**/*.py
+        - tests/test_*.py
+        - tests/conftest.py
+    - if: $CI_PIPELINE_SOURCE == "web" && $RUN_PYTEST == "true"
+      when: always
+  before_script:
+    - echo "Running PyTest."
+  script:
+    - ./cicd/run_pytest.sh
+  artifacts:
+    when: always
+    expire_in: 2 week
+    paths:
+      - pytest-junit*.xml
+      - log*.html
+      - output*.xml
+      - xunit*.xml
+    reports:
+      junit:
+        - pytest-junit*.xml
+        - xunit*.xml
+
+run-shellcheck:
+  stage: test
+  image: "registry.gitlab.com/relukko/py-tox-images/py-3.14-tox"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
+      changes:
+        - cicd/*.sh
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      changes:
+        - cicd/*.sh
+  before_script:
+    - echo "Running ShellCheck."
+  script:
+    - ./cicd/run_shellcheck.sh
+
+
+publish:
+  stage: deploy
+  image: "registry.gitlab.com/relukko/py-tox-images/py-3.14-tox"
+  environment: publish
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/ && $CI_PIPELINE_SOURCE == "push"
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  before_script:
+    - echo "Publishing to PyPi..."
+  script:
+    - ./cicd/run_publish.sh
+

pyrelukko-0.10.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    install:
+       # Since the install step is overridden, pip is no longer updated automatically.
+       - pip install --upgrade pip
+       - pip install .
+       - pip install --group 'docs'
+       - pip install --group 'test'
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py

pyrelukko-0.10.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Reto Zingg <g.d0b3rm4n@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyrelukko-0.10.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: pyrelukko
+Version: 0.10.0
+Summary: The client library for Relukko can be found in module
+Author-email: Reto Zingg <g.d0b3rm4n@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+License-File: LICENSE
+Requires-Dist: requests >=2.32.5
+Requires-Dist: websockets >= 15.0
+Project-URL: Homepage, https://gitlab.com/relukko/pyrelukko
+Project-URL: Issues, https://gitlab.com/relukko/pyrelukko/-/issues
+
+# PyRelukko
+
+![PyPI - Version](https://img.shields.io/pypi/v/pyrelukko.svg)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyrelukko.svg)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fgitlab.com%2Frelukko%2Fpyrelukko%2F-%2Fraw%2Fmaster%2Fpyproject.toml%3Fref_type%3Dheads)
+![Gitlab Pipeline Status](https://img.shields.io/gitlab/pipeline-status/relukko%2Fpyrelukko?branch=master)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pyrelukko)
+![PyPI - License](https://img.shields.io/pypi/l/pyrelukko)
+![GitLab License](https://img.shields.io/gitlab/license/relukko%2Fpyrelukko)
+![PyPI - Format](https://img.shields.io/pypi/format/pyrelukko)
+![PyPI - Status](https://img.shields.io/pypi/status/pyrelukko)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyrelukko)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/pyrelukko)
+![GitLab Stars](https://img.shields.io/gitlab/stars/relukko%2Fpyrelukko)
+![GitLab Forks](https://img.shields.io/gitlab/forks/relukko%2Fpyrelukko)
+
+---
+
+**PyRelukko** is the official Python client library for the
+[Relukko](https://gitlab.com/relukko/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:
+
+👉 [https://pyrelukko.readthedocs.io](https://pyrelukko.readthedocs.io)
+
+---
+
+## Features
+
+* **Simple, Pythonic API** for acquiring and releasing locks.
+* **Centralized lock management** via the
+  [Relukko](https://gitlab.com/relukko/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](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](https://gitlab.com/relukko/pyrelukko)
+
+👉 [https://pyrelukko.readthedocs.io](https://pyrelukko.readthedocs.io)
+
+### 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](https://gitlab.com/relukko/robotframework-relukko)
+
+---
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pyrelukko
+```
+
+Requires Python **3.11+**.
+
+---
+
+## Quick Start
+
+### Basic Example
+
+```python
+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:
+
+👉 [https://gitlab.com/relukko/relukko](https://gitlab.com/relukko/relukko)
+
+---
+
+## 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.
+

pyrelukko-0.10.0/README.md

@@ -0,0 +1,175 @@
+# PyRelukko
+
+![PyPI - Version](https://img.shields.io/pypi/v/pyrelukko.svg)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyrelukko.svg)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fgitlab.com%2Frelukko%2Fpyrelukko%2F-%2Fraw%2Fmaster%2Fpyproject.toml%3Fref_type%3Dheads)
+![Gitlab Pipeline Status](https://img.shields.io/gitlab/pipeline-status/relukko%2Fpyrelukko?branch=master)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pyrelukko)
+![PyPI - License](https://img.shields.io/pypi/l/pyrelukko)
+![GitLab License](https://img.shields.io/gitlab/license/relukko%2Fpyrelukko)
+![PyPI - Format](https://img.shields.io/pypi/format/pyrelukko)
+![PyPI - Status](https://img.shields.io/pypi/status/pyrelukko)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyrelukko)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/pyrelukko)
+![GitLab Stars](https://img.shields.io/gitlab/stars/relukko%2Fpyrelukko)
+![GitLab Forks](https://img.shields.io/gitlab/forks/relukko%2Fpyrelukko)
+
+---
+
+**PyRelukko** is the official Python client library for the
+[Relukko](https://gitlab.com/relukko/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:
+
+👉 [https://pyrelukko.readthedocs.io](https://pyrelukko.readthedocs.io)
+
+---
+
+## Features
+
+* **Simple, Pythonic API** for acquiring and releasing locks.
+* **Centralized lock management** via the
+  [Relukko](https://gitlab.com/relukko/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](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](https://gitlab.com/relukko/pyrelukko)
+
+👉 [https://pyrelukko.readthedocs.io](https://pyrelukko.readthedocs.io)
+
+### 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](https://gitlab.com/relukko/robotframework-relukko)
+
+---
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pyrelukko
+```
+
+Requires Python **3.11+**.
+
+---
+
+## Quick Start
+
+### Basic Example
+
+```python
+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:
+
+👉 [https://gitlab.com/relukko/relukko](https://gitlab.com/relukko/relukko)
+
+---
+
+## 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.

pyrelukko-0.10.0/cicd/run_publish.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Main script execution
+main() {
+    tox run -e publish
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/run_pylint.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Main script execution
+main() {
+    tox run -e pylint
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/run_pytest.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Main script execution
+main() {
+    tox run --skip-missing-interpreters --skip-env 'pylint|shellcheck|docs|publish'
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/run_shellcheck.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Main script execution
+main() {
+    tox run -e shellcheck
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/tox_docs_pages.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
+REPO_DIR="$(readlink -f "${SCRIPT_DIR}/..")"
+PUBLIC_DIR="${REPO_DIR}/public"
+DOCS_DIR="${REPO_DIR}/docs"
+
+# Main script execution
+main() {
+    rm -rf "${PUBLIC_DIR}"
+    mkdir -p "${PUBLIC_DIR}"
+    sphinx-build --jobs auto --builder html --write-all "${DOCS_DIR}" "${PUBLIC_DIR}"
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/tox_publish.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+export FLIT_INDEX_URL="https://upload.pypi.org/legacy/"
+export FLIT_USERNAME="__token__"
+
+# Main script execution
+main() {
+    echo "CI: ${CI}"
+    if [[ "${CI}" == "true" ]]; then
+        echo "Push to PyPi!"
+        # Retrieve the OIDC token from GitLab CI/CD,
+        # and exchange it for a PyPI API token
+        oidc_token=$(python -m id PYPI)
+        resp=$(curl -X POST https://pypi.org/_/oidc/mint-token \
+               -d "{\"token\":\"${oidc_token}\"}")
+        api_token=$(jq --raw-output '.token' <<< "${resp}")
+
+        FLIT_PASSWORD="${api_token}" flit publish
+    else
+        echo "Running local, will not push to PyPi!"
+    fi
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/cicd/tox_shellcheck.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
+REPO_DIR="$(readlink -f "${SCRIPT_DIR}/..")"
+
+# Main script execution
+main() {
+    shellcheck "${REPO_DIR}"/cicd/*.sh   
+}
+
+# Execute the main function
+main
+
+# vim:set softtabstop=4 shiftwidth=4 tabstop=4 expandtab:

pyrelukko-0.10.0/docs/apidocs/modules.rst

@@ -0,0 +1,10 @@
+PyRelukko
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   pyrelukko
+
+.. DO NOT CONVERT TO Markdown! MESSES WITH AUTODOC!
+

pyrelukko-0.10.0/docs/apidocs/pyrelukko.decorators.rst

@@ -0,0 +1,10 @@
+pyrelukko.decorators module
+===========================
+
+.. automodule:: pyrelukko.decorators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. DO NOT CONVERT TO Markdown! MESSES WITH AUTODOC!
+

pyrelukko-0.10.0/docs/apidocs/pyrelukko.pyrelukko.rst

@@ -0,0 +1,10 @@
+pyrelukko.pyrelukko module
+==========================
+
+.. automodule:: pyrelukko.pyrelukko
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. DO NOT CONVERT TO Markdown! MESSES WITH AUTODOC!
+