API#

A platform independent file lock that supports the with-statement.

filelock.__version__#: version of the project as a string

class filelock.AcquireReturnProxy(lock)[source]#

Bases: object

A context-aware object that will release the lock file when exiting.

class filelock.BaseFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, is_singleton=False)[source]#

Bases: ABC, ContextDecorator

Abstract base class for a file lock object.

is_thread_local()[source]#

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

property is_singleton#

Returns:: a flag indicating if this lock is singleton or not

property lock_file#

Returns:: path to the lock file

property timeout#

Returns:: the default timeout value, in seconds

New in version 2.0.0.

property mode#

Returns:: the file permissions for the lockfile

property is_locked#

Returns:: 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#

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

acquire(timeout=None, poll_interval=0.05, *, poll_intervall=None, blocking=True)[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) – interval of trying to acquire the lock file
poll_intervall (float | None) – deprecated, kept for backwards compatibility, use poll_interval instead
blocking (bool) – 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.

Raises:

Timeout – if fails to acquire lock within the timeout period

Return type:

AcquireReturnProxy

Returns:

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

# 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]#

Releases the file lock. Please note, that the lock is only completely released, if the lock counter is 0. Also note, that the lock file itself is not automatically deleted.

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.SoftFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, is_singleton=False)[source]#

Bases: BaseFileLock

Simply watches the existence of the lock file.

exception filelock.Timeout(lock_file)[source]#

Bases: TimeoutError

Raised when the lock could not be acquired in timeout seconds.

property lock_file#

Returns:: The path of the file lock.

class filelock.UnixFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, is_singleton=False)[source]#

Bases: BaseFileLock

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

class filelock.WindowsFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, is_singleton=False)[source]#

Bases: BaseFileLock

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