lockfile (deprecated PyPI package)

Warnings

• breaking The API underwent significant changes in version 0.9. Classes like `LinkFileLock`, `MkdirFileLock`, and `SQLiteFileLock` were moved from the top-level `lockfile` module into their own submodules (e.g., `lockfile.linklockfile.LinkFileLock`). The class naming convention also reversed, changing from `SomethingFileLock` to `SomethingLockFile`.
  Fix: Update import paths and class names to reflect the new structure (e.g., `from lockfile.linklockfile import LinkLockFile`). For backward compatibility, the old module-level definitions were retained until the 1.0 release, but direct submodule imports are recommended.
• deprecated This `lockfile` package is officially deprecated and has not been updated since November 2015. It is highly recommended to migrate to actively maintained alternatives.
  Fix: Migrate to modern, actively maintained file locking libraries such as `fasteners` or `oslo.concurrency`.
• gotcha The `LockFile` implementation relies on the atomic nature of `link()` on Unix and `mkdir()` on Windows. While providing cross-platform compatibility, this mechanism might not be suitable for all network file systems (e.g., NFS), where atomic guarantees can be an issue.
  Fix: For applications requiring robust locking over network file systems, consider alternatives explicitly designed for such environments or more advanced coordination primitives. For instance, `flufl.lock` is noted as NFS-safe for POSIX systems.
• gotcha Calling `release()` on an already unlocked `LockFile` instance will raise a `LockError`. This can occur if the lock is released prematurely or if there's a logic error in handling lock states, particularly in complex multi-process scenarios or when mixing explicit `acquire`/`release` with context managers.
  Fix: Ensure `release()` is only called when the lock is known to be held. Using the `with` statement for `LockFile` instances is the safest approach, as it automatically handles acquisition and release, reducing the chance of `LockError` from manual management. If manual control is necessary, check `lock.is_locked()` before calling `release()`.

Install

• pip install lockfile Install deprecated version

Imports

• LockFile

  from lockfile import LockFile

  While 'import lockfile' works, accessing LockFile directly from the top-level package is the common pattern.
• LinkFileLock

  from lockfile.linklockfile import LinkFileLock

  As of version 0.9, classes like LinkFileLock were moved into submodules, though the old top-level import was retained for backward compatibility until 1.0.
• MkdirFileLock

  from lockfile.mkdirlockfile import MkdirFileLock

  Similar to LinkFileLock, MkdirFileLock was moved to a submodule in version 0.9.

Quickstart

This quickstart demonstrates how to acquire and release a file lock using `LockFile`. It includes a timeout mechanism and proper error handling for when the lock cannot be acquired or is already held. The `os.environ.get` is used for the lock file path for potential external configuration.

from lockfile import LockFile
import os

lock_path = os.environ.get('LOCK_FILE_PATH', 'my_app.lock')
lock = LockFile(lock_path)

try:
    print(f"Attempting to acquire lock for {lock.path}...")
    lock.acquire(timeout=10) # Wait up to 10 seconds
    print(f"Lock acquired for {lock.path}. Performing critical operation...")
    # Simulate work
    with open('shared_resource.txt', 'a') as f:
        f.write('Critical operation performed.\n')
    print("Critical operation complete.")
except lock.AlreadyLocked: # Using lock.AlreadyLocked for consistency across versions
    print(f"Could not acquire lock for {lock.path}: Already locked by another process.")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if lock.is_locked():
        lock.release()
        print(f"Lock released for {lock.path}.")
    else:
        print(f"Lock was not acquired, so no release needed for {lock.path}.")