Repository files navigation

Sadly, this is not a nuclear-powered utility to swap files.

atomicswap is a Python module that implements the swapping of two files on a filesystemin a single operation that can't be broken up; either the entire operationcompletes correctly or none of it completes. This prevents the filesystemfrom being left in an inconsistent state and avoids certain race conditions.

The API is very simple; only a singleswap() function is provided. Thefunction takes two file paths for the two files to be swapped. In the eventthat either path is a relative path, you may also provide file descriptorsfor directories that the relative paths should start from; if either ismissing then the path is relative to the current working directory. Pathscan be provided either as Python strings orpathlib paths.

The latest stable version ofatomicswap can be installed from thePythonPackage Index usingpip in the normal manner:

pip install atomicswap

If you want to try out the latest code then you can install it from theGitHub repository:

pip install atomicswap@git+https://github.com/nickovs/atomicswap.git

Swapping the files/etc/something/active and/etc/something/standby ina single operation can be performed as follows:

fromatomicswapimportswap...swap("/etc/something/active","/etc/something/standby")

Alternatively, if usingPath objects, this could be implemented as:

frompathlibimportPathfromatomicswapimportswap...base_dir=Path("/etc/something")swap(base_dir/"active",base_dir/"standby")

Currentlyatomicswap supports Linux, macOS and Windows. Note that the Windowsimplementation does not support specifying the base directories for relative pathsusing directory file descriptors.

On both macOS and Linuxatomicswap is not dependent on any non-standardlibraries or third party packages. On Windows it requirespywin32.

Both Linux and macOS have kernel system calls that provide the simultaneous,atomic swapping of the names of two files. On Linux the system call is namedrenameat2 while on macOS it is namedrenameatx_np, but the operation ismuch the same: passing a specific flag to the extended version of the renamefunction causes it to swap the names of two existing files rather than justchanging the name of one file. On macOS therenameatx_np is exposed in thestandard C library and can be called directly. Not all Linux distributions exposetherenameat2 system call in their C library so thesyscall wrapper functionis used instead.

While there is no equivalent single function to perform the same operation onWindows, it is possible to perform an atomic swap operation using the WindowsKernel Transaction Manager andTransactional NTFS.Unfortunately Microsoft have stated that"TxF may not be available in future versions ofMicrosoft Windows", which potentially limits the utility of this sort ofimplementation.

atomicswap is released under the MIT license. See LICENSE.md for details.