Rename file without overwriting existing files

[Peter Otten]

Jon Ribbens wrote:

> On 2017-01-30, Jussi Piitulainen <jussi.piitulainen at helsinki.fi> wrote:
>> It doesn't seem to be documented. I looked at help(os.link) on Python
>> 3.4 and the corresponding current library documentation on the web. I
>> saw no mention of what happens when dst exists already.
>>
>> Also, creating a hard link doesn't seem to work between different file
>> systems, which may well be relevant to Steve's case. I get:
>>
>>     OSError: [Errno 18] Invalid cross-device link: [snip]
>>
>> And that also is not mentioned in the docs.
> 
> Nor *should* either of those things be mentioned in the Python docs.
> 
> A lot of the functions of the 'os' module do nothing but call the
> underlying OS system call with the same name. It would not only be
> redundant to copy the OS documentation into the Python documentation,
> it would be misleading and wrong, because of course the behaviour may
> vary slightly from OS to OS.

However, the current Python version of link() is sufficiently different from 
<https://linux.die.net/man/2/link>, say, to warrant its own documentation.