مثال¶

نمونه‌ای از پایتون سفارشی‌شده که همیشه با حالت توسعه پایتون فعال اجرا می‌شود؛ در صورت خطا -1 را برمی‌گرداند:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) {
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    }

    // Enable the Python Development Mode
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    PyInitConfig_Free(config);
    return 0;

error:
    {
        // Display the error message.
        //
        // This uncommon braces style is used, because you cannot make
        // goto targets point to variable declarations.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);
        return -1;
    }
}

ایجاد پیکربندی¶

struct PyInitConfig¶

ساختار غیرشفاف برای پیکربندی مقداردهی اولیه پایتون.

PyInitConfig *PyInitConfig_Create(void)¶

یک پیکربندی مقداردهی اولیه‌ی جدید با استفاده از مقادیر پیش‌فرض پیکربندی ایزوله ایجاد کنید.

آن باید توسط PyInitConfig_Free() آزاد شود.

در صورت شکست تخصیص حافظه، NULL را برمی‌گرداند.

void PyInitConfig_Free(PyInitConfig *config)¶

آزاد کردن حافظه‌ی پیکربندی مقداردهی اولیه config.

اگر config برابر NULL باشد، هیچ عملیاتی انجام نمی‌شود.

مدیریت خطا¶

int PyInitConfig_GetError(PyInitConfig *config, const char **err_msg)¶

دریافت پیام خطای config.

• در صورتی که خطا تنظیم شده باشد، *err_msg را تنظیم کرده و 1 برمی‌گرداند.

• در غیر این صورت، *err_msg را روی NULL تنظیم کرده و 0 را برمی‌گرداند.

پیام خطا یک رشته کدگذاری‌شده با UTF-8 است.

اگر config دارای یک کد خروج باشد، کد خروج را به‌عنوان یک پیام خطا قالب‌بندی می‌کند.

پیام خطا تا زمانی که تابع PyInitConfig دیگری با config فراخوانی شود معتبر باقی می‌ماند. فراخوانی‌کننده نیازی به آزاد کردن پیام خطا ندارد.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶

گرفتن کد خروج config.

• اگر config دارای کد خروج تنظیم‌شده باشد، *exitcode را تنظیم می‌کند و 1 را برمی‌گرداند.

• اگر config کد خروجی تنظیم‌شده‌ای نداشته باشد، 0 را برمی‌گرداند.

تنها تابع Py_InitializeFromInitConfig() می‌تواند در صورتی که گزینه parse_argv ناصفر باشد، کد خروج را تنظیم کند.

می‌توان یک کد خروج را هنگامی تنظیم کرد که تجزیه‌ی خط فرمان شکست بخورد (کد خروج 2) یا هنگامی که یک گزینه‌ی خط فرمان درخواست نمایش راهنمای خط فرمان کند (کد خروج 0).

دریافت گزینه‌ها¶

پارامتر name گزینه پیکربندی باید یک رشته غیر NULL، پایان‌یافته با نویسه تهی و کدگذاری‌شده با UTF-8 باشد. به گزینه‌های پیکربندی مراجعه کنید.

int PyInitConfig_HasOption(PyInitConfig *config, const char *name)¶

بررسی می‌کند که آیا پیکربندی گزینه‌ای با نام name دارد.

اگر گزینه وجود داشته باشد 1 را برمی‌گرداند، در غیر این صورت 0 را برمی‌گرداند.

int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)¶

دریافت یک گزینه‌ی پیکربندی از نوع عدد صحیح.

• مقدار *value را تنظیم می‌کند و در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)¶

یک گزینه پیکربندی رشته‌ای را به‌صورت رشته‌ای کدگذاری‌شده با UTF-8 و پایان‌یافته با تهی دریافت می‌کند.

• مقدار *value را تنظیم می‌کند و در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

*value can be set to NULL if the option is unset or if the option is an optional string. Optional strings are documented with the type str | None in the Configuration Options table.

در صورت موفقیت، اگر رشته NULL نباشد، باید با free(value) آزاد شود.

int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)¶

یک گزینه پیکربندی فهرست رشته‌ها را به‌صورت آرایه‌ای از رشته‌های کدگذاری‌شده با UTF-8 و خاتمه‌یافته با تهی دریافت می‌کند.

• مقدار *length و *value را تنظیم می‌کند و در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

در صورت موفقیت، فهرست رشته‌ها باید با PyInitConfig_FreeStrList(length, items) آزاد شود.

void PyInitConfig_FreeStrList(size_t length, char **items)¶

حافظه‌ی فهرست رشته‌های ایجادشده توسط PyInitConfig_GetStrList() را آزاد می‌کند.

تنظیم گزینه‌ها¶

پارامتر name گزینه پیکربندی باید یک رشته غیر NULL، پایان‌یافته با نویسه تهی و کدگذاری‌شده با UTF-8 باشد. به گزینه‌های پیکربندی مراجعه کنید.

برخی گزینه‌های پیکربندی روی گزینه‌های دیگر اثر جانبی دارند. این منطق تنها هنگامی پیاده‌سازی می‌شود که Py_InitializeFromInitConfig() فراخوانی شود، نه توسط توابع «Set» در ادامه. برای مثال، تنظیم dev_mode به 1 باعث نمی‌شود faulthandler به 1 تنظیم شود.

int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)¶

یک گزینه‌ی پیکربندی از نوع عدد صحیح را تنظیم می‌کند.

• در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)¶

یک گزینه پیکربندی رشته‌ای را از یک رشته‌ی کدگذاری‌شده با UTF-8 و خاتمه‌یافته با نویسه تهی تنظیم می‌کند. رشته کپی می‌شود.

Options documented with the type str | None in the Configuration Options table can be set to NULL.

• در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char *const *items)¶

یک گزینه پیکربندی فهرست رشته‌ای را از آرایه‌ای از رشته‌های کدگذاری‌شده با UTF-8 و پایان‌یافته با نویسه تهی تنظیم می‌کند. فهرست رشته‌ها کپی می‌شود.

• در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

ماژول¶

int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))¶

افزودن یک ماژول توسعه‌ای توکار به جدول ماژول‌های توکار.

ماژول جدید را می‌توان با نام name ایمپورت کرد و از تابع initfunc به عنوان تابع مقداردهی اولیه‌ای که در نخستین تلاش برای ایمپورت فراخوانی می‌شود، استفاده می‌کند.

• در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

اگر پایتون چند بار مقداردهی اولیه شود، PyInitConfig_AddModule() باید در هر مقداردهی اولیه پایتون فراخوانی شود.

مشابه تابع PyImport_AppendInittab().

مقداردهی اولیه پایتون¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

پایتون را از پیکربندی مقداردهی اولیه راه‌اندازی کنید.

• در صورت موفقیت 0 را برمی‌گرداند.

• در صورت خطا، خطا را در config تنظیم کرده و -1 برمی‌گرداند.

• اگر پایتون بخواهد خارج شود، یک کد خروج در config تنظیم می‌کند و -1 را برمی‌گرداند.

برای مورد کد خروج، PyInitConfig_GetExitcode() را ببینید.

مثال¶

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

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}

PyWideStringList¶

type PyWideStringList¶

فهرستی از رشته‌های wchar_t*.

اگر length ناصفر باشد، items باید غیر NULL باشد و همه‌ی رشته‌ها باید غیر NULL باشند.

متدها:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶

افزودن آیتم به فهرست.

برای فراخوانی این تابع، پایتون باید از پیش مقداردهی اولیه شده باشد.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶

درج آیتم در فهرست در اندیس.

اگر index بزرگ‌تر یا مساوی طول list باشد، item به list افزوده می‌شود.

index باید بزرگ‌تر یا مساوی با 0 باشد.

برای فراخوانی این تابع، پایتون باید از پیش مقداردهی اولیه شده باشد.

فیلد‌های ساختار:

Py_ssize_t length¶

طول فهرست.

wchar_t **items¶

آیتم‌های فهرست.

PyStatus¶

type PyStatus¶

ساختاری برای ذخیره‌سازی وضعیت یک تابع مقداردهی اولیه: موفقیت، خطا یا خروج.

