API Reference ¶

write_lock(timeout=None, *, blocking=None)[source]¶

Async context manager that acquires and releases an exclusive write lock.

Falls back to instance defaults for timeout and blocking when None.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Return type:

AsyncAcquireReadWriteReturnProxy

async acquire_read(timeout=-1, *, blocking=True)[source]¶

Acquire a shared read lock.

See ReadWriteLock.acquire_read() for full semantics.

Parameters:

timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable

Return type:

Returns:

a proxy that can be used as an async context manager to release the lock

Raises:

RuntimeError – if a write lock is already held on this instance
Timeout – if the lock cannot be acquired within timeout seconds

async acquire_write(timeout=-1, *, blocking=True)[source]¶

Acquire an exclusive write lock.

See ReadWriteLock.acquire_write() for full semantics.

Parameters:

timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable

Return type:

AsyncAcquireReadWriteReturnProxy

Returns:

a proxy that can be used as an async context manager to release the lock

Raises:

RuntimeError – if a read lock is already held, or a write lock is held by a different thread
Timeout – if the lock cannot be acquired within timeout seconds

async release(*, force=False)[source]¶

Release one level of the current lock.

See ReadWriteLock.release() for full semantics.

Parameters:: force (bool) – if True, release the lock completely regardless of the current lock level
Raises:: RuntimeError – if no lock is currently held and force is False
Return type:: None

async close()[source]¶

Release the lock (if held) and close the underlying SQLite connection.

After calling this method, the lock instance is no longer usable.

Return type:: None

class filelock.AsyncSoftFileLock(lock_file, timeout=-1, mode=-1, thread_local=False, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False, loop=None, run_in_executor=True, executor=None)[source]¶

Bases: SoftFileLock, BaseAsyncFileLock

Simply watches the existence of the lock file.

class filelock.AsyncSoftReadWriteLock(lock_file, timeout=-1, *, blocking=True, is_singleton=True, heartbeat_interval=30.0, stale_threshold=None, poll_interval=0.25, loop=None, executor=None)[source]¶

Bases: object

Async wrapper around SoftReadWriteLock for asyncio applications.

The sync class’s blocking filesystem operations run on a thread pool via loop.run_in_executor(). The underlying SoftReadWriteLock handles reentrancy, upgrade/downgrade rules, fork handling, heartbeat and TTL stale detection, and singleton behavior.

Parameters:

lock_file (str | PathLike[str]) – path to the lock file; sidecar state/write/readers live next to it
timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately on contention
is_singleton (bool) – if True, reuse existing SoftReadWriteLock instances per resolved path
heartbeat_interval (float) – seconds between heartbeat refreshes; default 30 s
stale_threshold (float | None) – seconds of mtime inactivity before a marker is stale; defaults to 3 * heartbeat_interval
poll_interval (float) – seconds between acquire retries under contention; default 0.25 s
loop (AbstractEventLoop | None) – event loop for run_in_executor; None uses the running loop
executor (Executor | None) – executor for run_in_executor; None uses the default executor

Added in version 3.27.0.

property lock_file¶: The path to the lock file passed to the constructor.

property timeout¶: The default timeout applied when acquire_read / acquire_write is called without one.

property blocking¶: Whether acquire_* defaults to blocking; False makes contention raise immediately.

property loop¶: The event loop used for run_in_executor, or None for the running loop.

property executor¶: The executor used for run_in_executor, or None for the default executor.

read_lock(timeout=None, *, blocking=None)[source]¶

Async context manager that acquires and releases a shared read lock.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Raises:

RuntimeError – if a write lock is already held on this instance
Timeout – if the lock cannot be acquired within timeout seconds

Return type:

write_lock(timeout=None, *, blocking=None)[source]¶

Async context manager that acquires and releases an exclusive write lock.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Raises:

RuntimeError – if a read lock is already held, or a write lock is held by a different thread
Timeout – if the lock cannot be acquired within timeout seconds

Return type:

AsyncAcquireSoftReadWriteReturnProxy

async acquire_read(timeout=None, *, blocking=None)[source]¶

Acquire a shared read lock.

