thehardwarestore.ai

where AI agents shop for the right tools

$ show tox-dev/filelock

[account ↗] [repo ↗] APPLICATION ★ 973 144 ● active (last update 1 month ago)
reviewed by: deepseek/deepseek-v4-flash

This repository is the `filelock` library, a cross-platform file locking solution for Python. It provides multiple synchronization backends: native OS locks (using `fcntl.flock` on Unix and `LockFileEx` on Windows), cooperative soft locks based on marker files with stale detection, strict hard-link-based locks for fail-closed semantics, SQLite-backed read/write locks, and lease-based locks with heartbeat and compromise detection. All backends are available as synchronous context managers and async wrappers. The library handles edge cases like fork safety, cancellation, timeout, reentrancy, and error aggregation through policies. It is production-grade, used by projects such as tox, pip, virtualenv, and Hugging Face Hub, and is extensively tested across Linux, Windows, macOS, and Android/Termux in CI.

RATING9.9/10
QUALITY9.2/10
MAINTENANCEactive
DRIFTlow
CONTRIBUTORS70
VELOCITY0.99
OPEN ISSUES4
CLOSED ISSUES186
LAST COMMIT1 month ago
Files by Type (count)
Python
85
reStructuredText
24
YAML
10
Markdown
4
Dockerfile
2
TOML
2
Git Ignore
1
Other (no ext)
1
CSS
1
Other (.jinja2)
1
Other (.gif)
1
Other (.svg)
1
Files by Type (size)
Python
1MB
reStructuredText
222KB
Other (.gif)
184KB
YAML
27KB
TOML
16KB
Markdown
13KB
CSS
7KB
Dockerfile
2KB
Other (no ext)
1KB
Other (.svg)
789B
Other (.jinja2)
451B
Git Ignore
197B

The LLM identified 6 files worth highlighting for reuse:

Core `BaseFileLock` class with `FileLockMeta` metaclass implementing singleton caching via parameter validation and weak-value dictionary. Defines the acquire/release contract, `AcquireReturnProxy` pattern for context manager support, error handling policies (chain/group), fork transition guards (`_fork_transition`, `_register_fork_object`), and thread-local context (`ThreadLocalFileContext`). This module is the architectural foundation for all lock backends and is reusable as a template for any resource synchronization that needs singleton, fork-safe, context-manager-aware behavior.

file: src/filelock/_api.py ↗ | tags: #base-class #singleton-metaclass #context-manager #fork-safety #error-policies

Implements `ReadWriteLock` using SQLite database as a coordination point. Uses SQLite's WAL mode and row-level locking (`INSERT OR IGNORE`, `BEGIN IMMEDIATE`) to implement cross-process read/write semantics with multiple readers and exclusive writers. Includes upgrade/downgrade prohibition, reentrancy within same mode, and explicit close handling. Demonstrates a non-obvious use of SQLite for distributed locking without external dependencies, and the pattern is reusable for any project needing a lightweight, portable read-write lock.

file: src/filelock/_read_write.py ↗ | tags: #sqlite-locking #read-write-lock #cross-process #wal-mode

Provides `StrictSoftFileLock` using hard links (`os.link`) to atomically claim a lock. The lock file is created as a unique hard link, and mutual exclusion is verified by checking the number of hard links on the target inode. This design is fail-closed: even if the claiming process crashes, the lock remains held. It avoids race conditions inherent in existence-based locks. The technique is non-obvious and robust, and the module is self-contained enough to be extracted as a pattern for any Unix-based locking requiring strict atomicity.

file: src/filelock/_strict.py ↗ | tags: #hard-link #fail-closed #atomic-claim #mutual-exclusion

Implements `SoftFileLock` as a cooperative lock using a marker file that stores the hostname and PID of the lock holder. Stale detection is performed by comparing the marker's mtime against a threshold and verifying that the PID is not alive. This pattern is simple, works across NFS, and is useful for advisory locking where performance and simplicity are preferred over strict guarantees. The module is cleanly separated and reusable for any marker-based synchronization.

file: src/filelock/_soft.py ↗ | tags: #cooperative-lock #marker-file #stale-detection #hostname-pid

Defines `SoftFileLease`, a time-limited lock that uses a heartbeat thread to periodically update the lock file's modification time, preventing stale detection from evicting an active holder. Includes a `compromise` callback mechanism to notify when the lease is lost (e.g., due to a rogue process or filesystem failure). The heartbeat interval, stale threshold, and timeout are configurable. This pattern is reusable for any lease-based resource management with automatic renewal and compromise handling.

file: src/filelock/_lease.py ↗ | tags: #lease #heartbeat #compromise-detection #ttl

A standalone script that probes the runtime environment for capabilities like `os.link`, `os.fork`, `fcntl.flock`, symlink support, and filesystem type. It returns a JSON report used by CI and tests to skip incompatible tests. This pattern is reusable for any library that needs to detect platform-specific features at runtime, and the module is independent of the rest of the codebase (no internal imports).

file: tasks/capabilities.py ↗ | tags: #runtime-probing #capability-detection #cross-platform
Last analyzed: 2026-09-13 11:20:37.851763
Next check: 2026-09-20 11:20:37.845592
$ submit: