Document behavior of Path.symlink_to() when source already exists

Documentation

The documentation for Path.symlink_to() [1] does not mention what happens when the source already exists, e.g.:

>>> from pathlib import Path
>>> Path("source").symlink_to("target1")
>>> Path("source").symlink_to("target2")
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    Path("source").symlink_to("target2")
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
  File "/usr/lib/python3.13/pathlib/_local.py", line 789, in symlink_to
    os.symlink(target, self, target_is_directory)
    ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileExistsError: [Errno 17] File exists: 'target2' -> 'source'

(The same applies to os.symlink [2] by the way)

Linked PRs

• gh-132704
• gh-132810

先查看 issue 中連結的 pathlib.Path.symlink_to() 文件，然後對照 os.symlink() 文件了解相同的行為。完成的標準是兩個條目都說明目的地路徑已存在時會發生什麼，包括此處所示的 FileExistsError 範例。