Upgrading filelock 2 to 3
Breaking2.0.13 → 3.32.7Breaking1Security7Platform1New21Changed35Fixed85Other87
BreakingUpgrade verdict
1 breaking change and a platform requirement change and 6 security fixes.
In plain terms
- If you pass conflicting timeout and mode options to the singleton lock, it now fails with an error instead of silently proceeding.
- The package now works on Termux and Android.
- Fails safe on transient heartbeat errors in soft locks.
- Reading the lock marker file no longer blocks, so a malicious FIFO placed by an attacker cannot hang the process.
Must act Top 5 of 8 that need code or config changes
Requires Python >=3.10 from 3.20.0 (none stated before).
What you must change
Breaking1
Raises an error when incompatible singleton timeout and mode arguments are used.
Security6
Fails safe on transient heartbeat errors in soft locks.
Opens marker reads non-blocking to refuse attacker-placed FIFO.
Hardens stale-lock breaking and self-heals malformed locks in the soft lock implementation.
Refuses to follow symlinks when reading the lock file in the soft lock implementation.
filelock Time-of-Check-Time-of-Use (TOCTOU) Symlink Vulnerability in SoftFileLock
SoftFileLockMedium · CVSS 5.3Fixes CVE-2025-68146, a TOCTOU symlink vulnerability in lock file creation.
Medium · CVSS 6.3Platform1
Adds support for Termux/Android platforms.
API changes
Generated by DepDelta from published Python source. Not mixed with prose notes.
- removed:
class BaseFileLock(object) - removed:
class SoftFileLock(BaseFileLock) - removed:
class Timeout(TimeoutError) - removed:
class UnixFileLock(BaseFileLock) - removed:
class WindowsFileLock(BaseFileLock) - removed:
constructor BaseFileLock(lock_file, timeout=…) - removed:
constructor Timeout(lock_file) - removed:
method BaseFileLock.acquire(timeout=…, poll_intervall=…) - removed:
method BaseFileLock.release(force=…) - removed:
property BaseFileLock.is_locked - removed:
property BaseFileLock.lock_file - removed:
property BaseFileLock.timeout - added:
export AcquireReturnProxy - added:
export AsyncAcquireReadWriteReturnProxy - added:
export AsyncAcquireReturnProxy - added:
export AsyncAcquireSoftReadWriteReturnProxy - added:
export AsyncReadWriteLock - added:
export AsyncSoftFileLease - added:
export AsyncSoftFileLock - added:
export AsyncSoftReadWriteLock - added:
export AsyncStrictSoftFileLock - added:
export AsyncUnixFileLock - added:
export AsyncWindowsFileLock - added:
export BaseAsyncFileLock - added:
export BaseFileLock - added:
export CloseErrorPolicy - added:
export ContextErrorPolicy - added:
export LeaseCompromise - added:
export LeaseSettingsMismatch - added:
export LockOptions - added:
export MarkerSoftFileLock - added:
export OwnerRecord - added:
export ReadWriteLock - added:
export SoftFileLease - added:
export SoftFileLock - added:
export SoftFileLockLifetimeWarning - added:
export SoftFileLockProtocolError - added:
export SoftReadWriteLock - added:
export StrictSoftFileClaim - added:
export StrictSoftFileClaimState - added:
export StrictSoftFileLock - added:
export Timeout - added:
export UnixFileLock - added:
export WindowsFileLock - added:
export lock_descriptor - added:
export unlock_descriptor - added:
variable AsyncAcquireReadWriteReturnProxy - added:
variable AsyncFileLock - added:
variable AsyncReadWriteLock - added:
variable ReadWriteLock - added:
variable __version__: Final[str]
- added:
async method BaseAsyncFileLock.acquire(timeout: float | None=…, poll_interval: float | None=…, *, blocking: bool | None=…, cancel_check: Callable[[], bool] | None=…) -> AsyncAcquireReturnProxy - added:
async method BaseAsyncFileLock.release(force: bool=…) -> None - added:
class AsyncAcquireReturnProxy - added:
class AsyncSoftFileLease(SoftFileLease, BaseAsyncFileLock) - added:
class AsyncSoftFileLock(SoftFileLock, BaseAsyncFileLock) - added:
class AsyncStrictSoftFileLock(StrictSoftFileLock, BaseAsyncFileLock) - added:
class AsyncUnixFileLock(UnixFileLock, BaseAsyncFileLock) - added:
class AsyncWindowsFileLock(WindowsFileLock, BaseAsyncFileLock) - added:
class BaseAsyncFileLock(BaseFileLock) - added:
constructor AsyncAcquireReturnProxy(lock: BaseAsyncFileLock) -> None - added:
constructor BaseAsyncFileLock(lock_file: str | os.PathLike[str], timeout: float=…, mode: int=…, thread_local: bool=…, *, blocking: bool=…, is_singleton: bool=…, poll_interval: float=…, lifetime: float | None=…, context_error_policy: ContextErrorPolicy=…, close_error_policy: CloseErrorPolicy=…, fallback_to_soft: bool=…, preserve_lock_file: bool=…, on_acquired: Callable[[int], None] | None=…, loop:… - added:
property BaseAsyncFileLock.executor -> futures.Executor | None - added:
property BaseAsyncFileLock.loop -> asyncio.AbstractEventLoop | None - added:
property BaseAsyncFileLock.run_in_executor -> bool
- added:
variable __commit_id__ - added:
variable __commit_id__: str | None - added:
variable __version__ - added:
variable __version__: str - added:
variable __version_tuple__ - added:
variable __version_tuple__: tuple[int | str, ...] - added:
variable commit_id - added:
variable commit_id: str | None - added:
variable version - added:
variable version: str - added:
variable version_tuple - added:
variable version_tuple: tuple[int | str, ...]