sysconfig — 提供對 Python 配置資訊的訪問

在 3.2 版本加入。

原始碼: Lib/sysconfig


sysconfig 模組提供對 Python 配置資訊的訪問,例如安裝路徑列表和與當前平臺相關的配置變數。

配置變數

Python 發行版包含一個 Makefile 和一個 pyconfig.h 標頭檔案,它們對於構建 Python 二進位制檔案本身和使用 setuptools 編譯的第三方 C 擴充套件都是必需的。

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

使用示例

>>> 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 使用的安裝方案根據平臺和安裝選項而異。這些方案儲存在 sysconfig 中,其唯一識別符號基於 os.name 返回的值。這些方案由包安裝程式用於確定將檔案複製到何處。

Python 目前支援九種方案

  • posix_prefix: 用於 Linux 或 macOS 等 POSIX 平臺的方案。這是安裝 Python 或元件時使用的預設方案。

  • posix_home: 用於 POSIX 平臺的方案,當使用 home 選項時。此方案定義位於特定主目錄字首下的路徑。

  • posix_user: 用於 POSIX 平臺的方案,當使用 user 選項時。此方案定義位於使用者主目錄 (site.USER_BASE) 下的路徑。

  • posix_venv: 用於 POSIX 平臺上的 Python 虛擬 環境 的方案;預設情況下,它與 posix_prefix 相同。

  • nt: 用於 Windows 的方案。這是安裝 Python 或元件時使用的預設方案。

  • nt_user: 用於 Windows 的方案,當使用 user 選項時。

  • nt_venv: 用於 Windows 平臺上的 Python 虛擬 環境 的方案;預設情況下,它與 nt 相同。

  • venv: 一個方案,其值取決於 Python 執行的平臺是 posix_venv 還是 nt_venv

  • osx_framework_user: 用於 macOS 的方案,當使用 user 選項時。

每個方案本身由一系列路徑組成,每個路徑都有一個唯一的識別符號。Python 目前使用八種路徑

  • stdlib: 包含不特定於平臺的標準 Python 庫檔案的目錄。

  • platstdlib: 包含特定於平臺的標準 Python 庫檔案的目錄。

  • platlib: 用於特定於站點的、特定於平臺的檔案目錄。

  • 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/pythonX.Y

platstdlib

userbase/lib/pythonX.Y

platlib

userbase/lib/pythonX.Y/site-packages

purelib

userbase/lib/pythonX.Y/site-packages

include

userbase/include/pythonX.Y

scripts

userbase/bin

資料

userbase

nt_user

路徑

安裝目錄

stdlib

userbase\PythonXY

platstdlib

userbase\PythonXY

platlib

userbase\PythonXY\site-packages

purelib

userbase\PythonXY\site-packages

include

userbase\PythonXY\Include

scripts

userbase\PythonXY\Scripts

資料

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/pythonX.Y

scripts

userbase/bin

資料

userbase

主目錄方案

“主目錄方案”背後的想法是構建和維護個人 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

資料

home

字首方案

當您希望使用一個 Python 安裝來執行構建/安裝(即執行 setup 指令碼),但將模組安裝到另一個 Python 安裝(或看起來像另一個 Python 安裝)的第三方模組目錄時,“字首方案”非常有用。如果這聽起來有點不尋常,那是因為使用者和主目錄方案更常用。然而,至少有兩種已知情況會用到字首方案。

首先,許多 Linux 發行版將 Python 放在 /usr 中,而不是更傳統的 /usr/local。這完全是合適的,因為在這些情況下,Python 是“系統”的一部分,而不是本地附加元件。但是,如果您從原始碼安裝 Python 模組,您可能希望它們進入 /usr/local/lib/python2.X 而不是 /usr/lib/python2.X

另一種可能性是網路檔案系統,其中用於寫入遠端目錄的名稱與用於讀取它的名稱不同:例如,訪問為 /usr/local/bin/python 的 Python 直譯器可能會在 /usr/local/lib/python2.X 中搜索模組,但這些模組必須安裝到,例如,/mnt/@server/export/lib/python2.X

posix_prefix

路徑

安裝目錄

stdlib

prefix/lib/pythonX.Y

platstdlib

prefix/lib/pythonX.Y

platlib

prefix/lib/pythonX.Y/site-packages

purelib

prefix/lib/pythonX.Y/site-packages

include

prefix/include/pythonX.Y

platinclude

prefix/include/pythonX.Y

scripts

prefix/bin

資料

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

資料

prefix

安裝路徑函式

sysconfig 提供一些函式來確定這些安裝路徑。

sysconfig.get_scheme_names()

返回一個元組,其中包含 sysconfig 當前支援的所有方案。

sysconfig.get_default_scheme()

返回當前平臺的預設方案名稱。

3.10 新增: 此函式以前名為 _get_default_scheme(),並被認為是實現細節。

3.11 版變更: 當 Python 從虛擬環境執行時,返回 venv 方案。

sysconfig.get_preferred_scheme(key)

返回由 key 指定的安裝佈局的首選方案名稱。

key 必須是 "prefix""home""user"

返回值是 get_scheme_names() 中列出的方案名稱。它可以傳遞給接受 scheme 引數的 sysconfig 函式,例如 get_paths()

在 3.10 版本加入。

3.11 版變更: 當 Python 從虛擬環境執行且 key="prefix" 時,返回 venv 方案。

sysconfig._get_preferred_schemes()

返回一個字典,其中包含當前平臺上的首選方案名稱。Python 實現者和再分發者可以將他們首選的方案新增到模組級別的全域性值 _INSTALL_SCHEMES 中,並修改此函式以返回這些方案名稱,例如為系統和語言包管理器提供不同的方案,以便透過其中任何一個安裝的包不會與另一個安裝的包混淆。

終端使用者不應使用此函式,而應使用 get_default_scheme()get_preferred_scheme()

在 3.10 版本加入。

sysconfig.get_path_names()

返回一個元組,其中包含 sysconfig 當前支援的所有路徑名稱。

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

返回與路徑 name 對應的安裝路徑,來自名為 scheme 的安裝方案。

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 設定為 false,則路徑不會被擴充套件。

如果 scheme 不是現有方案,get_paths() 將引發 KeyError

其他函式

sysconfig.get_python_version()

以字串形式返回 MAJOR.MINOR Python 版本號。類似於 '%d.%d' % sys.version_info[:2]

sysconfig.get_platform()

返回標識當前平臺的字串。

這主要用於區分平臺特定的構建目錄和平臺特定的構建發行版。通常包括作業系統名稱和版本以及架構(由 os.uname() 提供),儘管包含的確切資訊取決於作業系統;例如,在 Linux 上,核心版本並不是特別重要。

返回值的示例

Windows

  • win-amd64 (AMD64 上的 64 位 Windows,也稱為 x86_64、Intel64 和 EM64T)

  • win-arm64 (ARM64 上的 64 位 Windows,也稱為 AArch64)

  • win32 (所有其他 - 特別是返回 sys.platform)

基於 POSIX 的作業系統

  • 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 直譯器是從原始碼構建的,並且正在從其構建位置執行,而不是從例如執行 make install 或透過二進位制安裝程式安裝的位置執行,則返回 True

sysconfig.parse_config_h(fp[, vars])

解析 config.h 樣式檔案。

fp 是指向 config.h 樣式檔案的類檔案物件。

返回一個包含名稱/值對的字典。如果將可選字典作為第二個引數傳入,則使用它而不是新字典,並使用檔案中讀取的值進行更新。

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() 返回的資訊。