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
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
