asyncpg-lock 0.0.1__py3-none-any.whl

asyncpg_lock/__init__.py

@@ -0,0 +1,38 @@
+import collections
+import re
+import sys
+
+from .guard import AdvisoryLockGuard, ConnectFunc, connect_func  # noqa
+
+__all__: tuple[str, ...] = (
+    # guard.py
+    "ConnectFunc",
+    "AdvisoryLockGuard",
+    "connect_func",
+)
+
+__version__ = "0.0.1"
+
+version = f"{__version__}, Python {sys.version}"
+
+VersionInfo = collections.namedtuple("VersionInfo", "major minor micro release_level serial")
+
+
+def _parse_version(v: str) -> VersionInfo:
+    version_re = r"^(?P<major>\d+)\.(?P<minor>\d+)\.(?P<micro>\d+)" r"((?P<release_level>[a-z]+)(?P<serial>\d+)?)?$"
+    match = re.match(version_re, v)
+    if not match:
+        raise ImportError(f"Invalid package version {v}")
+    try:
+        major = int(match.group("major"))
+        minor = int(match.group("minor"))
+        micro = int(match.group("micro"))
+        levels = {"rc": "candidate", "a": "alpha", "b": "beta", None: "final"}
+        release_level = levels[match.group("release_level")]
+        serial = int(match.group("serial")) if match.group("serial") else 0
+        return VersionInfo(major, minor, micro, release_level, serial)
+    except Exception as e:
+        raise ImportError(f"Invalid package version {v}") from e
+
+
+version_info = _parse_version(__version__)

asyncpg_lock/guard.py

@@ -0,0 +1,138 @@
+import asyncio
+import logging
+import time
+from typing import Any, Callable, Coroutine
+
+import asyncpg
+
+logger = logging.getLogger(__package__)
+
+ConnectFunc = Callable[[], Coroutine[Any, Any, asyncpg.Connection]]
+
+
+def connect_func(*args: Any, **kwargs: Any) -> ConnectFunc:
+    async def _connect() -> asyncpg.Connection:
+        return await asyncpg.connect(*args, **kwargs)
+
+    return _connect
+
+
+class AdvisoryLockGuard:
+    __slots__ = (
+        "__connect",
+        "__reconnect_delay",
+        "__after_acquire_delay",
+        "__reacquire_delay",
+    )
+
+    def __init__(
+        self,
+        *,
+        connect: ConnectFunc = asyncpg.connect,
+        reconnect_delay: float = 5,
+        reacquire_delay: float = 5,
+        after_acquire_delay: float = 5,
+    ) -> None:
+        if reconnect_delay < 0:
+            raise ValueError("reconnect_delay must be non-negative")
+        if reacquire_delay <= 0:
+            raise ValueError("reacquire_delay must be positive")
+        if after_acquire_delay <= 0:
+            raise ValueError("after_acquire_delay must be positive")
+
+        self.__reconnect_delay = reconnect_delay
+        self.__after_acquire_delay = after_acquire_delay
+        self.__reacquire_delay = reacquire_delay
+        self.__connect = connect
+
+    async def run(
+        self,
+        key: int | tuple[int, int],
+        func: Callable[[], Coroutine],
+    ) -> None:
+        if isinstance(key, int):
+            if not (-(2**63) <= key < 2**63):
+                raise ValueError("key must be a signed 64-bit integer")
+        else:
+            if not (-(2**31) <= key[0] < 2**31) or not (-(2**31) <= key[1] < 2**31):
+                raise ValueError("key must be a tuple of two signed 32-bit integers")
+
+        await self.__ensure_connection_established(
+            lambda connection: self.__ensure_lock_acquired(connection, key, func)
+        )
+
+    async def __ensure_connection_established(self, func: Callable[[asyncpg.Connection], Coroutine]) -> None:
+        failed_attempts = 0
+        while True:
+            try:
+                connection = await self.__connect()
+                failed_attempts = 0
+                try:
+                    await func(connection)
+                finally:
+                    await asyncio.shield(connection.close())
+            except Exception:
+                if failed_attempts > 0:
+                    logger.exception("Connection closed or not established")
+                failed_attempts += 1
+
+            await asyncio.sleep(self.__reconnect_delay)
+
+    async def __ensure_lock_acquired(
+        self,
+        connection: asyncpg.Connection,
+        key: int | tuple[int, int],
+        func: Callable[[], Coroutine],
+    ) -> None:
+        logger.info("Acquiring lock %s", key)
+        await self.__acquire_lock(connection, key)
+        logger.info("Lock %s acquired, waiting for %s s", key, self.__after_acquire_delay)
+        await asyncio.sleep(self.__after_acquire_delay)
+        logger.info("Lock %s acquired, running", key)
+        try:
+            async with asyncio.TaskGroup() as tg:
+                tg.create_task(self.__ensure_connection_alive(connection, key))
+                tg.create_task(self.__run_forever(func))
+        finally:
+            logger.info("Lock %s might be lost", key)
+
+    async def __acquire_lock(self, connection: asyncpg.Connection, key: int | tuple[int, int]) -> None:
+        while True:
+            try:
+                if isinstance(key, int):
+                    acquired = await connection.fetchval("SELECT pg_try_advisory_lock($1)", key)
+                else:
+                    acquired = await connection.fetchval("SELECT pg_try_advisory_lock($1, $2)", key[0], key[1])
+            except Exception:
+                raise Exception(f"Lock {key} not acquired")
+            if acquired:
+                return
+            await asyncio.sleep(self.__reacquire_delay)
+
+    async def __ensure_connection_alive(self, connection: asyncpg.Connection, key: int | tuple[int, int]) -> None:
+        per_attempt_keep_alive_budget = self.__after_acquire_delay / 3
+        while True:
+            started_at = time.monotonic()
+            if connection.is_closed():
+                raise Exception(f"Lock {key} might be lost: connection is closed")
+            try:
+                await connection.execute("SELECT 1", timeout=per_attempt_keep_alive_budget)
+            except asyncio.TimeoutError:
+                raise Exception(f"Lock {key} might be lost: keep-alive query timed out")
+            except Exception:
+                raise Exception(f"Lock {key} might be lost: keep-alive query failed")
+
+            finished_at = time.monotonic()
+            elapsed = finished_at - started_at
+            if elapsed > per_attempt_keep_alive_budget * 2:
+                raise Exception(f"Lock {key} might be lost: keep-alive query took too long")
+            if elapsed < per_attempt_keep_alive_budget:
+                await asyncio.sleep(per_attempt_keep_alive_budget - elapsed)
+
+    @staticmethod
+    async def __run_forever(func: Callable[[], Coroutine]) -> None:
+        while True:
+            try:
+                await func()
+            except Exception:
+                logger.exception("Unexpected exception")

