"sysconfig" --- Python の構成情報へのアクセスを提供する
*******************************************************

Added in version 3.2.

**ソースコード:** Lib/sysconfig

======================================================================

"sysconfig" モジュールは、インストールパスの一覧や現在のプラットフォー
ムに関する構成変数など、Python の構成情報へのアクセスを提供します。


構成変数
========

Python の配布物は、Python 自体のバイナリや、 "setuptools" によってコン
パイルされるサードパーティの C 拡張をビルドするために必要な、
"Makefile" と "pyconfig.h" ヘッダーファイルを含んでいます。

"sysconfig" は、これらのファイルにあるすべての変数を辞書に格納します。
この辞書には "get_config_vars()" または "get_config_var()" でアクセス
できます。

Windows では構成変数はだいぶ少なくなります。

sysconfig.get_config_vars(*args)

   引数がない場合、現在のプラットフォームに関するすべての構成変数の辞
   書を返します。

   引数がある場合は、各引数を構成変数の辞書で検索して得た値のリストを
   返します。

   各引数において、変数が見つからなかった場合は "None" が返されます。

sysconfig.get_config_var(name)

   *name* という変数の値を返します。 "get_config_vars().get(name)" と
   同等です。

   *name* が見つからない場合、"None" を返します。

Example of usage:

   >>> import sysconfig
   >>> sysconfig.get_config_var('Py_ENABLE_SHARED')
   0
   >>> sysconfig.get_config_var('LIBDIR')
   '/usr/local/lib'
   >>> sysconfig.get_config_vars('AR', 'CXX')
   ['ar', 'g++']


インストールパス
================

Python では、プラットフォームとインストール時のオプションに応じて異な
るインストールスキームを使います。 これらのスキームは、"os.name" の戻
り値に基づく一意の識別子で "sysconfig" に格納されています。 パッケージ
インストーラーは、ファイルのコピー先を決めるためにスキームを使います。

Python は現在9つのスキームをサポートしています:

* *posix_prefix*: Linux や macOS などの POSIX プラットフォーム用のスキ
  ームです。これは Python やコンポーネントをインストールするときに使わ
  れるデフォルトのスキームです。

* *posix_home*: *home* オプションを使う場合の POSIX プラットフォーム用
  スキームです。 指定されたホームプレフィックス配下のパスを定義します
  。

* *posix_user*: *user* オプションを使う場合の POSIX プラットフォーム用
  スキームです。 ユーザーのホームディレクトリ ("site.USER_BASE") 配下
  のパスを定義します。

* *posix_venv*: POSIX プラットフォームの "Python 仮想環境" 用スキーム
  です。 デフォルトでは *posix_prefix* と同じです。

* *nt*: Windows 用のスキームです。 Python やコンポーネントをインストー
  ルするときに使うデフォルトのスキームです。

* *nt_user*: *user* オプションを使う場合の Windows 用スキームです。

* *nt_venv*: Windows の "Python 仮想環境" 用スキームです。 デフォルト
  では *nt* と同じです。

* *venv*: Python が動作するプラットフォームに応じて、*posix_venv* また
  は *nt_venv* の値を使うスキームです。

* *osx_framework_user*: *user* オプションを使う場合の macOS 用スキーム
  です。

各スキームは、ユニークな識別子を持ったいくつかのパスの集合から成ってい
ます。現在 Python は8つのパスを利用します:

* *stdlib*: プラットフォーム非依存の、標準 Python ライブラリファイルを
  格納するディレクトリ.

* *platstdlib*: プラットフォーム依存の、標準 Python ライブラリファイル
  を格納するディレクトリ.

* *platlib*: プラットフォーム依存の、site ごとのファイルを格納するディ
  レクトリ。

* *purelib*: サイト固有で、プラットフォームに依存しないファイル (純粋
  な Python) のためのディレクトリです。

* *include*: Python C API のプラットフォーム非依存のヘッダーファイル用
  ディレクトリです。

* *platinclude*: Python C API のプラットフォーム依存のヘッダーファイル
  用ディレクトリです。

* *scripts*: スクリプトファイルのためのディレクトリ。

* *data*: データファイルのためのディレクトリ。


ユーザースキーム
================

このスキームは、グローバルな site-packages ディレクトリへの書き込み権
限がないユーザーや、そこへインストールしたくないユーザーにとって、最も
便利な方法になるように設計されています。

ファイルは "site.USER_BASE" (以下では "*userbase*" と表記) のサブディ
レクトリにインストールされます。 このスキームでは、純粋な Python のモ
ジュールと拡張モジュールを同じ場所 ("site.USER_SITE" としても知られて
います) にインストールします。


"posix_user"
------------

