1PY-FILELOCK(1) py-filelock PY-FILELOCK(1)
2
6 py-filelock - py-filelock Documentation
7 py-filelock is a single Python module, which implements a platform
9 independent file lock. The lock is thread safe and easy to use:
10 lock = filelock.FileLock("my_lock_file")
12 with lock:
13 shutil.copy("...", "...")
14 The lock implements also a counter, which allows you to acquire the
16 lock multiple times without blocking:
17 lock = filelock.FileLock("my_lock_file")
19 def update_files1():
21 with lock:
22 assert lock.is_locked
23 # ...
24 return None
25 def update_files2():
27 with lock:
28 assert lock.is_locked
29 # ...
30 return None
31 def update_all_files():
33 with lock:
34 assert lock.is_locked
35 update_files1()
37 assert lock.is_locked
39 update_files2()
41 assert lock.is_locked
43 assert not lock.is_locked
44 return None
45 update_all_files()
47
49 This package is listed on PyPi, so you’re done with:
50 $ pip3 install filelock
52
54 import filelock
55 lock = filelock.FileLock("my_lock_file")
57 # Simply use the lock into a with statement.
59 with lock:
60 pass
61 # If you want to set a timeout parameter, you can do it by:
63 with lock.acquire(timeout = 10):
64 pass
65 # You can also set a default timeout value, which is used, when no
67 # special timeout value is given to the *acquire()* method:
68 lock.timeout = 20
69 with lock: # 20s timeout
71 pass
72 with lock.acquire() # 20s timeout
74 pass
75 with lock.acquire(timeout = 10) # 10s timeout
77 pass
78 # If you want to use a timeout value, you should consider to catch
80 # a Timeout exception:
81 try:
82 with lock.acquire(timeout = 10):
83 pass
84 except filelock.Timeout:
85 pass
86 # If you can not use the *with* statement, use a try-finally construct
88 # instead:
89 lock.acquire()
90 try:
91 pass
92 finally:
93 lock.release()
94 # Please note, that you can acquire the lock multiple times without
96 # blocking. The lock will count, how often it has been acquired and releases
97 # the lock, as soon as the counter is 0.
98 with lock:
99 assert lock.is_locked
100 with lock:
101 assert lock.is_locked
102 assert lock.is_locked
103 assert (not lock.is_locked)
104
106 A platform independent file lock that supports the with-statement.
107 exception filelock.Timeout(lock_file)
109 Bases: exceptions.OSError
110 Raised when the lock could not be acquired in timeout seconds.
112 lock_file = None
114 The path of the file lock.
115 class filelock.BaseFileLock(lock_file, timeout=-1)
117 Bases: object
118 Implements the base class of a file lock.
120 acquire(timeout=None, poll_intervall=0.05)
122 Acquires the file lock or fails with a Timeout error.
123 # You can use this method in the context manager (recommended)
125 with lock.acquire():
126 pass
127 # Or you use an equal try-finally construct:
129 lock.acquire()
130 try:
131 pass
132 finally:
133 lock.release()
134 Parameters
136 · timeout (float) – The maximum time waited for
138 the file lock. If timeout <= 0, there is no
139 timeout and this method will block until the
140 lock could be acquired. If timeout is None, the
141 default timeout is used.
142 · poll_intervall (float) – We check once in
144 poll_intervall seconds if we can acquire the
145 file lock.
146 Raises Timeout – if the lock could not be acquired in
148 timeout seconds.
149 Changed in version 2.0.0: This method returns now a proxy
151 object instead of self, so that it can be used in a with
152 statement without side effects.
153 is_locked
156 True, if the object holds the file lock.
157 Changed in version 2.0.0: This was previously a method
159 and is now a property.
160 lock_file
163 The path to the lock file.
164 release(force=False)
166 Releases the file lock.
167 Please note, that the lock is only completly released, if
169 the lock counter is 0.
170 Also note, that the lock file itself is not automatically
172 deleted.
173 Parameters
175 force (bool) – If true, the lock counter is
176 ignored and the lock is released in every case.
177 timeout
179 You can set a default timeout for the filelock. It will
180 be used as fallback value in the acquire method, if no
181 timeout value (None) is given.
182 If you want to disable the timeout, set it to a negative
184 value.
185 A timeout of 0 means, that there is exactly one attempt
187 to acquire the file lock.
188 New in version 2.0.0.
190 class filelock.WindowsFileLock(lock_file, timeout=-1)
193 Bases: filelock.BaseFileLock
194 Uses the msvcrt.locking() function to hard lock the lock file on
196 windows systems.
197 class filelock.UnixFileLock(lock_file, timeout=-1)
199 Bases: filelock.BaseFileLock
200 Uses the fcntl.flock() to hard lock the lock file on unix sys‐
202 tems.
203 class filelock.SoftFileLock(lock_file, timeout=-1)
205 Bases: filelock.BaseFileLock
206 Simply watches the existence of the lock file.
208 filelock.FileLock
210 Alias for the lock, which should be used for the current plat‐
211 form. On Windows, this is an alias for WindowsFileLock, on Unix
212 for UnixFileLock and otherwise for SoftFileLock.
213 alias of filelock.UnixFileLock
215
217 py-filelock is public domain:
218 This is free and unencumbered software released into the public domain.
220 Anyone is free to copy, modify, publish, use, compile, sell, or
222 distribute this software, either in source code form or as a compiled
223 binary, for any purpose, commercial or non-commercial, and by any
224 means.
225 In jurisdictions that recognize copyright laws, the author or authors
227 of this software dedicate any and all copyright interest in the
228 software to the public domain. We make this dedication for the benefit
229 of the public at large and to the detriment of our heirs and
230 successors. We intend this dedication to be an overt act of
231 relinquishment in perpetuity of all present and future rights to this
232 software under copyright law.
233 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
235 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
236 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
237 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
238 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
239 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
240 OTHER DEALINGS IN THE SOFTWARE.
241 For more information, please refer to <http://unlicense.org>
243
245 This module is hosted on GitHub. If you have any questions or sugges‐
246 tions, don’t hesitate to open a new issue :).
247
249 Benedikt Schmitt
250
252 2015, Benedikt Schmitt
2532.0.8 Jul 15, 2018 PY-FILELOCK(1)