در صورت وقوع خطا، می‌تواند نام تابع C که خطا را ایجاد کرده است را ذخیره کند.

فیلد‌های ساختار:

int exitcode¶

کد خروج. آرگومان پاس‌داده‌شده به exit().

const char *err_msg¶

پیام خطا.

const char *func¶

نام تابعی که خطا ایجاد کرده است، می‌تواند NULL باشد.

توابع برای ایجاد وضعیت:

PyStatus PyStatus_Ok(void)¶

موفقیت.

PyStatus PyStatus_Error(const char *err_msg)¶

خطای مقداردهی اولیه همراه با پیام.

err_msg نباید NULL باشد.

PyStatus PyStatus_NoMemory(void)¶

شکست تخصیص حافظه (کمبود حافظه).

PyStatus PyStatus_Exit(int exitcode)¶

با کد خروج مشخص‌شده از پایتون خارج شوید.

توابعی برای مدیریت یک وضعیت:

int PyStatus_Exception(PyStatus status)¶

آیا وضعیت خطا یا خروج است؟ اگر درست باشد، استثنا باید مدیریت شود؛ برای مثال با فراخوانی Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)¶

آیا نتیجه یک خطا است؟

int PyStatus_IsExit(PyStatus status)¶

آیا نتیجه یک خروج است؟

void Py_ExitStatusException(PyStatus status)¶

اگر status یک خروج باشد، exit(exitcode) را فراخوانی کنید. اگر status یک خطا باشد، پیام خطا را چاپ کرده و با کد خروج ناصفر خارج شوید. فقط باید در صورتی فراخوانی شود که PyStatus_Exception(status) ناصفر باشد.

مثال:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig¶

type PyPreConfig¶

ساختاری که برای پیش‌مقداردهی اولیه (preinitialize) پایتون استفاده می‌شود.

تابعی برای مقداردهی اولیه‌ی پیش‌پیکربندی:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶

پیش‌پیکربندی را با پیکربندی پایتون مقداردهی اولیه کنید.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶

پیش‌پیکربندی را با پیکربندی ایزوله مقداردهی اولیه کنید.

فیلد‌های ساختار:

int allocator¶

نام تخصیص‌دهنده‌های حافظه‌ی پایتون:

• PYMEM_ALLOCATOR_NOT_SET (0): تخصیص‌دهنده‌های حافظه تغییر داده نمی‌شوند (از پیش‌فرض‌ها استفاده می‌شود).

• PYMEM_ALLOCATOR_DEFAULT (1): تخصیص‌دهنده‌های حافظه پیش‌فرض.

• PYMEM_ALLOCATOR_DEBUG (2): تخصیص‌دهنده‌های حافظه پیش‌فرض به همراه قلاب‌های اشکال‌زدایی.

• PYMEM_ALLOCATOR_MALLOC (3): استفاده از malloc() کتابخانه‌ی C.

• PYMEM_ALLOCATOR_MALLOC_DEBUG (4): اجبار به استفاده از malloc() به همراه قلاب‌های اشکال‌زدایی.

• PYMEM_ALLOCATOR_PYMALLOC (5): تخصیص‌دهنده حافظه pymalloc پایتون.

• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): تخصیص‌دهنده حافظه pymalloc پایتون به همراه قلاب‌های اشکال‌زدایی.

• PYMEM_ALLOCATOR_MIMALLOC (6): استفاده از mimalloc، جایگزین سریعی برای malloc.

• PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): استفاده از mimalloc، جایگزین سریعی برای malloc با قلاب‌های اشکال‌زدایی.

PYMEM_ALLOCATOR_PYMALLOC و PYMEM_ALLOCATOR_PYMALLOC_DEBUG در صورتی که پایتون با --without-pymalloc پیکربندی شده باشد، پشتیبانی نمی‌شوند.

اگر پایتون با --without-mimalloc پیکربندی‌شده باشد یا پشتیبانی اتمی زیرین در دسترس نباشد، PYMEM_ALLOCATOR_MIMALLOC و PYMEM_ALLOCATOR_MIMALLOC_DEBUG پشتیبانی نمی‌شوند.

به مدیریت حافظه مراجعه کنید.

پیش‌فرض: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale¶

locale مربوط به LC_CTYPE را به locale ترجیحی کاربر تنظیم کنید.

اگر برابر 0 باشد، اعضای coerce_c_locale و coerce_c_locale_warn را بر 0 تنظیم می‌کند.

به locale encoding مراجعه کنید.

پیش‌فرض: 1 در پیکربندی پایتون، 0 در پیکربندی ایزوله.

int coerce_c_locale¶

اگر برابر با 2 باشد، C locale اجبار می‌شود.

اگر برابر 1 باشد، locale مربوط به LC_CTYPE خوانده می‌شود تا مشخص شود که آیا باید اجبار (coerce) شود یا خیر.

به locale encoding مراجعه کنید.

پیش‌فرض: -1 در پیکربندی پایتون، 0 در پیکربندی ایزوله.

int coerce_c_locale_warn¶

اگر ناصفر باشد، در صورت اجبار locale C هشداری نشان داده می‌شود.

پیش‌فرض: -1 در پیکربندی پایتون، 0 در پیکربندی ایزوله.

int dev_mode¶

حالت توسعه پایتون: به PyConfig.dev_mode مراجعه کنید.

پیش‌فرض: -1 در حالت پایتون، 0 در حالت ایزوله.

int isolated¶

حالت ایزوله : به PyConfig.isolated مراجعه کنید.

پیش‌فرض: 0 در حالت پایتون، 1 در حالت ایزوله.

int legacy_windows_fs_encoding¶

اگر نا‌صفر باشد:

• مقدار PyPreConfig.utf8_mode را برابر 0 قرار دهید،

• PyConfig.filesystem_encoding را روی "mbcs" تنظیم کنید،

• PyConfig.filesystem_errors را روی "replace" تنظیم کنید.

از مقدار متغیر محیطی PYTHONLEGACYWINDOWSFSENCODING مقداردهی اولیه می‌شود.

فقط در ویندوز در دسترس است. می‌توان از ماکروی #ifdef MS_WINDOWS برای کد مخصوص ویندوز استفاده کرد.

پیش‌فرض: 0.

int parse_argv¶

اگر ناصفر باشد، Py_PreInitializeFromArgs() و Py_PreInitializeFromBytesArgs() آرگومان argv خود را همان‌گونه تجزیه می‌کنند که پایتون معمولی آرگومان‌های خط فرمان را تجزیه می‌کند: به آرگومان‌های خط فرمان مراجعه کنید.

پیش‌فرض: 1 در پیکربندی پایتون، 0 در پیکربندی ایزوله.

int use_environment¶

از متغیرهای محیطی استفاده می‌کنید؟ PyConfig.use_environment را ببینید.

پیش‌فرض: 1 در پیکربندی پایتون و 0 در پیکربندی ایزوله.

int utf8_mode¶

اگر ناصفر باشد، حالت UTF-8 پایتون را فعال می‌کند.

توسط گزینه‌ی خط فرمان -X utf8 و متغیر محیطی PYTHONUTF8 روی 0 یا 1 تنظیم می‌شود.

پیش‌فرض: 1.

پیش‌مقداردهی اولیه‌ی پایتون با PyPreConfig¶

پیش‌مقداردهی اولیه پایتون:

• تنظیم تخصیص‌دهنده‌های حافظه پایتون (PyPreConfig.allocator)

• locale مربوط به LC_CTYPE را پیکربندی کنید (کدگذاری locale)

• تنظیم حالت UTF-8 پایتون (PyPreConfig.utf8_mode)

پیش‌پیکربندی فعلی (نوع PyPreConfig) در _PyRuntime.preconfig ذخیره می‌شود.

توابعی برای پیش‌مقداردهی اولیه (preinitialize) پایتون:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶

پایتون را از پیش‌پیکربندی preconfig پیش‌مقداردهی اولیه می‌کند.

preconfig نباید NULL باشد.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)¶

پایتون را از پیش‌پیکربندی preconfig پیش‌مقداردهی اولیه می‌کند.

