Introduction

The “Python library” contains several different kinds of components.

It contains data types that would normally be considered part of the “core” of alanguage, such as numbers and lists. For these types, the Python language coredefines the form of literals and places some constraints on their semantics, butdoes not fully define the semantics. (On the other hand, the language core doesdefine syntactic properties like the spelling and priorities of operators.)

The library also contains built-in functions and exceptions — objects that canbe used by all Python code without the need of animport statement.Some of these are defined by the core language, but many are not essential forthe core semantics and are only described here.

The bulk of the library, however, consists of a collection of modules. There aremany ways to dissect this collection. Some modules are written in C and builtin to the Python interpreter; others are written in Python and imported insource form. Some modules provide interfaces that are highly specific toPython, like printing a stack trace; some provide interfaces that are specificto particular operating systems, such as access to specific hardware; othersprovide interfaces that are specific to a particular application domain, likethe World Wide Web. Some modules are available in all versions and ports ofPython; others are only available when the underlying system supports orrequires them; yet others are available only when a particular configurationoption was chosen at the time when Python was compiled and installed.

This manual is organized “from the inside out:” it first describes the built-infunctions, data types and exceptions, and finally the modules, grouped inchapters of related modules.

This means that if you start reading this manual from the start, and skip to thenext chapter when you get bored, you will get a reasonable overview of theavailable modules and application areas that are supported by the Pythonlibrary. Of course, you don’thave to read it like a novel — you can alsobrowse the table of contents (in front of the manual), or look for a specificfunction, module or term in the index (in the back). And finally, if you enjoylearning about random subjects, you choose a random page number (see modulerandom) and read a section or two. Regardless of the order in which youread the sections of this manual, it helps to start with chapterBuilt-in Functions, as the remainder of the manual assumes familiarity withthis material.

Let the show begin!

Notes on availability

  • An “Availability: Unix” note means that this function is commonly found onUnix systems. It does not make any claims about its existence on a specificoperating system.

  • If not separately noted, all functions that claim “Availability: Unix” aresupported on macOS, iOS and Android, all of which build on a Unix core.

  • If an availability note contains both a minimum Kernel version and a minimumlibc version, then both conditions must hold. For example a feature with noteAvailability: Linux >= 3.17 with glibc >= 2.27 requires both Linux 3.17 ornewer and glibc 2.27 or newer.

WebAssembly platforms

TheWebAssembly platformswasm32-emscripten (Emscripten) andwasm32-wasi (WASI) provide a subset of POSIX APIs. WebAssembly runtimesand browsers are sandboxed and have limited access to the host and externalresources. Any Python standard library module that uses processes, threading,networking, signals, or other forms of inter-process communication (IPC), iseither not available or may not work as on other Unix-like systems. File I/O,file system, and Unix permission-related functions are restricted, too.Emscripten does not permit blocking I/O. Other blocking operations likesleep() block the browser event loop.

The properties and behavior of Python on WebAssembly platforms depend on theEmscripten-SDK orWASI-SDK version, WASM runtimes (browser, NodeJS,wasmtime), and Python build time flags. WebAssembly, Emscripten, and WASIare evolving standards; some features like networking may besupported in the future.

For Python in the browser, users should considerPyodide orPyScript.PyScript is built on top of Pyodide, which itself is built on top ofCPython and Emscripten. Pyodide provides access to browsers’ JavaScript andDOM APIs as well as limited networking capabilities with JavaScript’sXMLHttpRequest andFetch APIs.

  • Process-related APIs are not available or always fail with an error. Thatincludes APIs that spawn new processes (fork(),execve()), wait for processes (waitpid()), send signals(kill()), or otherwise interact with processes. Thesubprocess is importable but does not work.

  • Thesocket module is available, but is limited and behavesdifferently from other platforms. On Emscripten, sockets are alwaysnon-blocking and require additional JavaScript code and helpers on theserver to proxy TCP through WebSockets; seeEmscripten Networkingfor more information. WASI snapshot preview 1 only permits sockets from anexisting file descriptor.

  • Some functions are stubs that either don’t do anything and always returnhardcoded values.

  • Functions related to file descriptors, file permissions, file ownership, andlinks are limited and don’t support some operations. For example, WASI doesnot permit symlinks with absolute file names.

Mobile platforms

Android and iOS are, in most respects, POSIX operating systems. File I/O, socket handling,and threading all behave as they would on any POSIX operating system. However,there are several major differences:

  • Mobile platforms can only use Python in “embedded” mode. There is no PythonREPL, and no ability to use separate executables such aspython orpip. To add Python code to your mobile app, you must usethePython embedding API. For more details, seeUsing Python on Android andUsing Python on iOS.

  • Subprocesses:

    • On Android, creating subprocesses is possible butofficially unsupported.In particular, Android does not support any part of the System V IPC API,somultiprocessing is not available.

    • An iOS app cannot use any form of subprocessing, multiprocessing, orinter-process communication. If an iOS app attempts to create a subprocess,the process creating the subprocess will either lock up, or crash. An iOS apphas no visibility of other applications that are running, nor any ability tocommunicate with other running applications, outside of the iOS-specific APIsthat exist for this purpose.

  • Mobile apps have limited access to modify system resources (such as the systemclock). These resources will often bereadable, but attempts to modifythose resources will usually fail.

  • Console input and output:

    • On Android, the nativestdout andstderr are not connected toanything, so Python installs its own streams which redirect messages to thesystem log. These can be seen under the tagspython.stdout andpython.stderr respectively.

    • iOS apps have a limited concept of console output.stdout andstderrexist, and content written tostdout andstderr will bevisible in logs when running in Xcode, but this contentwon’t be recordedin the system log. If a user who has installed your app provides their applogs as a diagnostic aid, they will not include any detail written tostdout orstderr.

    • Mobile apps have no usablestdin at all. While apps can display an on-screenkeyboard, this is a software feature, not something that is attached tostdin.

      As a result, Python modules that involve console manipulation (such ascurses andreadline) are not available on mobile platforms.