| 1 |
.. _library-intro: |
| 2 |
|
| 3 |
************ |
| 4 |
Introduction |
| 5 |
************ |
| 6 |
|
| 7 |
The "Python library" contains several different kinds of components. |
| 8 |
|
| 9 |
It contains data types that would normally be considered part of the "core" of a |
| 10 |
language, such as numbers and lists. For these types, the Python language core |
| 11 |
defines the form of literals and places some constraints on their semantics, but |
| 12 |
does not fully define the semantics. (On the other hand, the language core does |
| 13 |
define syntactic properties like the spelling and priorities of operators.) |
| 14 |
|
| 15 |
The library also contains built-in functions and exceptions --- objects that can |
| 16 |
be used by all Python code without the need of an :keyword:`import` statement. |
| 17 |
Some of these are defined by the core language, but many are not essential for |
| 18 |
the core semantics and are only described here. |
| 19 |
|
| 20 |
The bulk of the library, however, consists of a collection of modules. There are |
| 21 |
many ways to dissect this collection. Some modules are written in C and built |
| 22 |
in to the Python interpreter; others are written in Python and imported in |
| 23 |
source form. Some modules provide interfaces that are highly specific to |
| 24 |
Python, like printing a stack trace; some provide interfaces that are specific |
| 25 |
to particular operating systems, such as access to specific hardware; others |
| 26 |
provide interfaces that are specific to a particular application domain, like |
| 27 |
the World Wide Web. Some modules are available in all versions and ports of |
| 28 |
Python; others are only available when the underlying system supports or |
| 29 |
requires them; yet others are available only when a particular configuration |
| 30 |
option was chosen at the time when Python was compiled and installed. |
| 31 |
|
| 32 |
This manual is organized "from the inside out:" it first describes the built-in |
| 33 |
functions, data types and exceptions, and finally the modules, grouped in |
| 34 |
chapters of related modules. |
| 35 |
|
| 36 |
This means that if you start reading this manual from the start, and skip to the |
| 37 |
next chapter when you get bored, you will get a reasonable overview of the |
| 38 |
available modules and application areas that are supported by the Python |
| 39 |
library. Of course, you don't *have* to read it like a novel --- you can also |
| 40 |
browse the table of contents (in front of the manual), or look for a specific |
| 41 |
function, module or term in the index (in the back). And finally, if you enjoy |
| 42 |
learning about random subjects, you choose a random page number (see module |
| 43 |
:mod:`random`) and read a section or two. Regardless of the order in which you |
| 44 |
read the sections of this manual, it helps to start with chapter |
| 45 |
:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with |
| 46 |
this material. |
| 47 |
|
| 48 |
Let the show begin! |
| 49 |
|
| 50 |
|
| 51 |
.. _availability: |
| 52 |
|
| 53 |
Notes on availability |
| 54 |
===================== |
| 55 |
|
| 56 |
* An "Availability: Unix" note means that this function is commonly found on |
| 57 |
Unix systems. It does not make any claims about its existence on a specific |
| 58 |
operating system. |
| 59 |
|
| 60 |
* If not separately noted, all functions that claim "Availability: Unix" are |
| 61 |
supported on macOS, iOS and Android, all of which build on a Unix core. |
| 62 |
|
| 63 |
* If an availability note contains both a minimum Kernel version and a minimum |
| 64 |
libc version, then both conditions must hold. For example a feature with note |
| 65 |
*Availability: Linux >= 3.17 with glibc >= 2.27* requires both Linux 3.17 or |
| 66 |
newer and glibc 2.27 or newer. |
| 67 |
|
| 68 |
.. _wasm-availability: |
| 69 |
|
| 70 |
WebAssembly platforms |
| 71 |
--------------------- |
| 72 |
|
| 73 |
The `WebAssembly`_ platforms ``wasm32-emscripten`` (`Emscripten`_) and |
| 74 |
``wasm32-wasi`` (`WASI`_) provide a subset of POSIX APIs. WebAssembly runtimes |
| 75 |
and browsers are sandboxed and have limited access to the host and external |
| 76 |
resources. Any Python standard library module that uses processes, threading, |
| 77 |
networking, signals, or other forms of inter-process communication (IPC), is |
| 78 |
either not available or may not work as on other Unix-like systems. File I/O, |
| 79 |
file system, and Unix permission-related functions are restricted, too. |
| 80 |
Emscripten does not permit blocking I/O. Other blocking operations like |
| 81 |
:func:`~time.sleep` block the browser event loop. |
| 82 |
|
| 83 |
The properties and behavior of Python on WebAssembly platforms depend on the |
| 84 |
`Emscripten`_-SDK or `WASI`_-SDK version, WASM runtimes (browser, NodeJS, |
| 85 |
`wasmtime`_), and Python build time flags. WebAssembly, Emscripten, and WASI |
| 86 |
are evolving standards; some features like networking may be |
| 87 |
supported in the future. |
| 88 |
|
| 89 |
For Python in the browser, users should consider `Pyodide`_ or `PyScript`_. |
| 90 |
PyScript is built on top of Pyodide, which itself is built on top of |
| 91 |
CPython and Emscripten. Pyodide provides access to browsers' JavaScript and |
| 92 |
DOM APIs as well as limited networking capabilities with JavaScript's |
| 93 |
``XMLHttpRequest`` and ``Fetch`` APIs. |
| 94 |
|
| 95 |
* Process-related APIs are not available or always fail with an error. That |
| 96 |
includes APIs that spawn new processes (:func:`~os.fork`, |
| 97 |
:func:`~os.execve`), wait for processes (:func:`~os.waitpid`), send signals |
| 98 |
(:func:`~os.kill`), or otherwise interact with processes. The |
| 99 |
:mod:`subprocess` is importable but does not work. |
| 100 |
|
| 101 |
* The :mod:`socket` module is available, but is limited and behaves |
| 102 |
differently from other platforms. On Emscripten, sockets are always |
| 103 |
non-blocking and require additional JavaScript code and helpers on the |
| 104 |
server to proxy TCP through WebSockets; see `Emscripten Networking`_ |
| 105 |
for more information. WASI snapshot preview 1 only permits sockets from an |
| 106 |
existing file descriptor. |
| 107 |
|
| 108 |
* Some functions are stubs that either don't do anything and always return |
| 109 |
hardcoded values. |
| 110 |
|
| 111 |
* Functions related to file descriptors, file permissions, file ownership, and |
| 112 |
links are limited and don't support some operations. For example, WASI does |
| 113 |
not permit symlinks with absolute file names. |
| 114 |
|
| 115 |
.. _WebAssembly: https://webassembly.org/ |
| 116 |
.. _Emscripten: https://emscripten.org/ |
| 117 |
.. _Emscripten Networking: https://emscripten.org/docs/porting/networking.html |
| 118 |
.. _WASI: https://wasi.dev/ |
| 119 |
.. _wasmtime: https://wasmtime.dev/ |
| 120 |
.. _Pyodide: https://pyodide.org/ |
| 121 |
.. _PyScript: https://pyscript.net/ |
| 122 |
|
| 123 |
.. _mobile-availability: |
| 124 |
.. _iOS-availability: |
| 125 |
|
| 126 |
Mobile platforms |
| 127 |
---------------- |
| 128 |
|
| 129 |
Android and iOS are, in most respects, POSIX operating systems. File I/O, socket handling, |
| 130 |
and threading all behave as they would on any POSIX operating system. However, |
| 131 |
there are several major differences: |
| 132 |
|
| 133 |
* Mobile platforms can only use Python in "embedded" mode. There is no Python |
| 134 |
REPL, and no ability to use separate executables such as :program:`python` or |
| 135 |
:program:`pip`. To add Python code to your mobile app, you must use |
| 136 |
the :ref:`Python embedding API <embedding>`. For more details, see |
| 137 |
:ref:`using-android` and :ref:`using-ios`. |
| 138 |
|
| 139 |
* Subprocesses: |
| 140 |
|
| 141 |
* On Android, creating subprocesses is possible but `officially unsupported |
| 142 |
<https://issuetracker.google.com/issues/128554619#comment4>`__. |
| 143 |
In particular, Android does not support any part of the System V IPC API, |
| 144 |
so :mod:`multiprocessing` is not available. |
| 145 |
|
| 146 |
* An iOS app cannot use any form of subprocessing, multiprocessing, or |
| 147 |
inter-process communication. If an iOS app attempts to create a subprocess, |
| 148 |
the process creating the subprocess will either lock up, or crash. An iOS app |
| 149 |
has no visibility of other applications that are running, nor any ability to |
| 150 |
communicate with other running applications, outside of the iOS-specific APIs |
| 151 |
that exist for this purpose. |
| 152 |
|
| 153 |
* Mobile apps have limited access to modify system resources (such as the system |
| 154 |
clock). These resources will often be *readable*, but attempts to modify |
| 155 |
those resources will usually fail. |
| 156 |
|
| 157 |
* Console input and output: |
| 158 |
|
| 159 |
* On Android, the native ``stdout`` and ``stderr`` are not connected to |
| 160 |
anything, so Python installs its own streams which redirect messages to the |
| 161 |
system log. These can be seen under the tags ``python.stdout`` and |
| 162 |
``python.stderr`` respectively. |
| 163 |
|
| 164 |
* iOS apps have a limited concept of console output. ``stdout`` and |
| 165 |
``stderr`` *exist*, and content written to ``stdout`` and ``stderr`` will be |
| 166 |
visible in logs when running in Xcode, but this content *won't* be recorded |
| 167 |
in the system log. If a user who has installed your app provides their app |
| 168 |
logs as a diagnostic aid, they will not include any detail written to |
| 169 |
``stdout`` or ``stderr``. |
| 170 |
|
| 171 |
* Mobile apps have no usable ``stdin`` at all. While apps can display an on-screen |
| 172 |
keyboard, this is a software feature, not something that is attached to |
| 173 |
``stdin``. |
| 174 |
|
| 175 |
As a result, Python modules that involve console manipulation (such as |
| 176 |
:mod:`curses` and :mod:`readline`) are not available on mobile platforms. |