[issue44837] os.symlink arg names are bad

[krey]

New submission from krey :

From: https://docs.python.org/3/library/os.html

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

Create a symbolic link pointing to `src` named `dst`.

It's a bit like saying

find(needle, haystack)

Finds `haystack` in `needle`

If you look at the manpage ln, it says
ln [OPTION]... [-T] TARGET LINK_NAME

So os.symlink isn't consistent with ln

--
assignee: docs@python
components: Documentation
messages: 398977
nosy: docs@python, krey
priority: normal
severity: normal
status: open
title: os.symlink arg names are bad
type: enhancement
versions: Python 3.9

___
Python tracker 
<https://bugs.python.org/issue44837>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44837] os.symlink arg names are bad

[krey]

krey  added the comment:

OK, let's ignore the analogy.

Everywhere else I've seen, arrows (or directed edges in a graph) point as
SOURCE -> TARGET
SOURCE -> DESTINATION
(TARGET and DESTINATION are synonymous in this context)
An example from math: 
https://en.wikipedia.org/wiki/Category_(mathematics)#Definition

ln has two arguments, LINKNAME and TARGET, so it's implied that
LINKNAME -> TARGET
In fact that's exactly what you see visually when you run ls -l

In os.symlink, however, you have
SRC <- DST
which is weird. I agree that this weirdness is explained in grammatically 
correct English.

Just because it's the first argument, we shouldn't call it src. The arg 
ordering is already confusing enough 
https://unix.stackexchange.com/questions/541795/tips-for-remembering-the-order-of-parameters-for-ln

--

___
Python tracker 
<https://bugs.python.org/issue44837>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44837] os.symlink arg names are bad

[krey]

krey  added the comment:

@eric.smith Sorry for tagging this as docs, wasn't sure what to pick. I guess 
it should be under Library 

Does CPython have a process for changing arg names via deprecation warnings?

--

___
Python tracker 
<https://bugs.python.org/issue44837>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44837] os.symlink arg names are bad

[krey]

krey  added the comment:

@eric.smith Fair enough, though the impact would probably be quite low in 
reality. Nobody seems to pass these args by keyword: 
https://github.com/search?q=%22os.symlink(src%3D%22&type=Code

@steven.daprano My suggestion was changing the names of the args, not the order

Current
def os.symlink(src, dst):
ln -s src dst

Changing the names
def os.symlink(dst, src):
ln -s dst src

Changing the order
def os.symlink(dst, src):
ln -s src dst

I concede that different unixes have different argnames for ln, it's a bit of a 
mess. From a CS theory perspective, I think the GNU convention makes more sense.

--
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

___
Python tracker 
<https://bugs.python.org/issue44837>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com