API documentation

renameat2 is a wrapper around Linux’s renameat2 system call.

The most likely reason you might want to use renameat2 is to atomically swap two files; the exchange() function is for you.

If you just want to rename things with more control than os.rename(), and/or possibly do some weird overlayfs stuff, check out rename().

Finally, if you really just like the interface of renameat2 as it’s implemented in the system call, renameat2() recreates it in Python.

class renameat2.Flags(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bit flags accepted by the flags parameter of renameat2.renameat2()

RENAME_EXCHANGE = 2

Atomically exchange oldpath and newpath. Both pathnames must exist but may be of different types (e.g., one could be a non-empty directory and the other a symbolic link).

RENAME_EXCHANGE can’t be used in combination with RENAME_NOREPLACE or RENAME_WHITEOUT.

RENAME_NOREPLACE = 1

Don’t overwrite newpath of the rename. Return an error if newpath already exists.

RENAME_NOREPLACE requires support from the underlying filesystem. See the renameat(2) manpage for more information.

RENAME_WHITEOUT = 4

Specifying RENAME_WHITEOUT creates a “whiteout” object at the source of the rename at the same time as performing the rename. The whole operation is atomic, so that if the rename succeeds then the whiteout will also have been created.

This operation makes sense only for overlay/union filesystem implementations.

See the renameat(2) man page for more information.

renameat2.exchange(a: Union[Path, str], b: Union[Path, str]) → None

Atomically swap two files.

This is probably the main attraction of this module.

After this call, the file originally referred to by the first path will be referred to by the second, and the file originally referred to by the second path will be referred to by the first.

This is an atomic operation; that is to say, there is no possible intermediate state where the files could be “partially” swapped; either the call succeeds and the files are exchanged, or the call fails and the files are not exchanged.

This function is implemented by passing RENAME_EXCHANGE to the system call.

Parameters
Raises

OSError – if a and b cannot be swapped

renameat2.rename(oldpath: Union[Path, str], newpath: Union[Path, str], replace: bool = True, whiteout: bool = False) → None

Rename a file using the renameat2 system call.

Parameters

  • oldpath (Union[pathlib.Path, str]) – Path to the file to rename

  • newpath (Union[pathlib.Path, str]) – Path to rename the file to

  • replace (bool) – If true, any existing file at newpath will be replaced. If false, any existing file at newpath will cause an error to be raised. False corresponds to passing RENAME_NOREPLACE to the system call.

  • whiteout (bool) – If true, a “whiteout” file will be left behind at oldpath. True corresponds to passing RENAME_WHITEOUT to the system call.

Raises

OSError – if the system call fails

renameat2.renameat2(olddirfd: int, oldpath: str, newdirfd: int, newpath: str, flags: ~renameat2.Flags = Flags.None) → None

A thin wrapper around the renameat2 C library function.

Most people will likely prefer the more Pythonic interfaces provided by the rename() or exchange() wrapper functions; this one is for people who prefer their C library bindings without any sugar.

Parameters

  • olddirfd (int) – A directory file descriptor

  • oldpath (str) – The name of a file in the directory represented by olddirfd

  • newdirfd (int) – A directory file descriptor

  • newpath (str) – The name of a file in the in the directory represented by newdirfd

  • flags (Flags) – A bit mask consisting of zero or more of RENAME_EXCHANGE, RENAME_NOREPLACE, or RENAME_WHITEOUT.

Raises

OSError – if the system call fails