bpo-23747: Add small note to document default method behavior

[slateny]

Not too sure on the convention for whether the two notes should be bunched together into one or kept separate. Also not too sure on the difference between using :func: vs :meth: as both seem to resolve to the same link in the end

https://bugs.python.org/issue23747

[vstinner]

It's hard to give a global rule for all platform functions. Default values:

• win32_edition() returns None
• win32_is_iot() returns a boolean
• freedesktop_os_release() has no default value, it raises an OSError if the file is missing
• processor() returns an empty string

To be less misleading, maybe you can name a function which returns a tuple of empty strings.

But it's strange to have a global rule saying "by default, return the default value"... but don't actually document the default value of each function... I'm not sure that this addition is helpful.

platform.version() documents its default value. Maybe it's an example to follow?

An empty string is returned if the value cannot be determined.

[vstinner]

Another example: https://bugs.python.org/issue23747#msg238996

[slateny]

My understanding of the bpo is that the return values for these functions are a bit atypical, and as such we want to make note of it so users pay a bit closer attention to the platform and the functions they're using, so maybe we can use weaker language and say 'Calling some platform-specific functions on a mismatched platform may return their default values, such as a tuple with empty string values'.

As for documenting its default value, would all functions be documented with their return values for mismatched platforms? That seems like it might add too much unneeded information and add to maintainability, but it would definitely avoid confusion. I don't feel too strongly either way as both methods seem fine to me, so I'd differ to you on which choice is better here.

[vstinner]

Documenting default value of each function sounds more correct to me than a general note which is either incorrect (if you are too specific about the default value) or unclear (don't say anything about the default value).

[slateny]

Looking at the platform-specific functions on the platform page, win32_ver and win32_edition seem to be the only two functions with unclear return values in the case of using on mismatched platform, so I threw in some documentation for their return values there (and some slight formatting changes above).

I also see that java_ver has this: Values which cannot be determined are set to the defaults given as parameters (which all default to ''), but I'm wondering whether that's correct as vminfo defaults to ('', '', '') instead. Maybe it should say something like ... (which default to an empty string or a tuple of empty strings) or ... (which default to '' or a tuple of '')

[vstinner]

Merged, thanks.

[miss-islington]

Thanks @slateny for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

[miss-islington]

Thanks @slateny for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9.
🐍🍒⛏🤖

[miss-islington]

Sorry @slateny and @vstinner, I had trouble checking out the 3.10 backport branch.
Please backport using cherry_picker on command line.
cherry_picker ad3ca17ff5cd63f907430073b52be27695674148 3.10

[bedevere-bot]

GH-91753 is a backport of this pull request to the 3.9 branch.

[miss-islington]

Thanks @slateny for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

[bedevere-bot]

GH-91754 is a backport of this pull request to the 3.10 branch.