API

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

filelock.__version__

version of the project as a string

class filelock.AcquireReturnProxy(lock)

Bases: object

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

class filelock.AsyncAcquireReturnProxy(lock)

Bases: object

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

filelock.AsyncFileLock

alias of AsyncUnixFileLock

class filelock.AsyncSoftFileLock(lock_file, timeout=-1, mode=420, thread_local=False, *, blocking=True, is_singleton=False, loop=None, run_in_executor=True, executor=None)

Bases: SoftFileLock, BaseAsyncFileLock

Simply watches the existence of the lock file.

class filelock.AsyncUnixFileLock(lock_file, timeout=-1, mode=420, thread_local=False, *, blocking=True, is_singleton=False, loop=None, run_in_executor=True, executor=None)

Bases: UnixFileLock, BaseAsyncFileLock

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

class filelock.AsyncWindowsFileLock(lock_file, timeout=-1, mode=420, thread_local=False, *, blocking=True, is_singleton=False, loop=None, run_in_executor=True, executor=None)

Bases: WindowsFileLock, BaseAsyncFileLock

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

class filelock.BaseAsyncFileLock(lock_file, timeout=-1, mode=420, thread_local=False, *, blocking=True, is_singleton=False, loop=None, run_in_executor=True, executor=None)

Bases: BaseFileLock

Base class for asynchronous file locks.

property run_in_executor

::return: whether run in executor.

Return type:

bool

property executor

::return: the executor.

Return type:

Executor | None

property loop

::return: the event loop.

Return type:

AbstractEventLoop | None

async acquire(timeout=None, poll_interval=0.05, *, blocking=None)

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

• 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.

Raises:

Timeout – if fails to acquire lock within the timeout period

Return type:

AsyncAcquireReturnProxy

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()

async release(force=False)

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

class filelock.BaseFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, blocking=True, is_singleton=False)

Bases: ContextDecorator

Abstract base class for a file lock object.

is_thread_local()

Return type:

bool

Returns:

a flag indicating if this lock is thread local or not

property is_singleton

Return type:

bool

Returns:

a flag indicating if this lock is singleton or not

property lock_file

Return type:

str

Returns:

path to the lock file

property timeout

Return type:

float

Returns:

the default timeout value, in seconds

Added in version 2.0.0.

property blocking

Return type:

bool

Returns:

whether the locking is blocking or not

property mode

Return type:

int

Returns:

the file permissions for the lockfile

property is_locked

Return type:

bool

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

Return type:

int

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=None)

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 | 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.

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)

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, *, blocking=True, is_singleton=False)

Bases: BaseFileLock

Simply watches the existence of the lock file.

exception filelock.Timeout(lock_file)

Bases: TimeoutError

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

property lock_file

Return type:

str

Returns:

The path of the file lock.

class filelock.UnixFileLock(lock_file, timeout=-1, mode=420, thread_local=True, *, blocking=True, is_singleton=False)

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, *, blocking=True, is_singleton=False)

Bases: BaseFileLock

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