+----------------+-------------------------------------------------------------+
| パス           | インストールディレクトリ                                    |
|================|=============================================================|
| *stdlib*       | "*userbase*/lib/python*X.Y*"                                |
+----------------+-------------------------------------------------------------+
| *platstdlib*   | "*userbase*/lib/python*X.Y*"                                |
+----------------+-------------------------------------------------------------+
| *platlib*      | "*userbase*/lib/python*X.Y*/site-packages"                  |
+----------------+-------------------------------------------------------------+
| *purelib*      | "*userbase*/lib/python*X.Y*/site-packages"                  |
+----------------+-------------------------------------------------------------+
| *include*      | "*userbase*/include/python*X.Y*"                            |
+----------------+-------------------------------------------------------------+
| *scripts*      | "*userbase*/bin"                                            |
+----------------+-------------------------------------------------------------+
| *data*         | "*userbase*"                                                |
+----------------+-------------------------------------------------------------+


"nt_user"
---------

+----------------+-------------------------------------------------------------+
| パス           | インストールディレクトリ                                    |
|================|=============================================================|
| *stdlib*       | "*userbase*\Python*XY*"                                     |
+----------------+-------------------------------------------------------------+
| *platstdlib*   | "*userbase*\Python*XY*"                                     |
+----------------+-------------------------------------------------------------+
| *platlib*      | "*userbase*\Python*XY*\site-packages"                       |
+----------------+-------------------------------------------------------------+
| *purelib*      | "*userbase*\Python*XY*\site-packages"                       |
+----------------+-------------------------------------------------------------+
| *include*      | "*userbase*\Python*XY*\Include"                             |
+----------------+-------------------------------------------------------------+
| *scripts*      | "*userbase*\Python*XY*\Scripts"                             |
+----------------+-------------------------------------------------------------+
| *data*         | "*userbase*"                                                |
+----------------+-------------------------------------------------------------+


"osx_framework_user"
--------------------

+----------------+-------------------------------------------------------------+
| パス           | インストールディレクトリ                                    |
|================|=============================================================|
| *stdlib*       | "*userbase*/lib/python"                                     |
+----------------+-------------------------------------------------------------+
| *platstdlib*   | "*userbase*/lib/python"                                     |
+----------------+-------------------------------------------------------------+
| *platlib*      | "*userbase*/lib/python/site-packages"                       |
+----------------+-------------------------------------------------------------+
| *purelib*      | "*userbase*/lib/python/site-packages"                       |
+----------------+-------------------------------------------------------------+
| *include*      | "*userbase*/include/python*X.Y*"                            |
+----------------+-------------------------------------------------------------+
| *scripts*      | "*userbase*/bin"                                            |
+----------------+-------------------------------------------------------------+
| *data*         | "*userbase*"                                                |
+----------------+-------------------------------------------------------------+


ホームスキーム
==============

"home スキーム" の背後にある考え方は、Python モジュールを個人用のモジ
ュール置き場でビルドし、維持するというものです。このスキームの名前は
Unixの「ホーム」ディレクトリの概念からとりました。というのも、 Unixの
ユーザにとって、自分のホームディレクトリを "/usr/" や "/usr/local/" の
ようにレイアウトするのはよくあることだからです。とはいえ、このスキーム
はどのオペレーティングシステムのユーザでも使えます。


"posix_home"
------------

+----------------+-------------------------------------------------------------+
| パス           | インストールディレクトリ                                    |
|================|=============================================================|
| *stdlib*       | "*home*/lib/python"                                         |
+----------------+-------------------------------------------------------------+
| *platstdlib*   | "*home*/lib/python"                                         |
+----------------+-------------------------------------------------------------+
| *platlib*      | "*home*/lib/python"                                         |
+----------------+-------------------------------------------------------------+
| *purelib*      | "*home*/lib/python"                                         |
+----------------+-------------------------------------------------------------+
| *include*      | "*home*/include/python"                                     |
+----------------+-------------------------------------------------------------+
| *platinclude*  | "*home*/include/python"                                     |
+----------------+-------------------------------------------------------------+
| *scripts*      | "*home*/bin"                                                |
+----------------+-------------------------------------------------------------+
| *data*         | "*home*"                                                    |
+----------------+-------------------------------------------------------------+


プレフィックススキーム
======================

ある Python 環境を使ってビルドやインストール (setup スクリプトの実行)
を行いながら、別の Python 環境のサードパーティーモジュール用ディレクト
リ (またはそれに似た構成のディレクトリ) にモジュールをインストールした
い場合、プレフィックススキームが便利です。 少し変わった使い方に思える
かもしれませんが、その通りです。 そのため、ユーザースキームとホームス
キームを先に説明しました。 それでも、プレフィックススキームが役立つ場
面は少なくとも 2 つあります。

