pg-advisory-lock 0.0.15__tar.gz

pg_advisory_lock-0.0.15/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Tryastsyn
+
+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.

pg_advisory_lock-0.0.15/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.1
+Name: pg-advisory-lock
+Version: 0.0.15
+Summary: Pythonic PostgreSQL advisory locking for SQLAlchemy, with structured keys and explicit contention handling.
+License: MIT
+Keywords: postgresql,advisory-lock,sqlalchemy,locking,concurrency
+Author: Alexander Tryastsyn
+Requires-Python: >=3.12,<4.0
+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.12
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Dist: sqlalchemy (>=1.4,<3.0)
+Description-Content-Type: text/markdown
+
+# pg-advisory-lock
+
+## Pythonic PostgreSQL advisory locking for SQLAlchemy, with structured keys and explicit contention handling.
+
+Provides a high-level interface for acquiring PostgreSQL advisory locks with structured
+lock arguments and timeout support. Advisory locks are application-level locks that are
+automatically released when the transaction commits or rolls back.
+
+
+### Key features:
+- Deterministic lock keys composed from `str`, `int`, and `uuid.UUID` components
+- Non-blocking immediate lock acquisition
+- Blocking lock acquisition with configurable timeout
+- Automatic lock release on transaction end (uses pg_advisory_xact_lock functions)
+- Configurable handling for expected lock contention: raise exceptions (default) or return a boolean
+- Database and infrastructure errors are propagated unchanged
+- Inline type hints shipped with the package (PEP 561)
+
+
+### Failure handling
+`raise_on_failure` controls expected lock contention only:
+
+- `raise_on_failure=True` (default):
+  - `lock_immediate()` raises `PgAdvisoryLockNotAcquired` when the lock is already held.
+  - `lock()` raises `PgAdvisoryLockTimeout` when its timeout expires.
+- `raise_on_failure=False`:
+  - Both methods return `False` for expected contention or timeout.
+- Unexpected database and infrastructure errors are always propagated.
+
+`raise_on_failure` must be a boolean. Other values raise `PgAdvisoryLockError`.
+
+`PgAdvisoryLockTimeout` is a subclass of `PgAdvisoryLockNotAcquired`.
+
+Boolean mode discards the originating database error. Use the default exception mode when the
+cause matters: the underlying `DBAPIError` is chained as `__cause__`.
+
+
+### Usage examples:
+Import the public API from the installed package:
+
+```python
+from pg_advisory_lock import (
+    PgAdvisoryLock,
+    PgAdvisoryLockError,
+    PgAdvisoryLockNotAcquired,
+    PgAdvisoryLockTimeout,
+)
+```
+
+#### Default behavior: raises exception on failure (safe by default):
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user_id])
+
+with session.begin():
+    locker.lock(session=session)
+    process_payment()
+```
+
+
+#### Boolean mode: explicit handling of lock contention:
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user_id], raise_on_failure=False)
+
+with session.begin():
+    if locker.lock(session=session, timeout_in_ms=5000):
+        process_payment()
+    else:
+        schedule_retry()
+```
+
+
+#### Immediate (non-blocking) attempts:
+
+```python
+locker = PgAdvisoryLock(
+    lock_args=['payment_processing', order_id],
+    raise_on_failure=False,
+)
+
+with session.begin():
+    if locker.lock_immediate(session=session):
+        process_payment()
+    else:
+        schedule_retry()
+```
+
+
+#### Lock on multiple components:
+
+```python
+locker = PgAdvisoryLock(lock_args=['user_sync', region, user_id])
+
+with session.begin():
+    locker.lock(session=session)
+    synchronize_user()
+```
+
+### Transaction behavior
+The library uses transaction-scoped advisory locks. The critical section must remain
+inside the same open transaction in which the lock was acquired. Committing or rolling
+back that transaction releases the lock automatically.
+
+When `lock()` reaches its timeout, the failed PostgreSQL statement is isolated within
+a savepoint. After `False` is returned or `PgAdvisoryLockTimeout` is caught, the caller's
+outer transaction remains usable.
+
+`lock()` temporarily changes the transaction-local PostgreSQL `lock_timeout`. After a
+successful acquisition or handled timeout, the caller's previous `lock_timeout` value
+is restored.
+
+A connection or infrastructure failure cannot be repaired by a savepoint and is
+propagated to the caller.
+
+### Lock arguments and key generation
+`lock_args` must be a non-empty list or tuple. A bare string, set, mapping, generator,
+or other iterable is rejected.
+
+The arguments are copied to an immutable tuple during construction, so later changes
+to the original list do not affect the lock identity.
+
+For a lock with one component, wrap the value in a list or one-element tuple:
+
+```python
+PgAdvisoryLock(lock_args=['payment_processing'])
+PgAdvisoryLock(lock_args=('payment_processing',))
+```
+
+Each component must be a `str`, `int`, or `uuid.UUID`. Any other type, including `None`, SQLAlchemy
+model instances, model classes, and `Table` objects, raises `PgAdvisoryLockError` at construction.
+
+The restriction exists because a value relying on Python's default `repr` stringifies with a memory
+address that differs in every process. Hashing one would derive a key that never matches another
+process, so the lock would appear granted while excluding nobody.
+
+Pass the table name explicitly:
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user.id])
+```
+
+`__table__.name` avoids duplicating the table name in application code. Note that renaming the table
+changes the derived key, whereas a string literal would not.
+
+The normalized strings are serialized as a compact JSON array, preserving component
+boundaries even when values contain separators. The serialized value is hashed with
+SHA-256 and mapped to PostgreSQL's signed 64-bit advisory-lock key range.
+
+Normalization is intentionally type-insensitive, so values with the same normalized
+string representation, such as `1` and `'1'`, produce the same lock key.
+
+
+### Thread safety
+- An instance keeps no state after construction and can be shared across sessions and threads.
+- Each thread needs its own `Session`; SQLAlchemy sessions are not thread-safe.
+- A single acquisition belongs to the session and transaction that made it.
+
+
+## Development
+
+### Running tests
+Install the project and its development dependencies:
+
+```bash
+poetry install
+```
+
+Start the local PostgreSQL test database and run the test suite:
+
+```bash
+docker compose -f docker/compose.yaml up -d
+poetry run pytest
+```
+
+Tests connect to the following database by default:
+
+```text
+postgresql+psycopg://postgres:123@localhost:6543/testing
+```
+
+Override the database URL when using another PostgreSQL instance:
+
+```bash
+TEST_DATABASE_URL='postgresql+psycopg://user:password@host:5432/database' \
+  poetry run pytest
+```
+
+Stop the local test database when it is no longer needed:
+
+```bash
+docker compose -f docker/compose.yaml down
+```
+
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+

pg_advisory_lock-0.0.15/README.md

@@ -0,0 +1,198 @@
+# pg-advisory-lock
+
+## Pythonic PostgreSQL advisory locking for SQLAlchemy, with structured keys and explicit contention handling.
+
+Provides a high-level interface for acquiring PostgreSQL advisory locks with structured
+lock arguments and timeout support. Advisory locks are application-level locks that are
+automatically released when the transaction commits or rolls back.
+
+
+### Key features:
+- Deterministic lock keys composed from `str`, `int`, and `uuid.UUID` components
+- Non-blocking immediate lock acquisition
+- Blocking lock acquisition with configurable timeout
+- Automatic lock release on transaction end (uses pg_advisory_xact_lock functions)
+- Configurable handling for expected lock contention: raise exceptions (default) or return a boolean
+- Database and infrastructure errors are propagated unchanged
+- Inline type hints shipped with the package (PEP 561)
+
+
+### Failure handling
+`raise_on_failure` controls expected lock contention only:
+
+- `raise_on_failure=True` (default):
+  - `lock_immediate()` raises `PgAdvisoryLockNotAcquired` when the lock is already held.
+  - `lock()` raises `PgAdvisoryLockTimeout` when its timeout expires.
+- `raise_on_failure=False`:
+  - Both methods return `False` for expected contention or timeout.
+- Unexpected database and infrastructure errors are always propagated.
+
+`raise_on_failure` must be a boolean. Other values raise `PgAdvisoryLockError`.
+
+`PgAdvisoryLockTimeout` is a subclass of `PgAdvisoryLockNotAcquired`.
+
+Boolean mode discards the originating database error. Use the default exception mode when the
+cause matters: the underlying `DBAPIError` is chained as `__cause__`.
+
+
+### Usage examples:
+Import the public API from the installed package:
+
+```python
+from pg_advisory_lock import (
+    PgAdvisoryLock,
+    PgAdvisoryLockError,
+    PgAdvisoryLockNotAcquired,
+    PgAdvisoryLockTimeout,
+)
+```
+
+#### Default behavior: raises exception on failure (safe by default):
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user_id])
+
+with session.begin():
+    locker.lock(session=session)
+    process_payment()
+```
+
+
+#### Boolean mode: explicit handling of lock contention:
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user_id], raise_on_failure=False)
+
+with session.begin():
+    if locker.lock(session=session, timeout_in_ms=5000):
+        process_payment()
+    else:
+        schedule_retry()
+```
+
+
+#### Immediate (non-blocking) attempts:
+
+```python
+locker = PgAdvisoryLock(
+    lock_args=['payment_processing', order_id],
+    raise_on_failure=False,
+)
+
+with session.begin():
+    if locker.lock_immediate(session=session):
+        process_payment()
+    else:
+        schedule_retry()
+```
+
+
+#### Lock on multiple components:
+
+```python
+locker = PgAdvisoryLock(lock_args=['user_sync', region, user_id])
+
+with session.begin():
+    locker.lock(session=session)
+    synchronize_user()
+```
+
+### Transaction behavior
+The library uses transaction-scoped advisory locks. The critical section must remain
+inside the same open transaction in which the lock was acquired. Committing or rolling
+back that transaction releases the lock automatically.
+
+When `lock()` reaches its timeout, the failed PostgreSQL statement is isolated within
+a savepoint. After `False` is returned or `PgAdvisoryLockTimeout` is caught, the caller's
+outer transaction remains usable.
+
+`lock()` temporarily changes the transaction-local PostgreSQL `lock_timeout`. After a
+successful acquisition or handled timeout, the caller's previous `lock_timeout` value
+is restored.
+
+A connection or infrastructure failure cannot be repaired by a savepoint and is
+propagated to the caller.
+
+### Lock arguments and key generation
+`lock_args` must be a non-empty list or tuple. A bare string, set, mapping, generator,
+or other iterable is rejected.
+
+The arguments are copied to an immutable tuple during construction, so later changes
+to the original list do not affect the lock identity.
+
+For a lock with one component, wrap the value in a list or one-element tuple:
+
+```python
+PgAdvisoryLock(lock_args=['payment_processing'])
+PgAdvisoryLock(lock_args=('payment_processing',))
+```
+
+Each component must be a `str`, `int`, or `uuid.UUID`. Any other type, including `None`, SQLAlchemy
+model instances, model classes, and `Table` objects, raises `PgAdvisoryLockError` at construction.
+
+The restriction exists because a value relying on Python's default `repr` stringifies with a memory
+address that differs in every process. Hashing one would derive a key that never matches another
+process, so the lock would appear granted while excluding nobody.
+
+Pass the table name explicitly:
+
+```python
+locker = PgAdvisoryLock(lock_args=[UserModel.__table__.name, user.id])
+```
+
+`__table__.name` avoids duplicating the table name in application code. Note that renaming the table
+changes the derived key, whereas a string literal would not.
+
+The normalized strings are serialized as a compact JSON array, preserving component
+boundaries even when values contain separators. The serialized value is hashed with
+SHA-256 and mapped to PostgreSQL's signed 64-bit advisory-lock key range.
+
+Normalization is intentionally type-insensitive, so values with the same normalized
+string representation, such as `1` and `'1'`, produce the same lock key.
+
+
+### Thread safety
+- An instance keeps no state after construction and can be shared across sessions and threads.
+- Each thread needs its own `Session`; SQLAlchemy sessions are not thread-safe.
+- A single acquisition belongs to the session and transaction that made it.
+
+
+## Development
+
+### Running tests
+Install the project and its development dependencies:
+
+```bash
+poetry install
+```
+
+Start the local PostgreSQL test database and run the test suite:
+
+```bash
+docker compose -f docker/compose.yaml up -d
+poetry run pytest
+```
+
+Tests connect to the following database by default:
+
+```text
+postgresql+psycopg://postgres:123@localhost:6543/testing
+```
+
+Override the database URL when using another PostgreSQL instance:
+
+```bash
+TEST_DATABASE_URL='postgresql+psycopg://user:password@host:5432/database' \
+  poetry run pytest
+```
+
+Stop the local test database when it is no longer needed:
+
+```bash
+docker compose -f docker/compose.yaml down
+```
+
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pg_advisory_lock-0.0.15/pyproject.toml

@@ -0,0 +1,70 @@
+[tool.poetry]
+name = "pg-advisory-lock"
+version = "0.0.15"
+description = "Pythonic PostgreSQL advisory locking for SQLAlchemy, with structured keys and explicit contention handling."
+authors = ["Alexander Tryastsyn"]
+license = "MIT"
+readme = "README.md"
+keywords = ["postgresql", "advisory-lock", "sqlalchemy", "locking", "concurrency"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Database",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+packages = [{ include = "pg_advisory_lock", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+sqlalchemy = ">=1.4,<3.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.1.1"
+ruff = "^0.16.0"
+psycopg = "^3.3.4"
+mypy = "^2.3.0"
+pytest-cov = "^7.1.0"
+twine = "^7.0.0"
+
+[tool.ruff]
+line-length = 120
+include = ["src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.mypy]
+files = ['src']
+python_version = '3.12'
+strict = true
+enable_error_code = ['ignore-without-code']
+
+[tool.pytest.ini_options]
+testpaths = ["tests",]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short --cov=src --cov-report=term-missing --cov-fail-under=90"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pg_advisory_lock-0.0.15/src/pg_advisory_lock/__init__.py

@@ -0,0 +1,10 @@
+"""Transaction-scoped PostgreSQL advisory locks for SQLAlchemy sessions."""
+
+from importlib.metadata import version
+
+from .exceptions import PgAdvisoryLockError, PgAdvisoryLockNotAcquired, PgAdvisoryLockTimeout
+from .lock import PgAdvisoryLock
+
+__all__ = ['PgAdvisoryLock', 'PgAdvisoryLockError', 'PgAdvisoryLockTimeout', 'PgAdvisoryLockNotAcquired']
+
+__version__ = version('pg-advisory-lock')

pg_advisory_lock-0.0.15/src/pg_advisory_lock/exceptions.py

@@ -0,0 +1,41 @@
+"""Public exception hierarchy and classification of PostgreSQL lock-contention errors."""
+
+from sqlalchemy.exc import DBAPIError
+
+
+class PgAdvisoryLockError(Exception):
+    """Base error for every failure raised by this library.
+
+    Also covers misuse detected before any database call, such as an invalid lock-argument
+    container or a non-boolean raise_on_failure.
+    """
+
+
+class PgAdvisoryLockNotAcquired(PgAdvisoryLockError):
+    """Raised when the lock is already held and immediate acquisition cannot proceed."""
+
+
+class PgAdvisoryLockTimeout(PgAdvisoryLockNotAcquired):
+    """Raised when a blocking acquisition exceeds its timeout.
+
+    Subclasses PgAdvisoryLockNotAcquired so a single except clause catches every contention outcome.
+    """
+
+
+LOCK_NOT_AVAILABLE_CODE = '55P03'
+
+
+def lock_is_not_available(error: DBAPIError) -> bool:
+    """Report whether a database error is lock contention rather than a real failure.
+
+    Only SQLSTATE 55P03 counts as contention. Psycopg 3 exposes it as sqlstate and Psycopg 2 as
+    pgcode, so both are probed with sqlstate taking precedence. Anything else, including a driver
+    that exposes neither attribute, is treated as unrelated so the caller propagates it.
+    """
+
+    if hasattr(error.orig, 'sqlstate'):
+        return bool(getattr(error.orig, 'sqlstate', None) == LOCK_NOT_AVAILABLE_CODE)
+    elif hasattr(error.orig, 'pgcode'):
+        return bool(getattr(error.orig, 'pgcode', None) == LOCK_NOT_AVAILABLE_CODE)
+    else:
+        return False

pg_advisory_lock-0.0.15/src/pg_advisory_lock/lock.py

@@ -0,0 +1,88 @@
+"""Transaction-scoped PostgreSQL advisory locks acquired through a SQLAlchemy session."""
+
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.exc import DBAPIError
+from sqlalchemy.orm import Session
+
+from .exceptions import PgAdvisoryLockError, PgAdvisoryLockNotAcquired, PgAdvisoryLockTimeout, lock_is_not_available
+from .lock_arguments import get_key_from_args, validate
+from .pg_local_setting import set_lock_timeout
+
+
+class PgAdvisoryLock:
+    """Advisory lock addressed by a key derived from structured lock arguments.
+
+    The key is derived once at construction, so invalid arguments fail before any database call.
+    Acquisition is transaction-scoped: PostgreSQL releases the lock when the surrounding
+    transaction commits or rolls back, so the critical section must stay inside that transaction.
+
+    An instance holds no session state and can be reused, but any single acquisition belongs to the
+    one session and transaction that made it.
+    """
+
+    def __init__(self, lock_args: list[Any] | tuple[Any, ...], raise_on_failure: bool = True) -> None:
+        if not isinstance(raise_on_failure, bool):
+            raise PgAdvisoryLockError('Raise_on_failure argument must be a bool.')
+        self.raise_on_failure = raise_on_failure
+
+        validate(lock_args)
+        self.lock_args = tuple(lock_args)
+
+        self.lock_key = get_key_from_args(self.lock_args)
+
+    def lock_immediate(self, session: Session) -> bool:
+        """Try to acquire the lock without waiting.
+
+        Contention either raises PgAdvisoryLockNotAcquired or returns False, according to
+        raise_on_failure. No lock_timeout is involved, so the call never blocks.
+        """
+
+        result = session.execute(
+            statement=text('SELECT pg_try_advisory_xact_lock(:key)'),
+            params={'key': self.lock_key},
+        ).scalar()
+        if result:
+            return True
+        else:
+            if self.raise_on_failure:
+                raise PgAdvisoryLockNotAcquired('Failed to acquire advisory lock.')
+            else:
+                return False
+
+    def lock(self, session: Session, timeout_in_ms: int = 1000) -> bool:
+        """Acquire the lock, waiting up to the given timeout.
+
+        A zero timeout delegates to the non-blocking path. Otherwise the wait runs inside a
+        savepoint with lock_timeout applied transaction-locally, so a timeout aborts only that
+        savepoint and leaves the caller's transaction usable.
+
+        Only SQLSTATE 55P03 counts as contention: it raises PgAdvisoryLockTimeout or returns False,
+        according to raise_on_failure. Every other database error propagates unchanged. The boolean
+        mode discards the originating error, so use the exception mode when the cause matters,
+        where it is available as __cause__.
+        """
+
+        if not isinstance(timeout_in_ms, int) or timeout_in_ms < 0:
+            raise PgAdvisoryLockError('Lock timeout must be a non-negative integer.')
+
+        if timeout_in_ms == 0:
+            return self.lock_immediate(session=session)
+
+        try:
+            with session.begin_nested(), set_lock_timeout(session, f'{timeout_in_ms}ms'):
+                session.execute(text('SELECT pg_advisory_xact_lock(:key)'), {'key': self.lock_key})
+                return True
+
+        except DBAPIError as exc:
+            if not lock_is_not_available(error=exc):
+                raise
+
+            elif self.raise_on_failure:
+                raise PgAdvisoryLockTimeout(
+                    f'Failed to acquire advisory lock within {timeout_in_ms} ms.',
+                ) from exc
+
+            else:
+                return False

pg_advisory_lock-0.0.15/src/pg_advisory_lock/lock_arguments.py

@@ -0,0 +1,66 @@
+"""Validation and deterministic key derivation for advisory-lock arguments."""
+
+import hashlib
+import json
+import uuid
+from typing import Any
+
+from .exceptions import PgAdvisoryLockError
+
+LOCK_ARGUMENT_TYPES: tuple[type, ...] = (str, int, uuid.UUID)
+LOCK_ARGUMENT_TYPE_NAMES = ', '.join([_.__name__ for _ in LOCK_ARGUMENT_TYPES])
+
+
+def validate(args: Any) -> None:
+    """Enforce the lock-argument contract before a key is derived.
+
+    Only lists and tuples are accepted. Bare strings, sets, mappings, and generators are rejected
+    because they iterate per character, have no stable order, or would be consumed on first use.
+    None is rejected because it cannot be told apart from the string 'None'.
+
+    Components are restricted to str, int, and UUID, whose str() is stable across processes. Anything
+    else, including ORM instances, model classes, and Table objects, is rejected rather than hashed: a
+    value relying on the default repr embeds a memory address and would derive a different key in every
+    process, granting a lock that excludes nobody.
+    """
+
+    if not isinstance(args, (list, tuple)):
+        raise PgAdvisoryLockError('Lock arguments must be a list or tuple.')
+
+    if not args:
+        raise PgAdvisoryLockError('At least one lock argument is required.')
+
+    for _arg in args:
+        if _arg is None:
+            raise PgAdvisoryLockError('Lock argument can not be "None".')
+        if not isinstance(_arg, LOCK_ARGUMENT_TYPES):
+            raise PgAdvisoryLockError(
+                f'Lock argument must be one of "{LOCK_ARGUMENT_TYPE_NAMES}", got "{type(_arg).__name__}" instead.'
+            )
+
+
+def normalize(arg: Any) -> str:
+    """Reduce one lock component to the string used for key derivation.
+
+    Normalization is deliberately type-insensitive: 1 and '1' yield the same component, so an integer
+    primary key and its string form address the same lock.
+    """
+
+    return str(arg)
+
+
+def get_key_from_args(args: tuple[Any, ...]) -> int:
+    """Build a deterministic signed 64-bit PostgreSQL advisory-lock key.
+
+    Components are normalized to strings and serialized as a compact JSON array so
+    component boundaries remain unambiguous. The first eight bytes of the SHA-256
+    digest are mapped to PostgreSQL's signed bigint range.
+
+    Truncating the digest retains a theoretical 64-bit hash-collision risk. A collision
+    only causes unrelated operations to serialize on the same advisory lock.
+    """
+
+    serialized = json.dumps(obj=[normalize(_arg) for _arg in args], ensure_ascii=False, separators=(',', ':'))
+    digest = hashlib.sha256(serialized.encode('utf-8')).digest()
+    raw = int.from_bytes(digest[:8], 'big')
+    return raw - (1 << 64) if raw & (1 << 63) else raw

pg_advisory_lock-0.0.15/src/pg_advisory_lock/pg_local_setting.py

@@ -0,0 +1,44 @@
+"""Helpers for reading and temporarily overriding transaction-local PostgreSQL settings."""
+
+from collections.abc import Generator
+from contextlib import AbstractContextManager, contextmanager
+
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+
+def pg_get_local_setting(session: Session, name: str) -> str:
+    """Read the session's effective value for a PostgreSQL run-time setting.
+
+    PostgreSQL errors on an unrecognized setting name, so the caller must pass one that exists in
+    the server configuration.
+    """
+
+    result = session.execute(statement=text('SELECT current_setting(:name)'), params={'name': name}).scalar_one()
+    return str(result)
+
+
+@contextmanager
+def pg_set_local_setting(session: Session, name: str, value: str) -> Generator[None]:
+    """Override a transaction-local PostgreSQL setting for the duration of the block.
+
+    The override uses SET LOCAL semantics, so it is scoped to the current transaction or savepoint
+    and never affects other sessions. On normal exit the captured previous value is written back
+    explicitly. If the block raises, that restore is skipped and the caller's transaction or
+    savepoint rollback is what undoes the override.
+    """
+
+    current_value = pg_get_local_setting(session=session, name=name)
+
+    session.execute(text('SELECT set_config(:name, :value, TRUE)'), {'name': name, 'value': value})
+
+    yield
+
+    session.execute(text('SELECT set_config(:name, :value, TRUE)'), {'name': name, 'value': current_value})
+
+
+def set_lock_timeout(session: Session, timeout: str) -> AbstractContextManager[None]:
+    """Override lock_timeout for the block, using a PostgreSQL interval string such as '1000ms'."""
+
+    setting_name = 'lock_timeout'
+    return pg_set_local_setting(session=session, name=setting_name, value=timeout)