misleading comment in socket.gethostname() documentation

[ned-deily]

BPO	5626
Nosy	@birkenfeld, @orsenthil, @ned-deily, @Rosuav, @berkerpeksag
Files	issue5626_v1.diff: Remove misleading comment.

^{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 2016-01-20.06:46:38.131>
created_at = <Date 2009-03-31.16:02:52.238>
labels = ['type-bug', 'docs']
title = 'misleading comment in socket.gethostname() documentation'
updated_at = <Date 2016-01-20.06:46:38.130>
user = 'https://github.com/ned-deily'

bugs.python.org fields:

activity = <Date 2016-01-20.06:46:38.130>
actor = 'berker.peksag'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-01-20.06:46:38.131>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2009-03-31.16:02:52.238>
creator = 'ned.deily'
dependencies = []
files = ['24698']
hgrepos = []
issue_num = 5626
keywords = ['patch']
message_count = 6.0
messages = ['84816', '212554', '258565', '258567', '258601', '258649']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'orsenthil', 'ned.deily', 'docs@python', 'python-dev', 'Rosuav', 'berker.peksag']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue5626'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[ned-deily]

The documentation for socket.gethostname() contains the following
comment:

"If you want to know the current machine’s IP address, you may want to
use gethostbyname(gethostname()). This operation assumes that there is a
valid address-to-host mapping for the host, and the assumption does not
always hold."

This comment leads to the mistaken assumption that a machine has only
one IP address, an assumption which results in bugs such as in
bpo-5625. The comment also does not deal with other address families,
i.e. IPv6 addresses. Either the paragraph should be expanded to cover
multiple addresses and families, requiring the use of other socket
functions, or the paragraph should simply be removed.

[Rosuav]

Python doesn't currently have any sort of function for fetching all a computer's IPs, as far as I know, but if there is one (either now or in the future), it would be good to link to that from there. "Here's how to get your host name. And if you're interested, over there is how to get your IP addresses." Otherwise, removing the potentially-misleading information (this is going to return something in 127.0.0.0/8 for a lot of systems) seems the reasonable option.

[orsenthil]

Given that we have not received any more reports on users tripping up on this message, it seems to me that we could just ignore this report and close it. Thoughts?

[ned-deily]

The point still stands that speaking of "the current machine's IP address" is misleading at best. I'd say either apply Berker's suggested patch or expand the description to better reflect the real world of multiple interfaces. Of course I'm biased.

[berkerpeksag]

I agree with Chris and Ned. I will apply issue5626_v1.diff today.

[python-dev]

New changeset e1a711808cfe by Berker Peksag in branch '3.5':
Issue bpo-5626: Remove misleading comment from socket.gethostname() documentation
https://hg.python.org/cpython/rev/e1a711808cfe

New changeset 689f881dd5d1 by Berker Peksag in branch 'default':
Issue bpo-5626: Remove misleading comment from socket.gethostname() documentation
https://hg.python.org/cpython/rev/689f881dd5d1