bpo-23747: Add small note to document default method behavior #31462
Conversation
slateny
changed the title
Doc/library/platform.rst
Outdated
| .. note:: | ||
|
|
||
| Calling a platform-specific method on a mismatched platform will return their | ||
| default values, such as a tuple with empty string values. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Another example: https://bugs.python.org/issue23747#msg238996
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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 '')
Co-authored-by: Victor Stinner <[email protected]>
|
Merged, thanks. |
vstinner
added
needs backport to 3.9
|
Sorry @slateny and @vstinner, I had trouble checking out the |
|
GH-91753 is a backport of this pull request to the 3.9 branch. |
vstinner
added
needs backport to 3.10
|
GH-91754 is a backport of this pull request to the 3.10 branch. |
…31462) (cherry picked from commit ad3ca17) Co-authored-by: slateny <[email protected]>
(cherry picked from commit ad3ca17) Co-authored-by: slateny <[email protected]>
(cherry picked from commit ad3ca17) Co-authored-by: slateny <[email protected]>
…31462) (cherry picked from commit ad3ca17) Co-authored-by: slateny <[email protected]>
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 endhttps://bugs.python.org/issue23747