# はじめに

この "Python ライブラリ" には様々な内容が収録されています。

このライブラリには、数値型やリスト型のような、通常は言語の "核" をなす部分とみなされるデータ型が含まれています。Python 言語のコア部分では、これらの型に対してリテラル表現形式を与え、意味づけ上のいくつかの制約を与えていますが、完全にその意味づけを定義しているわけではありません。(一方で、言語のコア部分では演算子のスペルや優先順位のような構文法的な属性を定義しています。)

このライブラリにはまた、組み込み関数と例外が納められています --- 組み込み関数および例外は、全ての Python で書かれたコード上で、 `import` 文を使わずに使うことができるオブジェクトです。これらの組み込み要素のうちいくつかは言語のコア部分で定義されていますが、大半は言語コアの意味づけ上不可欠なものではないのでここでしか記述されていません。

とはいえ、このライブラリの大部分に収録されているのはモジュールのコレクションです。このコレクションを細分化する方法はいろいろあります。あるモジュールは C 言語で書かれ、Python インタプリタに組み込まれています; 一方別のモジュールは Python で書かれ、ソースコードの形式で取り込まれます。またあるモジュールは、例えば実行スタックの追跡結果を出力するといった、Python に非常に特化したインターフェースを提供し、一方他のモジュールでは、特定のハードウェアにアクセスするといった、特定のオペレーティングシステムに特化したインターフェースを提供し、さらに別のモジュールでは WWW (ワールドワイドウェブ) のような特定のアプリケーション分野に特化したインターフェースを提供しています。モジュールによっては全てのバージョン、全ての移植版の Python で利用することができたり、背後にあるシステムがサポートしている場合にのみ使えたり、Python をコンパイルしてインストールする際に特定の設定オプションを選んだときにのみ利用できたりします。

このマニュアルは "内部から外部へ" と構成されています。つまり、最初に組み込みの関数を記述し、組み込みのデータ型、例外、そして最後に各モジュールと続きます。モジュールは関係のあるものでグループ化して一つの章にしています。

つまり、このマニュアルを最初から読み始め、読み飽きたところで次の章に進めば、 Python ライブラリで利用できるモジュールやサポートしているアプリケーション領域の概要をそこそこ理解できるということです。もちろん、このマニュアルを小説のように読む必要は ありません --- (マニュアルの先頭部分にある) 目次にざっと目を通したり、 (最後尾にある) 索引でお目当ての関数やモジュール、用語を探すことだってできます。もしランダムな項目について勉強してみたいのなら、ランダムにページを選び (`random` 参照)、そこから 1, 2 節読むこともできます。このマニュアルの各節をどんな順番で読むかに関わらず、 組み込み関数 の章から始めるとよいでしょう。マニュアルの他の部分は、この節の内容について知っているものとして書かれているからです。

それでは、ショーの始まりです！

## 利用可能性について

- 「利用できる環境 : Unix 」の意味はこの関数が Unix システムにあることが多いということです。このことは特定の OS における存在を主張するものではありません。

- If not separately noted, all functions that claim "Availability: Unix" are supported on macOS, iOS and Android, all of which build on a Unix core.

- 利用可能性の注釈に最小カーネルバージョンと最小 libc バージョンの両方が含まれている場合は、両方の条件を満たさなければなりません。例えば、 Availability: Linux >= 3.17 with glibc >= 2.27 という注釈付きの機能には、 Linux 3.17 以上と、 glibc 2.27 以上の両方が必要です。

### WebAssembly プラットフォーム

WebAssembly プラットフォームである `wasm32-emscripten` (Emscripten) と `wasm32-wasi` (WASI) は、 POSIX API のサブセットを提供します。 WebAssembly ランタイムとブラウザーはサンドボックス化されており、ホストや外部リソースへのアクセスが制限されています。プロセス、スレッド、ネットワーク、シグナル、または他の形のプロセス間通信 (IPC) を使用する標準ライブラリモジュールは、利用不可か、他の Unix ライクなシステムのようには動作しません。ファイル I/O 、ファイルシステム、 Unix の権限関係の機能も制限されています。 Emscripten はブロッキング I/O を許可しません。 `sleep()` のような他のブロッキング操作は、ブラウザーのイベントループをブロックします。

WebAssembly プラットフォーム上での Python の 性質と振る舞いは、 Emscripten-SDK や WASI-SDK のバージョン、 WASM ランタイム (ブラウザ、 NodeJS 、 wasmtime) 、Python のビルド時フラグによって決まります。 WebAssembly や Emscripten 、 WASI は標準を発展させており、ネットワークなどの機能は将来的にサポートされるかもしれません

ブラウザ上の Python では、ユーザーは Pyodide や PyScript を検討すべきでしょう。 PyScript は、 Pyodide をもとにして構築されており、 Pyodide 自体は CPython や Emscripten 上に構築されています。 Pyodide は、ブラウザの JavaScript と DOM API だけでなく、 JavaScript の `XMLHttpRequest` や `Fetch` API による制限されたネットワーク機能へのアクセスを提供します。

- プロセス関連の API は利用不可能か、常にエラーにより失敗します。これには、新しいプロセスを作成 (`fork()` や `execve()`) 、プロセスを待機 (`waitpid()`) 、シグナルを送信 (`kill()`) 、もしくはプロセスと通信する API が含まれます。 `subprocess` はインポート可能ですが、機能しません。

- The `socket` module is available, but is limited and behaves differently from other platforms. On Emscripten, sockets are always non-blocking and require additional JavaScript code and helpers on the server to proxy TCP through WebSockets; see Emscripten Networking for more information. WASI snapshot preview 1 only permits sockets from an existing file descriptor.

- Some functions are stubs that either don't do anything and always return hardcoded values.

- Functions related to file descriptors, file permissions, file ownership, and links are limited and don't support some operations. For example, WASI does not 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 Python REPL, and no ability to use separate executables such as python or pip. To add Python code to your mobile app, you must use the Python embedding API. For more details, see Using Python on Android and Using Python on iOS.

- Subprocesses:

  - On Android, creating subprocesses is possible but officially unsupported. In particular, Android does not support any part of the System V IPC API, so `multiprocessing` is not available.

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

- Mobile apps have limited access to modify system resources (such as the system clock). These resources will often be readable, but attempts to modify those resources will usually fail.

- Console input and output:

  - On Android, the native `stdout` and `stderr` are not connected to anything, so Python installs its own streams which redirect messages to the system log. These can be seen under the tags `python.stdout` and `python.stderr` respectively.

  - iOS apps have a limited concept of console output. `stdout` and `stderr` exist, and content written to `stdout` and `stderr` will be visible in logs when running in Xcode, but this content won't be recorded in the system log. If a user who has installed your app provides their app logs as a diagnostic aid, they will not include any detail written to `stdout` or `stderr`.

  - Mobile apps have no usable `stdin` at all. While apps can display an on-screen keyboard, this is a software feature, not something that is attached to `stdin`.

    As a result, Python modules that involve console manipulation (such as `curses` and `readline`) are not available on mobile platforms.