feat(lock): add aclose() method for async locks, deprecate close()

- Add BaseAsyncSadLock.aclose() for compatibility with contextlib.aclosing (Python 3.10+)
- Deprecate BaseAsyncSadLock.close() in favor of aclose(), will be removed in v0.9.0
- Fix __aexit__ to call aclose() instead of deprecated close()
- Add test cases for aclose() and deprecation warning

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tanbro

CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## v0.8.1 (in development)
+
+- 🆕 **New Features:**
+  - **Added `BaseAsyncSadLock.aclose()` method**: Async close method for compatibility with `contextlib.aclosing` (Python 3.10+)
+
+- ⚠️ **Deprecations:**
+  - **`BaseAsyncSadLock.close()` is deprecated**: It will be removed in v0.9.0, use `aclose()` instead
+
 ## v0.8.0
 
 > 📅 **Date** 2026-02-12
@@ -59,12 +67,12 @@
 
 - 🐛 Bug-fix:
   - Issue #4: PostgreSQL xact lock in context manager produces warning #4
-- ✅ Changes:
-  - `typing-extensions` required for Python earlier than 3.12
-- 🖊️ Modifications:
-  - Add some `override` decorators
-- 🎯 CI:
-  - update pre-commit hooks
+  - ✅ Changes:
+    - `typing-extensions` required for Python earlier than 3.12
+  - 🖊️ Modifications:
+    - Add some `override` decorators
+  - 🎯 CI:
+    - update pre-commit hooks
 
 ## v0.6.1
 
@@ -98,7 +106,7 @@
 Date: 2023-12-06
 
 - New:
-  - `contextual_timeout` parameter for “with” statement
+  - `contextual_timeout` parameter for "with" statement
   - Support Python 3.12
 
 ## v0.4
@@ -109,15 +117,15 @@ Date: 2023-06-17
   - remove `acquired` property, it's alias of `locked`
   - remove setter of `locked` property
 
-- Optimize:
-  - re-arrange package's structure
-  - Many optimizations
+  - Optimize:
+    - re-arrange package's structure
+    - Many optimizations
 
-- CI/Test:
-  - GitHub action: Python 3.8~3.11 x SQLAlchemy 1.x/2.x matrix testing
-  - Local compose: Python 3.7~3.11 x SQLAlchemy 1.x/2.x matrix testing
+  - CI/Test:
+    - GitHub action: Python 3.8~3.11 x SQLAlchemy 1.x/2.x matrix testing
+    - Local compose: Python 3.7~3.11 x SQLAlchemy 1.x/2.x matrix testing
 
-- Doc: Update to Sphinx 7.x, and Furo theme
+  - Doc: Update to Sphinx 7.x, and Furo theme
 
 ## v0.3.1
 
@@ -132,14 +140,14 @@ Date: 2023-06-13
 - Remove:
   - Python 3.6 support
 
-- Tests:
-  - New docker compose based tests, from python 3.7 to 3.11, both SQLAlchemy 1.x and 2.x
+  - Tests:
+    - New docker compose based tests, from python 3.7 to 3.11, both SQLAlchemy 1.x and 2.x
 
-- Docs:
-  - Update to newer Sphinx docs
+  - Docs:
+    - Update to newer Sphinx docs
 
-- Build:
-  - Move all project meta to pyproject.toml, remove setup.cfg and setup.py
+  - Build:
+    - Move all project meta to pyproject.toml, remove setup.cfg and setup.py
 
 ## v0.2.1
 
@@ -181,10 +189,10 @@ Date: 2021-03-14
   - Remove SQLAlchemy version requires earlier than 1.4 in setup, it's not supported, actually.
   - Adjust PostgreSQL lock's constructor arguments order
 
-- Add:
+  - Add:
 
-  - More test cases, and add test/deploy workflow in GitHub actions.
-  - Add docker-compose test scripts
+    - More test cases, and add test/deploy workflow in GitHub actions.
+    - Add docker-compose test scripts
 
 ## v0.2a2
 

src/sqlalchemy_dlock/lock/base.py

@@ -1,4 +1,5 @@
 import sys
+import warnings
 from abc import ABC, abstractmethod
 from threading import local
 from typing import Callable, Generic, Optional, TypeVar, Union, final
@@ -270,7 +271,7 @@ async def __aenter__(self) -> Self:
 
     @final
     async def __aexit__(self, exc_type, exc_value, exc_tb):
