`sys.md`

252 строк · 28.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/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.9/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes), то его счётчик ссылок увеличивается. Если объект реализует интерфейс [`os.PathLike`](https://python-all.ru/3.9/library/os.html#os.PathLike), то [`__fspath__()`](https://python-all.ru/3.9/library/os.html#os.PathLike.__fspath__) возвращается, если он является объектом [`str`](https://python-all.ru/3.9/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes). В противном случае возбуждается [`TypeError`](https://python-all.ru/3.9/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.9/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.9/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.9/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.9/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.9/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.9/c-api/init.html#fork-and-threads) ([«главного» интерпретатора](https://python-all.ru/3.9/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.9/library/os.html#os.register_at_fork) позволяет регистрировать пользовательские функции Python, которые будут вызываться [`PyOS_BeforeFork()`](https://python-all.ru/3.9/c-api/sys.html#c.PyOS_BeforeFork), [`PyOS_AfterFork_Parent()`](https://python-all.ru/3.9/c-api/sys.html#c.PyOS_AfterFork_Parent) и [`PyOS_AfterFork_Child()`](https://python-all.ru/3.9/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.9/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.9/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.9/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.9/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.9/c-api/sys.html#c.Py_EncodeLocale) для обратного кодирования строки символов в байтовую строку.9293> **См. также**94>95> Функции [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.9/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) и [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.9/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.9/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.9/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.9/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.9/c-api/memory.html#c.PyMem_Free). Возвращает `NULL` при ошибке кодирования или ошибке выделения памяти.118119Если error\_pos не равен `NULL`, то `*error_pos` устанавливается в `(size_t)-1` в случае успеха или в индекс недопустимого символа при ошибке кодирования.120121Используйте функцию [`Py_DecodeLocale()`](https://python-all.ru/3.9/c-api/sys.html#c.Py_DecodeLocale) для обратного декодирования байтовой строки в строку широких символов.122123> **См. также**124>125> Функции [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.9/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) и [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.9/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.9/c-api/init.html#c.Py_LegacyWindowsFSEncodingFlag) равен нулю.132133# Системные функции134135Это служебные функции, предоставляющие функциональность модуля [`sys`](https://python-all.ru/3.9/library/sys.html#module-sys) коду на C. Все они работают со словарём модуля [`sys`](https://python-all.ru/3.9/library/sys.html#module-sys) текущего потока интерпретатора, который хранится во внутренней структуре состояния потока.136137#### `PyObject *PySys_GetObject(const char *name)`138139*Возвращаемое значение: заимствованная ссылка.*140141Возвращает объект *name* из модуля [`sys`](https://python-all.ru/3.9/library/sys.html#module-sys) или `NULL`, если он не существует, без установки исключения.142143#### `int PySys_SetObject(const char *name, PyObject *v)`144145Устанавливает *name* в модуле [`sys`](https://python-all.ru/3.9/library/sys.html#module-sys) равным *v*, если *v* не равно `NULL`; в противном случае *name* удаляется из модуля sys. Возвращает `0` в случае успеха, `-1` при ошибке.146147#### `void PySys_ResetWarnOptions()`148149Сбрасывает [`sys.warnoptions`](https://python-all.ru/3.9/library/sys.html#sys.warnoptions) в пустой список. Эта функция может быть вызвана до [`Py_Initialize()`](https://python-all.ru/3.9/c-api/init.html#c.Py_Initialize).150151#### `void PySys_AddWarnOption(const wchar_t *s)`152153Добавляет *s* к [`sys.warnoptions`](https://python-all.ru/3.9/library/sys.html#sys.warnoptions). Эта функция должна вызываться до [`Py_Initialize()`](https://python-all.ru/3.9/c-api/init.html#c.Py_Initialize), чтобы повлиять на список фильтра предупреждений.154155#### `void PySys_AddWarnOptionUnicode(PyObject *unicode)`156157Добавляет *unicode* к [`sys.warnoptions`](https://python-all.ru/3.9/library/sys.html#sys.warnoptions).158159Примечание: эта функция пока не может использоваться за пределами реализации CPython, поскольку для её работы её нужно вызывать до неявного импорта [`warnings`](https://python-all.ru/3.9/library/warnings.html#module-warnings) в [`Py_Initialize()`](https://python-all.ru/3.9/c-api/init.html#c.Py_Initialize), но она не может быть вызвана, пока среда выполнения не будет достаточно инициализирована для создания объектов Unicode.160161#### `void PySys_SetPath(const wchar_t *path)`162163Устанавливает [`sys.path`](https://python-all.ru/3.9/library/sys.html#sys.path) в объект списка путей, найденных в *path*, который должен быть списком путей, разделённых разделителем пути поиска платформы (`:` в Unix, `;` в Windows).164165#### `void PySys_WriteStdout(const char *format, ...)`166167Записывает выходную строку, описываемую *format*, в [`sys.stdout`](https://python-all.ru/3.9/library/sys.html#sys.stdout). Исключения не вызываются, даже если произошло усечение (см. ниже).168169*format* должен ограничивать общий размер форматированной выходной строки до 1000 байт или менее – после 1000 байт строка усекается. В частности, это означает, что не должно быть неограниченных форматов «%s»; их следует ограничивать с помощью «%.\<N\>s», где \<N\> – десятичное число, рассчитанное так, чтобы \<N\> плюс максимальный размер другого форматированного текста не превышал 1000 байт. Также следует остерегаться «%f», который может печатать сотни цифр для очень больших чисел.170171Если возникает проблема или [`sys.stdout`](https://python-all.ru/3.9/library/sys.html#sys.stdout) не задан, форматированное сообщение записывается в настоящий (на уровне C) *stdout*.172173#### `void PySys_WriteStderr(const char *format, ...)`174175Аналогично [`PySys_WriteStdout()`](https://python-all.ru/3.9/c-api/sys.html#c.PySys_WriteStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.9/library/sys.html#sys.stderr) или *stderr* вместо этого.176177#### `void PySys_FormatStdout(const char *format, ...)`178179Функция подобна PySys\_WriteStdout(), но форматирует сообщение с помощью [`PyUnicode_FromFormatV()`](https://python-all.ru/3.9/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.9/c-api/sys.html#c.PySys_FormatStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.9/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.9/using/cmdline.html#id5) и добавляет их в текущее отображение опций, возвращаемое [`PySys_GetXOptions()`](https://python-all.ru/3.9/c-api/sys.html#c.PySys_GetXOptions). Эту функцию можно вызывать до [`Py_Initialize()`](https://python-all.ru/3.9/c-api/init.html#c.Py_Initialize).192193Новое в версии 3.2.194195#### `PyObject *PySys_GetXOptions()`196197*Возвращаемое значение: заимствованная ссылка.*198199Возвращает текущий словарь опций [`-X`](https://python-all.ru/3.9/using/cmdline.html#id5), аналогично [`sys._xoptions`](https://python-all.ru/3.9/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.9/c-api/arg.html#c.Py_BuildValue). Если построенное значение не является кортежем, оно будет добавлено в кортеж из одного элемента. (Опция формата `N` потребляет ссылку, но поскольку невозможно узнать, будут ли аргументы этой функции потреблены, её использование может привести к утечкам ссылок.)208209Обратите внимание, что символы форматирования `#` всегда должны рассматриваться как [`Py_ssize_t`](https://python-all.ru/3.9/c-api/intro.html#c.Py_ssize_t), независимо от того, был ли определён `PY_SSIZE_T_CLEAN`.210211[`sys.audit()`](https://python-all.ru/3.9/library/sys.html#sys.audit) выполняет ту же функцию из кода Python.212213Новое в версии 3.8.214215Изменено в версии 3.8.2: Требуется [`Py_ssize_t`](https://python-all.ru/3.9/c-api/intro.html#c.Py_ssize_t) для символов форматирования `#`. Ранее выдавалось неизбежное предупреждение об устаревании.216217#### `int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)`218219Добавляет вызываемый объект *hook* в список активных перехватчиков аудита. Возвращает ноль при успехе и ненулевое значение при ошибке. Если среда выполнения была инициализирована, также устанавливает ошибку при неудаче. Перехватчики, добавленные через этот API, вызываются для всех интерпретаторов, созданных средой выполнения.220221Указатель *userData* передаётся в функцию-обработчик. Поскольку функции-обработчики могут вызываться из разных сред выполнения, этот указатель не должен напрямую ссылаться на состояние Python.222223Эту функцию можно безопасно вызывать до [`Py_Initialize()`](https://python-all.ru/3.9/c-api/init.html#c.Py_Initialize). При вызове после инициализации среды выполнения существующие перехватчики аудита уведомляются и могут молча прервать операцию, вызвав ошибку, являющуюся подклассом [`Exception`](https://python-all.ru/3.9/library/exceptions.html#Exception) (другие ошибки не будут скрыты).224225Функция-обработчик имеет тип `int (*)(const char *event, PyObject *args, void *userData)`, где *args* гарантированно является [`PyTupleObject`](https://python-all.ru/3.9/c-api/tuple.html#c.PyTupleObject). Функция-обработчик всегда вызывается при удержании GIL интерпретатором Python, вызвавшим событие.226227См. [**PEP 578**](https://python-all.ru/3.9/c-api/sys.html) для подробного описания аудита. Функции в среде выполнения и стандартной библиотеке, которые вызывают события, перечислены в [таблице событий аудита](https://python-all.ru/3.9/library/audit_events.html#audit-events). Подробности приведены в документации каждой функции.228229Если интерпретатор инициализирован, эта функция вызывает событие аудита `sys.addaudithook` без аргументов. Если какой-либо из существующих обработчиков возбуждает исключение, производное от [`Exception`](https://python-all.ru/3.9/library/exceptions.html#Exception), новый обработчик не будет добавлен, и исключение сбрасывается. В результате вызывающий код не может предполагать, что его обработчик был добавлен, если только он не контролирует все существующие обработчики.230231Новое в версии 3.8.232233# Управление процессами234235#### `void Py_FatalError(const char *message)`236237Выводит фатальное сообщение об ошибке и завершает процесс. Очистка не выполняется. Эту функцию следует вызывать только при обнаружении условия, которое делает опасным продолжение использования интерпретатора Python; например, когда управление объектами повреждено. В Unix вызывается стандартная функция библиотеки C `abort()`, которая пытается создать файл `core`.238239Функция `Py_FatalError()` заменяется макросом, который автоматически регистрирует имя текущей функции, если не определён макрос `Py_LIMITED_API`.240241Изменено в версии 3.9: Имя функции регистрируется автоматически.242243#### `void Py_Exit(int status)`244245Завершает текущий процесс. Вызывает [`Py_FinalizeEx()`](https://python-all.ru/3.9/c-api/init.html#c.Py_FinalizeEx), а затем вызывает стандартную функцию библиотеки C `exit(status)`. Если [`Py_FinalizeEx()`](https://python-all.ru/3.9/c-api/init.html#c.Py_FinalizeEx) указывает на ошибку, код завершения устанавливается в 120.246247Изменено в версии 3.6: Ошибки при финализации больше не игнорируются.248249#### `int Py_AtExit(void (*func)())`250251Регистрирует функцию очистки, которая будет вызвана с помощью [`Py_FinalizeEx()`](https://python-all.ru/3.9/c-api/init.html#c.Py_FinalizeEx). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. При успешной регистрации [`Py_AtExit()`](https://python-all.ru/3.9/c-api/sys.html#c.Py_AtExit) возвращает `0`; при неудаче – `-1`. Последняя зарегистрированная функция очистки вызывается первой. Каждая функция очистки будет вызвана не более одного раза. Поскольку внутренняя финализация Python завершится до вызова функции очистки, *func* не должна вызывать никакие API Python.252