| 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 |
|
| 7 |
.. moduleauthor:: Marc-André Lemburg <[email protected]> |
| 8 |
.. sectionauthor:: Bjorn Pettersen <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/platform.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
.. note:: |
| 15 |
|
| 16 |
Specific platforms listed alphabetically, with Linux included in the Unix |
| 17 |
section. |
| 18 |
|
| 19 |
|
| 20 |
Cross platform |
| 21 |
-------------- |
| 22 |
|
| 23 |
|
| 24 |
.. function:: architecture(executable=sys.executable, bits='', linkage='') |
| 25 |
|
| 26 |
Queries the given executable (defaults to the Python interpreter binary) for |
| 27 |
various architecture information. |
| 28 |
|
| 29 |
Returns a tuple ``(bits, linkage)`` which contain information about the bit |
| 30 |
architecture and the linkage format used for the executable. Both values are |
| 31 |
returned as strings. |
| 32 |
|
| 33 |
Values that cannot be determined are returned as given by the parameter presets. |
| 34 |
If bits is given as ``''``, the ``sizeof(pointer)`` (or |
| 35 |
``sizeof(long)`` on Python version < 1.5.2) is used as indicator for the |
| 36 |
supported pointer size. |
| 37 |
|
| 38 |
The function relies on the system's :file:`file` command to do the actual work. |
| 39 |
This is available on most if not all Unix platforms and some non-Unix platforms |
| 40 |
and then only if the executable points to the Python interpreter. Reasonable |
| 41 |
defaults are used when the above needs are not met. |
| 42 |
|
| 43 |
.. note:: |
| 44 |
|
| 45 |
On macOS (and perhaps other platforms), executable files may be |
| 46 |
universal files containing multiple architectures. |
| 47 |
|
| 48 |
To get at the "64-bitness" of the current interpreter, it is more |
| 49 |
reliable to query the :data:`sys.maxsize` attribute:: |
| 50 |
|
| 51 |
is_64bits = sys.maxsize > 2**32 |
| 52 |
|
| 53 |
|
| 54 |
.. function:: machine() |
| 55 |
|
| 56 |
Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the |
| 57 |
value cannot be determined. |
| 58 |
|
| 59 |
The output is platform-dependent and may differ in casing and naming conventions. |
| 60 |
|
| 61 |
|
| 62 |
.. function:: node() |
| 63 |
|
| 64 |
Returns the computer's network name (may not be fully qualified!). An empty |
| 65 |
string is returned if the value cannot be determined. |
| 66 |
|
| 67 |
|
| 68 |
.. function:: platform(aliased=False, terse=False) |
| 69 |
|
| 70 |
Returns a single string identifying the underlying platform with as much useful |
| 71 |
information as possible. |
| 72 |
|
| 73 |
The output is intended to be *human readable* rather than machine parseable. It |
| 74 |
may look different on different platforms and this is intended. |
| 75 |
|
| 76 |
If *aliased* is true, the function will use aliases for various platforms that |
| 77 |
report system names which differ from their common names, for example SunOS will |
| 78 |
be reported as Solaris. The :func:`system_alias` function is used to implement |
| 79 |
this. |
| 80 |
|
| 81 |
Setting *terse* to true causes the function to return only the absolute minimum |
| 82 |
information needed to identify the platform. |
| 83 |
|
| 84 |
.. versionchanged:: 3.8 |
| 85 |
On macOS, the function now uses :func:`mac_ver`, if it returns a |
| 86 |
non-empty release string, to get the macOS version rather than the darwin |
| 87 |
version. |
| 88 |
|
| 89 |
|
| 90 |
.. function:: processor() |
| 91 |
|
| 92 |
Returns the (real) processor name, e.g. ``'amdk6'``. |
| 93 |
|
| 94 |
An empty string is returned if the value cannot be determined. Note that many |
| 95 |
platforms do not provide this information or simply return the same value as for |
| 96 |
:func:`machine`. NetBSD does this. |
| 97 |
|
| 98 |
|
| 99 |
.. function:: python_build() |
| 100 |
|
| 101 |
Returns a tuple ``(buildno, builddate)`` stating the Python build number and |
| 102 |
date as strings. |
| 103 |
|
| 104 |
|
| 105 |
.. function:: python_compiler() |
| 106 |
|
| 107 |
Returns a string identifying the compiler used for compiling Python. |
| 108 |
|
| 109 |
|
| 110 |
.. function:: python_branch() |
| 111 |
|
| 112 |
Returns a string identifying the Python implementation SCM branch. |
| 113 |
|
| 114 |
|
| 115 |
.. function:: python_implementation() |
| 116 |
|
| 117 |
Returns a string identifying the Python implementation. Possible return values |
| 118 |
are: 'CPython', 'IronPython', 'Jython', 'PyPy'. |
| 119 |
|
| 120 |
|
| 121 |
.. function:: python_revision() |
| 122 |
|
| 123 |
Returns a string identifying the Python implementation SCM revision. |
| 124 |
|
| 125 |
|
| 126 |
.. function:: python_version() |
| 127 |
|
| 128 |
Returns the Python version as string ``'major.minor.patchlevel'``. |
| 129 |
|
| 130 |
Note that unlike the Python ``sys.version``, the returned value will always |
| 131 |
include the patchlevel (it defaults to 0). |
| 132 |
|
| 133 |
|
| 134 |
.. function:: python_version_tuple() |
| 135 |
|
| 136 |
Returns the Python version as tuple ``(major, minor, patchlevel)`` of strings. |
| 137 |
|
| 138 |
Note that unlike the Python ``sys.version``, the returned value will always |
| 139 |
include the patchlevel (it defaults to ``'0'``). |
| 140 |
|
| 141 |
|
| 142 |
.. function:: release() |
| 143 |
|
| 144 |
Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'``. An empty string is |
| 145 |
returned if the value cannot be determined. |
| 146 |
|
| 147 |
|
| 148 |
.. function:: system() |
| 149 |
|
| 150 |
Returns the system/OS name, such as ``'Linux'``, ``'Darwin'``, ``'Java'``, |
| 151 |
``'Windows'``. An empty string is returned if the value cannot be determined. |
| 152 |
|
| 153 |
On iOS and Android, this returns the user-facing OS name (i.e, ``'iOS``, |
| 154 |
``'iPadOS'`` or ``'Android'``). To obtain the kernel name (``'Darwin'`` or |
| 155 |
``'Linux'``), use :func:`os.uname`. |
| 156 |
|
| 157 |
.. function:: system_alias(system, release, version) |
| 158 |
|
| 159 |
Returns ``(system, release, version)`` aliased to common marketing names used |
| 160 |
for some systems. It also does some reordering of the information in some cases |
| 161 |
where it would otherwise cause confusion. |
| 162 |
|
| 163 |
|
| 164 |
.. function:: version() |
| 165 |
|
| 166 |
Returns the system's release version, e.g. ``'#3 on degas'``. An empty string is |
| 167 |
returned if the value cannot be determined. |
| 168 |
|
| 169 |
On iOS and Android, this is the user-facing OS version. To obtain the |
| 170 |
Darwin or Linux kernel version, use :func:`os.uname`. |
| 171 |
|
| 172 |
.. function:: uname() |
| 173 |
|
| 174 |
Fairly portable uname interface. Returns a :func:`~collections.namedtuple` |
| 175 |
containing six attributes: :attr:`system`, :attr:`node`, :attr:`release`, |
| 176 |
:attr:`version`, :attr:`machine`, and :attr:`processor`. |
| 177 |
|
| 178 |
:attr:`processor` is resolved late, on demand. |
| 179 |
|
| 180 |
Note: the first two attribute names differ from the names presented by |
| 181 |
:func:`os.uname`, where they are named :attr:`!sysname` and |
| 182 |
:attr:`!nodename`. |
| 183 |
|
| 184 |
Entries which cannot be determined are set to ``''``. |
| 185 |
|
| 186 |
.. versionchanged:: 3.3 |
| 187 |
Result changed from a tuple to a :func:`~collections.namedtuple`. |
| 188 |
|
| 189 |
.. versionchanged:: 3.9 |
| 190 |
:attr:`processor` is resolved late instead of immediately. |
| 191 |
|
| 192 |
.. function:: invalidate_caches() |
| 193 |
|
| 194 |
Clear out the internal cache of information, such as the :func:`uname`. |
| 195 |
This is typically useful when the platform's :func:`node` is changed |
| 196 |
by an external process and one needs to retrieve the updated value. |
| 197 |
|
| 198 |
.. versionadded:: 3.14 |
| 199 |
|
| 200 |
|
| 201 |
Java platform |
| 202 |
------------- |
| 203 |
|
| 204 |
|
| 205 |
.. function:: java_ver(release='', vendor='', vminfo=('','',''), osinfo=('','','')) |
| 206 |
|
| 207 |
Version interface for Jython. |
| 208 |
|
| 209 |
Returns a tuple ``(release, vendor, vminfo, osinfo)`` with *vminfo* being a |
| 210 |
tuple ``(vm_name, vm_release, vm_vendor)`` and *osinfo* being a tuple |
| 211 |
``(os_name, os_version, os_arch)``. Values which cannot be determined are set to |
| 212 |
the defaults given as parameters (which all default to ``''``). |
| 213 |
|
| 214 |
.. deprecated-removed:: 3.13 3.15 |
| 215 |
It was largely untested, had a confusing API, |
| 216 |
and was only useful for Jython support. |
| 217 |
|
| 218 |
|
| 219 |
Windows platform |
| 220 |
---------------- |
| 221 |
|
| 222 |
|
| 223 |
.. function:: win32_ver(release='', version='', csd='', ptype='') |
| 224 |
|
| 225 |
Get additional version information from the Windows Registry and return a tuple |
| 226 |
``(release, version, csd, ptype)`` referring to OS release, version number, |
| 227 |
CSD level (service pack) and OS type (multi/single processor). Values which |
| 228 |
cannot be determined are set to the defaults given as parameters (which all |
| 229 |
default to an empty string). |
| 230 |
|
| 231 |
As a hint: *ptype* is ``'Uniprocessor Free'`` on single processor NT machines |
| 232 |
and ``'Multiprocessor Free'`` on multi processor machines. The ``'Free'`` refers |
| 233 |
to the OS version being free of debugging code. It could also state ``'Checked'`` |
| 234 |
which means the OS version uses debugging code, i.e. code that checks arguments, |
| 235 |
ranges, etc. |
| 236 |
|
| 237 |
.. function:: win32_edition() |
| 238 |
|
| 239 |
Returns a string representing the current Windows edition, or ``None`` if the |
| 240 |
value cannot be determined. Possible values include but are not limited to |
| 241 |
``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'``, and ``'nanoserver'``. |
| 242 |
|
| 243 |
.. versionadded:: 3.8 |
| 244 |
|
| 245 |
.. function:: win32_is_iot() |
| 246 |
|
| 247 |
Return ``True`` if the Windows edition returned by :func:`win32_edition` |
| 248 |
is recognized as an IoT edition. |
| 249 |
|
| 250 |
.. versionadded:: 3.8 |
| 251 |
|
| 252 |
|
| 253 |
macOS platform |
| 254 |
-------------- |
| 255 |
|
| 256 |
.. function:: mac_ver(release='', versioninfo=('','',''), machine='') |
| 257 |
|
| 258 |
Get macOS version information and return it as tuple ``(release, versioninfo, |
| 259 |
machine)`` with *versioninfo* being a tuple ``(version, dev_stage, |
| 260 |
non_release_version)``. |
| 261 |
|
| 262 |
Entries which cannot be determined are set to ``''``. All tuple entries are |
| 263 |
strings. |
| 264 |
|
| 265 |
iOS platform |
| 266 |
------------ |
| 267 |
|
| 268 |
.. function:: ios_ver(system='', release='', model='', is_simulator=False) |
| 269 |
|
| 270 |
Get iOS version information and return it as a |
| 271 |
:func:`~collections.namedtuple` with the following attributes: |
| 272 |
|
| 273 |
* ``system`` is the OS name; either ``'iOS'`` or ``'iPadOS'``. |
| 274 |
* ``release`` is the iOS version number as a string (e.g., ``'17.2'``). |
| 275 |
* ``model`` is the device model identifier; this will be a string like |
| 276 |
``'iPhone13,2'`` for a physical device, or ``'iPhone'`` on a simulator. |
| 277 |
* ``is_simulator`` is a boolean describing if the app is running on a |
| 278 |
simulator or a physical device. |
| 279 |
|
| 280 |
Entries which cannot be determined are set to the defaults given as |
| 281 |
parameters. |
| 282 |
|
| 283 |
|
| 284 |
Unix platforms |
| 285 |
-------------- |
| 286 |
|
| 287 |
.. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=16384) |
| 288 |
|
| 289 |
Tries to determine the libc version against which the file executable (defaults |
| 290 |
to the Python interpreter) is linked. Returns a tuple of strings ``(lib, |
| 291 |
version)`` which default to the given parameters in case the lookup fails. |
| 292 |
|
| 293 |
Note that this function has intimate knowledge of how different libc versions |
| 294 |
add symbols to the executable is probably only usable for executables compiled |
| 295 |
using :program:`gcc`. |
| 296 |
|
| 297 |
The file is read and scanned in chunks of *chunksize* bytes. |
| 298 |
|
| 299 |
|
| 300 |
Linux platforms |
| 301 |
--------------- |
| 302 |
|
| 303 |
.. function:: freedesktop_os_release() |
| 304 |
|
| 305 |
Get operating system identification from ``os-release`` file and return |
| 306 |
it as a dict. The ``os-release`` file is a `freedesktop.org standard |
| 307 |
<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ and |
| 308 |
is available in most Linux distributions. A noticeable exception is |
| 309 |
Android and Android-based distributions. |
| 310 |
|
| 311 |
Raises :exc:`OSError` or subclass when neither ``/etc/os-release`` nor |
| 312 |
``/usr/lib/os-release`` can be read. |
| 313 |
|
| 314 |
On success, the function returns a dictionary where keys and values are |
| 315 |
strings. Values have their special characters like ``"`` and ``$`` |
| 316 |
unquoted. The fields ``NAME``, ``ID``, and ``PRETTY_NAME`` are always |
| 317 |
defined according to the standard. All other fields are optional. Vendors |
| 318 |
may include additional fields. |
| 319 |
|
| 320 |
Note that fields like ``NAME``, ``VERSION``, and ``VARIANT`` are strings |
| 321 |
suitable for presentation to users. Programs should use fields like |
| 322 |
``ID``, ``ID_LIKE``, ``VERSION_ID``, or ``VARIANT_ID`` to identify |
| 323 |
Linux distributions. |
| 324 |
|
| 325 |
Example:: |
| 326 |
|
| 327 |
def get_like_distro(): |
| 328 |
info = platform.freedesktop_os_release() |
| 329 |
ids = [info["ID"]] |
| 330 |
if "ID_LIKE" in info: |
| 331 |
# ids are space separated and ordered by precedence |
| 332 |
ids.extend(info["ID_LIKE"].split()) |
| 333 |
return ids |
| 334 |
|
| 335 |
.. versionadded:: 3.10 |
| 336 |
|
| 337 |
|
| 338 |
Android platform |
| 339 |
---------------- |
| 340 |
|
| 341 |
.. function:: android_ver(release="", api_level=0, manufacturer="", \ |
| 342 |
model="", device="", is_emulator=False) |
| 343 |
|
| 344 |
Get Android device information. Returns a :func:`~collections.namedtuple` |
| 345 |
with the following attributes. Values which cannot be determined are set to |
| 346 |
the defaults given as parameters. |
| 347 |
|
| 348 |
* ``release`` - Android version, as a string (e.g. ``"14"``). |
| 349 |
|
| 350 |
* ``api_level`` - API level of the running device, as an integer (e.g. ``34`` |
| 351 |
for Android 14). To get the API level which Python was built against, see |
| 352 |
:func:`sys.getandroidapilevel`. |
| 353 |
|
| 354 |
* ``manufacturer`` - `Manufacturer name |
| 355 |
<https://developer.android.com/reference/android/os/Build#MANUFACTURER>`__. |
| 356 |
|
| 357 |
* ``model`` - `Model name |
| 358 |
<https://developer.android.com/reference/android/os/Build#MODEL>`__ – |
| 359 |
typically the marketing name or model number. |
| 360 |
|
| 361 |
* ``device`` - `Device name |
| 362 |
<https://developer.android.com/reference/android/os/Build#DEVICE>`__ – |
| 363 |
typically the model number or a codename. |
| 364 |
|
| 365 |
* ``is_emulator`` - ``True`` if the device is an emulator; ``False`` if it's |
| 366 |
a physical device. |
| 367 |
|
| 368 |
Google maintains a `list of known model and device names |
| 369 |
<https://storage.googleapis.com/play_public/supported_devices.html>`__. |
| 370 |
|
| 371 |
.. versionadded:: 3.13 |
| 372 |
|
| 373 |
.. _platform-cli: |
| 374 |
|
| 375 |
Command-line usage |
| 376 |
------------------ |
| 377 |
|
| 378 |
:mod:`!platform` can also be invoked directly using the :option:`-m` |
| 379 |
switch of the interpreter:: |
| 380 |
|
| 381 |
python -m platform [--terse] [--nonaliased] [{nonaliased,terse} ...] |
| 382 |
|
| 383 |
The following options are accepted: |
| 384 |
|
| 385 |
.. program:: platform |
| 386 |
|
| 387 |
.. option:: --terse |
| 388 |
|
| 389 |
Print terse information about the platform. This is equivalent to |
| 390 |
calling :func:`platform.platform` with the *terse* argument set to ``True``. |
| 391 |
|
| 392 |
.. option:: --nonaliased |
| 393 |
|
| 394 |
Print platform information without system/OS name aliasing. This is |
| 395 |
equivalent to calling :func:`platform.platform` with the *aliased* argument |
| 396 |
set to ``True``. |
| 397 |
|
| 398 |
You can also pass one or more positional arguments (``terse``, ``nonaliased``) |
| 399 |
to explicitly control the output format. These behave similarly to their |
| 400 |
corresponding options. |