py-redis-semaphore 0.1.1__tar.gz

py_redis_semaphore-0.1.1/.editorconfig

@@ -0,0 +1,25 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

py_redis_semaphore-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,89 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug", "triage"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug!
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Create Semaphore with config...
+        2. Call acquire()...
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Code Example
+      description: Minimal code to reproduce the issue.
+      render: python
+
+  - type: input
+    id: version
+    attributes:
+      label: Library Version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: input
+    id: redis-version
+    attributes:
+      label: Redis Version
+      placeholder: "7.2"
+
+  - type: dropdown
+    id: api-type
+    attributes:
+      label: API Type
+      options:
+        - Sync
+        - Async
+        - Both
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Traceback
+      description: Any relevant logs or error traceback.
+      render: shell
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem.

py_redis_semaphore-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,56 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or features you've considered.
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Example Usage
+      description: How would this feature be used?
+      render: python
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      options:
+        - New feature
+        - Enhancement to existing feature
+        - Performance improvement
+        - Documentation
+        - Other
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or references.

py_redis_semaphore-0.1.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"

py_redis_semaphore-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,32 @@
+## Description
+
+<!-- Brief description of what this PR does -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+
+## Related Issues
+
+<!-- Link to related issues: Fixes #123, Closes #456 -->
+
+## Checklist
+
+- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) guidelines
+- [ ] My code follows the project's code style (ran `make ruff-fix`)
+- [ ] I have added tests that prove my fix/feature works
+- [ ] All new and existing tests pass (`make test`)
+- [ ] Type checking passes (`make typecheck`)
+- [ ] I have updated documentation if needed
+
+## Testing
+
+<!-- How was this tested? -->
+
+## Screenshots / Logs
+
+<!-- If applicable, add screenshots or logs -->

py_redis_semaphore-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    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@v6
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov --cov-report=xml --cov-report=term-missing --cov-fail-under=80 -v
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

py_redis_semaphore-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

py_redis_semaphore-0.1.1/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.claude/
+
+# Virtual environments
+.venv
+
+habr_article.md

py_redis_semaphore-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [redis>=5.0.0, types-redis]
+        args: [--ignore-missing-imports]
+        files: ^src/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict

py_redis_semaphore-0.1.1/.python-version

@@ -0,0 +1 @@
+3.10

py_redis_semaphore-0.1.1/ARCHITECTURE.md

