🐛 fix(win): restore best-effort lock file cleanup on release (#511)

Version 3.25.0 introduced a regression on Windows where lock files were
no longer cleaned up after release, leaving orphaned `.lock` files on
disk. 🗑️ Users upgrading from 3.18.0 reported that their single-threaded
applications now leave persistent lock files, breaking the expected
behavior and diverging from how Unix platforms work (where lock files
are cleaned up).

The regression came from PR #484, which removed the `unlink()` call to
fix threading race conditions. While that fix correctly addressed
multi-threaded scenarios where Windows cannot delete files with open
handles, it sacrificed cleanup for the common single-threaded use case
where deletion would succeed.

This fix restores opportunistic cleanup by attempting to unlink the lock
file after closing it, with errors suppressed via `suppress(OSError)`. ✨
In single-threaded scenarios, the file deletes successfully and users
get the expected behavior. In multi-threaded scenarios where other
threads hold handles, the deletion fails silently and the lock file
persists, preserving the thread-safety guarantees from PR #484.

The test suite is updated to remove the Windows skip condition from
`test_lock_file_removed_after_release`, as Windows now supports cleanup
in typical usage patterns.

Closes #509

Author: gaborbernat

docs/concepts.rst

@@ -138,13 +138,21 @@ stale lock breaking is skipped because the lock file cannot be atomically rename
     The lock is exclusive and works reliably on local filesystems. Network filesystem (SMB) support is available but
     considered less reliable.
 
+    Lock file cleanup: Windows attempts to delete the lock file after release, but deletion is not guaranteed in
+    multi-threaded scenarios. Windows cannot delete files with open handles, so if another thread acquires the lock
+    before the previous holder finishes cleanup, the lock file persists. This is by design and does not affect lock
+    correctness.
+
 **Unix and macOS**
     Uses the :class:`UnixFileLock <filelock.UnixFileLock>` class, backed by ``fcntl.flock``. This is the POSIX standard
     for file locking and enforced by the kernel.
 
     Works best on local filesystems. Network filesystems (NFS) may have issues—locking isn't always reliable on NFS even
     in POSIX-compliant systems.
 
+    Lock file cleanup: Unix and macOS delete the lock file reliably after release, even in multi-threaded scenarios.
+    Unlike Windows, Unix allows unlinking files that other processes have open.
+
 **Other platforms without fcntl**
     Falls back to :class:`SoftFileLock <filelock.SoftFileLock>` and emits a warning. The lock is not enforced by the OS,
     but filelock includes stale lock detection on Unix-like systems (though without fcntl, this detection is less

src/filelock/_unix.py

@@ -35,7 +35,13 @@ def _release(self) -> None:
         has_fcntl = True
 
     class UnixFileLock(BaseFileLock):
-        """Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems."""
+        """
+        Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems.
+
+        Lock file cleanup: Unix and macOS delete the lock file reliably after release, even in
+        multi-threaded scenarios. Unlike Windows, Unix allows unlinking files that other processes
+        have open.
+        """
 
         def _acquire(self) -> None:  # noqa: C901, PLR0912
             ensure_directory_exists(self.lock_file)

src/filelock/_windows.py

@@ -2,7 +2,9 @@
 
 import os
 import sys
+from contextlib import suppress
 from errno import EACCES
+from pathlib import Path
 from typing import cast
 
 from ._api import BaseFileLock
@@ -46,7 +48,13 @@ def _is_reparse_point(path: str) -> bool:
         return bool(attrs & FILE_ATTRIBUTE_REPARSE_POINT)
 
     class WindowsFileLock(BaseFileLock):
-        """Uses the :func:`msvcrt.locking` function to hard lock the lock file on Windows systems."""
+        """
+        Uses the :func:`msvcrt.locking` function to hard lock the lock file on Windows systems.
+
+        Lock file cleanup: Windows attempts to delete the lock file after release, but deletion is
+        not guaranteed in multi-threaded scenarios where another thread holds an open handle. The lock
+        file may persist on disk, which does not affect lock correctness.
+        """
 
         def _acquire(self) -> None:
             raise_on_not_writable_file(self.lock_file)
@@ -83,6 +91,9 @@ def _release(self) -> None:
             msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
             os.close(fd)
 
+            with suppress(OSError):
+                Path(self.lock_file).unlink()
+
 else:  # pragma: win32 no cover
 
     class WindowsFileLock(BaseFileLock):

tests/test_filelock.py

@@ -903,15 +903,7 @@ def test_mtime_zero_exit_branch(
         lock.acquire(timeout=0)
 
 
-@pytest.mark.parametrize(
-    "lock_type",
-    [
-        pytest.param(
-            FileLock, marks=pytest.mark.skipif(sys.platform == "win32", reason="Windows cannot unlink open files")
-        ),
-        SoftFileLock,
-    ],
-)
+@pytest.mark.parametrize("lock_type", [FileLock, SoftFileLock])
 def test_lock_file_removed_after_release(tmp_path: Path, lock_type: type[BaseFileLock]) -> None:
     lock_path = tmp_path / "test.lock"
     lock = lock_type(str(lock_path))