اگر parse_argv در preconfig ناصفر باشد، آرگومان‌های خط فرمان argv (رشته‌های بایتی) را تجزیه می‌کند.

preconfig نباید NULL باشد.

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)¶

پایتون را از پیش‌پیکربندی preconfig پیش‌مقداردهی اولیه می‌کند.

اگر parse_argv در preconfig غیر صفر باشد، آرگومان‌های خط فرمان argv (رشته‌های پهن) را پارس می‌کند.

preconfig نباید NULL باشد.

فراخوان‌کننده مسئول مدیریت استثناها (خطا یا خروج) با استفاده از PyStatus_Exception() و Py_ExitStatusException() است.

برای پیکربندی پایتون (PyPreConfig_InitPythonConfig())، اگر پایتون با آرگومان‌های خط فرمان مقداردهی اولیه شود، آرگومان‌های خط فرمان باید برای پیش‌مقداردهی اولیه‌ی پایتون نیز پاس داده شوند، زیرا این آرگومان‌ها بر پیش‌پیکربندی، مانند کدگذاری‌ها، اثر می‌گذارند. برای مثال، گزینه‌ی خط فرمان -X utf8 حالت UTF-8 پایتون را فعال می‌کند.

می‌توان PyMem_SetAllocator() را پس از Py_PreInitialize() و پیش از Py_InitializeFromConfig() برای نصب یک تخصیص‌دهنده حافظه‌ی سفارشی فراخوانی کرد. اگر PyPreConfig.allocator برابر PYMEM_ALLOCATOR_NOT_SET تنظیم شده باشد، می‌توان آن را پیش از Py_PreInitialize() فراخوانی کرد.

توابع تخصیص حافظه‌ی پایتون مانند PyMem_RawMalloc() نباید پیش از پیش‌مقداردهی پایتون استفاده شوند، در حالی که فراخوانی مستقیم malloc() و free() همیشه ایمن است. Py_DecodeLocale() نباید پیش از پیش‌مقداردهی پایتون فراخوانی شود.

مثالی از استفاده از پیش‌مقداردهی اولیه (preinitialization) برای فعال‌سازی حالت UTF-8 پایتون:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig¶

type PyConfig¶

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

پس از اتمام کار، باید از تابع PyConfig_Clear() برای آزاد کردن حافظه‌ی پیکربندی استفاده شود.

متدهای ساختار:

void PyConfig_InitPythonConfig(PyConfig *config)¶

پیکربندی را با پیکربندی پایتون مقداردهی اولیه کنید.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶

پیکربندی را با پیکربندی ایزوله مقداردهی اولیه می‌کند.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)¶

رشته نویسه پهن str را در *config_str کپی کنید.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)¶

str را با استفاده از Py_DecodeLocale() کدگشایی کنید و نتیجه را در *config_str قرار دهید.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)¶

آرگومان‌های خط فرمان (عضو argv از config) را از فهرست argv از رشته‌های نویسه پهن تنظیم می‌کند.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)¶

آرگومان‌های خط فرمان (argv عضوی از config) را از فهرست argv از رشته‌های بایتی تنظیم می‌کند. بایت‌ها با استفاده از Py_DecodeLocale() کدگشایی می‌شوند.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)¶

فهرست رشته‌های پهن list را برابر length و items قرار می‌دهد.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

PyStatus PyConfig_Read(PyConfig *config)¶

خواندن تمام پیکربندی پایتون.

فیلد‌هایی که از قبل مقداردهی اولیه شده‌اند، بدون تغییر باقی می‌مانند.

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

تابع PyConfig_Read() آرگومان‌های PyConfig.argv را فقط یک بار تجزیه می‌کند: پس از تجزیه‌ی آرگومان‌ها، PyConfig.parse_argv روی 2 تنظیم می‌شود. از آنجا که آرگومان‌های پایتون از PyConfig.argv حذف می‌شوند، تجزیه‌ی دوباره‌ی آرگومان‌ها باعث می‌شد گزینه‌های برنامه به‌عنوان گزینه‌های پایتون تجزیه شوند.

پیش‌مقداردهی پایتون را در صورت نیاز انجام دهید.

تغییر یافته در نسخه‌ی 3.10: آرگومان‌های PyConfig.argv اکنون فقط یک‌بار تجزیه می‌شوند، PyConfig.parse_argv پس از تجزیه آرگومان‌ها برابر 2 تنظیم می‌شود، و آرگومان‌ها تنها در صورتی تجزیه می‌شوند که PyConfig.parse_argv برابر 1 باشد.

تغییر یافته در نسخه‌ی 3.11: PyConfig_Read() دیگر تمام مسیرها را محاسبه نمی‌کند و در نتیجه، ممکن است فیلدهای فهرست‌شده در پیکربندی مسیر پایتون تا زمان فراخوانی Py_InitializeFromConfig() به‌روزرسانی نشوند.

void PyConfig_Clear(PyConfig *config)¶

آزاد کردن حافظه پیکربندی.

بیشتر متدهای PyConfig در صورت نیاز پایتون را پیش‌مقداردهی اولیه می‌کنند. در این صورت، پیکربندی پیش‌مقداردهی اولیه پایتون (PyPreConfig) بر اساس PyConfig است. اگر فیلدهای پیکربندی که با PyPreConfig مشترک‌اند تنظیم شوند، باید پیش از فراخوانی یک متد PyConfig مقداردهی شده باشند:

• PyConfig.dev_mode

• PyConfig.isolated

• PyConfig.parse_argv

• PyConfig.use_environment

علاوه بر این، اگر از PyConfig_SetArgv() یا PyConfig_SetBytesArgv() استفاده شود، این متد باید پیش از سایر متدها فراخوانی شود، زیرا پیکربندی پیش‌مقداردهی اولیه به آرگومان‌های خط فرمان وابسته است (اگر parse_argv ناصفر باشد).

فراخوان‌کننده این متدها مسئول مدیریت استثناها (خطا یا خروج) با استفاده از PyStatus_Exception() و Py_ExitStatusException() است.

فیلد‌های ساختار:

PyWideStringList argv¶

آرگومان‌های خط فرمان sys.argv بر اساس argv تنظیم می‌شوند. این پارامترها مشابه پارامترهایی هستند که به تابع main() برنامه پاس داده می‌شوند، با این تفاوت که ورودی اول باید به پرونده اسکریپتی که قرار است اجرا شود اشاره کند، نه به پرونده اجرایی‌ای که مفسر پایتون را میزبانی می‌کند. اگر اسکریپتی که قرار است اجرا شود وجود نداشته باشد، ورودی اول در argv می‌تواند یک رشته خالی باشد.

مقدار parse_argv را برابر 1 قرار دهید تا argv به همان شیوه‌ای که پایتون معمولی آرگومان‌های خط فرمان پایتون را تجزیه می‌کند، تجزیه شود و سپس آرگومان‌های پایتون از argv حذف شوند.

اگر argv خالی باشد، یک رشته خالی افزوده می‌شود تا اطمینان حاصل شود که sys.argv همیشه وجود دارد و هرگز خالی نیست.

پیش‌فرض: NULL.

همچنین عضو orig_argv را ببینید.

int safe_path¶

اگر برابر با صفر باشد، Py_RunMain() هنگام راه‌اندازی یک مسیر بالقوه ناامن را به ابتدای sys.path اضافه می‌کند:

• اگر argv[0] برابر با L"-m" (python -m module) باشد، پوشه‌ی کاری جاری به ابتدا افزوده می‌شود.

• اگر اسکریپتی اجرا شود (python script.py)، پوشه‌ی اسکریپت در ابتدا قرار می‌گیرد. اگر اسکریپت یک پیوند نمادین باشد، پیوندهای نمادین حل می‌شوند.

• در غیر این صورت (python -c code و python)، یک رشته‌ی خالی در ابتدا قرار می‌گیرد که به معنای پوشه‌ی کاری فعلی است.

با گزینه‌ی خط فرمان -P و متغیر محیطی PYTHONSAFEPATH روی 1 تنظیم می‌شود.

