Update os.samefile docstring to match documentation

[eMPee584]

BPO	30974
Nosy	@bitdancer, @zooba, @eMPee584, @miss-islington, @iritkatriel
PRs	bpo-30974: fix os.path.samefile docstring with docs #7337 [3.8] bpo-30974: Change os.path.samefile docstring to match docs (GH-7337) #15086 [3.7] bpo-30974: Change os.path.samefile docstring to match docs (GH-7337) #15087

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-09-21.16:30:18.661>
created_at = <Date 2017-07-20.08:07:10.749>
labels = ['3.8', 'type-bug', '3.7', 'docs']
title = 'Update os.samefile docstring to match documentation'
updated_at = <Date 2020-09-21.16:30:18.660>
user = 'https://github.com/eMPee584'

bugs.python.org fields:

activity = <Date 2020-09-21.16:30:18.660>
actor = 'steve.dower'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-09-21.16:30:18.661>
closer = 'steve.dower'
components = ['Documentation']
creation = <Date 2017-07-20.08:07:10.749>
creator = 'eMPee584'
dependencies = []
files = []
hgrepos = []
issue_num = 30974
keywords = ['patch']
message_count = 10.0
messages = ['298708', '298731', '322555', '322556', '348928', '348929', '348930', '348932', '348933', '377161']
nosy_count = 6.0
nosy_names = ['r.david.murray', 'docs@python', 'steve.dower', 'eMPee584', 'miss-islington', 'iritkatriel']
pr_nums = ['7337', '15086', '15087']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue30974'
versions = ['Python 2.7', 'Python 3.7', 'Python 3.8']

[eMPee584]

Don't know whether it should be considered a documentation or behavioral issue, but os.samefile calls os.stat() on given files, following symlinks. Does this really "test whether two pathnames reference the same actual file"? I'd consider os.lstat() more suited for that.

This bites me every time I want to overwrite a symlink with its referenced file using ranger.

[bitdancer]

I would take "actual file" as meaning the file the symlink points to, so I'd say the documentation matches the implementation according to your description of the two. The current docs actually say "refer to the same file or directory", and mention os.stat explicitly, so again I'd say the docs and implementation match.

It sounds like what you want is to open a feature request for a samefile equivalent that does not follow symlinks. lsamefile?

We could use this issue for making the docstring match the docs, though. I think the sentence in the docs is short enough to just get copied into the docstring.

[zooba]

I think the docs are too specific about the mechanism used here - if we document *how* it works then we may not be able to make it work correctly (with a different mechanic) on a different platform.

[zooba]

Sorry, I meant the docs after the patch. Before, it's fine.

[zooba]

New changeset 8e568ef by Steve Dower (Timo Furrer) in branch 'master':
bpo-30974: Change os.path.samefile docstring to match docs (GH-7337)
8e568ef

[zooba]

I'm not personally thrilled about it being documented like this, but it's certainly how the current documentation reads. Consistency is better until we get motivated enough to fix all of it.

Thanks for the patch!

[zooba]

Still needs a 2.7 backport if someone would like to do it.

[miss-islington]

New changeset 6b83390 by Miss Islington (bot) in branch '3.8':
bpo-30974: Change os.path.samefile docstring to match docs (GH-7337)
6b83390

[miss-islington]

New changeset a49f203 by Miss Islington (bot) in branch '3.7':
bpo-30974: Change os.path.samefile docstring to match docs (GH-7337)
a49f203

[iritkatriel]

Since backport to 2.7 is no longer relevant, I think this issue can be closed.