sysconfig --- دسترسی به اطلاعات پیکربندی پایتون را فراهم می‌کند

اضافه شده در نسخه‌ی 3.2.

کد منبع: Lib/sysconfig

---

ماژول sysconfig دسترسی به اطلاعات پیکربندی پایتون، مانند فهرست مسیرهای نصب و متغیرهای پیکربندی مرتبط با پلتفرم فعلی را فراهم می‌کند.

متغیرهای پیکربندی

یک توزیع پایتون شامل یک Makefile و یک پرونده‌ی سرآیند pyconfig.h است که برای ساخت خود پرونده دودویی پایتون و نیز افزونه‌های C شخص ثالث که با استفاده از setuptools کامپایل می‌شوند، ضروری هستند.

sysconfig تمام متغیرهای موجود در این پرونده‌ها را در یک دیکشنری قرار می‌دهد که می‌توان با استفاده از get_config_vars() یا get_config_var() به آن دسترسی داشت.

توجه داشته باشید که در ویندوز، این مجموعه بسیار کوچک‌تر است.

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++']

مسیرهای نصب

پایتون از یک طرح‌واره نصب استفاده می‌کند که بسته به سکو و گزینه‌های نصب متفاوت است. این طرح‌ها در sysconfig با شناسه‌های یکتا بر اساس مقدار برگردانده‌شده توسط os.name ذخیره شده‌اند. نصب‌کننده‌های بسته از این طرح‌ها برای تعیین محل کپی پرونده‌ها استفاده می‌کنند.

پایتون در حال حاضر از ۹ طرح‌واره پشتیبانی می‌کند:

• posix_prefix: طرحی برای سکوهای POSIX مانند Linux یا macOS. این طرح‌واره پیش‌فرضی است که هنگام نصب Python یا یک کامپوننت استفاده می‌شود.

• posix_home: طرحی برای پلتفرم‌های POSIX، هنگامی که از گزینه home استفاده می‌شود. این طرح‌واره مسیرهایی را تعریف می‌کند که زیر یک پیشوند home مشخص قرار دارند.

• posix_user: طرحی برای سکوهای POSIX، هنگامی که از گزینه‌ی user استفاده می‌شود. این طرح‌واره مسیرهای واقع‌شده زیر پوشه‌ی خانگی کاربر را تعریف می‌کند (site.USER_BASE).

• posix_venv: طرح‌واره برای محیط‌های مجازی پایتون در سکوهای POSIX؛ به‌طور پیش‌فرض همان posix_prefix است.

• nt: طرح‌واره (scheme) برای ویندوز. این طرح‌واره پیش‌فرضی است که هنگام نصب پایتون یا یک کامپوننت استفاده می‌شود.

• nt_user: طرح‌واره برای ویندوز، هنگامی که از گزینه user استفاده می‌شود.

• nt_venv: طرح‌واره‌ای برای محیط‌های مجازی پایتون در ویندوز؛ به‌طور پیش‌فرض همان nt است.

• venv: طرح‌واره‌ای با مقادیری از posix_venv یا nt_venv، بسته به پلتفرمی که پایتون روی آن اجرا می‌شود.

• osx_framework_user: طرح‌واره برای macOS، هنگامی که گزینه‌ی user استفاده می‌شود.

هر طرح‌واره خود از مجموعه‌ای از مسیرها تشکیل شده است و هر مسیر یک شناسه یکتا دارد. پایتون در حال حاضر از هشت مسیر استفاده می‌کند:

• stdlib: پوشه‌ای شامل پرونده‌های کتابخانه استاندارد پایتون که وابسته به پلتفرم خاصی نیستند.

• platstdlib: پوشه‌ای شامل پرونده‌های کتابخانه استاندارد پایتون که مختص پلتفرم هستند.

• platlib: پوشه‌ای برای پرونده‌های مختص سایت و مختص پلتفرم.

• purelib: پوشه‌ای برای پرونده‌های ویژه‌ی سایت و غیرمختص به سکو (پایتون «خالص»).

• include: پوشه‌ی پرونده‌های سرآیند غیرمختص به سکو برای Python C-API.

• platinclude: پوشه‌ای برای پرونده‌های سرآیند وابسته به پلتفرم برای C-API پایتون.

• scripts: پوشه‌ای برای پرونده‌های اسکریپت.

• data: پوشه‌ای برای پرونده‌های داده.

طرح‌واره کاربر

این طرح‌واره به‌عنوان راحت‌ترین راه‌حل برای کاربرانی طراحی شده است که دسترسی نوشتن به پوشه‌ی سراسری site-packages را ندارند یا مایل به نصب در آن نیستند.