See SoftReadWriteLock.acquire_read() for reentrancy / upgrade / fork semantics. The blocking work runs inside run_in_executor so other coroutines on the same loop keep progressing while this call waits.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Return type:

Returns:

a proxy usable as an async context manager to release the lock

Raises:

RuntimeError – if a write lock is already held, if this instance was invalidated by os.fork(), or if close() was called
Timeout – if the lock cannot be acquired within timeout seconds

async acquire_write(timeout=None, *, blocking=None)[source]¶

Acquire an exclusive write lock.

See SoftReadWriteLock.acquire_write() for the two-phase writer-preferring semantics. The blocking work runs inside run_in_executor.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Return type:

AsyncAcquireSoftReadWriteReturnProxy

Returns:

a proxy usable as an async context manager to release the lock

Raises:

RuntimeError – if a read lock is already held, if a write lock is held by a different thread, if this instance was invalidated by os.fork(), or if close() was called
Timeout – if the lock cannot be acquired within timeout seconds

async release(*, force=False)[source]¶

Release one level of the current lock.

Parameters:: force (bool) – if True, release the lock completely regardless of the current lock level
Raises:: RuntimeError – if no lock is currently held and force is False
Return type:: None

async close()[source]¶

Release any held lock and release the underlying filesystem resources. Idempotent.

Return type:: None

class filelock.AsyncUnixFileLock(lock_file, timeout=-1, mode=-1, thread_local=False, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False, loop=None, run_in_executor=True, executor=None)[source]¶

Bases: UnixFileLock, BaseAsyncFileLock

Uses the fcntl.flock() to hard lock the lock file on unix systems.

class filelock.AsyncWindowsFileLock(lock_file, timeout=-1, mode=-1, thread_local=False, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False, loop=None, run_in_executor=True, executor=None)[source]¶

Bases: WindowsFileLock, BaseAsyncFileLock

Uses the msvcrt.locking() to hard lock the lock file on windows systems.

class filelock.BaseAsyncFileLock(lock_file, timeout=-1, mode=-1, thread_local=False, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False, loop=None, run_in_executor=True, executor=None)[source]¶

Bases: BaseFileLock

Base class for asynchronous file locks.

Added in version 3.15.0.

property run_in_executor¶: Whether run in executor.

property executor¶: The executor.

property loop¶: The event loop.

async acquire(timeout=None, poll_interval=None, *, blocking=None, cancel_check=None)[source]¶

Try to acquire the file lock.

Parameters:

timeout (float | None) – maximum wait time for acquiring the lock, None means use the default timeout is and if timeout < 0, there is no timeout and this method will block until the lock could be acquired
poll_interval (float | None) – interval of trying to acquire the lock file, None means use the default poll_interval
blocking (bool | None) – defaults to True. If False, function will return immediately if it cannot obtain a lock on the first attempt. Otherwise, this method will block until the timeout expires or the lock is acquired.
cancel_check (Callable[[], bool] | None) – a callable returning True when the acquisition should be canceled. Checked on each poll iteration. When triggered, raises Timeout just like an expired timeout.

Return type:

AsyncAcquireReturnProxy

Returns:

a context object that will unlock the file when the context is exited

Raises:

Timeout – if fails to acquire lock within the timeout period

# You can use this method in the context manager (recommended)
with lock.acquire():
    pass

# Or use an equivalent try-finally construct:
lock.acquire()
try:
    pass
finally:
    lock.release()

async release(force=False)[source]¶

Release the file lock. The lock is only completely released when the lock counter reaches 0. The lock file itself may be deleted automatically, the behavior is platform-specific.

Parameters:: force (bool) – If true, the lock counter is ignored and the lock is released in every case.
Return type:: None

class filelock.BaseFileLock(lock_file, timeout=-1, mode=-1, thread_local=True, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False)[source]¶

Bases: ContextDecorator

Abstract base class for a file lock object.

Provides a reentrant, cross-process exclusive lock backed by OS-level primitives. Subclasses implement the actual locking mechanism (UnixFileLock, WindowsFileLock, SoftFileLock).

is_thread_local()[source]¶

