[Python-checkins] cpython (2.7): Issue #12326: document the recommended idiom for checking sys.platform on Unix

[antoine.pitrou]

http://hg.python.org/cpython/rev/53d2d30d6ca0
changeset:   71284:53d2d30d6ca0
branch:      2.7
parent:      71271:a9c6f468012e
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Sat Jul 09 15:48:29 2011 +0200
summary:
  Issue #12326: document the recommended idiom for checking sys.platform on Unix systems.
Also, point to the various alternatives.

files:
  Doc/library/os.rst  |   7 +++++++
  Doc/library/sys.rst |  12 ++++++++++++
  2 files changed, 19 insertions(+), 0 deletions(-)


diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -53,6 +53,13 @@
    names have currently been registered: ``'posix'``, ``'nt'``,
    ``'os2'``, ``'ce'``, ``'java'``, ``'riscos'``.
 
+   .. seealso::
+      :attr:`sys.platform` has a finer granularity.  :func:`os.uname` gives
+      system-dependent version information.
+
+      The :mod:`platform` module provides detailed checks for the
+      system's identity.
+
 
 .. _os-procinfo:
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -726,6 +726,12 @@
    For Unix systems, this is the lowercased OS name as returned by ``uname -s``
    with the first part of the version as returned by ``uname -r`` appended,
    e.g. ``'sunos5'`` or ``'linux2'``, *at the time when Python was built*.
+   Unless you want to test for a specific system version, it is therefore
+   recommended to use the following idiom::
+
+      if sys.platform.startswith('linux'):
+          # Linux-specific code here...
+
    For other systems, the values are:
 
    ================ ===========================
@@ -740,6 +746,12 @@
    AtheOS           ``'atheos'``
    ================ ===========================
 
+   .. seealso::
+      :attr:`os.name` has a coarser granularity.  :func:`os.uname` gives
+      system-dependent version information.
+
+      The :mod:`platform` module provides detailed checks for the
+      system's identity.
 
 .. data:: prefix
 

-- 
Repository URL: http://hg.python.org/cpython