Metadata-Version: 2.5
Name: abide
Version: 0.0.2
Summary: Cross-process concurrency gate with leased lock-file slots.
Project-URL: Homepage, https://github.com/lqxnjk/abide
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: concurrency,lock,multiprocess,semaphore,throttle
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# abide

Cap how many processes hit a resource at once — using only lock files, so it
works across processes and across machines sharing a directory.

## Install

```console
pip install abide
```

## Usage

```python
from abide import GateLock

gate = GateLock("./locks", m_capacity=4, n_ttl=120, n_timeout=30)

with gate.slot() as index:
    call_the_rate_limited_api()
```

## Why not `threading.Semaphore`

A semaphore lives in one process. Nine worker processes each opening eight
threads means 72 concurrent requests, no matter what each process believes.
Slot files on disk are shared by everyone.

## Behaviour

| Aspect | Detail |
| --- | --- |
| Slot storage | `slot-<i>.lock` files created with `O_EXCL` |
| Crashed holder | slot older than `n_ttl` seconds is reclaimed |
| No free slot | waits, then raises `SlotTimeout` |
| Re-entrancy | **not** re-entrant: nested `with` blocks each take a slot |

`TimeoutError` (via `SlotTimeout`) is raised rather than blocking forever — a
gate that never opens is a deadlock, not a feature.

## License

MIT
