Debian Codegraph @

Doc/library/intro.rst

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