まず、多くの Linux ディストリビューションは、従来の "/usr/local" では
なく "/usr" に Python を配置します。 この場合の Python はローカルに追
加したものではなく「システム」の一部なので、これはまったく適切です。
ただし、Python モジュールをソースからインストールする場合は、
"/usr/lib/python2.*X*" ではなく "/usr/local/lib/python2.*X*" に配置し
たいでしょう。

もう 1 つは、リモートディレクトリへの書き込み時と読み取り時で、使う名
前が異なるネットワークファイルシステムの場合です。 例えば、
"/usr/local/bin/python" としてアクセスする Python インタープリタが
"/usr/local/lib/python2.*X*" でモジュールを検索しても、 そのモジュール
のインストール先には "/mnt/*@server*/export/lib/python2.*X*" などを指
定する必要がある場合です。


"posix_prefix"
--------------

+----------------+------------------------------------------------------------+
| パス           | インストールディレクトリ                                   |
|================|============================================================|
| *stdlib*       | "*prefix*/lib/python*X.Y*"                                 |
+----------------+------------------------------------------------------------+
| *platstdlib*   | "*prefix*/lib/python*X.Y*"                                 |
+----------------+------------------------------------------------------------+
| *platlib*      | "*prefix*/lib/python*X.Y*/site-packages"                   |
+----------------+------------------------------------------------------------+
| *purelib*      | "*prefix*/lib/python*X.Y*/site-packages"                   |
+----------------+------------------------------------------------------------+
| *include*      | "*prefix*/include/python*X.Y*"                             |
+----------------+------------------------------------------------------------+
| *platinclude*  | "*prefix*/include/python*X.Y*"                             |
+----------------+------------------------------------------------------------+
| *scripts*      | "*prefix*/bin"                                             |
+----------------+------------------------------------------------------------+
| *data*         | "*prefix*"                                                 |
+----------------+------------------------------------------------------------+


"nt"
----

+----------------+------------------------------------------------------------+
| パス           | インストールディレクトリ                                   |
|================|============================================================|
| *stdlib*       | "*prefix*\Lib"                                             |
+----------------+------------------------------------------------------------+
| *platstdlib*   | "*prefix*\Lib"                                             |
+----------------+------------------------------------------------------------+
| *platlib*      | "*prefix*\Lib\site-packages"                               |
+----------------+------------------------------------------------------------+
| *purelib*      | "*prefix*\Lib\site-packages"                               |
+----------------+------------------------------------------------------------+
| *include*      | "*prefix*\Include"                                         |
+----------------+------------------------------------------------------------+
| *platinclude*  | "*prefix*\Include"                                         |
+----------------+------------------------------------------------------------+
| *scripts*      | "*prefix*\Scripts"                                         |
+----------------+------------------------------------------------------------+
| *data*         | "*prefix*"                                                 |
+----------------+------------------------------------------------------------+


インストールパスの関数
======================

"sysconfig" は、これらのインストールパスを求める関数を提供します。

sysconfig.get_scheme_names()

   "sysconfig" が現在サポートするすべてのスキームを含むタプルを返しま
   す。

sysconfig.get_default_scheme()

   現在のプラットフォームのデフォルトのスキーム名を返します。

   Added in version 3.10: 以前、この関数は "_get_default_scheme()" と
   いう名前で、実装の詳細とされていました。

   バージョン 3.11 で変更: Python を仮想環境で実行している場合、*venv*
   スキームを返すようになりました。

sysconfig.get_preferred_scheme(key)

   *key* で指定したインストール構成に適したスキーム名を返します。

   *key* は ""prefix""、""home""、""user"" のいずれかでなければなりま
   せん。

   戻り値は "get_scheme_names()" に含まれるスキーム名です。
   "get_paths()" など、*scheme* 引数を受け取る "sysconfig" の関数に渡
   せます。

   Added in version 3.10.

   バージョン 3.11 で変更: Python を仮想環境で実行していて
   "key="prefix"" の場合、*venv* スキームを返すようになりました。

sysconfig._get_preferred_schemes()

   現在のプラットフォームに適したスキーム名を格納した辞書を返します。
   Python の実装者や再配布者は、モジュールレベルのグローバル値
   "_INSTALL_SCHEMES" に独自のスキームを追加し、この関数がそれらの名前
   を返すように変更できます。 例えば、システムのパッケージマネージャー
   と言語のパッケージマネージャーに別々のスキームを用意し、一方がイン
   ストールしたパッケージと他方のパッケージが混在しないようにできます
   。

   エンドユーザーはこの関数ではなく、"get_default_scheme()" と
   "get_preferred_scheme()" を使ってください。

   Added in version 3.10.

sysconfig.get_path_names()

   "sysconfig" が現在サポートするすべてのパス名を含むタプルを返します
   。

