| single |
# py-filelock
![travis-ci]
This package contains a single module, which implements a platform
independent
file lock in Python, which provides a simple way of inter-process
communication:
```Python
from filelock import Timeout, FileLock
lock = FileLock("high_ground.txt.lock")
with lock:
open("high_ground.txt", "a").write("You were the chosen one.")
```
**Don't use** a *FileLock* to lock the file you want to write to, instead
create
a separate *.lock* file as shown above.
![animated example]
## Similar libraries
Perhaps you are looking for something like
* https://pypi.python.org/pypi/pid/2.1.1
* https://docs.python.org/3.6/library/msvcrt.html#msvcrt.locking
* or https://docs.python.org/3/library/fcntl.html#fcntl.flock
## Installation
*py-filelock* is available via PyPi:
```
$ pip3 install filelock
```
## Documentation
The documentation for the API is available on
[readthedocs.org].
### Examples
A *FileLock* is used to indicate another process of your application that a
resource or working
directory is currently used. To do so, create a *FileLock* first:
```Python
from filelock import Timeout, FileLock
file_path = "high_ground.txt"
lock_path = "high_ground.txt.lock"
lock = FileLock(lock_path, timeout=1)
```
The lock object supports multiple ways for acquiring the lock, including
the
ones used to acquire standard Python thread locks:
```Python
with lock:
open(file_path, "a").write("Hello there!")
lock.acquire()
try:
open(file_path, "a").write("General Kenobi!")
finally:
lock.release()
```
The *acquire()* method accepts also a *timeout* parameter. If the lock
cannot be
acquired within *timeout* seconds, a *Timeout* exception is raised:
```Python
try:
with lock.acquire(timeout=10):
open(file_path, "a").write("I have a bad feeling about this.")
except Timeout:
print("Another instance of this application currently holds the lock.")
```
The lock objects are recursive locks, which means that once acquired, they
will
not block on successive lock requests:
```Python
def cite1():
with lock:
open(file_path, "a").write("I hate it when he does that.")
def cite2():
with lock:
open(file_path, "a").write("You don't want to sell me death
sticks.")
|