Portalocker

Warnings

• gotcha On Linux and Unix systems, file locks implemented by `portalocker` are advisory by default. This means other processes might ignore the lock and access the file, potentially leading to race conditions or data corruption if they do not also use `portalocker` or respect advisory locks. Mandatory locking requires specific filesystem mount options (-o mand), which is generally not recommended.
  Fix: Ensure all processes accessing the file use `portalocker` or coordinate access through other means. Be aware of the advisory nature on POSIX systems.
• gotcha When using `portalocker.Lock` with file modes like 'w' (write) or 'w+' (write and read), the file is opened and potentially truncated *before* the lock is acquired. This can lead to data loss if another process is simultaneously attempting to write to the file. For safe writing, consider using mode 'a' (append) or 'a+' (append and read) with `truncate=0` or `truncate=None` (or `portalocker.utils.open_atomic`).
  Fix: Use modes 'a' or 'a+' with `Lock(..., truncate=0)` to avoid premature truncation, or use `portalocker.utils.open_atomic` for atomic file writes. For example: `with portalocker.Lock('somefile', mode='a', truncate=0) as fh:`
• gotcha Data written to a locked file might remain in a buffer and not be immediately visible to other processes or persisted to disk until `file.flush()` and `os.fsync(file.fileno())` are called, or the file is closed. Relying solely on `file.close()` might still leave data in OS buffers.
  Fix: Always call `fh.flush()` followed by `os.fsync(fh.fileno())` after writing critical data to ensure it's written to disk within the locked section.
• breaking Python 2.x is no longer supported. `portalocker` versions 2.0 and above require Python 3. If you are on an older Python 2 environment, you must use `portalocker<2`.
  Fix: Upgrade to Python 3 (recommended) or pin `portalocker` to a version less than 2.0 (`pip install "portalocker<2"`).

Install

• pip install portalocker Install core library
• pip install "portalocker[redis]" Install with Redis support

Imports

• lock

  from portalocker import lock

  For low-level, manual locking. The context manager `Lock` is generally preferred.
• unlock

  from portalocker import unlock

  For low-level, manual unlocking. The context manager `Lock` handles unlocking automatically.
• Lock

  from portalocker import Lock

• RLock

  from portalocker import RLock

  Reentrant lock, similar to `threading.RLock` but for processes.
• BoundedSemaphore

  from portalocker import BoundedSemaphore

• RedisLock

  from portalocker import RedisLock

  Requires `portalocker[redis]` extra to be installed.
• LockFlags

  from portalocker import LockFlags

• AlreadyLocked

  from portalocker.exceptions import AlreadyLocked

Quickstart

This quickstart demonstrates the recommended way to use `portalocker` with the `Lock` context manager to safely acquire and release file locks, ensuring data integrity across processes. It explicitly shows flushing and syncing the file content to disk.

import portalocker
import os

file_path = 'my_locked_file.txt'

# Using the Lock context manager (recommended)
# The file is created/opened with 'a' mode, preventing truncation before lock
with portalocker.Lock(file_path, timeout=5, mode='a', truncate=0) as fh:
    print(f"Acquired lock on {file_path}. PID: {os.getpid()}")
    fh.write(f"Hello from process {os.getpid()}!\n")
    fh.flush()
    os.fsync(fh.fileno())
    print("Wrote data and flushed.")
# Lock is automatically released when exiting the 'with' block
print(f"Released lock on {file_path}.")

# Example of manual locking (less common, use with care)
# try:
#     f = open(file_path, 'r+')
#     portalocker.lock(f, portalocker.LockFlags.EXCLUSIVE)
#     print(f"Manually acquired lock on {file_path}")
#     f.seek(0)
#     f.write(f"Manual write from process {os.getpid()}\n")
#     f.flush()
#     os.fsync(f.fileno())
# finally:
#     portalocker.unlock(f)
#     f.close()
#     print(f"Manually released lock on {file_path}")