Metadata-Version: 2.1
Name: pg-dlock
Version: 0.0.0a2
Summary: PostgreSQL-based distributed advisory lock (sync + async).
Keywords: postgres,postgresql,distributed-lock,advisory-lock,lock
Author-Email: Trim21 <trim21me@gmail.com>
License: MIT
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/trim21/pg-dlock
Project-URL: Repository, https://github.com/trim21/pg-dlock
Project-URL: Issues, https://github.com/trim21/pg-dlock/issues
Requires-Python: >=3.12
Requires-Dist: psycopg[binary,pool]>=3.3
Requires-Dist: xxhash>=3.0
Description-Content-Type: text/markdown

# pg-dlock

PostgreSQL advisory-lock based distributed lock, sync + async.

```python
from pg_dlock import Locker

with Locker("postgres://...") as locker:
    with locker.lock("my-key"):
        ...  # critical section
```

Async:

```python
from pg_dlock import AsyncLocker

async with AsyncLocker("postgres://...") as locker:
    async with locker.lock("my-key"):
        ...
```

## API

- `Locker(conninfo, *, pool_min_size=0, pool_max_size=10)`
- `locker.lock(key, *, scope="session"|"transaction", shared=False) -> Lock`
- `lock.acquire(blocking=True, timeout=-1) -> bool`
  - `blocking=True, timeout=-1`: block forever
  - `blocking=False`: non-blocking
  - `blocking=True, timeout>=0` (seconds): wait up to N seconds (uses `statement_timeout`)
- `lock.release()`
- Context manager support (`with lock:` / `async with lock:`).

### Scopes

- `session`: each lock opens its own dedicated connection (autocommit). Released via `pg_advisory_unlock`.
- `transaction`: connection is checked out from an internal pool and a transaction is begun; lock is released by the commit/rollback on exit.

### Keys

- `str` / `bytes`: hashed with `xxhash.xxh3_64` into a signed int64.
- `int`: used directly (must fit in signed int64).
- `tuple[int, int]`: each element must fit in signed int32; packed into a single int64.
