Issue #12760: Add a create mode to open(). Patch by David Townshend.

3 files changed, 21 insertions, 5 deletions

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 85e8c5b..82969eb 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -471,10 +471,13 @@ Raw File I/O
    * an integer representing the number of an existing OS-level file descriptor
      to which the resulting :class:`FileIO` object will give access.
 
-   The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
-   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.  Add a
-   ``'+'`` to the mode to allow simultaneous reading and writing.
+   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.
 
    The :meth:`read` (when called with a positive argument), :meth:`readinto`
    and :meth:`write` methods on this class will only make one system call.
@@ -487,6 +490,7 @@ Raw File I/O
 
    .. versionchanged:: 3.3
       The *opener* parameter was added.
+      The ``'x'`` mode was added.
 
    In addition to the attributes and methods from :class:`IOBase` and
    :class:`RawIOBase`, :class:`FileIO` provides the following data
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index bb1ebd9..53f5025 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -591,7 +591,8 @@ These functions create new :term:`file objects <file object>`. (See also :func:`
    the built-in :func:`open` function.
 
    When specified, the *mode* argument must start with one of the letters
-   ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
+   ``'r'``, ``'w'``, ``'x'`` or ``'a'``, otherwise a :exc:`ValueError` is
+   raised.
 
    On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
    set on the file descriptor (which the :c:func:`fdopen` implementation already
@@ -599,6 +600,8 @@ These functions create new :term:`file objects <file object>`. (See also :func:`
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.3
+      The ``'x'`` mode was added.
 
 .. _os-fd-ops:
 
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index f458ae0..0b0f8f6 100644
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -408,6 +408,15 @@ parameter to control parameters of the secure channel.
 (Contributed by Sijin Joseph in :issue:`8808`)
 
 
+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.
+
+(Contributed by David Townshend in :issue:`12760`)
+
+
 lzma
 ----