asyncpg-lock 0.0.1__tar.gz

asyncpg_lock-0.0.1/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/PKG-INFO

@@ -0,0 +1,66 @@
+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
+
+# 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/README.md

@@ -0,0 +1,35 @@
+# 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())
+```

asyncpg_lock-0.0.1/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-0.0.1/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-0.0.1/asyncpg_lock/py.typed

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

asyncpg_lock-0.0.1/asyncpg_lock.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+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
+
+# 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/asyncpg_lock.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+setup.cfg
+setup.py
+./asyncpg_lock/__init__.py
+./asyncpg_lock/guard.py
+./asyncpg_lock/py.typed
+asyncpg_lock.egg-info/PKG-INFO
+asyncpg_lock.egg-info/SOURCES.txt
+asyncpg_lock.egg-info/dependency_links.txt
+asyncpg_lock.egg-info/requires.txt
+asyncpg_lock.egg-info/top_level.txt

asyncpg_lock-0.0.1/asyncpg_lock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

asyncpg_lock-0.0.1/asyncpg_lock.egg-info/requires.txt

@@ -0,0 +1 @@
+asyncpg>=0.30.0

asyncpg_lock-0.0.1/asyncpg_lock.egg-info/top_level.txt

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

asyncpg_lock-0.0.1/setup.cfg

@@ -0,0 +1,10 @@
+[tool:pytest]
+norecursedirs = .git .venv
+python_files = tests.py test_*.py *_tests.py
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

asyncpg_lock-0.0.1/setup.py

@@ -0,0 +1,67 @@
+import re
+from pathlib import Path
+
+from setuptools import setup
+
+install_requires = [
+    "asyncpg>=0.30.0",
+]
+
+
+def read(*parts):
+    return Path(__file__).resolve().parent.joinpath(*parts).read_text().strip()
+
+
+def read_version():
+    regexp = re.compile(r"^__version__\W*=\W*\"([\d.abrc]+)\"")
+    for line in read("asyncpg_lock", "__init__.py").splitlines():
+        match = regexp.match(line)
+        if match is not None:
+            return match.group(1)
+    else:
+        raise RuntimeError("Cannot find version in asyncpg_lock/__init__.py")
+
+
+long_description_parts = []
+with open("README.md", "r") as fh:
+    long_description_parts.append(fh.read())
+
+with open("CHANGELOG.md", "r") as fh:
+    long_description_parts.append(fh.read())
+
+long_description = "\r\n".join(long_description_parts)
+
+
+setup(
+    name="asyncpg_lock",
+    version=read_version(),
+    description="Run long-running work exclusively using PostgreSQL advisory locks",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    platforms=["macOS", "POSIX", "Windows"],
+    author="Iurii Pliner",
+    python_requires=">=3.11",
+    project_urls={},
+    url="https://github.com/Pliner/asyncpg-lock",
+    author_email="yury.pliner@gmail.com",
+    license="MIT",
+    packages=["asyncpg_lock"],
+    package_dir={"asyncpg_lock": "./asyncpg_lock"},
+    package_data={"asyncpg_lock": ["py.typed"]},
+    install_requires=install_requires,
+    include_package_data=True,
+    classifiers=[
+        "License :: OSI Approved :: MIT License",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Operating System :: OS Independent",
+        "Environment :: Web Environment",
+        "Development Status :: 5 - Production/Stable",
+        "Framework :: AsyncIO",
+        "Typing :: Typed",
+    ],
+)