Return type:: bool
Returns:: a flag indicating if this lock is thread local or not

property is_singleton¶: A flag indicating if this lock is singleton or not.

Added in version 3.13.0.

property context_error_policy¶: How a context manager reconciles a body failure with a release failure on exit.

Added in version 3.27.0.

property close_error_policy¶: What a native lock does with an os.close failure after the OS unlock committed.

Added in version 3.27.0.

property fallback_to_soft¶

Whether a FileLock falls back to SoftFileLock when the filesystem lacks flock.

Only UnixFileLock acts on it: when False an ENOSYS from flock propagates instead of switching to existence-lock semantics.

Added in version 3.27.0.

property preserve_lock_file¶

Whether filelock promises not to unlink the lock pathname on release.

When True, Windows skips its post-release unlink and Unix refuses the ENOSYS soft fallback. SoftFileLock rejects True because unlinking its marker is how it releases.

Added in version 3.27.0.

property lock_file¶: Path to the lock file.

property timeout¶: The default timeout value, in seconds.

Added in version 2.0.0.

property blocking¶: Whether the locking is blocking or not.

Added in version 3.14.0.

property poll_interval¶: The default polling interval, in seconds.

Added in version 3.24.0.

property lifetime¶: The lock lifetime in seconds, or None if the lock never expires.

Added in version 3.24.0.

property mode¶: The file permissions for the lockfile.

property has_explicit_mode¶: Whether the file permissions were explicitly set.

property is_locked¶: A boolean indicating if the lock file is holding the lock currently.

Changed in version 2.0.0: This was previously a method and is now a property.

property lock_counter¶: The number of times this lock has been acquired (but not yet released).

acquire(timeout=None, poll_interval=None, *, poll_intervall=None, blocking=None, cancel_check=None)[source]¶

Try to acquire the file lock.

Parameters:

timeout (float | None) – maximum wait time for acquiring the lock, None means use the default timeout is and if timeout < 0, there is no timeout and this method will block until the lock could be acquired
poll_interval (float | None) – interval of trying to acquire the lock file, None means use the default poll_interval
poll_intervall (float | None) – deprecated, kept for backwards compatibility, use poll_interval instead
blocking (bool | None) – defaults to True. If False, function will return immediately if it cannot obtain a lock on the first attempt. Otherwise, this method will block until the timeout expires or the lock is acquired.
cancel_check (Callable[[], bool] | None) – a callable returning True when the acquisition should be canceled. Checked on each poll iteration. When triggered, raises Timeout just like an expired timeout.

Return type:

Returns:

a context object that will unlock the file when the context is exited

Raises:

Timeout – if fails to acquire lock within the timeout period

# You can use this method in the context manager (recommended)
with lock.acquire():
    pass

# Or use an equivalent try-finally construct:
lock.acquire()
try:
    pass
finally:
    lock.release()

Changed in version 2.0.0: This method returns now a proxy object instead of self, so that it can be used in a with statement without side effects.

release(force=False)[source]¶

Release the file lock. The lock is only completely released when the lock counter reaches 0. The lock file itself may be deleted automatically, the behavior is platform-specific.

Parameters:: force (bool) – If true, the lock counter is ignored and the lock is released in every case.
Return type:: None

filelock.FileLock¶: Alias for the lock, which should be used for the current platform.

class filelock.ReadWriteLock(lock_file, timeout=-1, *, blocking=True, is_singleton=True)[source]¶

Bases: object

Cross-process read-write lock backed by SQLite.

Allows concurrent shared readers or a single exclusive writer. The lock is reentrant within the same mode (multiple acquire_read calls nest, as do multiple acquire_write calls from the same thread), but upgrading from read to write or downgrading from write to read raises RuntimeError. Write locks are pinned to the thread that acquired them.

By default, is_singleton=True: calling ReadWriteLock(path) with the same resolved path returns the same instance. The lock file must use a .db extension (SQLite database).

Parameters:

lock_file (str | PathLike[str]) – path to the SQLite database file used as the lock
timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable
is_singleton (bool) – if True, reuse existing instances for the same resolved path

Added in version 3.21.0.

