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 On iOS and Android, this is the user-facing OS release. To obtain the
148 Darwin or Linux kernel release, use :func:`os.uname`.
149
150 .. function:: system()
151
152 Returns the system/OS name, such as ``'Linux'``, ``'Darwin'``, ``'Java'``,
153 ``'Windows'``. An empty string is returned if the value cannot be determined.
154
155 On iOS and Android, this returns the user-facing OS name (i.e, ``'iOS``,
156 ``'iPadOS'`` or ``'Android'``). To obtain the kernel name (``'Darwin'`` or
157 ``'Linux'``), use :func:`os.uname`.
158
159 .. function:: system_alias(system, release, version)
160
161 Returns ``(system, release, version)`` aliased to common marketing names used
162 for some systems. It also does some reordering of the information in some cases
163 where it would otherwise cause confusion.
164
165
166 .. function:: version()
167
168 Returns the system's release version, e.g. ``'#3 on degas'``. An empty string is
169 returned if the value cannot be determined.
170
171 .. function:: uname()
172
173 Fairly portable uname interface. Returns a :func:`~collections.namedtuple`
174 containing six attributes: :attr:`system`, :attr:`node`, :attr:`release`,
175 :attr:`version`, :attr:`machine`, and :attr:`processor`.
176
177 :attr:`processor` is resolved late, on demand.
178
179 Note: the first two attribute names differ from the names presented by
180 :func:`os.uname`, where they are named :attr:`!sysname` and
181 :attr:`!nodename`.
182
183 Entries which cannot be determined are set to ``''``.
184
185 .. versionchanged:: 3.3
186 Result changed from a tuple to a :func:`~collections.namedtuple`.
187
188 .. versionchanged:: 3.9
189 :attr:`processor` is resolved late instead of immediately.
190
191
192 Java platform
193 -------------
194
195
196 .. function:: java_ver(release='', vendor='', vminfo=('','',''), osinfo=('','',''))
197
198 Version interface for Jython.
199
200 Returns a tuple ``(release, vendor, vminfo, osinfo)`` with *vminfo* being a
201 tuple ``(vm_name, vm_release, vm_vendor)`` and *osinfo* being a tuple
202 ``(os_name, os_version, os_arch)``. Values which cannot be determined are set to
203 the defaults given as parameters (which all default to ``''``).
204
205 .. deprecated-removed:: 3.13 3.15
206 It was largely untested, had a confusing API,
207 and was only useful for Jython support.
208
209
210 Windows platform
211 ----------------
212
213
214 .. function:: win32_ver(release='', version='', csd='', ptype='')
215
216 Get additional version information from the Windows Registry and return a tuple
217 ``(release, version, csd, ptype)`` referring to OS release, version number,
218 CSD level (service pack) and OS type (multi/single processor). Values which
219 cannot be determined are set to the defaults given as parameters (which all
220 default to an empty string).
221
222 As a hint: *ptype* is ``'Uniprocessor Free'`` on single processor NT machines
223 and ``'Multiprocessor Free'`` on multi processor machines. The ``'Free'`` refers
224 to the OS version being free of debugging code. It could also state ``'Checked'``
225 which means the OS version uses debugging code, i.e. code that checks arguments,
226 ranges, etc.
227
228 .. function:: win32_edition()
229
230 Returns a string representing the current Windows edition, or ``None`` if the
231 value cannot be determined. Possible values include but are not limited to
232 ``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'``, and ``'nanoserver'``.
233
234 .. versionadded:: 3.8
235
236 .. function:: win32_is_iot()
237
238 Return ``True`` if the Windows edition returned by :func:`win32_edition`
239 is recognized as an IoT edition.
240
241 .. versionadded:: 3.8
242
243
244 macOS platform
245 --------------
246
247 .. function:: mac_ver(release='', versioninfo=('','',''), machine='')
248
249 Get macOS version information and return it as tuple ``(release, versioninfo,
250 machine)`` with *versioninfo* being a tuple ``(version, dev_stage,
251 non_release_version)``.
252
253 Entries which cannot be determined are set to ``''``. All tuple entries are
254 strings.
255
256 iOS platform
257 ------------
258
259 .. function:: ios_ver(system='', release='', model='', is_simulator=False)
260
261 Get iOS version information and return it as a
262 :func:`~collections.namedtuple` with the following attributes:
263
264 * ``system`` is the OS name; either ``'iOS'`` or ``'iPadOS'``.
265 * ``release`` is the iOS version number as a string (e.g., ``'17.2'``).
266 * ``model`` is the device model identifier; this will be a string like
267 ``'iPhone13,2'`` for a physical device, or ``'iPhone'`` on a simulator.
268 * ``is_simulator`` is a boolean describing if the app is running on a
269 simulator or a physical device.
270
271 Entries which cannot be determined are set to the defaults given as
272 parameters.
273
274
275 Unix platforms
276 --------------
277
278 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=16384)
279
280 Tries to determine the libc version against which the file executable (defaults
281 to the Python interpreter) is linked. Returns a tuple of strings ``(lib,
282 version)`` which default to the given parameters in case the lookup fails.
283
284 Note that this function has intimate knowledge of how different libc versions
285 add symbols to the executable is probably only usable for executables compiled
286 using :program:`gcc`.
287
288 The file is read and scanned in chunks of *chunksize* bytes.
289
290
291 Linux platforms
292 ---------------
293
294 .. function:: freedesktop_os_release()
295
296 Get operating system identification from ``os-release`` file and return
297 it as a dict. The ``os-release`` file is a `freedesktop.org standard
298 <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ and
299 is available in most Linux distributions. A noticeable exception is
300 Android and Android-based distributions.
301
302 Raises :exc:`OSError` or subclass when neither ``/etc/os-release`` nor
303 ``/usr/lib/os-release`` can be read.
304
305 On success, the function returns a dictionary where keys and values are
306 strings. Values have their special characters like ``"`` and ``$``
307 unquoted. The fields ``NAME``, ``ID``, and ``PRETTY_NAME`` are always
308 defined according to the standard. All other fields are optional. Vendors
309 may include additional fields.
310
311 Note that fields like ``NAME``, ``VERSION``, and ``VARIANT`` are strings
312 suitable for presentation to users. Programs should use fields like
313 ``ID``, ``ID_LIKE``, ``VERSION_ID``, or ``VARIANT_ID`` to identify
314 Linux distributions.
315
316 Example::
317
318 def get_like_distro():
319 info = platform.freedesktop_os_release()
320 ids = [info["ID"]]
321 if "ID_LIKE" in info:
322 # ids are space separated and ordered by precedence
323 ids.extend(info["ID_LIKE"].split())
324 return ids
325
326 .. versionadded:: 3.10
327
328
329 Android platform
330 ----------------
331
332 .. function:: android_ver(release="", api_level=0, manufacturer="", \
333 model="", device="", is_emulator=False)
334
335 Get Android device information. Returns a :func:`~collections.namedtuple`
336 with the following attributes. Values which cannot be determined are set to
337 the defaults given as parameters.
338
339 * ``release`` - Android version, as a string (e.g. ``"14"``).
340
341 * ``api_level`` - API level of the running device, as an integer (e.g. ``34``
342 for Android 14). To get the API level which Python was built against, see
343 :func:`sys.getandroidapilevel`.
344
345 * ``manufacturer`` - `Manufacturer name
346 <https://developer.android.com/reference/android/os/Build#MANUFACTURER>`__.
347
348 * ``model`` - `Model name
349 <https://developer.android.com/reference/android/os/Build#MODEL>`__ –
350 typically the marketing name or model number.
351
352 * ``device`` - `Device name
353 <https://developer.android.com/reference/android/os/Build#DEVICE>`__ –
354 typically the model number or a codename.
355
356 * ``is_emulator`` - ``True`` if the device is an emulator; ``False`` if it's
357 a physical device.
358
359 Google maintains a `list of known model and device names
360 <https://storage.googleapis.com/play_public/supported_devices.html>`__.
361
362 .. versionadded:: 3.13
363
364 .. _platform-cli:
365
366 Command-line usage
367 ------------------
368
369 :mod:`platform` can also be invoked directly using the :option:`-m`
370 switch of the interpreter::
371
372 python -m platform [--terse] [--nonaliased] [{nonaliased,terse} ...]
373
374 The following options are accepted:
375
376 .. program:: platform
377
378 .. option:: --terse
379
380 Print terse information about the platform. This is equivalent to
381 calling :func:`platform.platform` with the *terse* argument set to ``True``.
382
383 .. option:: --nonaliased
384
385 Print platform information without system/OS name aliasing. This is
386 equivalent to calling :func:`platform.platform` with the *aliased* argument
387 set to ``True``.
388
389 You can also pass one or more positional arguments (``terse``, ``nonaliased``)
390 to explicitly control the output format. These behave similarly to their
391 corresponding options.