-        await self.close()
+        await self.aclose()
 
     @final
     def __str__(self):
@@ -319,6 +320,38 @@ async def do_release(self, *args, **kwargs):
         raise NotImplementedError()
 
     @final
-    async def close(self, *args, **kwargs):
+    async def aclose(self, *args, **kwargs):
+        """Async close method for compatibility with :func:`contextlib.aclosing` (Python 3.10+).
+
+        Example::
+
+            from contextlib import aclosing
+
+            async with aclosing(create_async_sadlock(some_connection, some_key)) as lock:
+                # will **NOT** acquire at the begin of with-block
+                assert not lock.locked
+                # ...
+                # lock when need
+                await lock.acquire()
+                assert lock.locked
+                # ...
+
+            # `aclose` will be called at the end with-block
+            assert not lock.locked
+
+        .. versionadded:: 0.8.1
+        """
         if self._acquired:
             await self.release(*args, **kwargs)
+
+    @final
+    async def close(self, *args, **kwargs):
+        """.. deprecated:: 0.8.1
+        Use :meth:`aclose` instead. Will be removed in 0.9.0.
+        """
+        warnings.warn(
+            "The 'close' method is deprecated and will be removed in 0.9.0. Use 'aclose' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.aclose(*args, **kwargs)

tests/asyncio/test_basic.py

@@ -1,9 +1,11 @@
+import sys
 from contextlib import AsyncExitStack
 from multiprocessing import cpu_count
 from random import randint
 from secrets import token_bytes, token_hex
-from unittest import IsolatedAsyncioTestCase
+from unittest import IsolatedAsyncioTestCase, skipIf
 from uuid import uuid4
+import warnings
 
 from sqlalchemy_dlock import create_async_sadlock
 
@@ -220,3 +222,64 @@ async def test_release_unlocked_error(self):
                 lock1 = create_async_sadlock(conn1, key)
                 with self.assertRaisesRegex(ValueError, "invoked on an unlocked lock"):
                     await lock1.release()
+
+    async def test_aclose(self):
+        """Test aclose() method."""
+        for engine in get_engines():
+            async with engine.connect() as conn:
+                key = uuid4().hex
+                lock = create_async_sadlock(conn, key)
+                self.assertFalse(lock.locked)
+                await lock.acquire()
+                self.assertTrue(lock.locked)
+                await lock.aclose()
+                self.assertFalse(lock.locked)
+
+    async def test_aclose_when_unlocked(self):
+        """Test aclose() when lock is not acquired (should be no-op)."""
+        for engine in get_engines():
+            async with engine.connect() as conn:
+                key = uuid4().hex
+                lock = create_async_sadlock(conn, key)
+                self.assertFalse(lock.locked)
+                # aclose on unlocked lock should be no-op
+                await lock.aclose()
+                self.assertFalse(lock.locked)
+
+    @skipIf(sys.version_info < (3, 10), "contextlib.aclosing: New in version 3.10")
+    async def test_aclosing_context_manager(self):
+        """Test aclose() with contextlib.aclosing (Python 3.10+)."""
+        try:
+            from contextlib import aclosing
+        except ImportError:
+            self.skipTest("contextlib.aclosing not available")
+
+        for engine in get_engines():
+            async with engine.connect() as conn:
+                key = uuid4().hex
+                async with aclosing(create_async_sadlock(conn, key)) as lock:
+                    # will NOT acquire at the begin of with-block
+                    self.assertFalse(lock.locked)
+                    # lock when need
+                    await lock.acquire()
+                    self.assertTrue(lock.locked)
+                # aclose will be called at the end with-block
+                self.assertFalse(lock.locked)
+
+    async def test_close_deprecated(self):
+        """Test that close() is deprecated and calls aclose()."""
+        for engine in get_engines():
+            async with engine.connect() as conn:
+                key = uuid4().hex
+                lock = create_async_sadlock(conn, key)
+                await lock.acquire()
+                self.assertTrue(lock.locked)
+                with warnings.catch_warnings(record=True) as w:
+                    warnings.simplefilter("always")
+                    await lock.close()
+                    # Check that deprecation warning was raised
+                    self.assertEqual(len(w), 1)
+                    self.assertEqual(w[0].category, DeprecationWarning)
+                    self.assertIn("deprecated", str(w[0].message).lower())
+                    self.assertIn("aclose", str(w[0].message).lower())
+                self.assertFalse(lock.locked)