Debian Codegraph @

Doc/library/platform.rst

raw
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.