1FILELOCK(1)                        filelock                        FILELOCK(1)
2
3
4

NAME

6       filelock - filelock 3.3.1
7
8       This  package contains a single module, which implements a platform in‐
9       dependent file lock in Python, which  provides  a  simple  way  of  in‐
10       ter-process communication:
11
12          from filelock import Timeout, FileLock
13
14          lock = FileLock("high_ground.txt.lock")
15          with lock:
16              open("high_ground.txt", "a").write("You were the chosen one.")
17
18       Don't  use  a  FileLock  to lock the file you want to write to, instead
19       create a separate .lock file as shown above.  [image: Example gif] [im‐
20       age]
21

SIMILAR LIBRARIES

23       Perhaps you are looking for something like:
24
25       • the pid 3rd party library,
26
27       • for Windows the msvcrt module in the standard library,
28
29       • for UNIX the fcntl module in the standard library.
30

INSTALLATION

32       filelock is available via PyPI, so you can pip install it:
33
34          python -m pip install filelock
35

TUTORIAL

37       A FileLock is used to indicate another process of your application that
38       a resource or working directory is currently used. To do so,  create  a
39       FileLock first:
40
41          from filelock import Timeout, FileLock
42
43          file_path = "high_ground.txt"
44          lock_path = "high_ground.txt.lock"
45
46          lock = FileLock(lock_path, timeout=1)
47
48       The  lock object supports multiple ways for acquiring the lock, includ‐
49       ing the ones used to acquire standard Python thread locks:
50
51          with lock:
52              open(file_path, "a").write("Hello there!")
53
54          lock.acquire()
55          try:
56              open(file_path, "a").write("General Kenobi!")
57          finally:
58              lock.release()
59
60       The acquire method accepts also a timeout parameter. If the lock cannot
61       be acquired within timeout seconds, a Timeout exception is raised:
62
63          try:
64              with lock.acquire(timeout=10):
65                  open(file_path, "a").write("I have a bad feeling about this.")
66          except Timeout:
67              print("Another instance of this application currently holds the lock.")
68
69       The  lock  objects are recursive locks, which means that once acquired,
70       they will not block on successive lock requests:
71
72          def cite1():
73              with lock:
74                  open(file_path, "a").write("I hate it when he does that.")
75
76
77          def cite2():
78              with lock:
79                  open(file_path, "a").write("You don't want to sell me death sticks.")
80
81
82          # The lock is acquired here.
83          with lock:
84              cite1()
85              cite2()
86          # And released here.
87

LOGGING

89       All log messages by this library are made using the DEBUG_ level, under
90       the filelock name. On how to control displaying/hiding that please con‐
91       sult the logging documentation of the standard library.  E.g.  to  hide
92       these messages you can use:
93
94          logging.getLogger("filelock").setLevel(logging.INFO)
95

FILELOCK VS SOFTFILELOCK

97       The  FileLock  is platform dependent while the SoftFileLock is not. Use
98       the FileLock if all instances of your application are  running  on  the
99       same host and a SoftFileLock otherwise.
100
101       The  SoftFileLock  only  watches  the  existence of the lock file. This
102       makes it ultra portable, but also more prone to dead locks if  the  ap‐
103       plication crashes. You can simply delete the lock file in such cases.
104

ASYNCIO SUPPORT

106       This  library currently does not support asyncio. We'd recommend adding
107       an asyncio variant though if someone can make a pull  request  for  it,
108       see here.
109

CONTRIBUTIONS AND ISSUES