پیش‌فرض: 0 در پیکربندی پایتون، 1 در پیکربندی ایزوله.

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

wchar_t *base_exec_prefix¶

sys.base_exec_prefix.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.exec_prefix را ببینید.

wchar_t *base_executable¶

پرونده اجرایی پایه‌ی پایتون: sys._base_executable.

توسط متغیر محیطی __PYVENV_LAUNCHER__ تنظیم می‌شود.

اگر NULL باشد، از PyConfig.executable تنظیم می‌شود.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.executable را ببینید.

wchar_t *base_prefix¶

sys.base_prefix.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.prefix را ببینید.

int buffered_stdio¶

اگر برابر با 0 باشد و configure_c_stdio غیر‌صفر باشد، بافر کردن جریان‌های stdout و stderr زبان C غیر‌فعال می‌شود.

توسط گزینه‌ی خط فرمان -u و متغیر محیطی PYTHONUNBUFFERED روی 0 تنظیم می‌شود.

stdin همیشه در حالت بافرشده باز می‌شود.

پیش‌فرض: 1.

int bytes_warning¶

اگر برابر با 1 باشد، هنگام مقایسه‌ی bytes یا bytearray با str، یا مقایسه‌ی bytes با int، هشداری صادر می‌شود.

اگر برابر یا بزرگ‌تر از 2 باشد، در این موارد استثنای BytesWarning مطرح می‌شود.

با گزینه‌ی خط فرمان -b افزایش می‌یابد.

پیش‌فرض: 0.

منسوخ شده از نسخه‌ی 3.15, در نسخه‌ی 3.17 حذف خواهد شد: گزینه‌های -b و -bb در نسخه‌ی 3.17 به عملیات بی‌اثر تبدیل خواهند شد. عضو bytes_warning در نسخه‌ی 3.17 حذف خواهد شد.

int warn_default_encoding¶

اگر نا‌صفر باشد، هنگامی که io.TextIOWrapper از کدگذاری پیش‌فرض خود استفاده می‌کند، هشدار EncodingWarning نشان داده می‌شود. برای جزئیات به فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning) مراجعه کنید.

پیش‌فرض: 0.

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

int code_debug_ranges¶

اگر برابر با 0 باشد، گنجاندن نگاشت‌های سطر پایانی و ستون در اشیاء کد را غیرفعال می‌کند. همچنین چاپ نشان‌های ^ (caret) در ردگیری برای مکان‌های مشخص خطا را غیرفعال می‌کند.

با متغیر محیطی PYTHONNODEBUGRANGES و با گزینه‌ی خط فرمان -X no_debug_ranges روی 0 تنظیم می‌شود.

پیش‌فرض: 1.

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

wchar_t *check_hash_pycs_mode¶

کنترل رفتار اعتبارسنجی پرونده‌های .pyc مبتنی بر هش: مقدار گزینه‌ی خط فرمان --check-hash-based-pycs.

مقادیر معتبر:

• L"always": هش پرونده‌ی منبع برای باطل‌سازی محاسبه می‌شود، صرف‌نظر از مقدار پرچم 'check_source'.

• L"never": فرض کنید که pycهای مبتنی بر هش همیشه معتبر هستند.

• L"default": پرچم 'check_source' در pyc‌های مبتنی بر هش، بی‌اعتبارسازی را تعیین می‌کند.

پیش‌فرض: L"default".

همچنین ببینید PEP 552 «pyc‌های قطعی».

int configure_c_stdio¶

اگر نا‌صفر باشد، جریان‌های استاندارد C را پیکربندی می‌کند:

• در ویندوز، حالت دودویی (O_BINARY) را روی stdin، stdout و stderr تنظیم کنید.

• اگر buffered_stdio برابر صفر باشد، بافر کردن جریان‌های stdin، stdout و stderr غیرفعال می‌شود.

• اگر interactive ناصفر باشد، بافر کردن جریان روی stdin و stdout فعال می‌شود (در ویندوز فقط stdout).

پیش‌فرض: 1 در پیکربندی پایتون، 0 در پیکربندی ایزوله.

int dev_mode¶

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

با گزینه‌ی -X dev و متغیر محیطی PYTHONDEVMODE برابر 1 قرار می‌گیرد.

پیش‌فرض: -1 در حالت پایتون، 0 در حالت ایزوله.

int dump_refs¶

ارجاع‌های پایتون برون‌ریزی شوند؟

اگر ناصفر باشد، تمام اشیایی که در زمان خروج هنوز زنده‌اند را برون‌ریزی می‌کند.

با متغیر محیطی PYTHONDUMPREFS روی 1 تنظیم می‌شود.

نیازمند ساخت خاصی از پایتون است که ماکروی Py_TRACE_REFS در آن تعریف‌شده باشد: گزینه‌ی configure --with-trace-refs را ببینید.

پیش‌فرض: 0.

wchar_t *dump_refs_file¶

نام پرونده‌ای که ارجاع‌های پایتون در آن برون‌ریزی می‌شوند.

توسط متغیر محیطی PYTHONDUMPREFSFILE تنظیم می‌شود.

پیش‌فرض: NULL.

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

wchar_t *exec_prefix¶

پیشوند پوشه‌ی مختص سایت که پرونده‌های پایتونِ وابسته به پلتفرم در آن نصب می‌شوند: sys.exec_prefix.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.base_exec_prefix را ببینید.

wchar_t *executable¶

مسیر مطلق پرونده دودویی اجرایی مفسر پایتون: sys.executable.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.base_executable را ببینید.

int faulthandler¶

فعال کردن faulthandler؟

اگر نا‌صفر باشد، تابع faulthandler.enable() در زمان راه‌اندازی فراخوانی می‌شود.

با گزینه‌ی -X faulthandler و متغیر محیطی PYTHONFAULTHANDLER روی 1 تنظیم می‌شود.

پیش‌فرض: -1 در حالت پایتون، 0 در حالت ایزوله.

wchar_t *filesystem_encoding¶

کدگذاری سامانه فایل‌بندی: sys.getfilesystemencoding().

در macOS، Android و VxWorks: به‌طور پیش‌فرض از "utf-8" استفاده می‌شود.

در ویندوز: به‌طور پیش‌فرض از "utf-8" استفاده کنید، یا "mbcs" در صورتی که legacy_windows_fs_encoding از PyPreConfig ناصفر باشد.

کدگذاری پیش‌فرض روی سایر پلتفرم‌ها:

• "utf-8" اگر PyPreConfig.utf8_mode ناصفر باشد.

• "ascii" اگر پایتون تشخیص دهد که nl_langinfo(CODESET) کدگذاری اسکی را اعلام می‌کند، در حالی که تابع mbstowcs() از کدگذاری دیگری (معمولاً Latin1) کدگشایی می‌کند.

• "utf-8" اگر nl_langinfo(CODESET) رشته‌ای خالی برگرداند.

• در غیر این صورت، از locale encoding استفاده کنید: نتیجه‌ی nl_langinfo(CODESET).

در زمان راه‌اندازی پایتون، نام کدگذاری به نام کدک پایتون نرمال‌سازی می‌شود. برای مثال، "ANSI_X3.4-1968" با "ascii" جایگزین می‌شود.

همچنین عضو filesystem_errors را ببینید.

همچنین برای کدگذاری مسیرها در زمان اجرا، به PyUnicode_EncodeFSDefault() و توابع مرتبط مراجعه کنید.

wchar_t *filesystem_errors¶

هندلر خطای سامانه فایل‌بندی: sys.getfilesystemencodeerrors().

در ویندوز: به‌طور پیش‌فرض از "surrogatepass" استفاده کنید، یا "replace" اگر legacy_windows_fs_encoding در PyPreConfig ناصفر باشد.

در پلتفرم‌های دیگر: به‌طور پیش‌فرض از "surrogateescape" استفاده کنید.

هندلرهای خطای پشتیبانی‌شده:

• "strict"

• "surrogateescape"

• "surrogatepass" (فقط با کدگذاری UTF-8 پشتیبانی می‌شود)

همچنین عضو filesystem_encoding را ببینید.

