From 35136724cad4d75f1ad67ddf7ba343eb0c5bc36f Mon Sep 17 00:00:00 2001 From: Martin Durant Date: Wed, 11 Dec 2024 09:38:25 -0500 Subject: [PATCH] Write prose for "exclusive" feature --- docs/source/features.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/source/features.rst b/docs/source/features.rst index 907084e0d..949e47107 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -408,3 +408,21 @@ tqdm. + + +Exclusive write +--------------- + +Some backends support writing to a file only if it doesn't already exist. This may be +implemented for the following methods: +- pipe_file (with argument ``mode=='create'``) +- put_file (with argument ``mode=='create'``) +- open (with argument ``mode="xb"``) +Since some writes will be achieved in blocks, the timing of when the check is done is +not defined - it may be at the start or at the completion of the operation, depending +on the backend. + +If using exclusive mode on a file that does already exist, a ``FileExistsError`` will +be raised. + +This feature is currently included on a trial basis and may change in the future.