classmethod get_lock(lock_file, timeout=-1, *, blocking=True)[source]¶

Return the singleton ReadWriteLock for lock_file.

Parameters:

lock_file (str | PathLike[str]) – path to the SQLite database file used as the lock
timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable

Return type:

ReadWriteLock

Returns:

the singleton lock instance

Raises:

ValueError – if an instance already exists for this path with different timeout or blocking values

acquire_read(timeout=-1, *, blocking=True)[source]¶

Acquire a shared read lock.

If this instance already holds a read lock, the lock level is incremented (reentrant). Attempting to acquire a read lock while holding a write lock raises RuntimeError (downgrade not allowed).

Parameters:

timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable

Return type:

Returns:

a proxy that can be used as a context manager to release the lock

Raises:

RuntimeError – if a write lock is already held on this instance
Timeout – if the lock cannot be acquired within timeout seconds

acquire_write(timeout=-1, *, blocking=True)[source]¶

Acquire an exclusive write lock.

If this instance already holds a write lock from the same thread, the lock level is incremented (reentrant). Attempting to acquire a write lock while holding a read lock raises RuntimeError (upgrade not allowed). Write locks are pinned to the acquiring thread: a different thread trying to re-enter also raises RuntimeError.

Parameters:

timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately when the lock is unavailable

Return type:

Returns:

a proxy that can be used as a context manager to release the lock

Raises:

RuntimeError – if a read lock is already held, or a write lock is held by a different thread
Timeout – if the lock cannot be acquired within timeout seconds

read_lock(timeout=None, *, blocking=None)[source]¶

Context manager that acquires and releases a shared read lock.

Falls back to instance defaults for timeout and blocking when None.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Return type:

write_lock(timeout=None, *, blocking=None)[source]¶

Context manager that acquires and releases an exclusive write lock.

Falls back to instance defaults for timeout and blocking when None.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Return type:

release(*, force=False)[source]¶

Release one level of the current lock.

When the lock level reaches zero the underlying SQLite transaction is rolled back, releasing the database lock.

Parameters:: force (bool) – if True, release the lock completely regardless of the current lock level
Raises:: RuntimeError – if no lock is currently held and force is False
Return type:: None

close()[source]¶

Release the lock (if held) and close the underlying SQLite connection.

After calling this method, the lock instance is no longer usable.

Return type:: None

class filelock.SoftFileLock(lock_file, timeout=-1, mode=-1, thread_local=True, *, blocking=True, is_singleton=False, poll_interval=0.05, lifetime=None, context_error_policy='chain', close_error_policy='default', fallback_to_soft=True, preserve_lock_file=False)[source]¶

Bases: BaseFileLock

Portable file lock based on file existence.

Unlike UnixFileLock and WindowsFileLock, this lock does not use OS-level locking primitives. Instead, it creates the lock file with O_CREAT | O_EXCL and treats its existence as the lock indicator. This makes it work on any filesystem but leaves stale lock files behind if the process crashes without releasing the lock.

To mitigate stale locks, the lock file contains the PID and hostname of the holding process. On contention, if the holder is on the same host and its PID no longer exists, the stale lock is broken automatically.

property pid¶

The PID of the process holding this lock, read from the lock file.

Returns:: the PID as an integer, or None if the lock file does not exist or cannot be parsed

property is_lock_held_by_us¶

Whether this lock is held by the current process.

Returns:: True if the lock file exists and names the current process’s PID and hostname

break_lock()[source]¶

Forcibly break the lock by removing the lock file, regardless of who holds it.

Return type:: None

class filelock.SoftReadWriteLock(lock_file, timeout=-1, *, blocking=True, is_singleton=True, heartbeat_interval=30.0, stale_threshold=None, poll_interval=0.25)[source]¶

Bases: object

Cross-process and cross-host reader/writer lock built on SoftFileLock primitives.

Use this class instead of ReadWriteLock when the lock file lives on a network filesystem (NFS, Lustre with -o flock, HPC cluster shared storage). ReadWriteLock is backed by SQLite and cannot run on NFS because SQLite’s fcntl locking is unreliable there.

Layout on disk for a lock at foo.lock:

