os.symlink variables src, dst is confusing

[trick2011]

Documentation

The documentation for os.symlink is as follows:

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)
    Create a symbolic link pointing to src named dst.

The intiuitive usage of source and destination is ambiguous. There are two common conceptions of source and destination. Is the destination the link we are creating that is pointing somewhere or is the destination the thing we are pointing to. Is the source the file we are pointing to and the 'source' of our file or is the source the starting point and thus the link that points to the file.

If we compare with the manpage for ln, the comparable unix command.

NAME
       ln - make links between files

SYNOPSIS
       ln [OPTION]... [-T] TARGET LINK_NAME
       ln [OPTION]... TARGET
       ln [OPTION]... TARGET... DIRECTORY
       ln [OPTION]... -t DIRECTORY TARGET...

DESCRIPTION
       In the 1st form, create a link to TARGET with the name LINK_NAME.

This is unambiguous, the LINK_NAME points towards the TARGET of the link. There is no possible reading possible where the TARGET points towards the LINK_NAME.

---

I couldn't find the place to propose the correct change, therefore this issue, but I propose the following language:

symlink(target, link_name, target_is_directory=False, *, dir_fd=None)
    Create a symbolic link pointing to target named link_name.

    target_is_directory is required on Windows if the target is to be
      interpreted as a directory.  (On Windows, symlink requires
      Windows 6.0 or greater, and raises a NotImplementedError otherwise.)
      target_is_directory is ignored on non-Windows platforms.

    If dir_fd is not None, it should be a file descriptor open to a directory,
      and path should be relative; path will then be relative to that directory.
    dir_fd may not be implemented on your platform.
      If it is unavailable, using it will raise a NotImplementedError

Linked PRs

• gh-141127: Clarify os.symlink() documentation for argument order #141144
• [3.13] gh-141127: Clarify os.symlink() documentation for argument order (GH-141144) #141277
• [3.14] gh-141127: Clarify os.symlink() documentation for argument order (GH-141144) #141278

[picnixz]

Changing the argument names is not possible because one could call them as keyword arguments. The docstring could be reformulated but not the signature (which the PR did)

[chillakalyan]

I have made the requested changes; please review again.

[picnixz]

@chillakalyan FYI, you should send that message in the PR discussion not in the issue discussion but I appreciate the notification :')

[chillakalyan]

My apologies, I have mixed up the issue and PR discussion in the previous post.
I think the issue is solved , thankyou for the guidance