[Python-ideas] Implement POSIX ln via shutil.link and shutil.symlink

[Tom Hale]

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 at 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