sysconfig.get_path(name[, scheme[, vars[, expand]]])

   *scheme* で指定されたインストールスキームから、パス *name* に従って
   インストールパスを返します。

   *name* は "get_path_names()" が返すリストに含まれる値でなければなり
   ません。

   "sysconfig" は、各パス名に対応するインストールパスを、プラットフォ
   ームごとに変数を含む未展開の形で格納しています。 例えば *nt* スキー
   ムの *stdlib* パスは "{base}/Lib" です。

   "get_path()" は "get_config_vars()" が返す変数を使ってパスを展開し
   ます。 すべての変数にはプラットフォームごとのデフォルト値があるため
   、この関数を呼び出せばデフォルトのパスを取得できます。

   *scheme* が指定された場合、"get_scheme_names()" が返すリストに含ま
   れる値でなければなりません。指定されなかった場合は、現在のプラット
   フォームでのデフォルトスキームが利用されます。

   *vars* を指定する場合は、"get_config_vars()" が返す辞書を更新する変
   数の辞書でなければなりません。

   *expand* が "False" に設定された場合、パスは変数を使って展開されま
   せん。

   *name* が見つからない場合、"KeyError" を送出します。

sysconfig.get_paths([scheme[, vars[, expand]]])

   インストールスキームに基づいたすべてのインストールパスを格納した辞
   書を返します。詳しい情報は "get_path()" を参照してください。

   *scheme* が指定されない場合、現在のプラットフォームでのデフォルトス
   キーマが使用されます。

   *vars* を指定する場合、パスを展開するために使用される辞書を更新する
   値の辞書でなければなりません。

   *expand* に偽を指定すると、パスは展開されません。

   *scheme* が実在するスキームでなかった場合、"get_paths()" は
   "KeyError" を発生させます。


その他の関数
============

sysconfig.get_python_version()

   "MAJOR.MINOR" の型の Python バージョン番号文字列を返します。
   "'%d.%d' % sys.version_info[:2]" に似ています。

sysconfig.get_platform()

   現在のプラットフォームを識別するための文字列を返します。

   主に、プラットフォーム固有のビルドディレクトリや、プラットフォーム
   固有のビルド済み配布物を区別するために使われます。 通常、OS の名前
   、バージョン、アーキテクチャ ("os.uname()" で得られるもの) を含みま
   すが、具体的にどの情報が含まれるかは OS によって異なります。 例えば
   Linux では、カーネルのバージョンは特に重要ではありません。

   返される値の例:

   * linux-x86_64

   * linux-aarch64

   * solaris-2.6-sun4u

   Windows:

   * win-amd64 (AMD64、別名 x86_64、Intel64、EM64T 上の 64 ビット
     Windows)

   * win-arm64 (ARM64、別名 AArch64 上の 64 ビット Windows)

   * win32 (その他すべて - 具体的には sys.platform が返す値)

   POSIX ベースの OS:

   * linux-x86_64

   * macosx-15.5-arm64

   * macosx-26.0-universal2 (Apple Silicon または Intel 上の macOS)

   * android-24-arm64_v8a

   その他の非 POSIX プラットフォームでは、現在のところ単に
   "sys.platform" を返します。

sysconfig.is_python_build()

   実行中の Python インタープリタがソースからビルドされ、そのビルド場
   所から実行されている場合は "True" を返します。 "make install" やバ
   イナリインストーラによるインストール先から実行されている場合は該当
   しません。

sysconfig.parse_config_h(fp[, vars])

   "config.h" スタイルのファイルを解析します。

   *fp* は "config.h" スタイルのファイルを指すファイルライクオブジェク
   トです。

   name/value ペアを格納した辞書を返します。第二引数にオプションの辞書
   が渡された場合、新しい辞書ではなくその辞書を利用し、ファイルから読
   み込んだ値で更新します。

sysconfig.get_config_h_filename()

   "pyconfig.h" のパスを返します。

sysconfig.get_makefile_filename()

   "Makefile" のパスを返します。


コマンドラインでの使用
======================

Python の *-m* オプションで "sysconfig" をスクリプトとして使えます:

   $ python -m sysconfig
   Platform: "macosx-10.4-i386"
   Python version: "3.2"
   Current installation scheme: "posix_prefix"

   Paths:
           data = "/usr/local"
           include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
           platinclude = "."
           platlib = "/usr/local/lib/python3.2/site-packages"
           platstdlib = "/usr/local/lib/python3.2"
           purelib = "/usr/local/lib/python3.2/site-packages"
           scripts = "/usr/local/bin"
           stdlib = "/usr/local/lib/python3.2"

   Variables:
           AC_APPLE_UNIVERSAL_BUILD = "0"
           AIX_GENUINE_CPLUSPLUS = "0"
           AR = "ar"
           ARFLAGS = "rc"
           ...

これは、"get_platform()"、"get_python_version()"、"get_path()" および
"get_config_vars()" が返す情報を標準出力に出力します。
