Issue #20517: Functions in the os module that accept two filenames

now register both filenames in the exception on failure.
This required adding new C API functions allowing OSError exceptions
to reference two filenames instead of one.

3 files changed, 67 insertions, 10 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index d4065e0..070dd17 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -241,6 +241,15 @@ in various ways.  There is a separate error indicator for each thread.
    exception instance.
 
 
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
+
+   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second
+   filename object, for raising errors when a function that takes two filenames
+   fails.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
@@ -248,6 +257,14 @@ in various ways.  There is a separate error indicator for each thread.
    (:func:`os.fsdecode`).
 
 
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenames(PyObject *type, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetFromErrnoWithFilename`, but accepts a
+   second filename.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 
    This is a convenience function to raise :exc:`WindowsError`. If called with
@@ -266,13 +283,6 @@ in various ways.  There is a separate error indicator for each thread.
    specifying the exception type to be raised. Availability: Windows.
 
 
-.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
-
-   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
-   that if *filenameObject* is not *NULL*, it is passed to the constructor of
-   :exc:`WindowsError` as a third parameter.  Availability: Windows.
-
-
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
@@ -280,6 +290,14 @@ in various ways.  There is a separate error indicator for each thread.
    encoding (:func:`os.fsdecode`).  Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenames(int ierr, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, but accepts
+   a second filename.  Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
@@ -287,12 +305,30 @@ in various ways.  There is a separate error indicator for each thread.
    Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
+
+   Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
+   but accepts a second filename object.
+   Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
    parameter specifying the exception type to be raised. Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenames(PyObject *type, int ierr, const char *filename, const char *filename2)
+
+   Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilename`,
+   but accepts a second filename object.
+   Availability: Windows.
+
+.. versionadded:: 3.4
+
+
 .. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
 
    This is a convenience function to raise :exc:`ImportError`. *msg* will be
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 814c3b0..2585a48 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -29,7 +29,7 @@
 # reference to the item argument!
 
 # The parameter names are as they appear in the API manual, not the source
-# code. 
+# code.
 
 PyBool_FromLong:PyObject*::+1:
 PyBool_FromLong:long:v:0:
@@ -317,6 +317,12 @@ PyErr_SetExcFromWindowsErrWithFilename:PyObject*:type:0:
 PyErr_SetExcFromWindowsErrWithFilename:int:ierr::
 PyErr_SetExcFromWindowsErrWithFilename:const char*:filename::
 
+PyErr_SetExcFromWindowsErrWithFilenames:PyObject*::null:
+PyErr_SetExcFromWindowsErrWithFilenames:PyObject*:type:0:
+PyErr_SetExcFromWindowsErrWithFilenames:int:ierr::
+PyErr_SetExcFromWindowsErrWithFilenames:const char*:filename::
+PyErr_SetExcFromWindowsErrWithFilenames:const char*:filename2::
+
 PyErr_SetFromErrno:PyObject*::null:
 PyErr_SetFromErrno:PyObject*:type:0:
 
@@ -324,6 +330,11 @@ PyErr_SetFromErrnoWithFilename:PyObject*::null:
 PyErr_SetFromErrnoWithFilename:PyObject*:type:0:
 PyErr_SetFromErrnoWithFilename:const char*:filename::
 
+PyErr_SetFromErrnoWithFilenames:PyObject*::null:
+PyErr_SetFromErrnoWithFilenames:PyObject*:type:0:
+PyErr_SetFromErrnoWithFilenames:const char*:filename::
+PyErr_SetFromErrnoWithFilenames:const char*:filename2::
+
 PyErr_SetFromWindowsErr:PyObject*::null:
 PyErr_SetFromWindowsErr:int:ierr::
 
@@ -331,6 +342,11 @@ PyErr_SetFromWindowsErrWithFilename:PyObject*::null:
 PyErr_SetFromWindowsErrWithFilename:int:ierr::
 PyErr_SetFromWindowsErrWithFilename:const char*:filename::
 
+PyErr_SetFromWindowsErrWithFilenames:PyObject*::null:
+PyErr_SetFromWindowsErrWithFilenames:int:ierr::
+PyErr_SetFromWindowsErrWithFilenames:const char*:filename::
+PyErr_SetFromWindowsErrWithFilenames:const char*:filename2::
+
 PyErr_SetInterrupt:void:::
 
 PyErr_SetNone:void:::
@@ -907,7 +923,7 @@ PyNumber_Xor:PyObject*::+1:
 PyNumber_Xor:PyObject*:o1:0:
 PyNumber_Xor:PyObject*:o2:0:
 
-PyObject_AsFileDescriptor:int::: 
+PyObject_AsFileDescriptor:int:::
 PyObject_AsFileDescriptor:PyObject*:o:0:
 
 PyObject_Call:PyObject*::+1:
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 704abbb..c2017cc 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -253,6 +253,11 @@ The following exceptions are the exceptions that are usually raised.
    For exceptions that involve a file system path (such as :func:`open` or
    :func:`os.unlink`), the exception instance will contain an additional
    attribute, :attr:`filename`, which is the file name passed to the function.
+   For functions that involve two file system paths (such as
+   :func:`os.rename`), the exception instance will contain a second
+   :attr:`filename2` attribute corresponding to the second file name passed
+   to the function.
+
 
    .. versionchanged:: 3.3
       :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
@@ -263,7 +268,7 @@ The following exceptions are the exceptions that are usually raised.
 
       The :attr:`filename` attribute is now the original file name passed to
       the function, instead of the name encoded to or decoded from the
-      filesystem encoding.
+      filesystem encoding.  Also, the :attr:`filename2` attribute was added.
 
 
 .. exception:: OverflowError