Утилиты операционной системы

PyObject* PyOS_FSPath(PyObject *path)

Return value: New reference.

Возвращает представление файловой системы для path. Если объект является объектом str или bytes, то количество его ссылок увеличивается. Если объект реализует интерфейс os.PathLike, тогда возвращается __fspath__(), если он является объектом str или bytes. В противном случае TypeError поднимается и возвращается NULL.

Добавлено в версии 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

Возвращает true (ненулевое значение), если стандартное I/O файла fp с именем filename считается интерактивным. Это относится к файлам, для которых isatty(fileno(fp)) соответствует true. Если глобальный флаг, Py_InteractiveFlag true, эта функция также возвращает true, если указатель filename - NULL или если имя равно одной из строк '<stdin>' или '???'.

void PyOS_BeforeFork()

Функция для подготовки внутреннего состояния перед fork процесса. Это должно быть вызвано перед вызовом fork() или любой аналогичной функцией, которая клонирует текущий процесс. Доступно только в системах, в которых определено fork().

Предупреждение

Вызов C fork() должен выполняться только из «главного» потока («главный» интерпретатор). То же самое относится и к PyOS_BeforeFork().

Добавлено в версии 3.7.

void PyOS_AfterFork_Parent()

Функция для обновления некоторых внутренних состояний после fork процесса. Ее следует вызывать из родительского процесса после вызова fork() или любой аналогичной функции, которая клонирует текущий процесс, независимо от того, было ли клонирование процесса успешным. Доступно только в системах, в которых определено fork().

Предупреждение

Вызов C fork() должен выполняться только из «главного» потока («главный» интерпретатор). То же самое относится и к PyOS_AfterFork_Parent().

Добавлено в версии 3.7.

void PyOS_AfterFork_Child()

Функция для обновления внутреннего состояния интерпретатора после fork процесса. Ее следует вызвать из дочернего процесса после вызова fork() или любой аналогичной функции, которая клонирует текущий процесс, если есть вероятность, что процесс перезвонит в Python интерпретатор. Доступно только в системах, в которых определено fork().

Предупреждение

Вызов C fork() должен выполняться только из «главного» потока («главный» интерпретатор). То же самое относится и к PyOS_AfterFork_Child().

Добавлено в версии 3.7.

См.также

os.register_at_fork() позволяет регистрировать пользовательские функции Python для вызова по PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child().

void PyOS_AfterFork()

Функция обновления некоторого внутреннего состояния после fork процесса; это должно быть вызвано в новом процессе, если Python интерпретатор будет по- прежнему использоваться. Если в новый процесс загружен новый исполняемый файл, вызов этой функции не требуется.

Не рекомендуется, начиная с версии 3.7: Эта функция заменяется PyOS_AfterFork_Child().

int PyOS_CheckStack()

Возвращает true, когда в интерпретатору не хватает места в стеке. Это надежная проверка, но доступна только при определении USE_STACKCHECK (в настоящее время в Windows используется компилятор Microsoft Visual C++). USE_STACKCHECK будет определяться автоматически; никогда не следует изменять определение в собственном коде.

PyOS_sighandler_t PyOS_getsig(int i)

Возвращает обработчик текущего сигнала для i сигнала. Это тонкая обертка вокруг sigaction() или signal(). Не вызывайте эти функции напрямую! PyOS_sighandler_t является typedef алиасом for:c:type:void (*)(int).

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Установить обработчик сигнала для h i сигнала; возвращает старый сигнальный обработчик. Это тонкая обертка вокруг sigaction() или signal(). Не вызывайте эти функции напрямую! PyOS_sighandler_t является typedef алиасом for:c:type:void (*)(int).

wchar_t* Py_DecodeLocale(const char* arg, size_t *size)

Декодировать строку байт с кодировкой локали с обработчиком ошибок суррогатного эскейпа: недекодируемые байты декодируются как символы в диапазоне U+DC80.. U+DCFF. Если последовательность байтов может быть декодирована как суррогатный символ, избегайте байтов, используя обработчик ошибки суррогатного эскейпа, вместо их декодирования.

Кодирование, от наивысшего приоритета, до наименьшего приоритета:

• UTF-8 на macOS, Android и VxWorks;
• UTF-8 на Windows, если Py_LegacyWindowsFSEncodingFlag равно нулю;
• UTF-8 если включен режим Python UTF-8;
• ASCII если LC_CTYPE локаль "C", nl_langinfo(CODESET) возвращает ASCII кодировку (или алиас), а функции mbstowcs() и wcstombs() используют ISO-8859-1 кодировку.
• Текущая кодировка локали.

Возвращает указатель на только что аллоцированную широкосимвольную строку, используйте PyMem_RawFree(), чтобы освободить память. Если размер не NULL, записать число широких символов, исключая нулевой символ, в *size