111       Contributions  are always welcome, please make sure they pass all tests
112       before creating a pull request. This module is hosted on GitHub. If you
113       have  any  questions or suggestions, don't hesitate to open a new issue
114       😊. There's no bad question, just a missed opportunity to learn more.
115
116   API
117       A platform independent file lock that supports the with-statement.
118
119       filelock.__version__
120              version of the project as a string
121
122       filelock.FileLock
123              alias of filelock._unix.UnixFileLock
124
125       class filelock.SoftFileLock(lock_file, timeout=- 1)
126              Bases: filelock._api.BaseFileLock
127
128              Simply watches the existence of the lock file.
129
130       exception filelock.Timeout(lock_file)
131              Bases: TimeoutError
132
133              Raised when the lock could not be acquired in timeout seconds.
134
135              lock_file
136                     The path of the file lock.
137
138       class filelock.UnixFileLock(lock_file, timeout=- 1)
139              Bases: filelock._api.BaseFileLock
140
141              Uses the fcntl.flock() to hard lock the lock file on  unix  sys‐
142              tems.
143
144       class filelock.WindowsFileLock(lock_file, timeout=- 1)
145              Bases: filelock._api.BaseFileLock, abc.ABC
146
147              Uses the msvcrt.locking() function to hard lock the lock file on
148              windows systems.
149
150       class filelock.BaseFileLock(lock_file, timeout=- 1)
151              Bases: abc.ABC
152
153              Abstract base class for a file lock object.
154
155              property lock_file
156
157                     Return type
158                            str
159
160                     Returns
161                            path to the lock file
162
163              property timeout
164
165                     Return type
166                            float
167
168                     Returns
169                            the default timeout value
170
171                     New in version 2.0.0.
172
173
174              property is_locked
175
176                     Return type
177                            bool
178
179                     Returns
180                            A boolean indicating if the lock file  is  holding
181                            the lock currently.
182
183                     Changed  in  version  2.0.0: This was previously a method
184                     and is now a property.
185
186
187              acquire(timeout=None, poll_intervall=0.05)
188                     Try to acquire the file lock.
189
190                     Parameters
191
192                            • timeout (typing.Optional[float, None]) --  maxi‐
193                              mum wait time for acquiring the lock, None means
194                              use the default timeout is and if timeout  <  0,
195                              there  is  no timeout and this method will block
196                              until the lock could be acquired
197
198                            • poll_intervall (float) -- interval of trying  to
199                              acquire the lock file
200
201                     Raises Timeout  --  if  fails  to acquire lock within the
202                            timeout period
203
204                     Return type
205                            filelock._api.AcquireReturnProxy
206
207                     Returns
208                            a context object that will unlock  the  file  when
209                            the context is exited
210
211                        # You can use this method in the context manager (recommended)
212                        with lock.acquire():
213                            pass
214
215                        # Or use an equivalent try-finally construct:
216                        lock.acquire()
217                        try:
218                            pass
219                        finally:
220                            lock.release()
221
222                     Changed in version 2.0.0: This method returns now a proxy
223                     object instead of self, so that it can be used in a  with
224                     statement without side effects.
225
226
227              release(force=False)
228                     Releases  the  file  lock.  Please note, that the lock is
229                     only completely released, if the lock counter is 0.  Also
230                     note,  that  the  lock  file  itself is not automatically
231                     deleted.
232
233                     Parameters
234                            force (bool) -- If true, the lock counter  is  ig‐
235                            nored and the lock is released in every case/
236
237                     Return type
238                            None
239
240       class filelock.AcquireReturnProxy(lock)
241              Bases: object
242
243              A  context aware object that will release the lock file when ex‐
244              iting.
245
246   License
247       py-filelock is public domain:
248
249          This is free and unencumbered software released into the public domain.
250
251          Anyone is free to copy, modify, publish, use, compile, sell, or
252          distribute this software, either in source code form or as a compiled
253          binary, for any purpose, commercial or non-commercial, and by any
254          means.
255
256          In jurisdictions that recognize copyright laws, the author or authors
257          of this software dedicate any and all copyright interest in the
258          software to the public domain. We make this dedication for the benefit
259          of the public at large and to the detriment of our heirs and
260          successors. We intend this dedication to be an overt act of
261          relinquishment in perpetuity of all present and future rights to this
262          software under copyright law.
263
264          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
265          EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
266          MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
267          IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
268          OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
269          ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
270          OTHER DEALINGS IN THE SOFTWARE.
271
272          For more information, please refer to <http://unlicense.org>
273
274
275   Changelog
276   v3.4.0 (2021-10-15)
277       • Add changelog to the documentation PR #108 - by @gaborbernat
278
279       • Leave the log level of the filelock logger as not set (previously was
280         set to warning) PR #108 - by @gaborbernat
281
282   v3.3.0 (2021-10-03)
283       • Drop  python  2.7  and  3.5  support,  add  type  hints  PR #100 - by
284         @gaborbernat
285
286       • Document asyncio support - by @gaborbernat
287
288       • fix typo PR #98 - by @jugmac00
289
290   v3.2.1 (2021-10-02)
291       • Improve documentation
292
293       • Changed logger name from  filelock._api  to  filelock  PR  #97  -  by
294         @hkennyv
295
296   v3.2.0 (2021-09-30)
297       • Raise  when  trying  to  acquire in R/O or missing folder PR #96 - by
298         @gaborbernat
299
300       • Move lock acquire/release  log  from  INFO  to  DEBUG  PR  #95  -  by
301         @gaborbernat
302
303       • Fix spelling and remove ignored flake8 checks - by @gaborbernat
304
305       • Split main module PR #94 - by @gaborbernat
306
307       • Move test suite to pytest PR #93 - by @gaborbernat
308
309   v3.1.0 (2021-09-27)
310       • Update links for new home at tox-dev PR #88 - by @hugovk
311
312       • Fixed link to LICENSE file PR #63 - by @sharkwouter
313
314       • Adopt tox-dev organization best practices PR #87 - by @gaborbernat
315
316       • Ownership  moved  from  @benediktschmitt  to the tox-dev organization
317         (new primary maintainer @gaborbernat)
318
319   v3.0.12 (2019-05-18)
320       • fixed setuptools and twine/warehouse error by making the license only
321         1 line long
322
323       • update version for pypi upload
324
325       • fixed python2 setup error
326
327       • added  test.py  module  to  MANIFEST  and made tests available in the
328         setup commands issue #48
329
330       • fixed documentation thanks to @AnkurTank issue #49
331
332       • Update Trove classifiers for PyPI
333
334       • test: Skip test_del on PyPy since it hangs
335
336   v3.0.10 (2018-11-01)
337       • Fix README rendering on PyPI
338
339   v3.0.9 (2018-10-02)
340       • PR #38 from cottsay/shebang
341
342       • updated docs config for older sphinx compatibility
343
344       • removed misleading shebang from module
345
346   v3.0.8 (2018-09-09)
347       • updated use setuptools
348
349   v3.0.7 (2018-09-09)
350       • fixed garbage collection (issue #37)
351
352       • fix travis ci badge (use rst not markdown)
353
354       • changed travis uri
355
356   v3.0.6 (2018-08-22)
357       • clean up
358
359       • Fixed unit test for Python 2.7
360
361       • Added Travis banner
362
363       • Added Travis CI support
364
365   v3.0.5 (2018-04-26)
366       • Corrected the prequel reference
367
368   v3.0.4 (2018-02-01)
369       • updated README
370
371   v3.0.3 (2018-01-30)
372       • updated readme
373
374   v3.0.1 (2018-01-30)
375       • updated README (added navigation)
376
377       • updated documentation issue #22
378
379       • fix the SoftFileLock test was influenced by the test for FileLock
380
381       • undo cb1d83d issue #31
382
383   v3.0.0 (2018-01-05)
384       • updated major version number due to issue #29 and issue #27
385
386       • fixed use proper Python3 reraise method
387
388       • Attempting to clean up lock file on Unix after release
389
390   v2.0.13 (2017-11-05)
391       • changed The logger is now acquired when first needed. issue #24
392
393   v2.0.12 (2017-09-02)
394       • correct spelling mistake
395
396   v2.0.11 (2017-07-19)
397       • added official support for python 2 issue #20
398
399   v2.0.10 (2017-06-07)
400       • updated readme
401
402   v2.0.9 (2017-06-07)
403       • updated readme issue #19
404
405       • added example PR #16
406
407       • updated readthedocs url
408
409       • updated change order of the examples (PR #16)
410
411   v2.0.8 (2017-01-24)
412       • Added logging
413
414       • Removed unused imports
415
416   v2.0.7 (2016-11-05)
417       • fixed issue #14 (moved license and readme file to MANIFEST)
418
419   v2.0.6 (2016-05-01)
420       • changed unlocking sequence to fix transient test failures
421
422       • changed threads in tests so exceptions surface
423
424       • added test lock file cleanup
425
426   v2.0.5 (2015-11-11)
427       • Don't remove file after releasing lock
428
429       • updated docs
430
431   v2.0.4 (2015-07-29)
432       • added the new classes to __all__
433
434   v2.0.3 (2015-07-29)
435       • added The SoftFileLock is now always tested
436
437   v2.0.2 (2015-07-29)
438       • The filelock classes are now always available and have been moved out
439         of the if msvrct: ... elif fcntl ... else clauses.
440
441   v2.0.1 (2015-06-13)
442       • fixed issue #5
443
444       • updated test cases
445
446       • updated documentation
447
448       • fixed issue #2 which has been introduced with the lock counter
449
450   v2.0.0 (2015-05-25)
451       • added default timeout (fixes issue #2)
452
453   v1.0.3 (2015-04-22)
454       • added new test case, fixed unhandled exception
455
456   v1.0.2 (2015-04-22)
457       • fixed a timeout could still be thrown if the lock is already acquired
458
459   v1.0.1 (2015-04-22)
460       • fixed issue #1
461
462   v1.0.0 (2015-04-07)
463       • added lock counter, added unittest, updated to version 1
464
465       • changed filenames
466
467       • updated version for pypi
468
469       • updated README, LICENSE (changed format from md to rst)
470
471       • added MANIFEST to gitignore
472
473       • added os independent file lock ; changed setup.py for pypi
474
475       • Update README.md
476
477       • initial version
478

AUTHOR

480       unknown
481

483       2014-2022, tox-dev
484
485
486
487
4883.3                            January 21, 2022                    FILELOCK(1)
Impressum