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

PyObject *PyOS_FSPath(PyObject *path)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.6.

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

Added in version 3.6.

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

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

Эта функция не должна вызываться до инициализации Python.

void PyOS_BeforeFork()

Часть Стабильный ABI on platforms with fork() с версии 3.7.

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

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

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

Added in version 3.7.

void PyOS_AfterFork_Parent()

Часть Стабильный ABI on platforms with fork() с версии 3.7.

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

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

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

Added in version 3.7.

void PyOS_AfterFork_Child()

Часть Стабильный ABI on platforms with fork() с версии 3.7.

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

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

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

Added in version 3.7.

См.также

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

void PyOS_AfterFork()

Часть Стабильный ABI on platforms with fork().

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

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

int PyOS_CheckStack()

Часть Стабильный ABI on platforms with USE_STACKCHECK с версии 3.7.

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

typedef void (*PyOS_sighandler_t)(int)

Часть Стабильный ABI.

PyOS_sighandler_t PyOS_getsig(int i)

Часть Стабильный ABI.

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

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Часть Стабильный ABI.

Установите обработчик сигнала i на h; верните старый обработчик сигнала. Это тонкая обертка вокруг sigaction() или signal(). Не вызывайте эти функции напрямую!

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

Часть Стабильный ABI с версии 3.7.

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

Эту функцию не следует вызывать напрямую: используйте PyConfig API с функцией PyConfig_SetBytesString(), которая гарантирует, что Python is preinitialized.

Эта функция не должна вызываться раньше Python is preinitialized, чтобы локаль LC_CTYPE была правильно настроена: см. функцию Py_PreInitialize().

Декодируйте байтовую строку из filesystem encoding and error handler. Если обработчик ошибок имеет значение surrogateescape error handler, недекодируемые байты декодируются как символы в диапазоне U+DC80…U+DCFF; если последовательность байтов может быть декодирована как суррогатный символ, то вместо декодирования байты экранируются с помощью обработчика ошибок surrogateescape.

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

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

filesystem encoding and error handler выбираются PyConfig_Read(): см. filesystem_encoding и filesystem_errors членов PyConfig.

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

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

См.также

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

Added in version 3.5.

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

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

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

Часть Стабильный ABI с версии 3.7.

Перекодируйте широкую символьную строку в filesystem encoding and error handler. Если обработчик ошибки имеет значение surrogateescape error handler, суррогатные символы в диапазоне U+DC80…U+DCFF преобразуются в байты 0x80…0xFF.

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

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

filesystem encoding and error handler выбираются PyConfig_Read(): см. filesystem_encoding и filesystem_errors членов PyConfig.

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

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

Эта функция не должна вызываться раньше Python is preinitialized, чтобы локаль LC_CTYPE была правильно настроена: см. функцию Py_PreInitialize().

См.также

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

Added in version 3.5.

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

Изменено в версии 3.8: Функция теперь использует кодировку UTF-8 в Windows, если PyPreConfig.legacy_windows_fs_encoding равен нулю.

Функции системы

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

PyObject *PySys_GetObject(const char *name)

Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI.

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

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

Часть Стабильный ABI.

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

void PySys_ResetWarnOptions()

Часть Стабильный ABI.

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

Утратил актуальность с версии 3.13, будет удален в версии 3.15: Вместо этого очистите sys.warnoptions и warnings.filters.

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

Часть Стабильный ABI.

Запишите строку вывода, описанную форматом, в sys.stdout. Никаких исключений не возникает, даже если происходит усечение (см. ниже).

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

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

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

Часть Стабильный ABI.

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

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

Часть Стабильный ABI.

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

Added in version 3.2.

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

Часть Стабильный ABI.

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

Added in version 3.2.

PyObject *PySys_GetXOptions()

Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI с версии 3.7.

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

Added in version 3.2.

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

Часть Стабильный ABI с версии 3.13.

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

Строковый аргумент event не должен быть NULL.

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

Опция формата N не должна использоваться. Она потребляет ссылку, но поскольку нет возможности узнать, будут ли потребляться аргументы этой функции, ее использование может привести к утечке ссылок.

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

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

См. также PySys_AuditTuple().

Added in version 3.8.

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

int PySys_AuditTuple(const char *event, PyObject *args)

Часть Стабильный ABI с версии 3.13.

Аналогично PySys_Audit(), но аргументы передаются как объект Python. args должен быть объектом tuple. Чтобы не передавать никаких аргументов, args может быть NULL.

Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

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

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

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

Функция hook всегда вызывается с GIL, принадлежащим интерпретатору Python, который вызвал событие.

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

Поднимает auditing event sys.addaudithook без аргументов.

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

Тип функции крючка. event - строковый аргумент события C, переданный в PySys_Audit() или PySys_AuditTuple(). args гарантированно будет PyTupleObject. userData - аргумент, передаваемый в PySys_AddAuditHook().

Added in version 3.8.

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

void Py_FatalError(const char *message)

Часть Стабильный ABI.

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

Функция Py_FatalError() заменяется макросом, который автоматически регистрирует имя текущей функции, если только не определен макрос Py_LIMITED_API.

Изменено в версии 3.9: Автоматически регистрируйте имя функции.

void Py_Exit(int status)

Часть Стабильный ABI.

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

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

int Py_AtExit(void (*func)())

Часть Стабильный ABI.

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