int use_frozen_modules¶

اگر نا‌صفر باشد، از ماژول‌های فریزشده استفاده می‌شود.

توسط متغیر محیطی PYTHON_FROZEN_MODULES تنظیم می‌شود.

پیش‌فرض: 1 در ساخت‌ انتشار، یا 0 در ساخت‌ اشکال‌زدایی.

unsigned long hash_seed¶

int use_hash_seed¶

بذر تصادفی‌سازی تابع هش.

اگر use_hash_seed صفر باشد، یک بذر هنگام راه‌اندازی پایتون به‌طور تصادفی انتخاب می‌شود و hash_seed نادیده گرفته می‌شود.

توسط متغیر محیطی PYTHONHASHSEED تنظیم می‌شود.

مقدار پیش‌فرض use_hash_seed: -1 در حالت پایتون، 0 در حالت ایزوله.

wchar_t *home¶

پوشه‌ی «خانه»ی پیش‌فرضِ پایتون را تنظیم می‌کند، یعنی مکان کتابخانه‌های استاندارد پایتون (به PYTHONHOME مراجعه کنید).

با متغیر محیطی PYTHONHOME تنظیم می‌شود.

پیش‌فرض: NULL.

بخشی از ورودی پیکربندی مسیر پایتون است.

int import_time¶

اگر 1 باشد، زمان ایمپورت پروفایل‌گیری می‌شود. اگر 2 باشد، خروجی اضافی‌ای گنجانده می‌شود که نشان می‌دهد یک ماژول ایمپورت‌شده از قبل بارگذاری شده است.

توسط گزینه‌ی -X importtime و متغیر محیطی PYTHONPROFILEIMPORTTIME تنظیم می‌شود.

پیش‌فرض: 0.

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از import_time = 2 افزوده شد

int inspect¶

پس از اجرای یک اسکریپت یا دستور، وارد حالت تعاملی شوید.

اگر بزرگ‌تر از 0 باشد، بررسی (inspect) را فعال می‌کند: وقتی یک اسکریپت به‌عنوان آرگومان اول پاس داده شود یا از گزینه -c استفاده شود، پس از اجرای اسکریپت یا فرمان وارد حالت تعاملی می‌شود، حتی زمانی که sys.stdin پایانه به نظر نرسد.

با گزینه‌ی خط فرمان -i افزایش می‌یابد. اگر متغیر محیطی PYTHONINSPECT غیرخالی باشد، روی 1 تنظیم می‌شود.

پیش‌فرض: 0.

int install_signal_handlers¶

نصب هندلر‌های سیگنال پایتون؟

پیش‌فرض: 1 در حالت پایتون، 0 در حالت ایزوله.

int interactive¶

اگر بزرگ‌تر از 0 باشد، حالت تعاملی (REPL) را فعال می‌کند.

توسط گزینه‌ی خط فرمان -i افزایش می‌یابد.

پیش‌فرض: 0.

int int_max_str_digits¶

محدودیت طول تبدیل رشته به عدد صحیح را پیکربندی می‌کند. مقدار اولیه‌ی -1 به این معناست که مقدار از خط فرمان یا محیط گرفته می‌شود و در غیر این صورت مقدار پیش‌فرض ۴۳۰۰ (sys.int_info.default_max_str_digits) خواهد بود. مقدار 0 این محدودیت را غیرفعال می‌کند. مقادیر بزرگ‌تر از صفر اما کوچک‌تر از ۶۴۰ (sys.int_info.str_digits_check_threshold) پشتیبانی نمی‌شوند و منجر به خطا می‌شوند.

با پرچم خط فرمان -X int_max_str_digits یا متغیر محیطی PYTHONINTMAXSTRDIGITS پیکربندی می‌شود.

پیش‌فرض: -1 در حالت پایتون. ۴۳۰۰ (sys.int_info.default_max_str_digits) در حالت ایزوله.

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

int cpu_count¶

اگر مقدار cpu_count برابر -1 نباشد، مقادیر بازگشتی os.cpu_count()، os.process_cpu_count() و multiprocessing.cpu_count() را بازنویسی می‌کند.

با پرچم خط فرمان -X cpu_count=n|default یا متغیر محیطی PYTHON_CPU_COUNT پیکربندی می‌شود.

پیش‌فرض: -1.

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

int isolated¶

اگر بزرگ‌تر از 0 باشد، حالت ایزوله را فعال می‌کند:

• مقدار safe_path را برابر 1 قرار دهید: هنگام راه‌اندازی پایتون، هیچ مسیری که بالقوه ناامن است — مانند پوشه‌ی جاری، پوشه‌ی اسکریپت یا یک رشته‌ی خالی — به ابتدای sys.path افزوده نشود.

• مقدار use_environment را روی 0 تنظیم کنید: متغیرهای محیطی PYTHON نادیده گرفته می‌شوند.

• مقدار user_site_directory را 0 قرار دهید: پوشه‌ی site کاربر به sys.path اضافه نشود.

• REPL پایتون ماژول readline را ایمپورت نمی‌کند و پیکربندی پیش‌فرض readline را نیز در اعلان‌های تعاملی فعال نمی‌کند.

با گزینه‌ی خط فرمان -I روی 1 تنظیم می‌شود.

پیش‌فرض: 0 در حالت پایتون، 1 در حالت ایزوله.

همچنین پیکربندی ایزوله و PyPreConfig.isolated را ببینید.

int lazy_imports¶

Control lazy imports.

A value of -1 keeps the default behaviour, where only imports marked with the lazy keyword are lazy. A value of 1 makes every import lazy. 0 is rejected.

با پرچم خط فرمان -X int_max_str_digits یا متغیر محیطی PYTHONINTMAXSTRDIGITS پیکربندی می‌شود.

پیش‌فرض: -1.

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

int legacy_windows_stdio¶

اگر غیر صفر باشد، به‌جای io._WindowsConsoleIO از io.FileIO برای sys.stdin، sys.stdout و sys.stderr استفاده می‌شود.

اگر متغیر محیطی PYTHONLEGACYWINDOWSSTDIO به یک رشته‌ی غیرخالی تنظیم شده باشد، به 1 تنظیم می‌شود.

فقط در ویندوز در دسترس است. می‌توان از ماکروی #ifdef MS_WINDOWS برای کد مخصوص ویندوز استفاده کرد.

پیش‌فرض: 0.

همچنین PEP 528 (تغییر کدگذاری کنسول ویندوز به UTF-8) را ببینید.

int malloc_stats¶

اگر ناصفر باشد، آمار تخصیص‌دهنده حافظه pymalloc پایتون در زمان خروج برون‌ریزی می‌شود.

توسط متغیر محیطی PYTHONMALLOCSTATS به 1 تنظیم می‌شود.

اگر پایتون با گزینه‌ی --without-pymalloc پیکربندی شده باشد، این گزینه نادیده گرفته می‌شود.

پیش‌فرض: 0.

wchar_t *platlibdir¶

نام پوشه‌ی کتابخانه‌ی پلتفرم: sys.platlibdir.

توسط متغیر محیطی PYTHONPLATLIBDIR تنظیم می‌شود.

پیش‌فرض: مقدار ماکروی PLATLIBDIR که توسط configure --with-platlibdir option تنظیم می‌شود (پیش‌فرض: "lib"، یا "DLLs" در ویندوز).

بخشی از ورودی پیکربندی مسیر پایتون است.

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

تغییر یافته در نسخه‌ی 3.11: این ماکرو اکنون در ویندوز برای مکان‌یابی ماژول‌های توسعه‌ای کتابخانه استاندارد استفاده می‌شود که معمولاً در DLLs قرار دارند. با این حال، برای سازگاری، توجه داشته باشید که این مقدار برای هرگونه چیدمان غیراستاندارد، از جمله ساخت‌های درون‌درخت (in-tree builds) و محیط‌های مجازی، نادیده گرفته می‌شود.

wchar_t *pythonpath_env¶

مسیرهای جستجوی ماژول (sys.path) به‌صورت رشته‌ای که با DELIM (os.pathsep) جدا شده است.

