filelock 4.1.2__tar.gz → 4.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. {filelock-4.1.2 → filelock-4.2.1}/PKG-INFO +1 -1
  2. {filelock-4.1.2 → filelock-4.2.1}/docs/changelog.rst +117 -0
  3. {filelock-4.1.2 → filelock-4.2.1}/docs/concepts.rst +143 -44
  4. {filelock-4.1.2 → filelock-4.2.1}/docs/how-to.rst +59 -19
  5. {filelock-4.1.2 → filelock-4.2.1}/pyproject.toml +16 -0
  6. filelock-4.2.1/src/filelock/__init__.py +174 -0
  7. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_api.py +221 -61
  8. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_async.py +216 -78
  9. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_async_read_write.py +79 -36
  10. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_descriptor.py +5 -3
  11. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_error.py +2 -0
  12. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_identity.py +62 -12
  13. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_lease.py +60 -28
  14. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_marker.py +21 -8
  15. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_read_write.py +492 -141
  16. filelock-4.2.1/src/filelock/_soft.py +643 -0
  17. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_soft_protocol.py +2 -0
  18. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_soft_rw/__init__.py +4 -2
  19. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_soft_rw/_async.py +89 -40
  20. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_soft_rw/_protocol.py +71 -33
  21. filelock-4.2.1/src/filelock/_soft_rw/_storage.py +276 -0
  22. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_soft_rw/_sync.py +128 -50
  23. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_strict.py +321 -119
  24. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/_unix.py +85 -60
  25. filelock-4.2.1/src/filelock/_util.py +399 -0
  26. filelock-4.2.1/src/filelock/_windows.py +780 -0
  27. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/asyncio.py +66 -34
  28. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/version.py +2 -2
  29. {filelock-4.1.2 → filelock-4.2.1}/tasks/capabilities.py +30 -11
  30. {filelock-4.1.2 → filelock-4.2.1}/tasks/coverage_pragmas.py +2 -2
  31. {filelock-4.1.2 → filelock-4.2.1}/tests/capability_marks.py +11 -0
  32. filelock-4.2.1/tests/conftest.py +344 -0
  33. filelock-4.2.1/tests/pid_namespace_helpers.py +54 -0
  34. filelock-4.2.1/tests/process_helpers.py +73 -0
  35. {filelock-4.1.2 → filelock-4.2.1}/tests/read_write_helpers.py +26 -2
  36. {filelock-4.1.2 → filelock-4.2.1}/tests/soft_rw/test_soft_rw_async.py +326 -12
  37. {filelock-4.1.2 → filelock-4.2.1}/tests/soft_rw/test_soft_rw_protocol.py +147 -6
  38. {filelock-4.1.2 → filelock-4.2.1}/tests/soft_rw/test_soft_rw_storage.py +81 -7
  39. {filelock-4.1.2 → filelock-4.2.1}/tests/soft_rw/test_soft_rw_sync.py +397 -3
  40. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock.py +152 -12
  41. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock_acquire_cancellation.py +12 -4
  42. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock_transition_admission.py +94 -1
  43. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_read_write.py +310 -1
  44. filelock-4.2.1/tests/test_async_read_write_cancel_wait.py +157 -0
  45. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_read_write_cancellation.py +53 -1
  46. filelock-4.2.1/tests/test_async_read_write_worker_ownership.py +111 -0
  47. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_transition_gate.py +85 -10
  48. {filelock-4.1.2 → filelock-4.2.1}/tests/test_default_mode.py +56 -0
  49. {filelock-4.1.2 → filelock-4.2.1}/tests/test_filelock.py +691 -67
  50. {filelock-4.1.2 → filelock-4.2.1}/tests/test_fork_coordination.py +128 -0
  51. filelock-4.2.1/tests/test_fork_registries.py +175 -0
  52. filelock-4.2.1/tests/test_lazy_import.py +164 -0
  53. {filelock-4.1.2 → filelock-4.2.1}/tests/test_lock_expiry.py +36 -0
  54. {filelock-4.1.2 → filelock-4.2.1}/tests/test_marker_records.py +28 -3
  55. {filelock-4.1.2 → filelock-4.2.1}/tests/test_process_identity.py +131 -8
  56. {filelock-4.1.2 → filelock-4.2.1}/tests/test_read_write.py +604 -14
  57. {filelock-4.1.2 → filelock-4.2.1}/tests/test_read_write_fork.py +50 -36
  58. filelock-4.2.1/tests/test_read_write_private_link.py +415 -0
  59. {filelock-4.1.2 → filelock-4.2.1}/tests/test_read_write_unit.py +76 -6
  60. {filelock-4.1.2 → filelock-4.2.1}/tests/test_soft_lease.py +149 -1
  61. {filelock-4.1.2 → filelock-4.2.1}/tests/test_soft_stale.py +799 -23
  62. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_compat.py +22 -1
  63. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_failures.py +539 -130
  64. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_paths.py +0 -10
  65. {filelock-4.1.2 → filelock-4.2.1}/tests/test_unix_fallback.py +128 -1
  66. filelock-4.2.1/tests/test_util.py +677 -0
  67. {filelock-4.1.2 → filelock-4.2.1}/tox.toml +5 -0
  68. filelock-4.1.2/src/filelock/__init__.py +0 -131
  69. filelock-4.1.2/src/filelock/_soft.py +0 -378
  70. filelock-4.1.2/src/filelock/_soft_rw/_storage.py +0 -173
  71. filelock-4.1.2/src/filelock/_util.py +0 -151
  72. filelock-4.1.2/src/filelock/_windows.py +0 -339
  73. filelock-4.1.2/tests/conftest.py +0 -81
  74. filelock-4.1.2/tests/pid_namespace_helpers.py +0 -25
  75. filelock-4.1.2/tests/process_helpers.py +0 -32
  76. filelock-4.1.2/tests/test_fork_registries.py +0 -93
  77. filelock-4.1.2/tests/test_read_write_fd_fallback.py +0 -274
  78. filelock-4.1.2/tests/test_util.py +0 -314
  79. {filelock-4.1.2 → filelock-4.2.1}/.gitignore +0 -0
  80. {filelock-4.1.2 → filelock-4.2.1}/LICENSE +0 -0
  81. {filelock-4.1.2 → filelock-4.2.1}/README.md +0 -0
  82. {filelock-4.1.2 → filelock-4.2.1}/docs/_static/custom.css +0 -0
  83. {filelock-4.1.2 → filelock-4.2.1}/docs/api.rst +0 -0
  84. {filelock-4.1.2 → filelock-4.2.1}/docs/changelog/template.jinja2 +0 -0
  85. {filelock-4.1.2 → filelock-4.2.1}/docs/conf.py +0 -0
  86. {filelock-4.1.2 → filelock-4.2.1}/docs/example.gif +0 -0
  87. {filelock-4.1.2 → filelock-4.2.1}/docs/index.rst +0 -0
  88. {filelock-4.1.2 → filelock-4.2.1}/docs/license.rst +0 -0
  89. {filelock-4.1.2 → filelock-4.2.1}/docs/logo.svg +0 -0
  90. {filelock-4.1.2 → filelock-4.2.1}/docs/tutorials.rst +0 -0
  91. {filelock-4.1.2 → filelock-4.2.1}/src/filelock/py.typed +0 -0
  92. {filelock-4.1.2 → filelock-4.2.1}/tasks/benchmark.py +0 -0
  93. {filelock-4.1.2 → filelock-4.2.1}/tasks/capability/assert_fallback.py +0 -0
  94. {filelock-4.1.2 → filelock-4.2.1}/tasks/capability/sitecustomize.py +0 -0
  95. {filelock-4.1.2 → filelock-4.2.1}/tasks/deny_symlink.py +0 -0
  96. {filelock-4.1.2 → filelock-4.2.1}/tasks/termux/Dockerfile +0 -0
  97. {filelock-4.1.2 → filelock-4.2.1}/tasks/verify_filesystem.py +0 -0
  98. {filelock-4.1.2 → filelock-4.2.1}/tests/async_filelock_cancellation_helpers.py +0 -0
  99. {filelock-4.1.2 → filelock-4.2.1}/tests/fork_helpers.py +0 -0
  100. {filelock-4.1.2 → filelock-4.2.1}/tests/soft_rw/conftest.py +0 -0
  101. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock_release_cancellation.py +0 -0
  102. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock_rollback_agnostic.py +0 -0
  103. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_filelock_runner_shutdown.py +0 -0
  104. {filelock-4.1.2 → filelock-4.2.1}/tests/test_async_soft_contracts.py +0 -0
  105. {filelock-4.1.2 → filelock-4.2.1}/tests/test_error.py +0 -0
  106. {filelock-4.1.2 → filelock-4.2.1}/tests/test_fork_backends.py +0 -0
  107. {filelock-4.1.2 → filelock-4.2.1}/tests/test_fork_ownership.py +0 -0
  108. {filelock-4.1.2 → filelock-4.2.1}/tests/test_host_name_grammar.py +0 -0
  109. {filelock-4.1.2 → filelock-4.2.1}/tests/test_lifetime_validation.py +0 -0
  110. {filelock-4.1.2 → filelock-4.2.1}/tests/test_soft_lifetime_warning.py +0 -0
  111. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft.py +0 -0
  112. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_races.py +0 -0
  113. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_recovery.py +0 -0
  114. {filelock-4.1.2 → filelock-4.2.1}/tests/test_strict_soft_stress.py +0 -0
  115. {filelock-4.1.2 → filelock-4.2.1}/tests/test_subclass_options.py +0 -0
  116. {filelock-4.1.2 → filelock-4.2.1}/tests/test_virtualenv.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: filelock
