zc.lockfile

Warnings

• breaking In version 2.0, `zc.lockfile.LockFile` changed from an old-style to a new-style class. Additionally, `SimpleLockFile` was extracted, altering implicit behavior for writing to the lock file. Code relying on old-style class introspection or the previous implicit lock file writing mechanism will break.
  Fix: Update code to use new-style class patterns and explicitly handle lock file content if custom writing behavior was implicitly relied upon.
• breaking Version 4.0 replaced the `pkg_resources` namespace with PEP 420 native namespace packaging. This change affects how the package is discovered and imported in certain environments, particularly complex Zope setups or systems with custom package loaders.
  Fix: Ensure your packaging environment and tools are compatible with PEP 420 native namespaces. Direct `from zc.lockfile import LockFile` imports should generally be unaffected.
• gotcha Failing to call `lock.close()` will leave the lock file on the filesystem. This prevents other processes from acquiring the lock indefinitely, even if the original holding process terminates or crashes, leading to resource leaks or deadlocks.
  Fix: Always ensure `lock.close()` is called, typically within a `try...finally` block, to guarantee the lock is released. `zc.lockfile.LockFile` does not implement the context manager protocol, so a `with` statement cannot be used directly.
• gotcha The `lock.close()` method releases the lock but *does not remove the lock file* from the filesystem. The file persists by design. If the lock file is no longer needed after the lock is released, it must be explicitly removed.
  Fix: If lock files should not persist, add an `os.remove(lock_file_path)` call after `lock.close()` (and potentially wrap it in a `try...except OSError` block for robustness).
• gotcha In containerized environments (e.g., Docker), process IDs (PIDs) can be misleading or identical across different containers on the same host. Relying solely on PIDs within lock files for debugging or identification can be problematic.
  Fix: Leverage the `zc.lockfile` feature to include hostname (which often corresponds to container ID) in the lock file to aid in identifying the lock's origin in distributed or containerized setups.

Install

• pip install zc.lockfile Install latest version

Imports

• LockFile

  from zc.lockfile import LockFile

• LockError

  from zc.lockfile import LockError

Quickstart

This quickstart demonstrates how to acquire and release an inter-process lock using `zc.lockfile.LockFile`. It includes proper error handling for when a lock cannot be acquired and ensures the lock is released in a `finally` block to prevent deadlocks. It also shows how to optionally remove the lock file after use.

import zc.lockfile
import os
import time

lock_file_path = "my_app.lock"
lock = None

try:
    # Attempt to acquire the lock
    lock = zc.lockfile.LockFile(lock_file_path)
    print(f"Process {os.getpid()}: Acquired lock on {lock_file_path}")

    # Simulate critical section work
    print(f"Process {os.getpid()}: Doing some critical work...")
    time.sleep(2) # Simulate work
    print(f"Process {os.getpid()}: Critical work complete.")

except zc.lockfile.LockError:
    print(f"Process {os.getpid()}: Could not acquire lock on {lock_file_path}. Another process holds it.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if lock:
        lock.close()
        print(f"Process {os.getpid()}: Released lock on {lock_file_path}")
        # Optionally remove the lock file if it should not persist
        # In a real application, consider if other processes might still need to check for its existence
        try:
            os.remove(lock_file_path)
            print(f"Process {os.getpid()}: Removed lock file {lock_file_path}")
        except OSError as e:
            print(f"Process {os.getpid()}: Error removing lock file {lock_file_path}: {e}")