foo.lock.state — a SoftFileLock taken only during state transitions (microseconds).
foo.lock.write — writer marker; its presence means a writer is claiming or holding the lock.
foo.lock.readers/<host>.<pid>.<uuid> — one file per reader.

Each marker stores a random token (secrets.token_hex(16)), the holder’s pid, and the holder’s hostname. A daemon heartbeat thread refreshes mtime on every held marker. A marker whose mtime has not advanced in stale_threshold seconds may be evicted by any process on any host, giving correct behavior when a compute node crashes with a lock held.

Writer acquire is two-phase and writer-preferring: phase 1 claims .write (blocking any new reader), phase 2 waits for existing readers to drain. Writer starvation is impossible.

Reentrancy, upgrade/downgrade rules, thread pinning, and singleton caching by resolved path match ReadWriteLock.

Forking while holding a lock invalidates the inherited instance in the child so the child cannot double-own the lock with its parent; release() on a fork-invalidated instance is a no-op, and the child must re-acquire if it needs a lock.

Trust boundary: protects against same-UID non-cooperating processes (one host or cross-host) and same-host different-UID users via 0o600 / 0o700 permissions. Does not protect against root compromise, NTP tampering on same-UID cross-host nodes, or multi-tenant mounts where hostile co-tenants share the UID.

Parameters:

lock_file (str | PathLike[str]) – path to the lock file; sidecar state/write/readers live next to it
timeout (float) – maximum wait time in seconds; -1 means block indefinitely
blocking (bool) – if False, raise Timeout immediately on contention
is_singleton (bool) – if True, reuse existing instances for the same resolved path
heartbeat_interval (float) – seconds between heartbeat refreshes; default 30 s
stale_threshold (float | None) – seconds of mtime inactivity before a marker is stale; defaults to 3 * heartbeat_interval, matching etcd’s LeaseKeepAlive convention
poll_interval (float) – seconds between acquire retries under contention; default 0.25 s

Added in version 3.27.0.

read_lock(timeout=None, *, blocking=None)[source]¶

Context manager that acquires and releases a shared read lock.

Falls back to instance defaults for timeout and blocking when None.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Raises:

RuntimeError – if a write lock is already held on this instance
Timeout – if the lock cannot be acquired within timeout seconds

Return type:

write_lock(timeout=None, *, blocking=None)[source]¶

Context manager that acquires and releases an exclusive write lock.

Falls back to instance defaults for timeout and blocking when None.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default
blocking (bool | None) – if False, raise Timeout immediately; None uses the instance default

Raises:

RuntimeError – if a read lock is already held, or a write lock is held by a different thread
Timeout – if the lock cannot be acquired within timeout seconds

Return type:

acquire_read(timeout=None, *, blocking=None)[source]¶

Acquire a shared read lock.

If this instance already holds a read lock, the lock level is incremented (reentrant). Attempting to acquire a read lock while holding a write lock raises RuntimeError (downgrade not allowed). On the 0→1 transition a daemon heartbeat thread is started that refreshes the reader marker’s mtime every heartbeat_interval seconds so peers on other hosts do not evict the marker as stale.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default; -1 means block indefinitely
blocking (bool | None) – if False, raise Timeout immediately when the lock is unavailable; None uses the instance default

Return type:

Returns:

a proxy that can be used as a context manager to release the lock

Raises:

RuntimeError – if a write lock is already held on this instance, if this instance was invalidated by os.fork(), or if close() was called
Timeout – if the lock cannot be acquired within timeout seconds

acquire_write(timeout=None, *, blocking=None)[source]¶

Acquire an exclusive write lock.

Writer acquisition runs in two phases. Phase 1 atomically claims <path>.write via O_CREAT | O_EXCL, which immediately blocks any new reader on any host. Phase 2 waits for existing readers to drain. Writer starvation is impossible: new readers see <path>.write during phase 2 and wait behind the pending writer.

Parameters:

timeout (float | None) – maximum wait time in seconds, or None to use the instance default; -1 means block indefinitely
blocking (bool | None) – if False, raise Timeout immediately when the lock is unavailable; None uses the instance default

Return type: