This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: help for a module should list supported platforms
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, amaury.forgeotdarc, georg.brandl, rickysarraf, terry.reedy
Priority: normal Keywords:

Created on 2009-09-02 16:43 by rickysarraf, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (9)
msg92173 - (view) Author: Ritesh Raj Sarraf (rickysarraf) Date: 2009-09-02 16:42
Whey I do a help (python-module), I get the help text as follows:

Help on module tempfile:

NAME
    tempfile - Temporary files.

FILE
    /usr/lib/python2.5/tempfile.py

MODULE DOCS
    http://www.python.org/doc/2.5.4/lib/module-tempfile.html

DESCRIPTION
    This module provides generic, low- and high-level interfaces for
    creating temporary files and directories.  The interfaces listed
    as "safe" just below can be used without fear of race conditions.
    Those listed as "unsafe" cannot, and are provided for backward
    compatibility only.

The link to the webpage lists the supported platforms for the module.
It would be good to have an entry stating the list of platforms supported
by the module, in the module doc itself.
msg92226 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2009-09-03 23:11
I'm not sure to understand. The web page says the module "works on all 
supported platforms." Many python features works equally well on all 
platforms, and I don't feel necessary to repeat this everywhere.
The differences between platforms are more interesting IMO.
msg92231 - (view) Author: Ritesh Raj Sarraf (rickysarraf) Date: 2009-09-04 05:04
Take "help os" or "help os.fork" for example.

WIth the help output that they provide, how am I supposed to know that
os.fork is only supported on Unix.

We can also go with the assumption that the modules shipped are
cross-platform. But then, for those that aren't, I don't think we mention
that in the help file documentation.
msg92236 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2009-09-04 07:31
What makes you think that the tempfile module is not cross-platform?
msg92240 - (view) Author: Ritesh Raj Sarraf (rickysarraf) Date: 2009-09-04 07:58
I never said that I think it is not cross-platform.

My point is, it should be good to list down a module's dependency in the
python help docs.

Like:
tempfile

Supported Platforms: ALL
Exception: On Platform foo, feature tempfile.bar() is not available.
msg92264 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2009-09-04 19:03
*most* modules are platform independent, and for those, I do not think
anything needs to be said. 

I agree with OP that it would be nice if interactive help indicated
platform dependencies, if and when such is not done now. I have no idea
if any of such addition could be easily automated.
msg109130 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-02 20:42
>WIth the help output that they provide, how am I supposed to know that
os.fork is only supported on Unix.

On windows, os.fork does not exist, so help(os.fork) fails, so it is obvious to me that it is not available on Windows ;-).

help(winreg) returns
"help(winreg)
Help on built-in module winreg:

NAME
    winreg - This module provides access to the Windows registry API."

One could, for example, suggest "add 'Windows-only' between 'This' and 'module' in the module doc string that follows the name." This is not needed here because 'Windows' appears later. 

However, if you want to move this issue forward, use the quoted example as a model for a list of specific suggestions for objects specific to platforms you have access to. (For instance, I cannot easily get the os.fork doc string to see what it now says.) User suggestions are the main way existing docs get improved.

In other words, check the existing doc string and see if it is deficient. If it is, quote is and suggest a change. If the suggested change is the same for several objects, list and quote several and then make the suggestion, such as "insert 'unix-only' before 'module'."
msg241633 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2015-04-20 11:28
As there was no reply to msg109130 (nearly five years ago) can we close this as won't fix?
msg241686 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-04-20 21:00
I agree.  The resolution is that help fails for objects that do not exist on the platform.  We do not supply non-functional dummy objects that only exist to document non-support.  Any objects with undocumented platform-specific behavior should be handled on a case-by-case basis.
History
Date User Action Args
2022-04-11 14:56:52adminsetgithub: 51073
2015-04-20 21:00:23terry.reedysetstatus: open -> closed
resolution: works for me
messages: + msg241686

stage: resolved
2015-04-20 11:28:59BreamoreBoysetnosy: + BreamoreBoy
messages: + msg241633
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-08-07 18:20:02terry.reedysetversions: - Python 2.6, Python 3.1, Python 2.7
2010-07-02 20:42:28terry.reedysetmessages: + msg109130
2009-09-04 19:03:30terry.reedysetnosy: + terry.reedy

messages: + msg92264
versions: + Python 2.6, Python 3.1, Python 2.7, Python 3.2, - Python 2.5
2009-09-04 07:58:20rickysarrafsetmessages: + msg92240
2009-09-04 07:31:24amaury.forgeotdarcsetmessages: + msg92236
2009-09-04 05:04:30rickysarrafsetmessages: + msg92231
2009-09-03 23:11:19amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg92226
2009-09-02 16:43:43rickysarrafsettype: enhancement
2009-09-02 16:43:00rickysarrafcreate