Doc/library/platform.rst

   1
   2 :mod:`platform` ---  Access to underlying platform's identifying data.
   3 ======================================================================
   4
   5 .. module:: platform
   6    :synopsis: Retrieves as much platform identifying data as possible.
   7 .. moduleauthor:: Marc-Andre Lemburg <mal@egenix.com>
   8 .. sectionauthor:: Bjorn Pettersen <bpettersen@corp.fairisaac.com>
   9
  10
  11 .. versionadded:: 2.3
  12
  13 .. note::
  14
  15    Specific platforms listed alphabetically, with Linux included in the Unix
  16    section.
  17
  18
  19 Cross Platform
  20 --------------
  21
  22
  23 .. function:: architecture(executable=sys.executable, bits='', linkage='')
  24
  25    Queries the given executable (defaults to the Python interpreter binary) for
  26    various architecture information.
  27
  28    Returns a tuple ``(bits, linkage)`` which contain information about the bit
  29    architecture and the linkage format used for the executable. Both values are
  30    returned as strings.
  31
  32    Values that cannot be determined are returned as given by the parameter presets.
  33    If bits is given as ``''``, the :cfunc:`sizeof(pointer)` (or
  34    :cfunc:`sizeof(long)` on Python version < 1.5.2) is used as indicator for the
  35    supported pointer size.
  36
  37    The function relies on the system's :file:`file` command to do the actual work.
  38    This is available on most if not all Unix  platforms and some non-Unix platforms
  39    and then only if the executable points to the Python interpreter.  Reasonable
  40    defaults are used when the above needs are not met.
  41
  42
  43 .. function:: machine()
  44
  45    Returns the machine type, e.g. ``'i386'``. An empty string is returned if the
  46    value cannot be determined.
  47
  48
  49 .. function:: node()
  50
  51    Returns the computer's network name (may not be fully qualified!). An empty
  52    string is returned if the value cannot be determined.
  53
  54
  55 .. function:: platform(aliased=0, terse=0)
  56
  57    Returns a single string identifying the underlying platform with as much useful
  58    information as possible.
  59
  60    The output is intended to be *human readable* rather than machine parseable. It
  61    may look different on different platforms and this is intended.
  62
  63    If *aliased* is true, the function will use aliases for various platforms that
  64    report system names which differ from their common names, for example SunOS will
  65    be reported as Solaris.  The :func:`system_alias` function is used to implement
  66    this.
  67
  68    Setting *terse* to true causes the function to return only the absolute minimum
  69    information needed to identify the platform.
  70
  71
  72 .. function:: processor()
  73
  74    Returns the (real) processor name, e.g. ``'amdk6'``.
  75
  76    An empty string is returned if the value cannot be determined. Note that many
  77    platforms do not provide this information or simply return the same value as for
  78    :func:`machine`.  NetBSD does this.
  79
  80
  81 .. function:: python_build()
  82
  83    Returns a tuple ``(buildno, builddate)`` stating the Python build number and
  84    date as strings.
  85
  86
  87 .. function:: python_compiler()
  88
  89    Returns a string identifying the compiler used for compiling Python.
  90
  91
  92 .. function:: python_branch()
  93
  94    Returns a string identifying the Python implementation SCM branch.
  95
  96    .. versionadded:: 2.6
  97
  98
  99 .. function:: python_implementation()
 100
 101    Returns a string identifying the Python implementation. Possible return values
 102    are: 'CPython', 'IronPython', 'Jython'
 103
 104    .. versionadded:: 2.6
 105
 106
 107 .. function:: python_revision()
 108
 109    Returns a string identifying the Python implementation SCM revision.
 110
 111    .. versionadded:: 2.6
 112
 113
 114 .. function:: python_version()
 115
 116    Returns the Python version as string ``'major.minor.patchlevel'``
 117
 118    Note that unlike the Python ``sys.version``, the returned value will always
 119    include the patchlevel (it defaults to 0).
 120
 121
 122 .. function:: python_version_tuple()
 123
 124    Returns the Python version as tuple ``(major, minor, patchlevel)`` of strings.
 125
 126    Note that unlike the Python ``sys.version``, the returned value will always
 127    include the patchlevel (it defaults to ``'0'``).
 128
 129
 130 .. function:: release()
 131
 132    Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'`` An empty string is
 133    returned if the value cannot be determined.
 134
 135
 136 .. function:: system()
 137
 138    Returns the system/OS name, e.g. ``'Linux'``, ``'Windows'``, or ``'Java'``. An
 139    empty string is returned if the value cannot be determined.
 140
 141
 142 .. function:: system_alias(system, release, version)
 143
 144    Returns ``(system, release, version)`` aliased to common marketing names used
 145    for some systems.  It also does some reordering of the information in some cases
 146    where it would otherwise cause confusion.
 147
 148
 149 .. function:: version()
 150
 151    Returns the system's release version, e.g. ``'#3 on degas'``. An empty string is
 152    returned if the value cannot be determined.
 153
 154
 155 .. function:: uname()
 156
 157    Fairly portable uname interface. Returns a tuple of strings ``(system, node,
 158    release, version, machine, processor)`` identifying the underlying platform.
 159
 160    Note that unlike the :func:`os.uname` function this also returns possible
 161    processor information as additional tuple entry.
 162
 163    Entries which cannot be determined are set to ``''``.
 164
 165
 166 Java Platform
 167 -------------
 168
 169
 170 .. function:: java_ver(release='', vendor='', vminfo=('','',''), osinfo=('','',''))
 171
 172    Version interface for JPython.
 173
 174    Returns a tuple ``(release, vendor, vminfo, osinfo)`` with *vminfo* being a
 175    tuple ``(vm_name, vm_release, vm_vendor)`` and *osinfo* being a tuple
 176    ``(os_name, os_version, os_arch)``. Values which cannot be determined are set to
 177    the defaults given as parameters (which all default to ``''``).
 178
 179
 180 Windows Platform
 181 ----------------
 182
 183
 184 .. function:: win32_ver(release='', version='', csd='', ptype='')
 185
 186    Get additional version information from the Windows Registry and return a tuple
 187    ``(version, csd, ptype)`` referring to version number, CSD level and OS type
 188    (multi/single processor).
 189
 190    As a hint: *ptype* is ``'Uniprocessor Free'`` on single processor NT machines
 191    and ``'Multiprocessor Free'`` on multi processor machines. The *'Free'* refers
 192    to the OS version being free of debugging code. It could also state *'Checked'*
 193    which means the OS version uses debugging code, i.e. code that checks arguments,
 194    ranges, etc.
 195
 196    .. note::
 197
 198       This function only works if Mark Hammond's :mod:`win32all` package is installed
 199       and (obviously) only runs on Win32 compatible platforms.
 200
 201
 202 Win95/98 specific
 203 ^^^^^^^^^^^^^^^^^
 204
 205 .. function:: popen(cmd, mode='r', bufsize=None)
 206
 207    Portable :func:`popen` interface.  Find a working popen implementation
 208    preferring :func:`win32pipe.popen`.  On Windows NT, :func:`win32pipe.popen`
 209    should work; on Windows 9x it hangs due to bugs in the MS C library.
 210
 211
 212 Mac OS Platform
 213 ---------------
 214
 215
 216 .. function:: mac_ver(release='', versioninfo=('','',''), machine='')
 217
 218    Get Mac OS version information and return it as tuple ``(release, versioninfo,
 219    machine)`` with *versioninfo* being a tuple ``(version, dev_stage,
 220    non_release_version)``.
 221
 222    Entries which cannot be determined are set to ``''``.  All tuple entries are
 223    strings.
 224
 225    Documentation for the underlying :cfunc:`gestalt` API is available online at
 226    http://www.rgaros.nl/gestalt/.
 227
 228
 229 Unix Platforms
 230 --------------
 231
 232
 233 .. function:: dist(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake'))
 234
 235    Tries to determine the name of the OS distribution name Returns a tuple
 236    ``(distname, version, id)`` which defaults to the args given as parameters.
 237
 238 .. XXX Document linux_distribution()?
 239
 240
 241 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)
 242
 243    Tries to determine the libc version against which the file executable (defaults
 244    to the Python interpreter) is linked.  Returns a tuple of strings ``(lib,
 245    version)`` which default to the given parameters in case the lookup fails.
 246
 247    Note that this function has intimate knowledge of how different libc versions
 248    add symbols to the executable is probably only useable for executables compiled
 249    using :program:`gcc`.
 250
 251    The file is read and scanned in chunks of *chunksize* bytes.
 252