توسط متغیر محیطی PYTHONPATH تنظیم می‌شود.

پیش‌فرض: NULL.

بخشی از ورودی پیکربندی مسیر پایتون است.

PyWideStringList module_search_paths¶

int module_search_paths_set¶

مسیرهای جستجوی ماژول: sys.path.

اگر module_search_paths_set برابر با 0 باشد، Py_InitializeFromConfig() مقدار module_search_paths را جایگزین می‌کند و module_search_paths_set را روی 1 تنظیم می‌کند.

پیش‌فرض: فهرست خالی (module_search_paths) و 0 (module_search_paths_set).

بخشی از خروجی پیکربندی مسیر پایتون است.

int optimization_level¶

سطح بهینه‌سازی کامپایل:

• 0: بهینه‌ساز پنجره‌ای (peephole optimizer)، مقدار __debug__ برابر True قرار می‌گیرد.

• 1: سطح ۰، حذف ادعاها، تنظیم __debug__ به False.

• 2: سطح ۱، حذف رشته‌های مستند.

با گزینه‌ی خط فرمان -O افزایش می‌یابد. برابر با مقدار متغیر محیطی PYTHONOPTIMIZE قرار می‌گیرد.

پیش‌فرض: 0.

PyWideStringList orig_argv¶

فهرست آرگومان‌های اصلی خط فرمان که به پرونده اجرایی پایتون ارسال شده‌اند: sys.orig_argv.

اگر فهرست orig_argv خالی باشد و argv فهرستی نباشد که تنها شامل یک رشته خالی باشد، PyConfig_Read() پیش از تغییر دادن argv (اگر parse_argv ناصفر باشد)، argv را در orig_argv کپی می‌کند.

همچنین عضو argv و تابع Py_GetArgcArgv() را ببینید.

پیش‌فرض: فهرست خالی.

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

int parse_argv¶

پارس کردن آرگومان‌های خط فرمان؟

اگر برابر با 1 باشد، argv به همان روشی که پایتون معمولی آرگومان‌های خط فرمان را پارس می‌کند پارس می‌شود، و آرگومان‌های پایتون از argv حذف می‌شوند.

تابع PyConfig_Read() آرگومان‌های PyConfig.argv را فقط یک بار تجزیه می‌کند: پس از تجزیه‌ی آرگومان‌ها، PyConfig.parse_argv روی 2 تنظیم می‌شود. از آنجا که آرگومان‌های پایتون از PyConfig.argv حذف می‌شوند، تجزیه‌ی دوباره‌ی آرگومان‌ها باعث می‌شد گزینه‌های برنامه به‌عنوان گزینه‌های پایتون تجزیه شوند.

پیش‌فرض: 1 در حالت پایتون، 0 در حالت ایزوله.

تغییر یافته در نسخه‌ی 3.10: آرگومان‌های PyConfig.argv اکنون تنها زمانی تجزیه می‌شوند که PyConfig.parse_argv برابر با 1 باشد.

int parser_debug¶

حالت اشکال‌زدایی پارسر. اگر بزرگ‌تر از 0 باشد، خروجی اشکال‌زدایی پارسر را فعال می‌کند (فقط برای کاربران خبره، بسته به گزینه‌های کامپایل).

با گزینه‌ی خط فرمان -d افزایش می‌یابد. به مقدار متغیر محیطی PYTHONDEBUG تنظیم می‌شود.

به نسخه‌ی اشکال‌زدایی پایتون نیاز دارد (ماکروی Py_DEBUG باید تعریف شده باشد).

پیش‌فرض: 0.

int pathconfig_warnings¶

اگر ناصفر باشد، محاسبه‌ی پیکربندی مسیر مجاز است هشدارها را در stderr ثبت کند. اگر برابر 0 باشد، این هشدارها سرکوب می‌شوند.

پیش‌فرض: 1 در حالت پایتون، 0 در حالت ایزوله.

بخشی از ورودی پیکربندی مسیر پایتون است.

تغییر یافته در نسخه‌ی 3.11: اکنون در ویندوز نیز اعمال می‌شود.

wchar_t *prefix¶

پیشوند پوشه‌ی مختص سایت که پرونده‌های پایتونِ مستقل از پلتفرم در آن نصب می‌شوند: sys.prefix.

پیش‌فرض: NULL.

بخشی از خروجی پیکربندی مسیر پایتون است.

همچنین PyConfig.base_prefix را ببینید.

wchar_t *program_name¶

نام برنامه‌ای که برای مقداردهی اولیه‌ی executable و در پیام‌های خطای اولیه در حین مقداردهی اولیه پایتون استفاده می‌شود.

• در macOS، اگر متغیر محیطی PYTHONEXECUTABLE تنظیم شده باشد، از آن استفاده کنید.

• اگر ماکروی WITH_NEXT_FRAMEWORK تعریف شده باشد، در صورت تنظیم بودن، از متغیر محیطی __PYVENV_LAUNCHER__ استفاده می‌شود.

• در صورت موجود و غیرخالی بودن، از argv[0] argv استفاده کنید.

• در غیر این صورت، در ویندوز از L"python" و در سایر پلتفرم‌ها از L"python3" استفاده کنید.

پیش‌فرض: NULL.

بخشی از ورودی پیکربندی مسیر پایتون است.

wchar_t *pycache_prefix¶

پوشه‌ای که پرونده‌های .pyc نهانگاهی در آن نوشته می‌شوند: sys.pycache_prefix.

توسط گزینه‌ی خط فرمان -X pycache_prefix=PATH و متغیر محیطی PYTHONPYCACHEPREFIX تنظیم می‌شود. گزینه‌ی خط فرمان اولویت دارد.

اگر NULL باشد، sys.pycache_prefix روی None تنظیم می‌شود.

پیش‌فرض: NULL.

int quiet¶

حالت ساکت. اگر بزرگ‌تر از 0 باشد، حق نشر و نسخه هنگام راه‌اندازی پایتون در حالت تعاملی نمایش داده نمی‌شود.

توسط گزینه‌ی خط فرمان -q افزایش می‌یابد.

پیش‌فرض: 0.

wchar_t *run_command¶

مقدار گزینه‌ی خط فرمان -c.

توسط Py_RunMain() استفاده می‌شود.

پیش‌فرض: NULL.

wchar_t *run_filename¶

نام پرونده‌ی ارسال‌شده در خط فرمان: آرگومان انتهایی خط فرمان بدون -c یا -m. این نام پرونده توسط تابع Py_RunMain() استفاده می‌شود.

برای مثال، توسط خط فرمان python3 script.py arg برابر script.py قرار می‌گیرد.

همچنین گزینه‌ی PyConfig.skip_source_first_line را ببینید.

پیش‌فرض: NULL.

wchar_t *run_module¶

مقدار گزینه‌ی خط فرمان -m.

توسط Py_RunMain() استفاده می‌شود.

پیش‌فرض: NULL.

wchar_t *run_presite¶

نقطه‌ی ورودی module یا module:func که باید پیش از ایمپورت شدن ماژول site اجرا شود.

تنظیم‌شده توسط گزینه‌ی خط فرمان -X presite=module:func و متغیر محیطی PYTHON_PRESITE. گزینه‌ی خط فرمان اولویت دارد.

به نسخه‌ی اشکال‌زدایی پایتون نیاز دارد (ماکروی Py_DEBUG باید تعریف شده باشد).

پیش‌فرض: NULL.

int show_ref_count¶

نمایش مجموع شمارش ارجاع در هنگام خروج (به‌جز اشیاء نامیرا)؟

با گزینه‌ی خط فرمان -X showrefcount روی 1 تنظیم می‌شود.

نیازمند ساخت‌ دیباگ پایتون است (ماکروی Py_REF_DEBUG باید تعریف شده باشد).

پیش‌فرض: 0.

int site_import¶

آیا ماژول site در زمان راه‌اندازی ایمپورت شود؟

اگر برابر با صفر باشد، ایمپورت ماژول site و دستکاری‌های وابسته به site در sys.path که این ایمپورت در پی دارد را غیرفعال می‌کند.

