improve shutil.make_archive

[redstone-cold]

BPO	34450
Nosy	@emilyemorehouse

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-08-21.10:58:56.574>
labels = ['3.8', 'type-bug', 'library']
title = 'improve  shutil.make_archive'
updated_at = <Date 2018-08-22.07:34:56.987>
user = 'https://bugs.python.org/redstone-cold'

bugs.python.org fields:

activity = <Date 2018-08-22.07:34:56.987>
actor = 'redstone-cold'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2018-08-21.10:58:56.574>
creator = 'redstone-cold'
dependencies = []
files = []
hgrepos = []
issue_num = 34450
keywords = []
message_count = 3.0
messages = ['323829', '323835', '323868']
nosy_count = 2.0
nosy_names = ['redstone-cold', 'emilyemorehouse']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue34450'
versions = ['Python 3.8']

[redstone-cold]

The current behavior of shutil.make_archive caused many issues , the problem is mainly on the extracted archive directory hierarchy. These are the proofs:
https://stackoverflow.com/questions/51914467/directory-hierarchy-issue-when-using-shutil-make-archive

https://stackoverflow.com/questions/32640053/compressing-directory-using-shutil-make-archive-while-preserving-directory-str

https://stackoverflow.com/questions/41624800/shutil-make-archive-issue-dont-want-directories-included-in-zip-file

https://stackoverflow.com/questions/50156657/unexpected-file-using-shutil-make-archive-to-compress-file
For example , if I want to create a zip archive of the pip package (path specified by pip.__path__[0])), and need a directory named pip to hold the files and folders which originally reside in the pip package when unpacking the archive, then I need give root_dirparameter of shutil.make_archive the parent directory of the pippackage path (root_dir=Path(pip.__path__[0]).parent), and then the base_dir parameter the final path component of the pip package path(base_dir=Path(pip.__path__[0]).name) , so it is os.path.join(root_dir, base_dir) that specified the directory to archive , so weird !!!
I suggest to change shutil.make_archive(base_name, format[, root_dir[, base_dir]]) to shutil.make_archive(base_name, format[, archived_dir[, archive_prfix]]) where archived_dirdenotes the path to be archived and archive_prfix denotes the common prefix of all files and directories in the archive (it is just a path component and we shouldn’t assume the existence of it on the file system).

If the current behavior of shutil.make_archive won’t be changed , I’d suggest improve its doc, because so many people couldn’t grasp the use of shutil.make_archive even consulting the doc , these are the proofs:
https://stackoverflow.com/questions/45245079/python-how-to-use-shutil-make-archive
https://stackoverflow.com/questions/30049201/how-to-compress-a-file-with-shutil-make-archive-in-python

[emilyemorehouse]

I'll have to think through this a bit more, but my gut is that it would be much more favorable for backwards-compatibility to clarify the documentation instead of changing the functionality.

In any case, the change would only take effect in 3.8+, so it sounds like a backported documentation update is surely needed.

Thanks for the thorough report! :)

[redstone-cold]

one workaround is :
if os.path.join(root_dir, base_dir) exists, use the current implementation , this is set for backwards-compatibility, if not exist, please consider the feature in my last post(maybe we should recommend Python users to follow this approach in the doc).