asyncpg_lock/py.typed

@@ -0,0 +1 @@
+Marker

asyncpg_lock-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Iurii Pliner
+
+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.

asyncpg_lock-0.0.1.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.1
+Name: asyncpg-lock
+Version: 0.0.1
+Summary: Run long-running work exclusively using PostgreSQL advisory locks
+Home-page: https://github.com/Pliner/asyncpg-lock
+Author: Iurii Pliner
+Author-email: yury.pliner@gmail.com
+License: MIT
+Platform: macOS
+Platform: POSIX
+Platform: Windows
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Web Environment
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.30.0
+
+# asyncpg-lock
+
+Run long-running work exclusively using PostgreSQL advisory locks.
+
+## Usage
+
+```python
+import asyncio
+import asyncpg
+import asyncpg_lock
+
+
+async def worker_func() -> None:
+    # something very long-running
+    while True:
+        await asyncio.sleep(100500)
+
+
+async def main():
+    guard = asyncpg_lock.AdvisoryLockGuard(
+        connect=lambda: asyncpg.connect("postgresql://localhost/db")
+    )
+    # worker_func will not be executed concurrently
+    key = 100500
+    tasks = [
+        asyncio.create_task(guard.run(key, worker_func)),
+        asyncio.create_task(guard.run(key, worker_func)),
+        asyncio.create_task(guard.run(key, worker_func)),
+        asyncio.create_task(guard.run(key, worker_func))
+    ]
+    await asyncio.gather(*tasks)
+
+
+asyncio.run(main())
+```
+
+## v0.0.1 (2025-07-07)
+
+* Initial release

asyncpg_lock-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+asyncpg_lock/__init__.py,sha256=Uk1WOOUvy2uoU3MRztuA86Nc8SmAGISm_rZo-JyEvOU,1225
+asyncpg_lock/guard.py,sha256=WDsRzOdy3zQIH4_VOzigb1IBqbWJ6KEJf-V9LPe5Uo0,5236
+asyncpg_lock/py.typed,sha256=E84IaZyFwfLqvXjOVW4LS6WH7QOaKEFpNh9TFyzHNQc,6
+asyncpg_lock-0.0.1.dist-info/LICENSE,sha256=6EE2Lo1blA7_eNykqnMxzJjOOzuo_nJxFIdBolhFOwk,1069
+asyncpg_lock-0.0.1.dist-info/METADATA,sha256=d8Jq-zL9uxHH-LvR0Hv1zFYaoSZg_wbjsj-gcw44_Ws,1814
+asyncpg_lock-0.0.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+asyncpg_lock-0.0.1.dist-info/top_level.txt,sha256=rYtYbHwstzUbQw0LMH7TEgJNV52XfUFFIIrVwiY5MNo,13
+asyncpg_lock-0.0.1.dist-info/RECORD,,

asyncpg_lock-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

asyncpg_lock-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+asyncpg_lock