はじめに
********

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

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

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

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

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

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

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


利用可能性について
==================

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

* 特に記述がない場合、「利用できる環境 : Unix 」と書かれている関数は、
  Unix をコアにしているmacOS、iOS、Androidでも利用することができます。

* 利用可能性の注釈に最小カーネルバージョンと最小 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.


モバイルプラットフォーム
------------------------

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 Android で
  Python を使う and iOS で Python を使う.

* サブプロセス:

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