zc-lockfile

library4.0pypypi✓ verified 23d ago

The zc.lockfile package provides a basic, portable implementation of interprocess locks using file-locking primitives. It is not specifically for locking files themselves, but rather for providing general-purpose interprocess locks with a file-based mechanism. Currently at version 4.0, the library is actively maintained with updates primarily focused on Python version compatibility and bug fixes.

serialization

pip install zc.lockfile

github ↗package ↗

INSTALL

IMPORT

SIG · ZC-LOCKFILE

zc-lockfile

serializationpythonv4.0

Install

1.8s avg

Import

19ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.018s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.020s · 18MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LockFile

✓ from zc.lockfile import LockFile

LockError

✓ from zc.lockfile import LockError

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}")

Debug

Known issues

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

affects: 2.0+

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

affects: 4.0+

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

affects: All

gotchaThe `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).

affects: All

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

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'zc.lockfile'

The zc.lockfile package has not been installed in the current Python environment.

fix

pip install zc.lockfile

zc.lockfile.LockError: Couldn't create lock file

The system failed to acquire the lock because the lock file already exists and is held by another process, or it was not properly cleaned up after a previous crash.

fix

Ensure locks are always released using a 'with' statement or 'try...finally' block, or manually remove stale lock files if certain they are not in use. Example: `with LockFile('my.lock'): # critical section`

AttributeError: module 'zc.lockfile' has no attribute 'Lock'

The user is attempting to import or use a class named 'Lock' which does not exist in the 'zc.lockfile' module; the correct class name is 'LockFile'.

fix

Use 'LockFile' instead of 'Lock'. Example: `from zc.lockfile import LockFile`

PermissionError: [Errno 13] Permission denied: '/path/to/lockfile'

The current user or process lacks the necessary write permissions for the directory where the lock file is being created.

fix

Change the lock file's path to a directory where the process has write permissions, or adjust the file system permissions for the target directory.

Upgrade

Version history

4.0latest on PyPI · released Sep 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zopefoundation/zc.lockfile ↗

packagehttps://pypi.org/project/zc-lockfile/ ↗