"sysconfig" --- Provide access to Python's configuration information
********************************************************************

バージョン 3.2 で追加.

**Source code:** Lib/sysconfig.py

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

"sysconfig" モジュールは、インストールパスのリストや、現在のプラットフ
ォームに関連した構成などの、Python の構成情報 (configuration
information) へのアクセスを提供します。


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

A Python distribution contains a "Makefile" and a "pyconfig.h" header
file that are necessary to build both the Python binary itself and
third-party C extensions compiled using "distutils".

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

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

sysconfig.get_config_vars(*args)

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

   引数がある場合、各引数を構成変数辞書から検索した結果の変数のリスト
   を返します。

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

sysconfig.get_config_var(name)

   1つの変数 *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 uses an installation scheme that differs depending on the
platform and on the installation options.  These schemes are stored in
"sysconfig" under unique identifiers based on the value returned by
"os.name". The schemes are used by package installers to determine
where to copy files to.

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

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

* *posix_home*: scheme for POSIX platforms, when the *home* option is
  used. This scheme defines paths located under a specific home
  prefix.

* *posix_user*: scheme for POSIX platforms, when the *user* option is
  used. This scheme defines paths located under the user's home
  directory ("site.USER_BASE").

* *posix_venv*: scheme for "Python virtual environments" on POSIX
  platforms; by default it is the same as *posix_prefix*.

* *nt*: scheme for Windows. This is the default scheme used when
  Python or a component is installed.

* *nt_user*: scheme for Windows, when the *user* option is used.

* *nt_venv*: scheme for "Python virtual environments" on Windows; by
  default it is the same as *nt*.

* *venv*: a scheme with values from either *posix_venv* or *nt_venv*
  depending on the platform Python runs on.

* *osx_framework_user* オプションが利用された場合の、macOS 用のスキー
  ムです。

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

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

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

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

* *purelib*: directory for site-specific, non-platform-specific files
  ('pure' Python).

* *include*: directory for non-platform-specific header files for the
  Python C-API.

* *platinclude*: directory for platform-specific header files for the
  Python C-API.

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

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


User scheme
===========

This scheme is designed to be the most convenient solution for users
that don't have write permission to the global site-packages directory
or don't want to install into it.

Files will be installed into subdirectories of "site.USER_BASE"
(written as "*userbase*" hereafter).  This scheme installs pure Python
modules and extension modules in the same location (also known as
"site.USER_SITE").


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

+----------------+-------------------------------------------------------------+
| Path           | インストールディレクトリ                                    |
|================|=============================================================|
| *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"
---------

+----------------+-------------------------------------------------------------+
| Path           | インストールディレクトリ                                    |
|================|=============================================================|
| *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"
--------------------

+----------------+-------------------------------------------------------------+
| Path           | インストールディレクトリ                                    |
|================|=============================================================|
| *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 scheme
===========

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


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

+----------------+-------------------------------------------------------------+
| Path           | インストールディレクトリ                                    |
|================|=============================================================|
| *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*"                                                    |
+----------------+-------------------------------------------------------------+


Prefix scheme
=============

あるインストール済みの Python を使ってモジュールのビルド/インストール
を (例えば setup スクリプトを実行して) 行いたいけれども、 別のインスト
ール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見
えるようなディレクトリ構造) に、ビルドされた モジュールをインストール
したい場合には、"prefix スキーム" が便利です。そんな作業はまったくあり
えそうにない、と思うなら、確かにその通りです --- "home スキーム" を先
に説明したのもそのためです。とはいえ、prefix スキームが有用なケースは
少なくとも二つあります。

First, consider that many Linux distributions put Python in "/usr",
rather than the more traditional "/usr/local".  This is entirely
appropriate, since in those cases Python is part of "the system"
rather than a local add-on. However, if you are installing Python
modules from source, you probably want them to go in
"/usr/local/lib/python2.*X*" rather than "/usr/lib/python2.*X*".

Another possibility is a network filesystem where the name used to
write to a remote directory is different from the name used to read
it: for example, the Python interpreter accessed as
"/usr/local/bin/python" might search for modules in
"/usr/local/lib/python2.*X*", but those modules would have to be
installed to, say, "/mnt/*@server*/export/lib/python2.*X*".


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

+----------------+------------------------------------------------------------+
| Path           | インストールディレクトリ                                   |
|================|============================================================|
| *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"
----

+----------------+------------------------------------------------------------+
| Path           | インストールディレクトリ                                   |
|================|============================================================|
| *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*"                                                 |
+----------------+------------------------------------------------------------+


Installation path functions
===========================

"sysconfig" provides some functions to determine these installation
paths.

sysconfig.get_scheme_names()

   現在 "sysconfig" でサポートされているすべてのスキームを格納したタプ
   ルを返します。

sysconfig.get_default_scheme()

   Return the default scheme name for the current platform.

   バージョン 3.10 で追加: This function was previously named
   "_get_default_scheme()" and considered an implementation detail.

   バージョン 3.11 で変更: When Python runs from a virtual
   environment, the *venv* scheme is returned.

sysconfig.get_preferred_scheme(key)

   Return a preferred scheme name for an installation layout specified
   by *key*.

   *key* must be either ""prefix"", ""home"", or ""user"".

   The return value is a scheme name listed in "get_scheme_names()".
   It can be passed to "sysconfig" functions that take a *scheme*
   argument, such as "get_paths()".

   バージョン 3.10 で追加.

   バージョン 3.11 で変更: When Python runs from a virtual environment
   and "key="prefix"", the *venv* scheme is returned.

sysconfig._get_preferred_schemes()

   Return a dict containing preferred scheme names on the current
   platform. Python implementers and redistributors may add their
   preferred schemes to the "_INSTALL_SCHEMES" module-level global
   value, and modify this function to return those scheme names, to
   e.g. provide different schemes for system and language package
   managers to use, so packages installed by either do not mix with
   those by the other.

   End users should not use this function, but "get_default_scheme()"
   and "get_preferred_scheme()" instead.

   バージョン 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()" が返すリストに含ま
   れる値でなければなりません。指定されなかった場合は、現在のプラット
   フォームでのデフォルトスキームが利用されます。

   If *vars* is provided, it must be a dictionary of variables that
   will update the dictionary returned by "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()

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

   This is used mainly to distinguish platform-specific build
   directories and platform-specific built distributions.  Typically
   includes the OS name and version and the architecture (as supplied
   by 'os.uname()'), although the exact information included depends
   on the OS; e.g., on Linux, the kernel version isn't particularly
   important.

   返される値の例:

   * linux-i586

   * linux-alpha (?)

   * solaris-2.6-sun4u

   Windows では以下のどれかを返します:

   * win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and
     EM64T)

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

   macOS では以下のどれかを返します:

   * macosx-10.6-ppc

   * macosx-10.4-ppc64

   * macosx-10.3-i386

   * macosx-10.4-fat

   その他の非 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" のパスを返します。


Using "sysconfig" as a script
=============================

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()" が返す情報を標準出力に出力します。
