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       Note: this function works best with Mark Hammond's
 199       :mod:`win32all` package installed, but also on Python 2.3 and
 200       later (support for this was added in Python 2.6). It obviously
 201       only runs on Win32 compatible platforms.
 202
 203
 204 Win95/98 specific
 205 ^^^^^^^^^^^^^^^^^
 206
 207 .. function:: popen(cmd, mode='r', bufsize=None)
 208
 209    Portable :func:`popen` interface.  Find a working popen implementation
 210    preferring :func:`win32pipe.popen`.  On Windows NT, :func:`win32pipe.popen`
 211    should work; on Windows 9x it hangs due to bugs in the MS C library.
 212
 213
 214 Mac OS Platform
 215 ---------------
 216
 217
 218 .. function:: mac_ver(release='', versioninfo=('','',''), machine='')
 219
 220    Get Mac OS version information and return it as tuple ``(release, versioninfo,
 221    machine)`` with *versioninfo* being a tuple ``(version, dev_stage,
 222    non_release_version)``.
 223
 224    Entries which cannot be determined are set to ``''``.  All tuple entries are
 225    strings.
 226
 227    Documentation for the underlying :cfunc:`gestalt` API is available online at
 228    http://www.rgaros.nl/gestalt/.
 229
 230
 231 Unix Platforms
 232 --------------
 233
 234
 235 .. function:: dist(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...))
 236
 237    This is an old version of the functionality now provided by
 238    :func:`linux_distribution`. For new code, please use the
 239    :func:`linux_distribution`.
 240
 241    The only difference between the two is that ``dist()`` always
 242    returns the short name of the distribution taken from the
 243    ``supported_dists`` parameter.
 244
 245    .. deprecated:: 2.6
 246
 247 .. function:: linux_distribution(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...), full_distribution_name=1)
 248
 249    Tries to determine the name of the Linux OS distribution name.
 250
 251    ``supported_dists`` may be given to define the set of Linux distributions to
 252    look for. It defaults to a list of currently supported Linux distributions
 253    identified by their release file name.
 254
 255    If ``full_distribution_name`` is true (default), the full distribution read
 256    from the OS is returned. Otherwise the short name taken from
 257    ``supported_dists`` is used.
 258
 259    Returns a tuple ``(distname,version,id)`` which defaults to the args given as
 260    parameters.  ``id`` is the item in parentheses after the version number.  It
 261    is usually the version codename.
 262
 263    .. versionadded:: 2.6
 264
 265 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)
 266
 267    Tries to determine the libc version against which the file executable (defaults
 268    to the Python interpreter) is linked.  Returns a tuple of strings ``(lib,
 269    version)`` which default to the given parameters in case the lookup fails.
 270
 271    Note that this function has intimate knowledge of how different libc versions
 272    add symbols to the executable is probably only usable for executables compiled
 273    using :program:`gcc`.
 274
 275    The file is read and scanned in chunks of *chunksize* bytes.
 276