@@ -0,0 +1,258 @@
+# How the semaphore works
+
+A step-by-step description of the algorithm, in words and examples, without diagrams.
+
+Scenario: there is a shared Redis and several applications that need to limit
+concurrent access to a resource.
+
+---
+
+## 1) What is stored in Redis
+
+For a semaphore named `payments`, two keys are created (the `namespace` prefix
+defaults to `semaphore`):
+
+1) `semaphore:payments:owners` (ZSET)
+   - member: the unique identifier of an owner (process/instance)
+   - score: the expiration time of that owner (milliseconds)
+
+2) `semaphore:payments:fencing` (STRING)
+   - an integer that grows via INCR
+   - this is the fencing token
+
+---
+
+## 2) What acquire does (obtain a slot)
+
+Suppose `limit=2` and there are 3 processes: A, B, C.
+
+### What happens in Redis
+
+1) Expired owners are removed (ZREMRANGEBYSCORE).
+2) If the current identifier is already an owner:
+   - its TTL is updated
+   - the fencing token is incremented
+   - success is returned
+3) The current number of owners is counted (ZCARD).
+4) If there are fewer owners than `limit`:
+   - a new owner is added to the ZSET with a fresh expires_at
+   - the fencing token is incremented
+   - success is returned
+5) If there are already `limit` owners:
+   - "busy" is returned
+
+### Blocking vs non-blocking
+
+- `blocking=True` (default) — a wait loop stepping at `retry_interval`
+  until a slot is acquired or `acquire_timeout` elapses.
+- `acquire_timeout=None` — wait forever.
+- `blocking=False` — a single attempt and an immediate `busy` response, no waiting.
+
+Note: `with Semaphore(...)` always uses `blocking=True` and will wait for a
+slot; if `acquire_timeout` is set, an `AcquireTimeoutError` is raised when it
+elapses.
+
+### Example
+
+- A calls acquire -> gets a slot (token=1)
+- B calls acquire -> gets a slot (token=2)
+- C calls acquire:
+  - if blocking=False -> immediately "busy"
+  - if blocking=True -> waits and retries
+
+---
+
+## 3) How waiting works (blocking)
+
+There are two wait strategies, selected via `acquire_mode`:
+
+### BLPOP (default)
+
+Uses Redis `BLPOP` for a blocking wait:
+
+```
+try acquire
+if busy:
+    BLPOP semaphore:{name}:queue timeout
+    try again
+```
+
+On `release()`, a signal is pushed to the queue via `LPUSH`, which wakes a
+waiting client.
+
+**Advantages of BLPOP:**
+- Minimal load on Redis (no constant polling)
+- Instant wake-up when a slot is freed
+- The queue is not stored explicitly — it is a wake-up signal, not a strict FIFO
+
+**Fallback:**
+
+If the signal is lost (a race condition), a retry happens after `blpop_timeout`
+seconds — this protects against waiting forever.
+
+### Additional key for BLPOP
+
+When using BLPOP, a third key is created:
+
+3) `semaphore:payments:queue` (LIST)
+   - used to notify waiters via BLPOP/LPUSH
+   - this is not a real wait queue: the elements are just wake-up signals
+
+### POLLING
+
+Waiting is a local loop inside the process:
+
+```
+try acquire
+if busy:
+    sleep(retry_interval)
+    try again
+```
+
+**With exponential backoff:**
+
+If `retry_interval_max` is set, the interval grows exponentially:
+```
+attempt 1: sleep(0.1)
+attempt 2: sleep(0.2)
+attempt 3: sleep(0.4)
+...
+attempt N: sleep(min(calculated, retry_interval_max))
+```
+
+**With jitter:**
+
+If `retry_jitter` is set (e.g. 0.1), a random amount of up to 10% of the current
+interval is added. This helps avoid a thundering herd, when many clients wake up
+at the same time.
+
+---
+
+**Note:** In DEBUG logs, `waiting=1` is a **local counter** within this process
+only, not the global number of waiters across the whole system.
+
+---
+
+## 4) Release (free a slot)
+
+When a process is done, it calls `release()`:
+
+1) The heartbeat is stopped.
+2) Its identifier is removed from owners in Redis.
+3) Waiting clients are notified (LPUSH into queue).
+4) Local state is reset.
+
+The notification (step 3) always happens, regardless of `acquire_mode` —
+this lets different clients use different wait strategies.
+
+Calling `release()` without a successful `acquire()` raises an error.
+
+---
+
+## 5) Refresh and Heartbeat (extending the TTL)
+
+### Refresh
+
+`refresh()` extends the owner's TTL:
+1) Redis checks that the identifier still exists and has not expired.
+2) If everything is fine -> it extends the TTL.
+3) If it expired or is missing -> it returns False (lock lost).
+
+### Heartbeat
+
+Once a slot is acquired, a background heartbeat starts and periodically calls
+`refresh()` to extend the TTL.
+
+If the heartbeat stops working (the process dies, the network drops), the TTL
+expires and the slot frees itself.
+
+---
+
+## 6) Lock lost
+
+Scenario:
+
+- A process believes it holds a slot.
+- But its TTL expired or the record was removed.
+- refresh returns False.
+
+What happens next:
+- If strict_mode=False: a warning is logged, but the code keeps running.
+- If strict_mode=True: a LockLostError is raised immediately.
+
+This is useful for critical systems where you must not continue after losing the lock.
+
+---
+
+## 7) Fencing token (protection against races)
+
+A fencing token is a number that grows on every successful acquire.
+Even on a repeated acquire by the same owner, the token increases.
+
+### Why this is needed
+
+Imagine:
+- Process A obtained token=10 but then stalled and never finished its work.
+- Process B obtained token=11 and continued.
+
+If the resource (e.g. a database) only accepts the highest token, then stale
+operations carrying token=10 can be safely ignored.
+
+---
+
+## 8) Example of a full cycle
+
+limit=2, processes A, B, C:
+
+1) A acquire -> success, token=1
+2) B acquire -> success, token=2
+3) C acquire -> busy, waits
+4) A release -> a slot frees up
+5) C acquire -> success, token=3
+
+---
+
+## 9) Time: client-side or server-side
+
+By default, client-side time (`time.time()`) is used.
+You can enable `use_server_time=True`, and time will be taken from Redis (`TIME`).
+
+Why this is needed:
+- If clocks on different machines drift, server-side time is more reliable.
+- The downside: an extra network RTT.
+
+---
+
+## 10) Sync vs Async
+
+The same `Semaphore` object cannot be used in both sync and async modes
+at the same time.
+
+Example of incorrect usage:
+```
+sem.acquire()   # sync
+await sem.aacquire()  # async -> error
+```
+
+This protects against races inside a single object.
+
+---
+
+## 11) Metrics and logging
+
+### Metrics
+
+Metrics are counted **within the process**, not globally.
+If there are many processes, Prometheus should aggregate them itself.
+
+### DEBUG logs
+
+Logs like:
+```
+Semaphore 'payments' usage 2/2
+Semaphore 'payments' full 2/2; waiting=1
+```
+
+- `usage 2/2` — total slots taken in Redis
+- `waiting=1` — local to the current process
+

