Attached is a patch to return the final destination of files or directories sent through shutil's copy, copy2, and move functions. This removes the need to construct the destination path on your own.

This is especially useful for copy/copy2 where you copy a file into a directory and need to know that resulting path. Rather than calling os.path.join(dest, os.path.basename(source)) you could get that path from copy/copy2 (which does that join internally).

Patch has docs and tests.

Here's a patch that fixes the trailing whitespace Hynek noticed as well as adds an additional test case for copy/copy2.

Added another test using move as renaming the destination file.

Code LGTM, a deeper discussion happened on IRC. :)

I'd still suggest for the sake of consistency to return the destination from copytree() too, but that can be done separately.

packaging/distutils2 definitely needs that; the similar functions in distutils.file_util used to return the file paths, this was lost in the conversion to shutil, and there is at least one open bug that needs it back.

When you say "needs that", do you mean the patch as-is, or Hynek's suggestion to return consistently?

I meant that packaging needs some shutil functions to return the destination, but haven’t checked to see if that includes copytree.

In distutils, both copy_file and copy_tree return the destination path(s), which is needed by many commands.  In packaging there is code to compute and return those paths, as shutil functions return None; I’d love to remove that code.

The bug I was thinking about is actually about copy(_)file parameters, not return value: #13336.

Brian, are you going to update that patch so we can close this? :)

New changeset 8281233ec648 by Brian Curtin in branch 'default':
Fix #14772: Return the destination from some shutil functions.
http://hg.python.org/cpython/rev/8281233ec648

New changeset e8ea27ab9fa6 by Brian Curtin in branch 'default':
Add versionchanged tags for #14772 changes
http://hg.python.org/cpython/rev/e8ea27ab9fa6

Thanks!