Doc/library/platform.rst

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