They say silence is golden... But I'm still looking for some feedback on the below. Cheers! -- Tom Hale On 16 May 2019 21:13:50 Tom Hale <tom@hale.ee> wrote:
Thanks to all who have contributed to the discussion so far.
I've noticed that the documentation[1] for both os.link and os.symlink doesn't mention that the "dst" filename should not exist. Also omitted from the documentation of both is any mention of "FileExistsError".
Taking a step back, I believe that it would be far more useful for shutil to implement POSIX ln[2] as closely as possible via shutil.link and shutil.symlink.
I propose the following behaviour:
==============================================================================
shutil.link: * Create hard links, name follows os.link
shutil.symlink: * Create symlinks, name follows os.symlink * Takes target_is_directory=False parameter as does os.symlink (Windows has different symlinks depending on the type of the target)
Common: * Takes overwrite=False parameter. Updates links atomically. * Takes follow_symlinks=False parameter (as does os.link) * Takes target_or_targets as 1st argument * Behaviour depends on whether 2nd argument is directory (like POSIX ln) * If 2nd argument (destination) is a directory * Multiple targets are allowed * The basename of each target will be linked inside directory * If 2nd argument (destination) is a file * Only one target is allowed
Examples:
shutil.link(file1, file2, overwrite=True) shutil.symlink(list_of_files, dir_name)
===========================================================================
I also propose the following to be added to the documentation for os.(sym)link:
Raises FileExistsError if dst exists. Use shutil.(sym)link to atomically overwrite an existing (sym)link.
For os.symlink, the dir_fd=None parameter is undocumented. Add analogous documentation as per os.link.
===========================================================================
If this proposal has a positive reception (I may even need guidance in determining that), would anyone be willing to mentor me through the code submission process?
I have read https://devguide.python.org/stdlibchanges/ but would like to be able to have someone to review and bounce ideas off given this will be my first stdlib contribution.
If someone is willing to mentor, please contact me via private mail.
[1] https://docs.python.org/library/os.html [2] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/ln.html
-- Tom Hale