3
- Version: 4.1.2
3
+ Version: 4.2.1
4
4
  Summary: A platform independent file lock.
5
5
  Project-URL: Documentation, https://py-filelock.readthedocs.io
6
6
  Project-URL: Homepage, https://github.com/tox-dev/py-filelock
@@ -6,6 +6,123 @@
6
6
 
7
7
  .. towncrier release notes start
8
8
 
9
+ *******************
10
+ 4.2.1 (2026-10-17)
11
+ *******************
12
+
13
+ - On a singleton wrapper, :meth:`AsyncReadWriteLock.close() <filelock.AsyncReadWriteLock.close>` and
14
+ :meth:`AsyncSoftReadWriteLock.close() <filelock.AsyncSoftReadWriteLock.close>` end only the holds that tasks acquired
15
+ through that wrapper. A reader that arrives during ``close()`` gets the closed error instead of joining the ending hold.
16
+ After synchronous code closes or force-releases the shared lock, the wrappers refuse to admit readers into the ended
17
+ hold, and ``close()`` on such a wrapper returns.
18
+ Closing one wrapper no longer ends a task's nested hold taken through another wrapper on the same path. :pr:`832`
19
+ - :class:`~filelock.ReadWriteLock` locks again after a ``release()`` that an exception from a signal handler interrupted.
20
+ The async read-write wrappers stop admitting readers into such a level. The async read-write locks forget a hold whose
21
+ backend release failed after the backend let go, and they free the memory of each acquire that times out or is canceled.
22
+ :class:`~filelock.AsyncFileLock` returns from ``release()`` after a few hundred acquires gave up behind a waiting one. An exception from a signal handler delivered while an :class:`~filelock.AsyncFileLock` call joins
23
+ its queue no longer blocks every later call on that lock. :pr:`833`
24
+ - Fix :class:`~filelock.ReadWriteLock` acting on ``-journal``, ``-wal`` or ``-shm`` files another process puts beside its
25
+ database: a write could land in another file, a reader could get in beside a writer, and an acquire could fail. SQLite
26
+ now opens the database by name only in a directory no other account can write, and through a private hard link
27
+ elsewhere. On Windows the directory's access control list decides. Where hard links are unavailable, keep the database
28
+ in a directory other accounts cannot write, such as one under ``%LOCALAPPDATA%``. The lock removes link directories
29
+ through a checked descriptor rather than by name, reads a link directory's name only when the locking account owns it,
30
+ and leaves alone a directory with other content renamed onto a link directory's name. A database whose schema takes more
31
+ than a few kilobytes to load raises :class:`ValueError` instead of running past the acquire timeout. :pr:`834`
32
+ - Fix five bugs in opening the lock file. :class:`~filelock.UnixFileLock` no longer truncates a file it did not create,
33
+ such as one renamed to the lock path, and no longer applies ``mode`` to it. An ``on_acquired`` hook that writes holder
34
+ metadata now truncates the file itself. A lease (Linux) or an oplock (Windows) on the lock file or a soft lock's marker
35
+ no longer holds ``acquire()`` past its ``timeout`` or ``blocking=False``, and an oplock no longer holds ``release()``;
36
+ :class:`~filelock.ReadWriteLock` on Windows waits for its ``timeout`` and raises :class:`~filelock.Timeout`. On Windows,
37
+ a ``mode`` without group and other bits, such as ``0o600``, now creates the lock file with an owner-only permission
38
+ list; the :class:`~filelock.ReadWriteLock` database gets the same. The soft locks' writability check no longer follows a
39
+ symlink swapped in at the lock path. On a filesystem without ``flock``, a contender from another account now waits on a
40
+ marker it cannot write instead of raising ``PermissionError``. :pr:`835`
41
+ - Fix :class:`~filelock.SoftFileLock`, :class:`~filelock.MarkerSoftFileLock` and :class:`~filelock.SoftFileLease` removing
42
+ a live holder's marker in three cases: the holder and the contender run in Linux time namespaces with different boottime
43
+ offsets; only one of them can read the boot id; a process other than the owner rewrote the marker. Soft markers no
44
+ longer carry group or other write bits. A process name containing a carriage return or another line separator no longer
45
+ makes the stale check raise :class:`ValueError`. When ``/proc/self/ns/time`` exists but cannot be read, the stale check
46
+ no longer compares start times and keeps the marker. :pr:`836`
47
+ - The async read-write locks record their hold under a task owner, so synchronous code on the executor thread that took
48
+ the hold can no longer re-enter or release it. :class:`~filelock.AsyncSoftReadWriteLock` gives back one level on
49
+ release, so synchronous readers of a shared singleton keep theirs. :class:`~filelock.SoftReadWriteLock` tracks read
50
+ levels per thread: ``release()`` from a thread that holds none raises :class:`RuntimeError`. After its heartbeat
51
+ recorded a lost hold, it refuses new acquires until that hold is released. :pr:`838`
52
+ - :class:`~filelock.StrictSoftFileLock` creates ``<path>.filelock`` and its ``claims`` directory with the lock's ``mode``
53
+ and sets the sticky bit (a directory flag that lets only a file's owner remove it) on both. On the next acquisition it
54
+ narrows a directory it owns that an earlier release created wider; it leaves a directory of another account as it is,
55
+ so remove such leftovers by hand. It reaches ``claims`` through a descriptor opened without following symlinks; on
56
+ Windows it holds both directories open and refuses a junction (a directory that points at another directory). Under a
57
+ sticky parent such as ``/tmp`` it refuses a coordination directory of another account, as
58
+ :class:`~filelock.SoftReadWriteLock` does for ``<path>.rw``. One read grace now covers a whole claim scan, a failed
59
+ claim cleanup no longer leaves the sentinel descriptor open, and a non-regular node at a sentinel private-record name
60
+ raises :class:`~filelock.SoftFileLockProtocolError`. On Windows, contenders read claims without blocking their owner's
61
+ unlink. :pr:`839`
62
+ - Fix a lock reporting a hold the OS had dropped after a signal handler raised during
63
+ :meth:`~filelock.BaseFileLock.acquire` or :meth:`~filelock.BaseFileLock.release`. A release that a signal handler cuts
64
+ short after it has started now completes before the error propagates. A handler that acquires the lock its own thread is
65
+ releasing now gets :class:`RuntimeError` instead of a hold that stays held. The singleton cache no longer hands out an
66
+ ``is_singleton=True`` lock or a :class:`~filelock.ReadWriteLock` whose finalizer is running, which released the new
67
+ holder's lock. A signal during ``os.fork()`` no longer leaves the other threads blocked in their next lock call, and a
68
+ fork from another thread no longer waits for a :class:`~filelock.ReadWriteLock` acquire on a busy database. :pr:`840`
69
+ - Fix a lock on a relative path locking a file in the directory the process changed to while the lock waited, and leaving
70
+ its marker behind on release after such a change. The path resolved when an acquisition starts stays in use until
71
+ the hold ends. An ``is_singleton=True`` lookup no longer returns a cached lock whose relative path now resolves to
72
+ another file; a held lock still matches the file it holds. A rename of the lock's directory during a hold no longer
73
+ leaves the marker behind or reports a false lease compromise, and a waiter no longer creates a second lock file in a
74
+ directory that was renamed away. :pr:`841`
75
+ - :class:`~filelock.SoftReadWriteLock` reaches its records through descriptors of ``<path>.rw`` and ``gen`` or ``holders``
76
+ opened without following symlinks. On Windows it holds those directories open and refuses a junction (a directory that
77
+ points at another directory). A tree swapped in after an earlier acquire therefore cannot redirect them. Its heartbeat
78
+ rewrites a holder record only when the name still leads to the file it created, and does not block on a FIFO (a named
79
+ pipe). A heartbeat that finds ``<path>.rw`` replaced by a symlink or junction reports the hold lost instead of ending
80
+ the heartbeat thread. A live lock object repeats the ownership check whenever the tree it opens is not the one it
81
+ prepared. :pr:`842`
82
+ - Fix :class:`~filelock.SoftFileLock`, :class:`~filelock.MarkerSoftFileLock` and :class:`~filelock.SoftFileLease` removing
83
+ or displacing a live holder's marker in five cases. ext4 gave a freed inode number to the next marker. A stalled
84
+ :class:`~filelock.FileLock` removed its ``ENOSYS`` placeholder after a peer replaced it. A failed acquire cleaned up
85
+ after a successor took the path. A stale break left the lock path empty while it checked the marker it had moved. A
86
+ ``lifetime`` break judged a marker by a reused inode number. On Linux and macOS a stale marker now changes hands in one
87
+ atomic exchange. On other platforms without one, except Windows, including NFS and SMB, the marker stays in place and
88
+ waits for ``timeout`` or ``break_lock()``. Restoring a marker no longer follows a symlink found under the break name. A
89
+ holder that releases while a peer's exchange has its marker aside leaves a record no lock parses, so the put-back lands
90
+ a marker that ages out. A lease heartbeat that finds another file at the lock path once, while a peer's break has its
91
+ marker aside, waits for the next refresh before it reports a compromise. A contender that finds a dead breaker's marker
92
+ puts back the marker that breaker left under its break name. A marker is the breaker's own only when it names the
93
+ breaker's process on this host; the same process number on another host is a holder. A contender takes a stranded marker
94
+ under a name of its own before it puts the marker back, so two contenders no longer reverse each other's exchange and
95
+ remove the live holder's marker. A claim left behind by a failed put-back is retried on the next poll. :pr:`843`
96
+ - Canceling an :class:`~filelock.AsyncReadWriteLock` or :class:`~filelock.AsyncSoftReadWriteLock` acquire that waits for
97
+ another process now stops the wait and raises the cancellation. It used to wait until that process released, or raise
98
+ :class:`~filelock.Timeout`. A ``thread_local=True`` :class:`~filelock.AsyncFileLock` that threads with their own event
99
+ loops share no longer deadlocks when one thread waits for the lock while another holds it. :pr:`844`
100
+ - :class:`~filelock.SoftReadWriteLock` refuses a commit that lands a whole retention window behind the log, so two
101
+ committers stalled at adjacent generations can no longer admit a second writer. Its stale check samples the clock before
102
+ it reads a holder record, so a pause between the two no longer counts as time the record stayed unchanged. :pr:`845`
103
+ - Fix a :class:`~filelock.SoftFileLock` contender evicting an empty marker after two seconds while its owner held the
104
+ lock. The owner is a ``SoftFileLock`` before 3.22, which writes nothing into its marker, or a current one still writing
105
+ its record. An empty marker now reads as held, and ``timeout``, ``lifetime`` or ``break_lock()`` clears it. A contender
106
+ that finds an empty marker a dead breaker left aside puts it back instead of removing it. :pr:`846`
107
+ - Fix :class:`~filelock.ReadWriteLock` on Windows acting on ``-journal`` and ``-wal`` files another account places beside
108
+ its database: an acquire could fail with :class:`sqlite3.OperationalError`, or SQLite could replay the journal and
109
+ delete the file it names. The lock now reads the database directory's access control list. Where an account other than
110
+ the locking account, ``SYSTEM`` and ``Administrators`` can add or remove names, SQLite opens a hard link inside a
111
+ directory only those accounts can write. A filesystem without hard links raises :class:`OSError`. :pr:`854`
112
+ - Fix ``SoftReadWriteLock`` subclasses sharing singleton instances with the base class or sibling subclasses.
113
+ Each concrete class now keeps its own cache and construction guard, including after fork, while preserving
114
+ cooperative class-definition keywords. :pr:`855`
115
+ - GraalPy is now tested weekly instead of on every change: GraalPy 25.4.4 can freeze the test suite, which made its job
116
+ fail on unrelated changes. :pr:`849`
117
+
118
+ *******************
119
+ 4.2.0 (2026-10-14)
120
+ *******************
121
+
122
+ - ``import filelock`` is about twice as fast: lock types other than :class:`~filelock.FileLock` load on first use. :pr:`831`
123
+ - Fix :class:`~filelock.StrictSoftFileLock` raising :class:`~filelock.SoftFileLockProtocolError` on Windows when a
124
+ contender read a claim whose owner was still finishing its unlink. :pr:`829`
125
+
9
126
  *******************
10
127
  4.1.2 (2026-10-14)
11
128
  *******************
@@ -169,6 +169,15 @@ Every strict participant needs filelock 3.30.0 or newer. Legacy clients configur
169
169
  ``break_lock()``, and code that deletes lock files can remove the sentinel; mixing them with strict clients voids mutual
170
170
  exclusion.
171
171
 
172
+ The lock creates ``<path>.filelock`` and its ``claims`` directory with its ``mode``, plus search permission where the
173
+ mode grants read, so ``mode=0o600`` gives ``0o700``. It sets the sticky bit (a directory flag that lets only a file's
174
+ owner remove it) on both, so only the account that published a claim can remove it. On each acquisition it
175
+ narrows a directory it owns to the mode, which covers one an earlier release created wider. Under a sticky parent such
176
+ as ``/tmp``, acquisition raises :class:`SoftFileLockProtocolError <filelock.SoftFileLockProtocolError>` when
177
+ ``<path>.filelock`` belongs to an account that owns neither the lock nor the parent. Where the platform supports
178
+ ``dir_fd``, the lock reaches ``claims`` through a descriptor of ``<path>.filelock`` opened without following symlinks.
179
+ A symlink swapped in for either directory then fails the operation instead of redirecting it.
180
+
172
181
  Strict claims require coherent directory reads and atomic no-replace hard links. The class reports a protocol error
173
182
  when the filesystem reports that it cannot publish hard links. NFS and SMB remain outside this guarantee until their
174
183
  mount and server combination passes the protocol tests. Linux documents the hard-link lock pattern in `open(2)
@@ -219,6 +228,13 @@ Losing a private name makes the publisher retry; it never converts an unpublishe
219
228
  stable pathname across releases, construct the lock with ``preserve_lock_file=True`` (see :ref:`how-to:Keep the lock
220
229
  file on release`).
221
230
 
231
+ An oplock (opportunistic lock: a notice sent to a process holding a handle before another process opens the file,
232
+ which the opener waits on until the holder answers) on the lock file does not hold an acquire past its ``timeout``.
233
+ The open reports contention, and the retry loop keeps the deadline. :class:`~filelock.ReadWriteLock` waits for its
234
+ ``timeout`` on an oplocked database and then raises :class:`~filelock.Timeout`. Release deletes the lock file
235
+ through a handle that does not wait for an oplock holder either, so a holder that never answers leaves the file in
236
+ place.
237
+
222
238
  **Unix and macOS**
223
239
  Uses the :class:`UnixFileLock <filelock.UnixFileLock>` class, backed by the kernel's ``fcntl.flock`` interface. The
224
240
  interface is common on Unix systems but is not specified by POSIX. The lock is exclusive and enforced by the kernel.
@@ -230,10 +246,12 @@ Losing a private name makes the publisher retry; it never converts an unpublishe
230
246
  exclusion; remove the file only after the complete lock protocol has stopped using it.
231
247
 
232
248
  Filesystems without ``flock``: when ``flock`` fails with ``ENOSYS``, the lock switches to :class:`SoftFileLock
233
- <filelock.SoftFileLock>` and emits a warning, unless constructed with ``fallback_to_soft=False``. Before switching it
234
- removes the empty file only if this acquire created it. A file that already existed may be another process's soft
235
- marker, so it stays: the soft lock waits on a live holder and reclaims an empty leftover once it has stayed
236
- unchanged for two seconds.
249
+ <filelock.SoftFileLock>` and emits a warning, unless constructed with ``fallback_to_soft=False``. Before switching
250
+ it removes the empty file only if this acquire created it. It does so while still holding the file open, with the
251
+ exchange a stale break uses, so a peer's marker that replaced it is put back rather than deleted. A file that
252
+ already existed may be another process's soft marker, so it stays and the soft lock waits on it. An empty file there
253
+ reads as a holder that recorded nothing, as a release before 3.22 writes. A leftover one therefore waits for
254
+ ``timeout``, ``lifetime`` or ``break_lock()``.
237
255
 
238
256
  **Other platforms without fcntl**
239
257
  Falls back to :class:`SoftFileLock <filelock.SoftFileLock>` and emits a warning. The lock is not enforced by the OS,
@@ -430,17 +448,34 @@ How filelock mitigates this:
430
448
  The defense differs by platform:
431
449
 
432
450
  - On Unix, filelock opens lock files with ``O_NOFOLLOW``, so a symlink planted at the lock path makes the open fail
433
- instead of reaching its target.
451
+ instead of reaching its target. ``O_NOFOLLOW`` does not catch a hard link (a second name for the same file) or a file
452
+ renamed to the lock path, and such a file is indistinguishable from a lock file. :class:`UnixFileLock
453
+ <filelock.UnixFileLock>` therefore locks a file it did not create as found, without truncating it or changing its
454
+ mode.
434
455
  - Windows has no ``O_NOFOLLOW``. :class:`WindowsFileLock <filelock.WindowsFileLock>` opens the file without following
435
456
  reparse points and rejects a symlink or junction by inspecting the handle it locks, so a swap between check and use
436
457
  cannot redirect it. Only the last path component is guarded; the lock directory must not be writable by untrusted
437
458
  users.
438
459
  - :class:`SoftFileLock <filelock.SoftFileLock>` creates its marker with ``O_CREAT | O_EXCL``, which fails on any
439
460
  existing name. Before reading a marker it classifies the path with ``lstat`` and treats anything other than a regular
440
- file as malformed, then checks the opened handle again with ``fstat``.
441
-
442
- :class:`ReadWriteLock <filelock.ReadWriteLock>` refuses a symlink at its database path and keeps SQLite on the file it
443
- checked, so a link planted in a shared directory cannot point the lock at another file.
461
+ file as malformed, then checks the opened handle again with ``fstat``. On Windows it reads and breaks markers through
462
+ handles that do not wait for an oplock holder to answer, so an oplock on a marker ends as contention and the
463
+ ``timeout`` holds.
464
+ - :class:`StrictSoftFileLock <filelock.StrictSoftFileLock>` opens ``<path>.filelock`` with ``O_NOFOLLOW`` and reaches
465
+ ``claims`` relative to that descriptor on platforms that support ``dir_fd``. A symlink swapped in for either
466
+ directory after the check cannot redirect where claims are created, listed or removed.
467
+ - :class:`SoftReadWriteLock <filelock.SoftReadWriteLock>` opens ``<path>.rw`` and then ``gen`` or ``holders`` without
468
+ following symlinks for every record operation on platforms that support ``dir_fd``. A tree swapped in after an
469
+ earlier acquire cannot redirect its writes. It rewrites a holder record only when the name still leads to the file it
470
+ created and that file has no second name, and it opens the record without blocking. It leaves alone a hard link (a
471
+ second name for the same file) or a FIFO (a named pipe) renamed over the record.
472
+
473
+ :class:`ReadWriteLock <filelock.ReadWriteLock>` refuses a symlink at its database path. In a directory that processes of
474
+ other accounts can write, it opens SQLite through a hard link (a second name for the same file) in a directory only the
475
+ locking account can read, so a link or journal file another process puts beside the database cannot point the lock at
476
+ another file. On Windows the directory counts as writable by other accounts unless its owner and every entry of its
477
+ access control list (ACL) that allows adding or removing names belong to the locking account, ``SYSTEM`` or
478
+ ``Administrators``.
444
479
 
445
480
  ***************************************
446
481
  What filelock doesn't protect against
@@ -509,6 +544,17 @@ because that co-tenant owns the files and can bypass the protocol. Treat every s
509
544
  follow the protocol. Where that assumption does not hold, a file lock is the wrong tool; use an OS mechanism that enforces
510
545
  access, such as a privilege boundary or a broker process.
511
546
 
547
+ The directory boundary
548
+ ======================
549
+
550
+ Every protection filelock gives against processes of other accounts holds only while none of them can replace the
551
+ lock's directory or any of its ancestors. Each ancestor must belong to the account the lock runs as or to root, and must
552
+ either not be writable by others or carry the sticky bit. A process that can rename entries in a non-sticky ancestor
553
+ can move the lock file or protocol directory aside, even one it cannot read, and put its own in its place. Holders that
554
+ reached the old one keep using it while new contenders use the replacement, so two of them hold the lock at once and
555
+ neither learns of it. No check inside the lock can rule that out, because the owner of such a directory controls every name
556
+ in it. Keep locks in a directory that only the lock's users can write, or in a sticky one such as ``/tmp``.
557
+
512
558
  Native locks are advisory
513
559
  ==========================
514
560
 
@@ -594,12 +640,20 @@ cannot expire a live claim. In exchange a contender that first sees a long-aband
594
640
  Malformed and legacy markers
595
641
  ============================
596
642
 
597
- A soft lock treats a record it cannot parse as malformed, not as a holder. A plain :class:`SoftFileLock
598
- <filelock.SoftFileLock>` self-heals a malformed marker once it has watched it stay unchanged for a short grace window on
599
- its own monotonic clock, which absorbs the brief gap between creating a marker and writing its record. A strict lock
600
- never age-breaks, so it fails closed on an unreadable claim. A marker written by an older filelock stays readable: the
601
- process start token is an integer, so a 3.29 reader parses a newer marker as well-formed and stays conservative rather
602
- than evicting a live holder.
643
+ A soft lock treats a record it cannot parse as malformed, not as a holder. An empty marker is the exception: it is the
644
+ whole marker of a :class:`SoftFileLock <filelock.SoftFileLock>` before 3.22, held for as long as its owner runs, and
645
+ also what a current acquirer shows before it writes its record. A contender therefore waits on it like on any live
646
+ holder. A plain :class:`SoftFileLock <filelock.SoftFileLock>` self-heals any other malformed marker once it has watched
647
+ it stay unchanged for a short grace window on its own monotonic clock, which absorbs the brief gap between creating a
648
+ marker and writing its record.
649
+
650
+ It tells markers apart by modification time, inode number and change time (the time the kernel last changed the file's
651
+ metadata). An owner can set a file's modification time, and ext4 hands a freed inode number to the next file, but no
652
+ process can set the change time. A new marker therefore never inherits the time spent watching an old one.
653
+
654
+ A strict lock never age-breaks, so it fails closed on an unreadable claim. A marker written by an older filelock stays
655
+ readable: the process start token is an integer, so a 3.29 reader parses a newer marker as well-formed and stays
656
+ conservative rather than evicting a live holder.
603
657
 
604
658
  Filesystem support matrix
605
659
  =========================
@@ -679,24 +733,54 @@ Every platform records the holder's PID, hostname, and a process start token in
679
733
  only when the recorded owner is provably gone. A PID that no longer exists is gone; a live PID whose start token differs
680
734
  is a recycled PID, so the process that wrote the marker is gone; a live PID whose token still matches, a token that
681
735
  cannot be read, and a marker from another host all read as held. The start token is ``kill(pid, 0)`` plus the
682
- ``starttime`` from ``/proc/<pid>/stat`` folded with the boot id on Linux, ``sysctl`` process start time on macOS, and the
683
- ``GetProcessTimes`` creation time on Windows. A malformed or unparsable record follows a separate rule: a waiter may
684
- remove it once it has seen it unchanged for two seconds, so a half-written marker never wedges acquisition. This is the
685
- rule PostgreSQL, Qt ``QLockFile``, and Mercurial converge on: break a stale lock only on proof of death.
686
-
687
- Breaking a marker leaves a short window. Right before breaking it the contender reads the marker's inode and
688
- modification time again and leaves it alone if they moved since the stale check, the way Mercurial re-reads a lock under
689
- its break lock before removing it. It then renames the marker to a private ``<lock>.break.*`` name, so only one of
690
- several breakers takes it, and checks the renamed file's inode and modification time once more. A mismatch means a peer
691
- recreated the marker between that last read and the rename, so the contender hard-links that live marker back to the
692
- lock path and drops the break name. A third process that takes the empty path in the two syscalls between the rename
693
- and the link keeps it, whether a soft lock creating its marker or a :class:`StrictSoftFileLock
694
- <filelock.StrictSoftFileLock>` publishing its sentinel, and the live marker stays under the break name. Both then hold
695
- the lock. Mercurial
696
- closes this window by serializing breakers on a separate ``<lock>.break`` lock; filelock does not, because a breaker that
697
- crashes would leave that lock needing stale detection of its own and a 3.29 peer never takes it. Where ``os.link`` is
698
- missing or the filesystem refuses hard links, the live marker stays under the break name. The same applies to the
699
- ``lifetime`` and :class:`SoftFileLease <filelock.SoftFileLease>` expiry breaks.
736
+ ``starttime`` from ``/proc/<pid>/stat`` folded with the boot id on Linux, ``sysctl`` process start time on macOS, and
737
+ the ``GetProcessTimes`` creation time on Windows.
738
+
739
+ A malformed or unparsable record follows a separate rule: a waiter may remove it once it has seen it unchanged for two
740
+ seconds, so a half-written marker never wedges acquisition. An empty marker is the exception and always reads as held.
741
+ This is the rule PostgreSQL, Qt ``QLockFile``, and Mercurial converge on: break a stale lock only on proof of death.
742
+
743
+ Two Linux processes do not always read the same token for one task. Since Linux 5.6 the kernel adds the reader's
744
+ boottime offset (the shift a time namespace applies to the boot clock) to ``starttime``. A process in a time namespace
745
+ with such an offset therefore records no start token and reads none. It falls back to the PID alone, so a recycled PID
746
+ keeps a dead owner's marker until ``timeout``, ``lifetime`` or ``break_lock()``. A time namespace without an offset, as
747
+ container runtimes create, keeps the token. A process that cannot read ``/proc/sys/kernel/random/boot_id`` (systemd's
748
+ ``ProcSubset=pid`` hides it) records ``starttime`` without the boot id. A contender then compares ``starttime`` alone
749
+ whenever either side lacks the boot id.
750
+
751
+ A contender never leaves the lock path empty while it breaks a marker. Right before breaking it reads the marker's inode
752
+ (the kernel's identity for a file, independent of its name) and modification time again. If they moved since the stale
753
+ check, it leaves the marker alone, the way Mercurial re-reads a lock under its break lock before removing it. On Linux
754
+ (``renameat2``) and macOS (``renamex_np``) it then writes a complete marker of its own under a private
755
+ ``<lock>.break.*`` name and exchanges the two names in one step. A contender that polls meanwhile finds a marker and
756
+ waits.
757
+
758
+ If the file it took is the one judged stale, it removes that file and holds the lock from then on. A peer that
759
+ exchanges after that moves the holder's marker aside only while it checks what it took, and puts it back. A holder that
760
+ releases while its marker is aside leaves a record no lock parses, so the put-back lands a marker that ages out.
761
+ Otherwise a peer recreated the marker, and a second exchange puts the live marker back before its own is removed.
762
+
763
+ The private name is ``<lock>.break.<pid>.<token>``: the breaker's PID, then 32 random hex digits. A breaker killed
764
+ between its exchange and the put-back leaves its own marker at the lock path and a live holder's marker under that name.
765
+ A contender that finds the breaker's marker dead first looks in the lock's directory for names that start with
766
+ ``<lock>.break.<pid>.``, where ``<pid>`` is the dead breaker's. It first renames the record to
767
+ ``<lock>.restore.<pid>.<token>`` with its own PID, so only one of several contenders acts on it; a record whose
768
+ recoverer died there is claimable again, and a claim a failed put-back left in the same process is retried on the next
769
+ poll. It then exchanges back a marker whose owner is alive or cannot be proven dead, and removes one whose owner is
770
+ dead. Where the filesystem refuses that exchange, the lock counts as held until ``timeout`` or ``break_lock()``. The
771
+ placeholder a break writes while it works carries the same PID, so a contender that evicts a placeholder a killed
772
+ process left finds the same names.
773
+
774
+ The contender holds the judged marker open from before it reads the record until the break ends. ext4 gives a freed
775
+ inode number to the next file created, so a successor's marker could otherwise carry the number of the marker judged
776
+ stale.
777
+
778
+ Windows has no such exchange, but it refuses to rename a marker its live holder keeps open. There the contender renames
779
+ the marker aside, checks it, and links back a marker it took by mistake; ``link`` never replaces a name. Anywhere else
780
+ without an exchange, including NFS and SMB, which refuse it, a contender does not move a marker at all, because the path
781
+ would stand empty beside a possibly live holder. The marker then counts as held until ``timeout`` or ``break_lock()``.
782
+ The ``lifetime`` and :class:`SoftFileLease <filelock.SoftFileLease>` expiry breaks follow the same rules, and a failed
783
+ acquire removes its own marker by the same exchange before it closes it.
700
784
 
701
785
  A PID means something only inside its PID namespace, and two containers in one pod share the hostname and the boot id
702
786
  without sharing one. On Linux the recorded hostname therefore names the namespace too, as ``<host>?pidns-<inode>`` with
@@ -708,14 +792,16 @@ start token instead: a 3.30 reader compares the whole token and would read any n
708
792
  A release before the namespace was recorded wrote the bare hostname from inside a container too, so a contender in the
709
793
  host's namespace reads such a marker from a container that shares the hostname (host networking) as local, where its PID
710
794
  names another process or none. Before it calls that owner dead it looks for a task in another namespace whose innermost
711
- PID (``NSpid`` in ``/proc/<pid>/status``) and start token match the record, since ``starttime`` and the boot id are
712
- kernel-wide, and keeps the marker if one exists. Three limits remain. A marker without a start token, a kernel before
713
- 4.1 without ``NSpid``, or a ``/proc`` this process cannot list leaves the check nothing to find. Where
714
- ``/proc/self/ns/pid`` cannot be read, the bare hostname is all that separates namespaces. And a contender never reclaims
715
- a marker from another namespace: a container that crashes and is replaced comes back in a new namespace. A
716
- :class:`~filelock.Timeout` names such a holder. Containers that can crash while holding a soft lock should use
717
- :class:`SoftFileLease <filelock.SoftFileLease>`, set ``lifetime``, or call ``break_lock()`` at entrypoint once nothing
718
- else can hold the path.
795
+ PID (``NSpid`` in ``/proc/<pid>/status``) and start token match the record, since ``starttime`` and the boot id read the
796
+ same in every PID namespace, and keeps the marker if one exists. From a time namespace with a boottime offset it matches
797
+ the innermost PID alone.
798
+
799
+ Three limits remain. A marker without a start token, a kernel before 4.1 without ``NSpid``, or a ``/proc`` this process
800
+ cannot list leaves the check nothing to find. Where ``/proc/self/ns/pid`` cannot be read, the bare hostname is all that
801
+ separates namespaces. And a contender never reclaims a marker from another namespace: a container that crashes and is
802
+ replaced comes back in a new namespace. A :class:`~filelock.Timeout` names such a holder. Containers that can crash
803
+ while holding a soft lock should use :class:`SoftFileLease <filelock.SoftFileLease>`, set ``lifetime``, or call
804
+ ``break_lock()`` at entrypoint once nothing else can hold the path.
719
805
 
720
806
  Why is ReadWriteLock backed by SQLite?
721
807
  ======================================
@@ -944,8 +1030,11 @@ inherited ``with lock.read_lock():`` block can unwind in the child without raisi
944
1030
  fresh ``SoftReadWriteLock(path)`` before it can acquire again. This matches PyMongo's connection-pool semantics.
945
1031
 
946
1032
  **Trust boundary.** The class coordinates cooperating processes. Directory ownership, ACLs, and ``0o600`` / ``0o700``
947
- permissions can exclude another UID. A process with the same effective UID can alter the records. A filesystem that
948
- delays a rewrite's visibility past ``stale_threshold`` can also trigger expiry while a holder remains active.
1033
+ permissions can exclude another UID. Under a sticky parent such as ``/tmp``, acquisition raises :class:`RuntimeError`
1034
+ when ``<path>.rw``, ``gen`` or ``holders`` belongs to an account that owns neither the lock nor the parent. The refusal
1035
+ also applies to a lock object that used an earlier tree: it repeats the check whenever a directory it opens is not the
1036
+ one it prepared. A process with the same effective UID can alter the records. A filesystem that delays a rewrite's
1037
+ visibility past ``stale_threshold`` can also trigger expiry while a holder remains active.
949
1038
 
950
1039
  ****************************
951
1040
  File permissions and mode
@@ -957,7 +1046,17 @@ inheritance so the lock file gets the directory's default permissions rather tha
957
1046
 
958
1047
  When you pass an explicit ``mode`` value (e.g., ``mode=0o644``), filelock creates the file with it. On Unix,
959
1048
  :class:`UnixFileLock <filelock.UnixFileLock>` and :class:`SoftFileLock <filelock.SoftFileLock>` then apply it with
960
- ``fchmod``, so the umask cannot narrow it. This overrides any default ACLs on the directory.
1049
+ ``fchmod``, so the umask cannot narrow it. This overrides any default ACLs on the directory. A Unix lock file that
1050
+ already exists keeps the mode it has. A soft lock's marker never gets the group or other write bits, whatever the
1051
+ ``mode`` or umask. Contenders only read and rename it, and they act on the record its owner wrote.
1052
+
1053
+ Windows has no mode bits. A new file inherits the ACL (access control list, the Windows permission list) of its
1054
+ directory. :class:`WindowsFileLock <filelock.WindowsFileLock>` honors the one ``mode`` that has a Windows counterpart: a
1055
+ ``mode`` without group and other bits, such as ``0o600``, creates the lock file with an ACL that grants access to its
1056
+ owner, ``SYSTEM`` and ``Administrators`` only, the ACL ``os.mkdir(mode=0o700)`` applies. The
1057
+ :class:`~filelock.ReadWriteLock` database, always ``0o600``, gets the same ACL. A file that already exists keeps its own
1058
+ ACL. Every other ``mode`` inherits the directory's ACL, as do the files of the soft locks, which ``os.open`` creates;
1059
+ restrict the directory's ACL to keep other accounts out.
961
1060
 
962
1061
  An explicit ``mode`` must be an :class:`int` within ``0o000``-``0o777`` that grants the owner read and write;
963
1062
  construction raises :class:`TypeError` for another type and :class:`ValueError` otherwise. A lock reopens, reads, and
@@ -42,6 +42,8 @@ Two more constraints worth designing around:
42
42
  - **All contenders must agree on the path.** A lock is a rendezvous on one pathname. Resolve symlinks and relative
43
43
  paths the same way everywhere, or two processes will politely lock different files. Bind-mounted containers make this
44
44
  easy to get wrong: the same file, two paths, no exclusion.
45
+ filelock resolves a relative path when an acquisition starts and keeps that path until the hold ends. Do not rename
46
+ the lock's directory while a lock in it is held or waited on: a waiter then fails with :class:`FileNotFoundError`.
45
47
  - **Create the resource's directory when using a separate lock tree.** filelock creates the lock file's parent
46
48
  directories automatically, but it does not create directories for the resource being protected.
47
49
 
@@ -432,12 +434,38 @@ Parameters are frozen when the singleton is first created. Requesting the same p
432
434
 
433
435
  When you have many readers and occasional writers, use :class:`ReadWriteLock <filelock.ReadWriteLock>` to allow readers
434
436
  to proceed concurrently. ``ReadWriteLock`` is backed by SQLite; a ``.db`` extension is a convention rather than a
435
- requirement. Use a local filesystem the active SQLite VFS supports and a database file of its own. A WAL-mode database
436
- raises :class:`ValueError`, because WAL never blocks readers behind a writer.
437
-
438
- On macOS, the database directory must be writable and the filesystem must support hard links. filelock opens SQLite
439
- through a private alias of the validated database to avoid the ``/dev/fd`` lookup implicated in the kernel panic in
440
- `issue #818 <https://github.com/tox-dev/filelock/issues/818>`_. Alias creation failure raises :class:`OSError`.
437
+ requirement. Use a local filesystem the active SQLite VFS supports and a database file of its own. Two kinds of file
438
+ raise :class:`ValueError`: a database in WAL mode (SQLite's write-ahead log, which never blocks readers behind a
439
+ writer), and a database whose schema takes more than a few kilobytes to load, because the acquire timeout does not
440
+ bound that load.
441
+
442
+ On POSIX, SQLite opens the database by name. It also uses the names ``<database>-journal``, ``<database>-wal`` and
443
+ ``<database>-shm`` beside it, so a file placed under one of those names changes what SQLite does. filelock therefore
444
+ names the database directly only when no process of another account can create names in its directory: the directory
445
+ belongs to the locking account or root and is not writable by its group or by others. In any other directory, filelock
446
+ opens SQLite through a hard link (a second name for the same file) inside a ``.filelock-*`` directory that only the
447
+ locking account can read. That directory must be writable by the locking account, and the filesystem must support hard
448
+ links; when the link cannot be made, the lock raises :class:`OSError`.
449
+
450
+ Both routes assume that no process of another account can replace the database directory or any directory above it.
451
+ That holds when every directory above belongs to the locking account or root and is either not writable by others or
452
+ has the sticky bit (a directory flag that lets only a file's owner rename or remove it).
453
+
454
+ A process that can rename an entry in a directory above owns every name below it, and can put a replacement at the
455
+ database path between the lock's checks. filelock compares the name with the file it checked before it runs any SQL statement, and raises
456
+ :class:`OSError` instead of reporting the lock held, and leaves the replacement's files as they were, except that
457
+ SQLite's open creates an empty ``lock.db`` there when the name is missing, following a symlink at that name. A swap that lands after that
458
+ comparison and before SQLite's first statement still makes SQLite look up ``-journal`` and ``-wal`` under the
459
+ replacement: it deletes both, and beside a non-empty lock database it first replays the journal into that database and
460
+ unlinks the file the journal names.
461
+
462
+ On Windows the lock makes the same choice from the directory's access control list (ACL). It connects by the database
463
+ name only when the directory's owner and every entry that allows adding files, adding subdirectories or deleting entries
464
+ name the locking account, ``SYSTEM`` or ``Administrators``. Otherwise it links the database into a directory created
465
+ with an ACL that grants only those accounts, and SQLite opens the link. The filesystem must support hard links, or the
466
+ lock raises :class:`OSError`. Where it does not, as on FAT or some network shares, keep the database in a directory
467
+ other accounts cannot create files in. The per-user temporary directory and ``%LOCALAPPDATA%`` qualify,
468
+ ``C:\Windows\Temp`` and ``C:\Users\Public`` do not.
441
469
 
442
470
  .. code-block:: python
443
471
 
@@ -628,9 +656,9 @@ expired holder can resume:
628
656
  # A store that rejects a lower generation than the highest it accepted refuses an evicted holder that resumes.
629
657
  store.write(payload, fence=rw.generation)
630
658
 
631
- As with ``ReadWriteLock``, ``release()`` of a write lock from another thread raises ``RuntimeError``. ``on_compromise``
632
- runs on the hold's own heartbeat thread, so it may release, and ``release(force=True)`` and ``close()`` work from any
633
- thread.
659
+ As with ``ReadWriteLock``, ``release()`` of a write lock from another thread raises ``RuntimeError``, and so does
660
+ ``release()`` from a thread that holds no level of a shared read lock. ``on_compromise`` runs on the hold's own heartbeat
661
+ thread, so it may release, and ``release(force=True)`` and ``close()`` work from any thread.
634
662
 
635
663
  ``timeout`` and ``blocking`` set instance-wide defaults that each acquisition inherits. Passing ``None`` per call means
636
664
  "use the instance default", which is not the same as ``-1``:
@@ -745,6 +773,10 @@ time of the call rather than at construction:
745
773
  finally:
746
774
  await rw.close() # shuts down the executor it created
747
775
 
776
+ With the default ``is_singleton=True`` every wrapper on a path shares one lock, so ``close()`` ends only the holds of
777
+ tasks that acquired through that wrapper. Tasks holding through another wrapper, and synchronous ``ReadWriteLock`` users
778
+ of the same path, keep their locks.
779
+
748
780
  Low-level ``acquire_read``/``acquire_write``/``release`` methods are also available:
749
781
 
750
782
  .. code-block:: python
@@ -803,11 +835,13 @@ a reused PID can also keep a dead owner's marker in place.
803
835
  Every platform stores a process start token in the marker to guard against PID recycling: Linux uses the
804
836
  ``/proc/<pid>/stat`` start time folded with the boot id, macOS reads it through ``sysctl``, and Windows uses the
805
837
  ``GetProcessTimes`` creation time. Malformed records follow a different rule: a waiter may evict them once it has seen
806
- them unchanged for two seconds.
838
+ them unchanged for two seconds. An empty marker, which is all a ``SoftFileLock`` before 3.22 writes, is never evicted
839
+ this way; remove a leftover one with ``break_lock()``.
807
840
  That recovery path is not fail closed.
808
841
 
809
- A contender breaking a stale marker while a peer recreates it can admit a third holder, soft or strict, in a window of
810
- two syscalls; see :ref:`concepts:How does stale lock detection work across platforms?` for the details.
842
+ A contender breaks a stale marker without the lock path ever standing empty. Where it cannot (NFS, SMB and platforms
843
+ without an atomic exchange, other than Windows) it leaves the marker in place; see :ref:`concepts:How does stale lock
844
+ detection work across platforms?` for the details.
811
845
 
812
846
  ********************************
813
847
  Use fail-closed soft locks
@@ -844,13 +878,14 @@ A soft-lock owner's marker at ``work.lock`` (from ``SoftFileLock``, ``MarkerSoft
844
878
  strict acquisition like any holder, without appearing in ``lock.claims``; :attr:`lock_path_occupant
845
879
  <filelock.StrictSoftFileLock.lock_path_occupant>` describes it, with its PID and host when the marker records them. A
846
880
  file strict cannot read blocks the same way, because Windows refuses to read a marker its holder keeps open. A file it
847
- reads but cannot parse, such as the empty marker filelock before 3.22 wrote or a path a ``UnixFileLock`` truncated,
881
+ reads but cannot parse, such as the empty marker filelock before 3.22 wrote or an empty ``UnixFileLock`` lock file,
848
882
  blocks while it changes and raises :class:`SoftFileLockProtocolError <filelock.SoftFileLockProtocolError>` once it stays
849
- unchanged for two seconds, the grace a soft contender waits before evicting it. A marker whose owner on this host has
850
- exited raises the same error naming that owner, and a directory, symlink, or other node no lock writes raises it after
851
- half a second. Strict mode never removes what it found. A crashed owner on another host, or one that left no PID, cannot
852
- be told apart from a live one, so its marker blocks until an operator who has confirmed that owner is gone deletes
853
- ``work.lock``.
883
+ unchanged for two seconds, the grace a soft contender waits before evicting a malformed marker other than an empty one.
884
+
885
+ A marker whose owner on this host has exited raises the same error naming that owner, and a directory, symlink, or other
886
+ node no lock writes raises it after half a second. Strict mode never removes what it found. A crashed owner on another
887
+ host, or one that left no PID, cannot be told apart from a live one, so its marker blocks until an operator who has
888
+ confirmed that owner is gone deletes ``work.lock``.
854
889
 
855
890
  A crash can leave an intent, a held claim, or both claims for one token. Strict mode treats each claim as live because
856
891
  PID and clock checks cannot prove that another host or a recycled process has stopped using the resource. Inspect the
@@ -1310,6 +1345,10 @@ thread returns without doing anything, and the interrupted release finishes the
1310
1345
  while the interrupted code is still acquiring that lock raises :class:`RuntimeError`: the interrupted acquire cannot go
1311
1346
  on until the handler returns.
1312
1347
 
1348
+ A ``release()`` that a handler interrupts after it has started finishes releasing before the handler's exception
1349
+ propagates, so the ``with`` block above never leaves the lock held. Only a handler that fires at the very entry of
1350
+ ``release()`` leaves the hold for the next call.
1351
+
1313
1352
  *******************************
1314
1353
  Check your own lock state
1315
1354
  *******************************
@@ -1452,7 +1491,8 @@ write, seek, truncate, or set metadata through ``os`` on it, but must not close,
1452
1491
  descriptor. A recursive acquire does not call it again. If the callback raises, filelock releases the lock and
1453
1492
  re-raises.
1454
1493
 
1455
- A common use is stamping holder metadata into the lock file:
1494
+ A common use is writing holder metadata into the lock file. filelock does not empty an existing lock file, so the hook
1495
+ truncates what an earlier holder wrote:
1456
1496
 
1457
1497
  .. code-block:: python
1458
1498
 
@@ -257,3 +257,19 @@ type = [
257
257
  { directory = "doc", name = "Improved documentation", showcontent = true },
258
258
  { directory = "packaging", name = "Packaging updates", showcontent = true },
259
259
  ]
260
+
261
+ [tool.flake8-lazy]
262
+ standalone.line-length = 120
263
+ standalone.lazy-exclude-modules = [
264
+ # installs the fork-safety audit hook and register_at_fork callbacks at import
265
+ "filelock._api",
266
+ # installs its sqlite audit hook and fork handler at import, and must fail at import without sqlite3 so the package
267
+ # __getattr__ resolves ReadWriteLock and AsyncReadWriteLock to None
268
+ "filelock._read_write",
269
+ # a marker released from a finalizer at interpreter exit unlinks through it, and a first import then fails
270
+ "filelock._windows",
271
+ # registers its atexit cleanup at import
272
+ "filelock._soft_rw._sync",
273
+ # a Python built without it must fail at import, as for filelock._read_write
274
+ "sqlite3",
275
+ ]