پرونده‌ها در زیرپوشه‌هایی از site.USER_BASE نصب خواهند شد (که از این پس userbase نوشته می‌شود). این طرح‌واره، ماژول‌های پایتون خالص و ماژول‌های توسعه را در یک مکان نصب می‌کند (که به‌عنوان 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
data	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
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/pythonX.Y
scripts	userbase/bin
data	userbase

طرح‌واره خانه

ایده‌ی پشت «طرح‌واره home (home scheme)» این است که شما یک مجموعه‌ی شخصی از ماژول‌های Python می‌سازید و نگهداری می‌کنید. نام این طرح‌واره از ایده‌ی پوشه‌ی «home» در Unix گرفته شده است، زیرا غیرمعمول نیست که یک کاربر Unix کاری کند که پوشه‌ی «home» او چیدمانی مشابه /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

طرح‌واره پیشوند

«طرح‌واره prefix» (prefix scheme) زمانی مفید است که بخواهید از یک نصب پایتون برای انجام ساخت/نصب (یعنی اجرای اسکریپت setup) استفاده کنید، اما ماژول‌ها را در پوشه‌ی ماژول‌های شخص ثالث یک نصب پایتون دیگر (یا چیزی که شبیه یک نصب پایتون دیگر به نظر می‌رسد) نصب کنید. اگر این موضوع کمی غیرعادی به نظر می‌رسد، واقعاً همین‌طور است—به همین دلیل طرح‌های user و home پیش‌تر آمده‌اند. با این حال، حداقل دو مورد شناخته‌شده وجود دارد که طرح‌واره prefix در آن‌ها مفید خواهد بود.

ابتدا در نظر بگیرید که بسیاری از توزیع‌های لینوکس، پایتون را در /usr قرار می‌دهند، نه در /usr/local که سنتی‌تر است. این کاملاً مناسب است، زیرا در آن موارد، پایتون بخشی از «سیستم» است، نه یک افزونه محلی. با این حال، اگر در حال نصب ماژول‌های پایتون از منبع هستید، احتمالاً می‌خواهید آن‌ها در /usr/local/lib/python2.X قرار بگیرند، نه در /usr/lib/python2.X.

احتمال دیگر، یک سامانه فایل‌بندی شبکه‌ای است که در آن نامی که برای نوشتن در یک پوشه‌ی دوردست به‌کار می‌رود با نامی که برای خواندن آن به‌کار می‌رود متفاوت است: برای مثال، ممکن است مفسر پایتون که به‌صورت /usr/local/bin/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
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()

نام طرح‌واره پیش‌فرض برای سکوی فعلی را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.10: این تابع پیش‌تر _get_default_scheme() نام داشت و به‌عنوان جزئیات پیاده‌سازی در نظر گرفته می‌شد.

تغییر یافته در نسخه‌ی 3.11: هنگامی که پایتون از یک محیط مجازی اجرا می‌شود، طرح‌واره venv برگردانده می‌شود.

sysconfig.get_preferred_scheme(key)

یک نام طرح‌واره ترجیحی برای چیدمان نصب مشخص‌شده با key را برمی‌گرداند.

key باید یکی از "prefix"، "home" یا "user" باشد.

مقدار بازگشتی یک نام طرح‌واره است که در get_scheme_names() فهرست‌شده است. می‌توان آن را به توابع sysconfig که آرگومان scheme می‌گیرند، مانند get_paths() ارسال کرد.

اضافه شده در نسخه‌ی 3.10.

تغییر یافته در نسخه‌ی 3.11: هنگامی که پایتون از یک محیط مجازی اجرا می‌شود و key="prefix" باشد، طرح‌واره venv برگردانده می‌شود.

sysconfig._get_preferred_schemes()

یک دیکشنری حاوی نام طرح‌واره‌های ترجیحی در سکوی فعلی برمی‌گرداند. پیاده‌سازان و بازتوزیع‌کنندگان پایتون می‌توانند طرح‌واره‌های ترجیحی خود را به مقدار سراسری در سطح ماژول _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 مسیرهای نصب متناظر با هر نام مسیر را برای هر سکو، با متغیرهایی که باید بسط داده شوند، ذخیره می‌کند. برای مثال، مسیر stdlib برای طرح‌واره nt برابر است با: {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 را به‌عنوان یک رشته برمی‌گرداند. مشابه '%d.%d' % sys.version_info[:2].

sysconfig.get_platform()

رشته‌ای را برمی‌گرداند که سکوی کنونی را مشخص می‌کند.

این عمدتاً برای تمایز پوشه‌های ساخت وابسته به پلتفرم و توزیع‌های ساخته‌شده وابسته به پلتفرم استفاده می‌شود. معمولاً شامل نام و نسخه سیستم‌عامل و معماری است (همان‌طور که توسط os.uname() ارائه می‌شود)، اگرچه اطلاعات دقیق گنجانده‌شده به سیستم‌عامل بستگی دارد؛ برای مثال، در لینوکس، نسخه کرنل اهمیت چندانی ندارد.

نمونه‌هایی از مقادیر برگردانده‌شده:

ویندوز:

• win-amd64 (ویندوز ۶۴ بیتی روی AMD64، معروف به x86_64، Intel64 و EM64T)

• win-arm64 (ویندوز ۶۴ بیتی روی ARM64، معروف به AArch64)

• win32 (همه‌ی موارد دیگر - به‌طور مشخص، sys.platform برگردانده می‌شود)

سیستم‌عامل مبتنی بر POSIX:

• linux-x86_64

• macosx-15.5-arm64

• macosx-26.0-universal2 (macOS روی Apple Silicon یا Intel)

• android-24-arm64_v8a

برای سایر سکوهای غیر POSIX، در حال حاضر فقط sys.platform را برمی‌گرداند.

sysconfig.is_python_build()

اگر مفسر پایتونِ در حال اجرا از کد منبع ساخته‌شده باشد و از محل ساخت خود اجرا شود، نه از محلی که در اثر مثلاً اجرای 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 را برمی‌گرداند.

استفاده از خط فرمان

می‌توانید از sysconfig به‌عنوان یک اسکریپت با گزینه‌ی -m پایتون استفاده کنید:

$ 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() را در خروجی استاندارد چاپ خواهد کرد.