py_redis_semaphore-0.1.1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [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).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-06-02
+
+### Added
+
+- `status()` / `astatus()` returning a `SemaphoreStatus` — observe occupancy,
+  availability, ownership, and slot expiry without acquiring (expired owners are
+  purged first)
+- `cleanup()` / `acleanup()` to force-remove expired owner entries; returns the
+  number of entries removed
+- `AcquireResult.used_slots` — slot occupancy observed atomically by the acquire
+  call, for observability without an extra round-trip
+- `SemaphoreConfig.refresh_retry_interval` — retry cadence for the heartbeat
+  after a transient connection error (defaults to `min(refresh_interval, 1.0)`)
+- Backend error hierarchy: `BackendError`, `TransientBackendError`,
+  `PermanentBackendError`, and `CommandDeniedError`
+- BLPOP wait strategy (now the default) and POLLING with exponential backoff and
+  jitter, selectable via `acquire_mode`
+
+### Changed
+
+- Heartbeat now tolerates transient Redis connection errors and keeps retrying
+  until the lock is refreshed or `lock_timeout` elapses since the last
+  successful refresh; only then is the lock treated as lost. Permanent errors
+  (e.g. ACL denial → `PermanentBackendError`) escalate immediately
+- `RedisConnectionError` is now a subclass of `TransientBackendError`
+
+### Removed
+
+- `RefreshError` (no longer part of the public API)
+
+## [0.1.0] - 2026-01-15
+
+### Added
+
+- Initial release
+- `Semaphore` - counting semaphore with configurable limit
+- `Mutex` - exclusive lock (binary semaphore)
+- Sync and async API support via same classes
+- Redis Sentinel support for high availability
+- Automatic heartbeat to maintain lock TTL
+- Fencing tokens for distributed consistency
+- `on_lock_lost` callback for lock loss detection
+- Prometheus metrics (optional)
+- Custom logger support (loguru, structlog compatible)
+
+### Technical
+
+- Atomic operations via Lua scripts
+- `py.typed` marker for PEP 561 compliance
+- Python 3.10+ support