filelock

The filelock package does exactly what it promises with a refreshingly simple API. The context manager pattern (`with FileLock("myfile.lock"):`) feels natural and Pythonic, making it easy to add file locking without cluttering your code. It handles the platform-specific differences between Windows and Unix transparently, which is a huge time-saver when building cross-platform applications.

The timeout parameter works reliably, and the library raises clear `Timeout` exceptions when locks can't be acquired. Type hints are present and work well with mypy and IDE autocompletion. The documentation is straightforward with practical examples that cover the common use cases like database file locking and preventing concurrent script execution.

One minor annoyance is that lock files aren't automatically cleaned up on process crashes (by design for safety), so you may need to implement your own stale lock detection for long-running systems. The error messages could be slightly more informative about which process holds a lock, but this is a minor quibble for an otherwise excellent library.

filelock does exactly what it promises with a straightforward API that you can learn in minutes. The context manager pattern (`with FileLock("myfile.lock"):`) feels natural and Pythonic, making it easy to protect file access across processes. It handles platform differences transparently—works the same on Windows, Linux, and macOS without code changes.

The library is remarkably low-maintenance once integrated. Error handling is predictable: you get `Timeout` exceptions when locks can't be acquired, and the messages clearly indicate which lock file is involved. Type hints are present and work well with mypy and IDE autocomplete. The documentation is concise but covers the essential use cases, including timeout configuration and non-blocking attempts.

One gotcha: lock files persist on disk after use, which can clutter directories if you're not careful about placement. The library also assumes you understand file locking semantics—it won't prevent you from common mistakes like acquiring multiple locks in inconsistent order (deadlock risk). For complex distributed locking scenarios, you'll need something more sophisticated, but for local file coordination, it's solid.

filelock is one of those utilities that just works. The API is dead simple - create a FileLock or SoftFileLock instance, use it as a context manager, and you're done. It handles the platform-specific differences between Unix fcntl and Windows msvcrt seamlessly. I've deployed this across Linux servers and Windows dev machines without changing a single line of code.

The timeout behavior is predictable and configurable. Default blocking behavior waits indefinitely, but you can set explicit timeouts that raise Timeout exceptions cleanly. The library doesn't do any hidden retries - you get exactly the behavior you configure. Resource cleanup is automatic with context managers, and I've never seen leaked lock files cause issues in production. Logging is minimal but sufficient; it uses the standard logging module so you can hook into it if needed.

Performance overhead is negligible - it's literally just OS-level file locking syscalls. Memory footprint is tiny. My only real gripe is that error messages when locks fail could be more descriptive about what's holding the lock, but that's an OS limitation more than a library issue.