همچنین در صورتی که ماژول site بعداً به‌طور صریح ایمپورت شود، این دستکاری‌ها را غیرفعال می‌کند (اگر می‌خواهید این دستکاری‌ها انجام شوند، site.main() را فراخوانی کنید).

با گزینه‌ی خط فرمان -S روی 0 تنظیم می‌شود.

sys.flags.no_site به مقدار معکوسِ site_import تنظیم می‌شود.

پیش‌فرض: 1.

int skip_source_first_line¶

اگر ناصفر باشد، از سطر نخستِ منبع PyConfig.run_filename صرف‌نظر می‌شود.

این اجازه می‌دهد که از شکل‌های غیر‌یونیکسی #!cmd استفاده کنید. این تنها برای یک ترفند مخصوص DOS در نظر گرفته شده است.

با گزینه‌ی خط فرمان -x روی 1 تنظیم می‌شود.

پیش‌فرض: 0.

wchar_t *stdio_encoding¶

wchar_t *stdio_errors¶

کدگذاری و خطاهای کدگذاری sys.stdin، sys.stdout و sys.stderr (اما sys.stderr همیشه از هندلر خطای "backslashreplace" استفاده می‌کند).

اگر متغیر محیطی PYTHONIOENCODING خالی نباشد، از آن استفاده کنید.

کدگذاری پیش‌فرض:

• "UTF-8" اگر PyPreConfig.utf8_mode غیر صفر باشد.

• در غیر این صورت، از locale encoding استفاده کنید.

هندلر خطای پیش‌فرض:

• در ویندوز: از "surrogateescape" استفاده کنید.

• "surrogateescape" اگر PyPreConfig.utf8_mode غیر صفر باشد، یا اگر locale مربوط به LC_CTYPE برابر با "C" یا "POSIX" باشد.

• "strict" در غیر این صورت.

همچنین PyConfig.legacy_windows_stdio را ببینید.

int tracemalloc¶

tracemalloc فعال شود؟

اگر ناصفر باشد، tracemalloc.start() در زمان راه‌اندازی فراخوانی می‌شود.

توسط گزینه‌ی خط فرمان -X tracemalloc=N و متغیر محیطی PYTHONTRACEMALLOC تنظیم می‌شود.

پیش‌فرض: -1 در حالت پایتون، 0 در حالت ایزوله.

int perf_profiling¶

فعال‌سازی پشتیبانی از پروفایل‌گیر perf لینوکس؟

اگر برابر با 1 باشد، پشتیبانی از پروفایل‌گیر perf لینوکس فعال می‌شود.

اگر برابر با 2 باشد، پشتیبانی از پروفایل‌گیر perf لینوکس به همراه پشتیبانی از DWARF JIT فعال می‌شود.

توسط گزینه‌ی خط فرمان -X perf و متغیر محیطی PYTHONPERFSUPPORT روی 1 تنظیم می‌شود.

توسط گزینه‌ی خط فرمان -X perf_jit و متغیر محیطی PYTHON_PERF_JIT_SUPPORT به 2 تنظیم می‌شود.

پیش‌فرض: -1.

همچنین ببینید

برای اطلاعات بیشتر به پشتیبانی پایتون از پروفایل‌گیرهای سازگار با perf map مراجعه کنید.

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

wchar_t *stdlib_dir¶

پوشه‌ی کتابخانه استاندارد پایتون.

پیش‌فرض: NULL.

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

int use_environment¶

استفاده از متغیرهای محیطی؟

اگر برابر با صفر باشد، متغیرهای محیطی نادیده گرفته می‌شوند.

با گزینه‌ی خط فرمان -S روی 0 تنظیم می‌شود.

پیش‌فرض: 1 در پیکربندی پایتون و 0 در پیکربندی ایزوله.

int use_system_logger¶

اگر نا‌صفر باشد، stdout و stderr به گزارش سیستم بازهدایت خواهند شد.

فقط در macOS 10.12 و نسخه‌های بعدی، و در iOS در دسترس است.

پیش‌فرض: 0 (استفاده نکردن از گزارش سیستم) در macOS؛ 1 در iOS (استفاده از گزارش سیستم).

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

int user_site_directory¶

اگر نا‌صفر باشد، پوشه‌ی site کاربر به sys.path افزوده می‌شود.

با گزینه‌های خط فرمان -s و -I به 0 تنظیم می‌شود.

توسط متغیر محیطی PYTHONNOUSERSITE روی 0 تنظیم می‌شود.

پیش‌فرض: 1 در حالت پایتون، 0 در حالت ایزوله.

int verbose¶

حالت پرگویی (verbose). اگر بزرگ‌تر از 0 باشد، هر بار که ماژولی ایمپورت می‌شود، پیامی چاپ می‌شود که مکان (نام پرونده یا ماژول توکار) بارگذاری آن را نشان می‌دهد.

اگر بزرگ‌تر یا مساوی 2 باشد، هنگام جست‌وجوی یک ماژول، برای هر پرونده‌ای که بررسی می‌شود پیامی چاپ می‌کند. همچنین اطلاعاتی درباره پاک‌سازی ماژول‌ها هنگام خروج ارائه می‌دهد.

با گزینه‌ی خط فرمان -v افزایش می‌یابد.

توسط مقدار متغیر محیطی PYTHONVERBOSE تنظیم می‌شود.

پیش‌فرض: 0.

PyWideStringList warnoptions¶

گزینه‌های ماژول warnings برای ساخت صافی‌های هشدار، از کمترین تا بیشترین اولویت: sys.warnoptions.

ماژول warnings مقدار sys.warnoptions را با ترتیب معکوس اضافه می‌کند: آخرین آیتم PyConfig.warnoptions به اولین آیتم warnings.filters تبدیل می‌شود که ابتدا بررسی می‌شود (بالاترین اولویت).

گزینه‌ی خط فرمان -W مقدار خود را به warnoptions اضافه می‌کند؛ می‌توان آن را چندین بار استفاده کرد.

متغیر محیطی PYTHONWARNINGS نیز می‌تواند برای افزودن گزینه‌های هشدار استفاده شود. می‌توان چندین گزینه را مشخص کرد که با کاما (,) از یکدیگر جدا شده‌اند.

پیش‌فرض: فهرست خالی.

int write_bytecode¶

اگر برابر 0 باشد، پایتون هنگام ایمپورت ماژول‌های سورس تلاشی برای نوشتن پرونده‌های .pyc نمی‌کند.

با گزینه‌ی خط فرمان -B و متغیر محیطی PYTHONDONTWRITEBYTECODE روی 0 تنظیم می‌شود.

sys.dont_write_bytecode به مقدار معکوسِ write_bytecode مقداردهی اولیه می‌شود.

پیش‌فرض: 1.

PyWideStringList xoptions¶

مقادیر گزینه‌های خط فرمان -X: sys._xoptions.

پیش‌فرض: فهرست خالی.

int _pystats¶

اگر نا‌صفر باشد، آمار عملکرد هنگام خروج پایتون نوشته می‌شود.

نیاز به ساخت‌ خاصی با ماکروی Py_STATS دارد: به --enable-pystats مراجعه کنید.

پیش‌فرض: 0.

اگر parse_argv ناصفر باشد، آرگومان‌های argv به همان شیوه‌ای تجزیه می‌شوند که پایتون معمولی آرگومان‌های خط فرمان را تجزیه می‌کند، و آرگومان‌های پایتون از argv حذف می‌شوند.

گزینه‌های xoptions برای تنظیم گزینه‌های دیگر تجزیه می‌شوند؛ به گزینه‌ی خط فرمان -X مراجعه کنید.

مقداردهی اولیه با PyConfig¶

مقداردهی اولیه مفسر از یک ساختار پیکربندی پرشده، با فراخوانی Py_InitializeFromConfig() انجام می‌شود.

فراخوان‌کننده مسئول مدیریت استثناها (خطا یا خروج) با استفاده از PyStatus_Exception() و Py_ExitStatusException() است.

