README.rst (3791B)
1 =================== 2 python-atomicwrites 3 =================== 4 5 .. image:: https://travis-ci.org/untitaker/python-atomicwrites.svg?branch=master 6 :target: https://travis-ci.org/untitaker/python-atomicwrites 7 8 .. image:: https://ci.appveyor.com/api/projects/status/vadc4le3c27to59x/branch/master?svg=true 9 :target: https://ci.appveyor.com/project/untitaker/python-atomicwrites/branch/master 10 11 Atomic file writes. 12 13 .. code-block:: python 14 15 from atomicwrites import atomic_write 16 17 with atomic_write('foo.txt', overwrite=True) as f: 18 f.write('Hello world.') 19 # "foo.txt" doesn't exist yet. 20 21 # Now it does. 22 23 24 Features that distinguish it from other similar libraries (see `Alternatives and Credit`_): 25 26 - Race-free assertion that the target file doesn't yet exist. This can be 27 controlled with the ``overwrite`` parameter. 28 29 - Windows support, although not well-tested. The MSDN resources are not very 30 explicit about which operations are atomic. 31 32 - Simple high-level API that wraps a very flexible class-based API. 33 34 - Consistent error handling across platforms. 35 36 37 How it works 38 ============ 39 40 It uses a temporary file in the same directory as the given path. This ensures 41 that the temporary file resides on the same filesystem. 42 43 The temporary file will then be atomically moved to the target location: On 44 POSIX, it will use ``rename`` if files should be overwritten, otherwise a 45 combination of ``link`` and ``unlink``. On Windows, it uses MoveFileEx_ through 46 stdlib's ``ctypes`` with the appropriate flags. 47 48 Note that with ``link`` and ``unlink``, there's a timewindow where the file 49 might be available under two entries in the filesystem: The name of the 50 temporary file, and the name of the target file. 51 52 Also note that the permissions of the target file may change this way. In some 53 situations a ``chmod`` can be issued without any concurrency problems, but 54 since that is not always the case, this library doesn't do it by itself. 55 56 .. _MoveFileEx: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365240%28v=vs.85%29.aspx 57 58 fsync 59 ----- 60 61 On POSIX, ``fsync`` is invoked on the temporary file after it is written (to 62 flush file content and metadata), and on the parent directory after the file is 63 moved (to flush filename). 64 65 ``fsync`` does not take care of disks' internal buffers, but there don't seem 66 to be any standard POSIX APIs for that. On OS X, ``fcntl`` is used with 67 ``F_FULLFSYNC`` instead of ``fsync`` for that reason. 68 69 On Windows, `_commit <https://msdn.microsoft.com/en-us/library/17618685.aspx>`_ 70 is used, but there are no guarantees about disk internal buffers. 71 72 Alternatives and Credit 73 ======================= 74 75 Atomicwrites is directly inspired by the following libraries (and shares a 76 minimal amount of code): 77 78 - The Trac project's `utility functions 79 <http://www.edgewall.org/docs/tags-trac-0.11.7/epydoc/trac.util-pysrc.html>`_, 80 also used in `Werkzeug <http://werkzeug.pocoo.org/>`_ and 81 `mitsuhiko/python-atomicfile 82 <https://github.com/mitsuhiko/python-atomicfile>`_. The idea to use 83 ``ctypes`` instead of ``PyWin32`` originated there. 84 85 - `abarnert/fatomic <https://github.com/abarnert/fatomic>`_. Windows support 86 (based on ``PyWin32``) was originally taken from there. 87 88 Other alternatives to atomicwrites include: 89 90 - `sashka/atomicfile <https://github.com/sashka/atomicfile>`_. Originally I 91 considered using that, but at the time it was lacking a lot of features I 92 needed (Windows support, overwrite-parameter, overriding behavior through 93 subclassing). 94 95 - The `Boltons library collection <https://github.com/mahmoud/boltons>`_ 96 features a class for atomic file writes, which seems to have a very similar 97 ``overwrite`` parameter. It is lacking Windows support though. 98 99 License 100 ======= 101 102 Licensed under the MIT, see ``LICENSE``.