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

Tom Hale tom at hale.ee
Thu May 16 10:13:43 EDT 2019

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:


* Create hard links, name follows os.link

* 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)

* 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


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 

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

More information about the Python-ideas mailing list