اگر از PyImport_FrozenModules()، PyImport_AppendInittab() یا PyImport_ExtendInittab() استفاده شود، باید پس از پیش‌مقداردهی اولیه پایتون و پیش از مقداردهی اولیه پایتون تنظیم یا فراخوانی شوند. اگر پایتون چندین بار مقداردهی اولیه شود، PyImport_AppendInittab() یا PyImport_ExtendInittab() باید پیش از هر مقداردهی اولیه پایتون فراخوانی شوند.

پیکربندی فعلی (نوع PyConfig) در PyInterpreterState.config ذخیره می‌شود.

نمونه‌ای از تنظیم نام برنامه:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);
    return;

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
}

مثال کامل‌تری که پیکربندی پیش‌فرض را تغییر می‌دهد، پیکربندی را می‌خواند و سپس برخی از پارامترها را بازنویسی می‌کند. توجه داشته باشید که از نسخه‌ی 3.11، بسیاری از پارامترها تا زمان راه‌اندازی محاسبه نمی‌شوند و بنابراین نمی‌توان مقادیر را از ساختار پیکربندی خواند. هر مقداری که پیش از فراخوانی initialize تنظیم شده باشد، توسط راه‌اندازی بدون تغییر باقی می‌ماند:

PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Specify sys.path explicitly */
    /* If you want to modify the default set of paths, finish
       initialization first and then use PySys_GetAttrString("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) {
        goto done;
    }
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

پیکربندی ایزوله¶

توابع PyPreConfig_InitIsolatedConfig() و PyConfig_InitIsolatedConfig() پیکربندی‌ای برای جداسازی پایتون از سیستم ایجاد می‌کنند. برای مثال، برای تعبیه کردن پایتون در یک برنامه.

این پیکربندی، متغیرهای پیکربندی سراسری، متغیرهای محیطی، آرگومان‌های خط فرمان (PyConfig.argv تجزیه نمی‌شود) و پوشه site کاربر را نادیده می‌گیرد. جریان‌های استاندارد C (مثلاً stdout) و locale مربوط به LC_CTYPE بدون تغییر باقی می‌مانند. هندلرهای سیگنال نصب نمی‌شوند.

پرونده‌های پیکربندی همچنان با این پیکربندی برای تعیین مسیرهایی که مشخص نشده‌اند استفاده می‌شوند. برای جلوگیری از محاسبه‌ی پیکربندی مسیر پیش‌فرض، اطمینان حاصل کنید که PyConfig.home مشخص شده باشد.

پیکربندی پایتون¶

توابع PyPreConfig_InitPythonConfig() و PyConfig_InitPythonConfig() پیکربندی‌ای برای ساخت پایتونی سفارشی که مانند پایتون معمولی رفتار می‌کند، ایجاد می‌کنند.

متغیرهای محیطی و آرگومان‌های خط فرمان برای پیکربندی پایتون استفاده می‌شوند، در حالی که متغیرهای پیکربندی سراسری نادیده گرفته می‌شوند.

این تابع بسته به locale مربوط به LC_CTYPE و متغیرهای محیطی PYTHONUTF8 و PYTHONCOERCECLOCALE، اجبار locale سی (C locale coercion) (PEP 538) و حالت UTF-8 پایتون (PEP 540) را فعال می‌کند.

پیکربندی مسیر پایتون¶

PyConfig شامل چندین فیلد برای پیکربندی مسیر است:

• ورودی‌های پیکربندی مسیر:

  • PyConfig.home

  • PyConfig.platlibdir

  • PyConfig.pathconfig_warnings

  • PyConfig.program_name

  • PyConfig.pythonpath_env

  • پوشه‌ی کاری جاری: برای به‌دست آوردن مسیرهای مطلق

  • متغیر محیطی PATH برای به‌دست آوردن مسیر کامل برنامه (از PyConfig.program_name)

  • متغیر محیطی __PYVENV_LAUNCHER__

  • (فقط ویندوز) مسیرهای برنامه در رجیستری، زیر "SoftwarePythonPythonCoreX.YPythonPath" از HKEY_CURRENT_USER و HKEY_LOCAL_MACHINE (که در آن X.Y نسخه‌ی پایتون است).

• فیلد‌های خروجی پیکربندی مسیر:

  • PyConfig.base_exec_prefix

  • PyConfig.base_executable

  • PyConfig.base_prefix

  • PyConfig.exec_prefix

  • PyConfig.executable

  • PyConfig.module_search_paths_set, PyConfig.module_search_paths

  • PyConfig.prefix

اگر حداقل یک "فیلد خروجی" تنظیم نشده باشد، پایتون پیکربندی مسیر را برای پر کردن فیلد‌های تنظیم‌نشده محاسبه می‌کند. اگر module_search_paths_set برابر 0 باشد، module_search_paths بازنویسی می‌شود و module_search_paths_set برابر 1 قرار می‌گیرد.

با تنظیم صریح همه‌ی فیلدهای خروجی پیکربندی مسیر که در بالا فهرست شده‌اند، می‌توان تابع محاسبه‌کننده‌ی پیکربندی پیش‌فرض مسیر را به‌طور کامل نادیده گرفت. یک رشته حتی اگر غیرخالی باشد، تنظیم‌شده در نظر گرفته می‌شود. module_search_paths زمانی تنظیم‌شده در نظر گرفته می‌شود که module_search_paths_set روی 1 تنظیم شده باشد. در این صورت، module_search_paths بدون تغییر استفاده خواهد شد.

مقدار pathconfig_warnings را برابر 0 قرار دهید تا هشدارها هنگام محاسبه پیکربندی مسیر سرکوب شوند (فقط در یونیکس؛ ویندوز هیچ هشداری ثبت نمی‌کند).

اگر فیلدهای base_prefix یا base_exec_prefix تنظیم نشده باشند، مقدار خود را به ترتیب از prefix و exec_prefix به ارث می‌برند.

Py_RunMain() و Py_Main() مقدار sys.path را تغییر می‌دهند:

• اگر run_filename تنظیم شده باشد و پوشه‌ای باشد که اسکریپت __main__.py را دربر دارد، run_filename به ابتدای sys.path اضافه می‌شود.

• اگر isolated صفر باشد:

  • اگر run_module تنظیم شده باشد، پوشه‌ی جاری به ابتدای sys.path افزوده می‌شود. اگر پوشه‌ی جاری قابل خواندن نباشد، هیچ کاری انجام نمی‌شود.

  • اگر run_filename تنظیم شده باشد، پوشه‌ی نام پرونده به ابتدای sys.path اضافه می‌شود.

  • در غیر این صورت، یک رشته خالی به ابتدای sys.path اضافه می‌کند.

اگر site_import غیر صفر باشد، ماژول site می‌تواند sys.path را تغییر دهد. اگر user_site_directory غیر صفر باشد و پوشه‌ی site-package کاربر وجود داشته باشد، ماژول site پوشه‌ی site-package کاربر را به sys.path می‌افزاید.

پرونده‌های پیکربندی زیر توسط پیکربندی مسیر استفاده می‌شوند:

• pyvenv.cfg

• پرونده ._pth (مثلاً python._pth)

• pybuilddir.txt (فقط یونیکس)

اگر یک پرونده‌ی ._pth موجود باشد:

• مقدار isolated را روی 1 قرار دهید.

• مقدار use_environment را برابر 0 قرار دهید.

• مقدار site_import را برابر 0 قرار دهید.

• تنظیم کردن user_site_directory روی 0 (از نسخه‌ی 3.15).

• مقدار safe_path را برابر 1 قرار دهید.

اگر home تنظیم نشده باشد و پرونده‌ی pyvenv.cfg در همان پوشه‌ای که executable در آن قرار دارد یا در پوشه‌ی والد آن وجود داشته باشد، prefix و exec_prefix به آن مکان تنظیم می‌شوند. در این حالت، base_prefix و base_exec_prefix همچنان مقدار خود را حفظ می‌کنند و به نصب پایه اشاره می‌کنند. برای اطلاعات بیشتر به محیط‌های مجازی مراجعه کنید.

از متغیر محیطی __PYVENV_LAUNCHER__ برای تنظیم PyConfig.base_executable استفاده می‌شود.