Возвращает NULL при ошибке декодирования или ошибке выделения памяти. Если size не NULL, *size устанавливается на (size_t)-1 ошибки памяти или на (size_t)-2 ошибки декодирования.

Ошибки декодирования не должны возникать, если в библиотеке C нет ошибки.

Используйте функцию Py_EncodeLocale() для кодирования символьной строки обратно в байтовую строку.

См.также

Функции PyUnicode_DecodeFSDefaultAndSize() и PyUnicode_DecodeLocaleAndSize().

Добавлено в версии 3.5.

Изменено в версии 3.7: Теперь функция использует UTF-8 кодировку в режиме UTF-8.

Изменено в версии 3.8: Теперь функция использует UTF-8 кодировку в Windows, если Py_LegacyWindowsFSEncodingFlag равно нулю;

char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Закодировать широкосимвольную строку кодировки локали с обработчиком ошибок суррогатного экранирования: суррогатные символы в диапазоне U+DC80..U+DCFF преобразуются в байты 0x80..0xFF.

Кодирование, от наивысшего приоритета, до наименьшего приоритета:

• UTF-8 на macOS, Android и VxWorks;
• UTF-8 на Windows, если Py_LegacyWindowsFSEncodingFlag равно нулю;
• UTF-8 если включен режим Python UTF-8;
• ASCII если LC_CTYPE локаль является "C", nl_langinfo(CODESET) возвращает ASCII кодировкой (или алиас), а функции mbstowcs() и wcstombs() используют ISO-8859-1 кодировку.
• Текущая кодировка локали.

Функция использует UTF-8 кодировку в режиме Python UTF-8.

Возвращает указатель на вновь аллоцированную байтовую строку, используйте PyMem_Free() для освобождения памяти. Возвращает NULL при ошибке кодировки или при ошибке выделения памяти

Если error_pos не NULL, *error_pos устанавливается на (size_t)-1 при успешном выполнении или на индекс недопустимого символа при ошибке кодировки.

Используйте функцию Py_DecodeLocale(), чтобы декодировать байтовую строку обратно в широкосимвольную строку.

См.также

Функции PyUnicode_EncodeFSDefault() и PyUnicode_EncodeLocale().

Добавлено в версии 3.5.

Изменено в версии 3.7: Теперь функция использует UTF-8 кодировку в режиме UTF-8.

Изменено в версии 3.8: Теперь функция использует UTF-8 кодировку в Windows, если Py_LegacyWindowsFSEncodingFlag равно нулю;

Системные функции

Это служебные функции, которые реализуют функциональные возможности модуля sys доступными для C кода. Они все работают с текущим словарем модуля sys потока интерпретатора, который содержится во внутренней структуре состояния потока.

PyObject *PySys_GetObject(const char *name)

Return value: Borrowed reference.

Возвращает объект name из модуля sys или NULL, если он не существует, без установки исключения.

int PySys_SetObject(const char *name, PyObject *v)

Установить для name в модуле sys значение v, если v не NULL, в этом случае name удаляется из модуля sys. Возвращает 0 при успехе, -1 при ошибке.

void PySys_ResetWarnOptions()

Сбросить sys.warnoptions в пустой список. Эта функция может быть вызвана до Py_Initialize().

void PySys_AddWarnOption(const wchar_t *s)

Добавить s к sys.warnoptions. Эта функция должна быть вызвана до Py_Initialize(), чтобы повлиять на список фильтров предупреждений.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

Добавить unicode к sys.warnoptions.

Примечание. Эта функция в настоящее время не используется вне CPython реализации, так как она должна быть вызвана до неявного импорта warnings в Py_Initialize(), чтобы быть эффективной, но не может быть вызвана до тех пор, пока не будет инициализировано достаточно времени выполнения для создания объектов Юникода.

void PySys_SetPath(const wchar_t *path)

Установить sys.path в объекте списка путей, найденных в path, который должен быть списком путей, разделенных разделителем пути поиска платформы (: в Unix, ; в Windows).

void PySys_WriteStdout(const char *format, ...)

Записать выходную строку, описанную format, в sys.stdout. Исключения не возникают, даже если происходит усечение (см. ниже).

format должен ограничить общий размер отформатированной выходной строки до 1000 байт или менее - после 1000 байт выходной строка усекается. В частности, это означает, что не должно возникать неограниченных форматов «%s»; их следует ограничить с помощью «%.<N>s», где <N> - десятичное число, вычисляемое так, чтобы <N> плюс максимальный размер другого форматированного текста не превышал 1000 байт. Также следите за «%f», который может печатать сотни цифр для очень больших чисел.

