Fasteners

Warnings

• breaking Python version support is periodically dropped. Version 0.20 removed support for Python 3.8, 3.9, and PyPy 3.9. Previous versions (0.19, 0.18) also dropped support for older Python releases.
  Fix: Ensure your project uses a Python version compatible with your installed `fasteners` version. Refer to the official documentation or release notes for precise compatibility matrix.
• gotcha `InterProcessLock` instances are *not reentrant*. Attempting to acquire a lock already held by the same process can lead to deadlocks or crashes upon release.
  Fix: Avoid recursive acquisition of `InterProcessLock`. Design your code so that a process either acquires the lock once or uses alternative reentrant locking mechanisms if recursion is necessary.
• gotcha `InterProcessReaderWriterLock` instances are *not upgradable*. You cannot acquire a read lock while holding a write lock, or vice versa, without risking deadlocks or crashes.
  Fix: Ensure distinct acquisition patterns. If you need to upgrade a read lock to a write lock (or downgrade), you must explicitly release the first lock before attempting to acquire the second.
• gotcha `InterProcessLock` and `InterProcessReaderWriterLock` provide guarantees *only between processes*, not between threads within a single process. They are not inherently thread-safe for intra-process concurrency.
  Fix: When using inter-process locks, ensure that any code within the locked section that involves multiple threads in the *same process* is protected by standard Python `threading` locks (e.g., `threading.Lock`) to prevent race conditions.
• gotcha When using `InterProcessLock` or `InterProcessReaderWriterLock`, the `path` argument to the constructor is critical. Different processes must use the exact same string path to refer to the same underlying lock. Mismatched paths will result in independent locks.
  Fix: Always use an absolute and consistent file path for your inter-process lock files across all participating processes. Consider using `os.path.join` with a well-known directory or a configuration variable to ensure consistency.

Install

• pip install fasteners Install latest version

Imports

• InterProcessLock

  from fasteners import InterProcessLock

• InterProcessReaderWriterLock

  from fasteners import InterProcessReaderWriterLock

• ReaderWriterLock

  from fasteners import ReaderWriterLock

• interprocess_locked

  from fasteners import interprocess_locked

  While functional, importing the decorator directly is more explicit for linting and clarity.
• locked

  from fasteners import locked

  While functional, importing the decorator directly is more explicit for linting and clarity.

Quickstart

This quickstart demonstrates using `fasteners.interprocess_locked` as a decorator and `fasteners.InterProcessLock` as a context manager to ensure exclusive execution across processes using a file-based lock. If you run multiple instances of this script simultaneously, only one will execute the protected section at a time.

import time
import fasteners
import os

# For inter-process locks, a file path is required.
# Use a temporary file path for demonstration.
lock_file_path = os.path.join(os.getcwd(), 'my_app.lock')

@fasteners.interprocess_locked(lock_file_path)
def protected_function(worker_id):
    print(f"Worker {worker_id}: Acquired lock. Performing exclusive task...")
    time.sleep(2)  # Simulate work
    print(f"Worker {worker_id}: Released lock.")

if __name__ == "__main__":
    print(f"Attempting to run protected_function for worker 1...")
    protected_function(1)
    print(f"Attempting to run protected_function for worker 2...")
    protected_function(2)

    # Example with context manager for more control
    print("\n--- Using context manager ---")
    my_lock = fasteners.InterProcessLock(lock_file_path + '.ctx')
    with my_lock:
        print("Main process: Acquired lock via context manager.")
        time.sleep(1)
    print("Main process: Released lock via context manager.")
    
    # Clean up lock files (optional, as fasteners typically handles this on exit)
    if os.path.exists(lock_file_path):
        os.remove(lock_file_path)
    if os.path.exists(lock_file_path + '.ctx'):
        os.remove(lock_file_path + '.ctx')