Issue #12760: Refer to the new 'x' open mode as "exclusive creation" mode.

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 82969ebda33c2d852ebbcff2f27936af487dc3e6..e1268cbc51d7929d2cf3ad8fce819bda4ae1d214 100644 (file)
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -472,12 +472,12 @@ Raw File I/O
      to which the resulting :class:`FileIO` object will give access.
 
    The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading
-   (default), writing, creating or appending. The file will be created if it
-   doesn't exist when opened for writing or appending; it will be truncated
-   when opened for writing. :exc:`FileExistsError` will be raised if it already
-   exists when opened for creating. Opening a file for creating implies
-   writing, so this mode behaves in a similar way to ``'w'``. Add a ``'+'`` to
-   the mode to allow simultaneous reading and writing.
+   (default), writing, exclusive creation or appending. The file will be
+   created if it doesn't exist when opened for writing or appending; it will be
+   truncated when opened for writing. :exc:`FileExistsError` will be raised if
+   it already exists when opened for creating. Opening a file for creating
+   implies writing, so this mode behaves in a similar way to ``'w'``. Add a
+   ``'+'`` to the mode to allow simultaneous reading and writing.
 
    The :meth:`read` (when called with a positive argument), :meth:`readinto`
    and :meth:`write` methods on this class will only make one system call.

diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index b2909f773eb6c6627a8313cef2da48b15ce79b42..a60e585622c20472bddb083c17188a8d9295a8cf 100644 (file)
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -427,8 +427,9 @@ parameter to control parameters of the secure channel.
 io
 --
 
-The :func:`~io.open` function has a new ``'x'`` mode that can be used to create
-a new file, and raise a :exc:`FileExistsError` if the file already exists.
+The :func:`~io.open` function has a new ``'x'`` mode that can be used to
+exclusively create a new file, and raise a :exc:`FileExistsError` if the file
+already exists. It is based on the C11 'x' mode to fopen().
 
 (Contributed by David Townshend in :issue:`12760`)
 

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index 6e8f3691bb0870d23ff3dc7935462df9dc799dc9..f66290fa51aa5345efbbeca908fbe1b70ca6336c 100644 (file)
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -41,7 +41,7 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None,
     mode is an optional string that specifies the mode in which the file is
     opened. It defaults to 'r' which means open for reading in text mode. Other
     common values are 'w' for writing (truncating the file if it already
-    exists), 'x' for creating and writing to a new file, and 'a' for appending
+    exists), 'x' for exclusive creation of a new file, and 'a' for appending
     (which on some Unix systems, means that all writes append to the end of the
     file regardless of the current seek position). In text mode, if encoding is
     not specified the encoding used is platform dependent. (For reading and

diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
index 57cd9aabe2ac562de4fdf5e6767d3e5ebef054e0..a21aa7a12d090e54936bd274423610a0fc51530b 100644 (file)
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -1066,9 +1066,9 @@ PyDoc_STRVAR(fileio_doc,
 "file(name: str[, mode: str][, opener: None]) -> file IO object\n"
 "\n"
 "Open a file.  The mode can be 'r', 'w', 'x' or 'a' for reading (default),\n"
-"writing, creating or appending.  The file will be created if it doesn't\n"
-"exist when opened for writing or appending; it will be truncated when\n"
-"opened for writing.  A `FileExistsError` will be raised if it already\n"
+"writing, exclusive creation or appending.  The file will be created if it\n"
+"doesn't exist when opened for writing or appending; it will be truncated\n"
+"when opened for writing.  A `FileExistsError` will be raised if it already\n"
 "exists when opened for creating. Opening a file for creating implies\n"
 "writing so this mode behaves in a similar way to 'w'.Add a '+' to the mode\n"
 "to allow simultaneous reading and writing. A custom opener can be used by\n"