`sys.md`

248 строк · 27.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/c-api/sys.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Утилиты операционной системы89#### `PyObject* PyOS_FSPath(PyObject *path)`1011*Возвращаемое значение: новая ссылка.*1213Возвращает представление файловой системы для *пути*. Если объект является объектом [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes), то его счётчик ссылок увеличивается. Если объект реализует интерфейс [`os.PathLike`](https://python-all.ru/3.8/library/os.html#os.PathLike), то [`__fspath__()`](https://python-all.ru/3.8/library/os.html#os.PathLike.__fspath__) возвращается, если он является объектом [`str`](https://python-all.ru/3.8/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes). В противном случае возбуждается [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError) и возвращается `NULL`.1415Новое в версии 3.6.1617#### `int Py_FdIsInteractive(FILE *fp, const char *filename)`1819Возвращает истину (ненулевое значение), если стандартный файл ввода-вывода *fp* с именем *filename* считается интерактивным. Это верно для файлов, для которых `isatty(fileno(fp))` истинно. Если глобальный флаг [`Py_InteractiveFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_InteractiveFlag) установлен в истину, эта функция также возвращает истину, если указатель *filename* равен `NULL` или если имя равно одной из строк `'<stdin>'` или `'???'`.2021#### `void PyOS_BeforeFork()`2223Функция для подготовки внутреннего состояния перед ветвлением процесса. Её следует вызывать перед вызовом `fork()` или любой аналогичной функции, клонирующей текущий процесс. Доступна только в системах, где определён `fork()`.2425> **Предупреждение**26>27> Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_BeforeFork()`.2829Добавлено в версии 3.7.3031#### `void PyOS_AfterFork_Parent()`3233Функция для обновления внутреннего состояния после ветвления процесса. Её следует вызывать из родительского процесса после вызова `fork()` или любой аналогичной функции, клонирующей текущий процесс, независимо от того, успешно ли прошло клонирование. Доступна только в системах, где определён `fork()`.3435> **Предупреждение**36>37> Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_AfterFork_Parent()`.3839Добавлено в версии 3.7.4041#### `void PyOS_AfterFork_Child()`4243Функция для обновления внутреннего состояния интерпретатора после ветвления процесса. Её необходимо вызывать из дочернего процесса после вызова `fork()` или любой аналогичной функции, клонирующей текущий процесс, если есть вероятность, что процесс снова вызовет интерпретатор Python. Доступна только в системах, где определён `fork()`.4445> **Предупреждение**46>47> Вызов C `fork()` должен выполняться только из [«главного» потока](https://python-all.ru/3.8/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.8/c-api/init.html#sub-interpreter-support)). То же самое верно для `PyOS_AfterFork_Child()`.4849Добавлено в версии 3.7.5051> **См. также**52>53> [`os.register_at_fork()`](https://python-all.ru/3.8/library/os.html#os.register_at_fork) позволяет регистрировать пользовательские функции Python, которые будут вызываться [`PyOS_BeforeFork()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_BeforeFork), [`PyOS_AfterFork_Parent()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Parent) и [`PyOS_AfterFork_Child()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Child).5455#### `void PyOS_AfterFork()`5657Функция для обновления некоторого внутреннего состояния после ветвления процесса; её следует вызвать в новом процессе, если интерпретатор Python будет продолжать использоваться. Если в новый процесс загружается новый исполняемый файл, эту функцию вызывать не нужно.5859Устарело с версии 3.7: Эта функция заменена на [`PyOS_AfterFork_Child()`](https://python-all.ru/3.8/c-api/sys.html#c.PyOS_AfterFork_Child).6061#### `int PyOS_CheckStack()`6263Возвращает истину, когда интерпретатору не хватает места в стеке. Это надёжная проверка, но доступна только при определении `USE_STACKCHECK` (в настоящее время в Windows с использованием компилятора Microsoft Visual C++). `USE_STACKCHECK` будет определён автоматически; никогда не следует изменять это определение в своём коде.6465#### `PyOS_sighandler_t PyOS_getsig(int i)`6667Возвращает текущий обработчик сигнала для сигнала *i*. Это тонкая обёртка вокруг `sigaction()` или `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`.6869#### `PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)`7071Устанавливает обработчик сигнала для сигнала *i* равным *h*; возвращает старый обработчик сигнала. Это тонкая обёртка вокруг либо `sigaction()`, либо `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`.7273#### `wchar_t* Py_DecodeLocale(const char* arg, size_t *size)`7475Декодирует байтовую строку из кодировки локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.8/library/codecs.html#surrogateescape): недекодируемые байты декодируются как символы в диапазоне U+DC80..U+DCFF. Если последовательность байтов может быть декодирована как суррогатный символ, то такие байты экранируются с помощью обработчика ошибок surrogateescape вместо их декодирования.7677Кодировка (от высшего приоритета к низшему):7879- `UTF-8` на macOS, Android и VxWorks;80- `UTF-8` на Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю;81- `UTF-8` если включён режим UTF-8 Python;82- `ASCII` если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`.83- текущая кодировка локали.8485Возвращает указатель на новую выделенную строку широких символов; для освобождения памяти используйте [`PyMem_RawFree()`](https://python-all.ru/3.8/c-api/memory.html#c.PyMem_RawFree). Если size не равен `NULL`, записывает количество широких символов, исключая нулевой символ, в `*size`.8687Возвращает `NULL` при ошибке декодирования или ошибке выделения памяти. Если *size* не равен `NULL`, `*size` устанавливается в `(size_t)-1` при ошибке памяти или в `(size_t)-2` при ошибке декодирования.8889Ошибки декодирования никогда не должны происходить, если только нет ошибки в библиотеке C.9091Используйте функцию [`Py_EncodeLocale()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_EncodeLocale) для обратного кодирования строки символов в байтовую строку.9293> **См. также**94>95> Функции [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) и [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).9697Новое в версии 3.5.9899Изменено в версии 3.7: Функция теперь использует кодировку UTF-8 в режиме UTF-8.100101Изменено в версии 3.8: Теперь функция использует кодировку UTF-8 в Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю;102103#### `char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)`104105Кодирует широкую символьную строку в кодировку локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.8/library/codecs.html#surrogateescape): суррогатные символы в диапазоне U+DC80..U+DCFF преобразуются в байты 0x80..0xFF.106107Кодировка (от высшего приоритета к низшему):108109- `UTF-8` на macOS, Android и VxWorks;110- `UTF-8` на Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю;111- `UTF-8` если включён режим UTF-8 Python;112- `ASCII` если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`.113- текущая кодировка локали.114115Функция использует кодировку UTF-8 в режиме UTF-8 Python.116117Возвращает указатель на вновь выделенную байтовую строку, используется [`PyMem_Free()`](https://python-all.ru/3.8/c-api/memory.html#c.PyMem_Free)\\nдля освобождения памяти. Возвращает `NULL` при ошибке кодирования или ошибке выделения\\nпамяти.118119Если error\_pos не равен `NULL`, то `*error_pos` устанавливается в `(size_t)-1` в случае успеха или в индекс недопустимого символа при ошибке кодирования.120121Используйте функцию [`Py_DecodeLocale()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_DecodeLocale) для обратного декодирования байтовой строки в строку широких символов.122123> **См. также**124>125> Функции [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) и [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_EncodeLocale).126127Новое в версии 3.5.128129Изменено в версии 3.7: Функция теперь использует кодировку UTF-8 в режиме UTF-8.130131Изменено в версии 3.8: Теперь функция использует кодировку UTF-8 в Windows, если [`Py_LegacyWindowsFSEncodingFlag`](https://python-all.ru/3.8/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю;132133# Системные функции134135Это служебные функции, предоставляющие функциональность модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) коду на C. Все они работают со словарём модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) текущего потока интерпретатора, который хранится во внутренней структуре состояния потока.136137#### `PyObject *PySys_GetObject(const char *name)`138139*Возвращаемое значение: заимствованная ссылка.*140141Возвращает объект *name* из модуля [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) или `NULL`, если он не существует, без установки исключения.142143#### `int PySys_SetObject(const char *name, PyObject *v)`144145Устанавливает *name* в модуле [`sys`](https://python-all.ru/3.8/library/sys.html#module-sys) равным *v*, если *v* не равно `NULL`; в противном случае *name* удаляется из модуля sys. Возвращает `0` в случае успеха, `-1` при ошибке.146147#### `void PySys_ResetWarnOptions()`148149Сбрасывает [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions) в пустой список. Эта функция может быть вызвана до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize).150151#### `void PySys_AddWarnOption(const wchar_t *s)`152153Добавляет *s* к [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions). Эта функция должна вызываться до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize), чтобы повлиять на список фильтра предупреждений.154155#### `void PySys_AddWarnOptionUnicode(PyObject *unicode)`156157Добавляет *unicode* к [`sys.warnoptions`](https://python-all.ru/3.8/library/sys.html#sys.warnoptions).158159Примечание: эта функция пока не может использоваться за пределами реализации CPython, поскольку для её работы её нужно вызывать до неявного импорта [`warnings`](https://python-all.ru/3.8/library/warnings.html#module-warnings) в [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize), но она не может быть вызвана, пока среда выполнения не будет достаточно инициализирована для создания объектов Unicode.160161#### `void PySys_SetPath(const wchar_t *path)`162163Устанавливает [`sys.path`](https://python-all.ru/3.8/library/sys.html#sys.path) в объект списка путей, найденных в *path*, который должен быть списком путей, разделённых разделителем пути поиска платформы (`:` в Unix, `;` в Windows).164165#### `void PySys_WriteStdout(const char *format, ...)`166167Записывает выходную строку, описываемую *format*, в [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout). Исключения не вызываются, даже если произошло усечение (см. ниже).168169*format* должен ограничивать общий размер форматированной выходной строки до 1000 байт или менее – после 1000 байт строка усекается. В частности, это означает, что не должно быть неограниченных форматов «%s»; их следует ограничивать с помощью «%.\<N\>s», где \<N\> – десятичное число, рассчитанное так, чтобы \<N\> плюс максимальный размер другого форматированного текста не превышал 1000 байт. Также следует остерегаться «%f», который может печатать сотни цифр для очень больших чисел.170171Если возникает проблема или [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout) не задан, форматированное сообщение записывается в настоящий (на уровне C) *stdout*.172173#### `void PySys_WriteStderr(const char *format, ...)`174175Аналогично [`PySys_WriteStdout()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_WriteStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.8/library/sys.html#sys.stderr) или *stderr* вместо этого.176177#### `void PySys_FormatStdout(const char *format, ...)`178179Функция подобна PySys\_WriteStdout(), но форматирует сообщение с помощью [`PyUnicode_FromFormatV()`](https://python-all.ru/3.8/c-api/unicode.html#c.PyUnicode_FromFormatV) и не обрезает сообщение до произвольной длины.180181Новое в версии 3.2.182183#### `void PySys_FormatStderr(const char *format, ...)`184185Аналогично [`PySys_FormatStdout()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_FormatStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.8/library/sys.html#sys.stderr) или *stderr* вместо этого.186187Новое в версии 3.2.188189#### `void PySys_AddXOption(const wchar_t *s)`190191Разбирает *s* как набор опций [`-X`](https://python-all.ru/3.8/using/cmdline.html#id5) и добавляет их в текущее отображение опций, возвращаемое [`PySys_GetXOptions()`](https://python-all.ru/3.8/c-api/sys.html#c.PySys_GetXOptions). Эту функцию можно вызывать до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize).192193Новое в версии 3.2.194195#### `PyObject *PySys_GetXOptions()`196197*Возвращаемое значение: заимствованная ссылка.*198199Возвращает текущий словарь опций [`-X`](https://python-all.ru/3.8/using/cmdline.html#id5), аналогично [`sys._xoptions`](https://python-all.ru/3.8/library/sys.html#sys._xoptions). При ошибке возвращается `NULL` и устанавливается исключение.200201Новое в версии 3.2.202203#### `int PySys_Audit(const char *event, const char *format, ...)`204205Вызывает событие аудита с любыми активными перехватчиками. Возвращает ноль при успехе и ненулевое значение с установленным исключением при ошибке.206207Если были добавлены какие-либо хуки, *format* и остальные аргументы будут использованы для создания кортежа для передачи. Кроме `N`, доступны те же символы формата, что и в [`Py_BuildValue()`](https://python-all.ru/3.8/c-api/arg.html#c.Py_BuildValue). Если построенное значение не является кортежем, оно будет добавлено в кортеж из одного элемента. (Опция формата `N` потребляет ссылку, но поскольку невозможно узнать, будут ли аргументы этой функции потреблены, её использование может привести к утечкам ссылок.)208209Обратите внимание, что символы форматирования `#` всегда должны рассматриваться как `Py_ssize_t`, независимо от того, был ли определён `PY_SSIZE_T_CLEAN`.210211[`sys.audit()`](https://python-all.ru/3.8/library/sys.html#sys.audit) выполняет ту же функцию из кода Python.212213Новое в версии 3.8.214215Изменено в версии 3.8.2: Требуется `Py_ssize_t` для символов форматирования `#`. Ранее выдавалось неизбежное предупреждение об устаревании.216217#### `int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)`218219Добавляет вызываемый объект *hook* в список активных хуков аудита.\\nВозвращает ноль при успехе\\nи ненулевое значение при ошибке. Если среда выполнения уже инициализирована, также устанавливает\\nошибку при неудаче. Хуки, добавленные через этот API, вызываются для всех\\nинтерпретаторов, созданных средой выполнения.220221Указатель *userData* передаётся в функцию-обработчик. Поскольку функции-обработчики могут вызываться из разных сред выполнения, этот указатель не должен напрямую ссылаться на состояние Python.222223Эту функцию можно безопасно вызывать до [`Py_Initialize()`](https://python-all.ru/3.8/c-api/init.html#c.Py_Initialize). При вызове после инициализации среды выполнения существующие перехватчики аудита уведомляются и могут молча прервать операцию, вызвав ошибку, являющуюся подклассом [`Exception`](https://python-all.ru/3.8/library/exceptions.html#Exception) (другие ошибки не будут скрыты).224225Функция-обработчик имеет тип `int (*)(const char *event, PyObject *args, void *userData)`, где *args* гарантированно является [`PyTupleObject`](https://python-all.ru/3.8/c-api/tuple.html#c.PyTupleObject). Функция-обработчик всегда вызывается при удержании GIL интерпретатором Python, вызвавшим событие.226227См. [**PEP 578**](https://python-all.ru/3.8/c-api/sys.html) для подробного описания аудита. Функции в среде выполнения и стандартной библиотеке, которые вызывают события, перечислены в [таблице событий аудита](https://python-all.ru/3.8/library/audit_events.html#audit-events). Подробности приведены в документации каждой функции.228229Если интерпретатор инициализирован, эта функция вызывает событие аудита `sys.addaudithook` без аргументов. Если какой-либо из существующих обработчиков возбуждает исключение, производное от [`Exception`](https://python-all.ru/3.8/library/exceptions.html#Exception), новый обработчик не будет добавлен, и исключение сбрасывается. В результате вызывающий код не может предполагать, что его обработчик был добавлен, если только он не контролирует все существующие обработчики.230231Новое в версии 3.8.232233# Управление процессами234235#### `void Py_FatalError(const char *message)`236237Выводит фатальное сообщение об ошибке и завершает процесс. Очистка не выполняется. Эту функцию следует вызывать только при обнаружении условия, которое делает опасным продолжение использования интерпретатора Python; например, когда управление объектами повреждено. В Unix вызывается стандартная функция библиотеки C `abort()`, которая пытается создать файл `core`.238239#### `void Py_Exit(int status)`240241Завершает текущий процесс. Вызывает [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx), а затем вызывает стандартную функцию библиотеки C `exit(status)`. Если [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx) указывает на ошибку, код завершения устанавливается в 120.242243Изменено в версии 3.6: Ошибки при финализации больше не игнорируются.244245#### `int Py_AtExit(void (*func)())`246247Регистрирует функцию очистки, которая будет вызвана с помощью [`Py_FinalizeEx()`](https://python-all.ru/3.8/c-api/init.html#c.Py_FinalizeEx). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. При успешной регистрации [`Py_AtExit()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_AtExit) возвращает `0`; при неудаче – `-1`. Последняя зарегистрированная функция очистки вызывается первой. Каждая функция очистки будет вызвана не более одного раза. Поскольку внутренняя финализация Python завершится до вызова функции очистки, *func* не должна вызывать никакие API Python.248