utils.py: improve documentation of move_atomicbschubert/mr938-comments

1 files changed, 8 insertions, 2 deletions

diff --git a/buildstream/utils.py b/buildstream/utils.py
index a0db963da..94c990357 100644
--- a/buildstream/utils.py
+++ b/buildstream/utils.py
@@ -512,10 +512,12 @@ def move_atomic(source, destination, *, ensure_parents=True):
     It wraps some `OSError` thrown errors to ensure their handling is correct.
 
     The main reason for this to exist is that rename can throw different errors
-    for the same symptom (https://www.unix.com/man-page/POSIX/3posix/rename/).
+    for the same symptom (https://www.unix.com/man-page/POSIX/3posix/rename/)
+    when we are moving a directory.
 
     We are especially interested here in the case when the destination already
-    exists. In this case, either EEXIST or ENOTEMPTY are thrown.
+    exists, is a directory and is not empty. In this case, either EEXIST or
+    ENOTEMPTY can be thrown.
 
     In order to ensure consistent handling of these exceptions, this function
     should be used instead of `os.rename`
@@ -525,6 +527,10 @@ def move_atomic(source, destination, *, ensure_parents=True):
       destination (str or Path): destination to which to move the source
       ensure_parents (bool): Whether or not to create the parent's directories
                              of the destination (default: True)
+    Raises:
+      DirectoryExistsError: if the destination directory already exists and is
+                            not empty
+      OSError: if another filesystem level error occured
     """
     if ensure_parents:
         os.makedirs(os.path.dirname(str(destination)), exist_ok=True)