Если возникает проблема или sys.stdout не установлена, форматированное сообщение записывается в вещественное (уровень C) stdout.

void PySys_WriteStderr(const char *format, ...)

Как PySys_WriteStdout(), но вместо этого записывает в sys.stderr или stderr.

void PySys_FormatStdout(const char *format, ...)

Функция похожа на PySys_WriteStdout(), но форматирует сообщение с помощью PyUnicode_FromFormatV() и не усекает его до произвольной длины.

Добавлено в версии 3.2.

void PySys_FormatStderr(const char *format, ...)

Как PySys_FormatStdout(), но вместо этого записывает в sys.stderr или stderr.

Добавлено в версии 3.2.

void PySys_AddXOption(const wchar_t *s)

Проанализировать s как набор опций -X и добавить их к текущему сопоставлению опций, как возвращенная PySys_GetXOptions(). Эта функция может быть вызвана до Py_Initialize().

Добавлено в версии 3.2.

PyObject *PySys_GetXOptions()

Return value: Borrowed reference.

Возвращает текущий словарь вариантов -X, аналогично sys._xoptions. При ошибке возвращается NULL и устанавливается исключение.

Добавлено в версии 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Создать событие аудита с любым активным хуком. Возвращает ноль при успехе и не нуль с исключением, установленным при сбое.

Если были добавлены какие-либо хуки, format и другие аргументы будут использоваться для построения кортежа для передачи. Кроме N, доступны символы того же формата, что и используется в Py_BuildValue(). Если построеннее значение не является кортежем, он будет добавлен в одноэлементный кортеж. (Параметр формата N использует ссылку, но поскольку нет возможности узнать, будут ли использованы аргументы этой функции, использование этого параметра может привести к утечке ссылки.

Следует отметить, что символы формата # всегда должны рассматриваться как Py_ssize_t независимо от того, определен ли PY_SSIZE_T_CLEAN.

sys.audit() выполняет ту же функцию из Python кода.

Добавлено в версии 3.8.

Изменено в версии 3.8.2: Требовать Py_ssize_t для символов формата #. Ранее поднималось неизбежное предупреждение об устаревании.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Добавить вызываемый hook в список активных хуков аудита. Возвращает ноль при успехе и не нуль при сбое. Если среда выполнения была инициализирована, также установить ошибку при сбое. Хуки, добавленные через это API, вызываются для всех интерпретаторов, созданных средой выполнения.

Указатель userData передается в хук функцию. Поскольку функции хуки могут вызываться из различных сред выполнения, этот указатель не должен ссылаться непосредственно на Python состояние.

Эта функция безопасна для вызова перед Py_Initialize(). При вызове после инициализации во время выполнения существующие хуки аудита уведомляются и могут молча прервать операцию, вызывая ошибку, подклассифицированную из Exception (другие ошибки не будут скрыты).

Функция хук типа int (*)(const char *event, PyObject *args, void *userData), где args гарантированно является PyTupleObject. Функция хук всегда вызывается с GIL, удерживаемым Python интерпретатором, который вызвал событие.

Подробное описание аудита см. в разделе PEP 578. Функции среды выполнения и стандартной библиотеки, вызывающие события, перечислены в таблице событий аудита. Подробная информация содержится в документации каждой функции.

Если интерпретатор инициализирован, эта функция вызывает событие аудита, sys.addaudithook без аргументов. Если какие-либо существующие хуки вызывают исключение, производное от Exception, новый хук не будет добавлен и исключение будет очищено. В результате вызывающие не могут предположить, что их хук был добавлен, если они не управляют всеми существующими хуками.

Добавлено в версии 3.8.

Управление процессом

void Py_FatalError(const char *message)

Распечатать неустранимое сообщение об ошибке и завершить процесс. Очистка не выполняется. Эта функция может быть вызвана только при обнаружении условия, которое может создать опасность продолжения использования Python интерпретатора; например, когда администрирование объекта, по-видимому, повреждено. В Unix вызывается стандартная функция библиотеки C abort(), которая попытается создать файл core.

void Py_Exit(int status)

Выход из текущего процесса. Вызов Py_FinalizeEx() а затем вызов стандартной функции библиотеки C exit(status). Если Py_FinalizeEx() указывает на ошибку, то состояние выхода устанавливается равным 120.

Изменено в версии 3.6: Ошибки завершения больше не игнорируются.

int Py_AtExit(void (*func)())

Зарегистрировать функцию очистки, вызываемую Py_FinalizeEx(). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. После успешной регистрации Py_AtExit() возвращает 0; при отказе она возвращает -1. Функция очистки, зарегистрированная последней, вызывается первой. Каждая функция очистки вызывается не более одного раза. Поскольку внутренняя доработка Python’а будет завершена до выполнения функции очистки, Python не должен вызывать func API.