[doc] platform module exposes win32_ver function on posix systems

[pythonhacker]

BPO	23747
Nosy	@vstinner, @bitdancer, @slateny
PRs	bpo-23747: Add small note to document default method behavior #31462

^{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 = None
created_at = <Date 2015-03-23.09:30:16.792>
labels = ['easy', '3.9', '3.10', '3.11', 'library', 'docs']
title = '[doc] platform module exposes win32_ver function on posix systems'
updated_at = <Date 2022-02-21.08:30:09.916>
user = 'https://bugs.python.org/pythonhacker'

bugs.python.org fields:

activity = <Date 2022-02-21.08:30:09.916>
actor = 'slateny'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2015-03-23.09:30:16.792>
creator = 'pythonhacker'
dependencies = []
files = []
hgrepos = []
issue_num = 23747
keywords = ['patch', 'easy']
message_count = 5.0
messages = ['238995', '238996', '238997', '239001', '239126']
nosy_count = 5.0
nosy_names = ['vstinner', 'pythonhacker', 'r.david.murray', 'docs@python', 'slateny']
pr_nums = ['31462']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue23747'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[pythonhacker]

>>> import platform
>>> platform.system()
'Linux'
>>> platform.win32_ver()
('', '', '', '')

Why is this function even exposed on Linux ? It should be conditionally exposed only on win32 platforms.

Funny that this is coming from the module named "platform" itself :)

[vstinner]

Why is this function even exposed on Linux?

It is a deliberate design choice of the platform module. mac_ver(), win32_ver() and linux_distribution() are available on all platforms.

mac_ver() says "entries which cannot be determined are set to ''. All tuple entries are strings."

Maybe it should be better explained in the doc.

[pythonhacker]

Similarly for mac_ver, java_ver etc.

>>> platform.mac_ver()
('', ('', '', ''), '')
>>> platform.java_ver()
('', '', ('', '', ''), ('', '', ''))

Maybe it is okay if these functions are present, but can't they raise an exception or return None instead of returning these funny tuples when empty strings ?

I am surprised at Python's inconsistency in such things. For example,

>>> import winsound
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'winsound'

Works as expected on Linux. In the same vein, these functions shouldn't be present as well IMHO - I agree this is debatable of course.

[vstinner]

Maybe it is okay if these functions are present, but can't they raise an exception or return None instead of returning these funny tuples when empty strings ?

It would break the backward compatibility. Again, it's a delibarate choice.

[bitdancer]

It is a deliberate choice because the functions accept default values to be returned if the actual values cannot be determined, and because it is easier therefore to write cross-platform scripts if the functions do *not* raise an error when called on the "wrong" platform. There are other functions in the platform module to use to determine which platform you are on.

Agreed that the fact that they work is currently documented only by implication for those familiar with our doc style (that is, there are no "avaiability" tags, implying they are available on all platforms). This should be corrected, probably in an introductory paragraph (which will be overlooked by most people reading the docs :)

[vstinner]

I merged #31462, thanks.