Утилиты операционной системы¶Operating System Utilities

PyObject *PyOS_FSPath(PyObject *path)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.6.
Возвращает представление файловой системы для path. Если объект является объектом str или bytes, возвращается новая сильная ссылка. Если объект реализует интерфейс os.PathLike, то возвращается __fspath__(), если это объект str или bytes. В противном случае возбуждается TypeError и возвращается NULL.

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

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

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

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

void PyOS_BeforeFork()¶: Часть Stable ABI на платформах с fork() начиная с версии 3.7.
Функция для подготовки внутреннего состояния перед ветвлением процесса. Её следует вызывать перед вызовом fork() или любой аналогичной функции, клонирующей текущий процесс. Доступна только в системах, где определён fork().

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

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

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

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

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

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

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

void PyOS_AfterFork_Child()¶: Часть Stable ABI на платформах с fork() начиная с версии 3.7.
Функция для обновления внутреннего состояния интерпретатора после ветвления процесса. Её необходимо вызывать из дочернего процесса после вызова 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()¶: Часть Stable ABI на платформах с fork().
Функция для обновления некоторого внутреннего состояния после ветвления процесса; её следует вызвать в новом процессе, если интерпретатор Python будет продолжать использоваться. Если в новый процесс загружается новый исполняемый файл, эту функцию вызывать не нужно.

Устарело с версии 3.7: Эта функция заменена на PyOS_AfterFork_Child().

int PyOS_CheckStack()¶: Часть Stable ABI на платформах с USE_STACKCHECK начиная с версии 3.7.
Возвращает истину, когда в интерпретаторе заканчивается место в стеке. Это надёжная проверка, но доступна только когда определён USE_STACKCHECK (в настоящее время на некоторых версиях Windows с компилятором Microsoft Visual C++). USE_STACKCHECK будет определён автоматически; не следует изменять это определение в своём коде.

typedef void (*PyOS_sighandler_t)(int)¶: Часть Stable ABI.

PyOS_sighandler_t PyOS_getsig(int i)¶: Часть Stable ABI.
Возвращает текущий обработчик сигнала для сигнала i. Это тонкая обёртка вокруг sigaction() или signal(). Не вызывайте эти функции напрямую!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)¶: Часть Stable ABI.
Устанавливает обработчик сигнала для сигнала i равным h; возвращает старый обработчик сигнала. Это тонкая обёртка вокруг sigaction() или signal(). Не вызывайте эти функции напрямую!

int PyOS_InterruptOccurred(void)¶

Часть Stable ABI.

Проверяет, был ли получен сигнал SIGINT.

Возвращает 1, если произошло SIGINT, и очищает флаг сигнала, иначе 0.

В большинстве случаев следует предпочесть PyErr_CheckSignals() этой функции. PyErr_CheckSignals() вызывает соответствующие обработчики сигналов для всех ожидающих сигналов, позволяя коду Python корректно обработать сигнал. Эта функция только обнаруживает SIGINT и не вызывает никаких обработчиков сигналов Python.

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

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

Часть Stable ABI начиная с версии 3.7.

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

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

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

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

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

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

Кодировка файловой системы и обработчик ошибок выбираются с помощью PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors структуры PyConfig.

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

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

См. также

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

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

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

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

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

Часть Stable ABI начиная с версии 3.7.

Кодирует строку широких символов в кодировку файловой системы и обработчик ошибок. Если обработчик ошибок – обработчик ошибок surrogateescape, суррогатные символы в диапазоне U+DC80..U+DCFF преобразуются в байты 0x80..0xFF.

Возвращает указатель на новую выделенную байтовую строку; для освобождения памяти используйте 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 Python.

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

FILE *Py_fopen(PyObject *path, const char *mode)¶

Аналогично fopen(), но path является объектом Python, и в случае ошибки устанавливается исключение.

path должен быть объектом str, объектом bytes или объектом, подобным пути.

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

Файл должен быть закрыт через Py_fclose(), а не прямым вызовом fclose().

Файловый дескриптор создаётся ненаследуемым (PEP 446).

Вызывающий должен иметь прикреплённое состояние потока.

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

int Py_fclose(FILE *file)¶

Закрывает файл, открытый вызовом Py_fopen().

В случае успеха возвращает 0. При ошибке возвращает EOF, а errno устанавливается для указания ошибки. В любом случае любой дальнейший доступ (включая повторный вызов Py_fclose()) к потоку данных приводит к неопределённому поведению.

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

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

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

PyObject *PySys_GetAttr(PyObject *name)¶

Часть Stable ABI начиная с версии 3.15.

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

Если отсутствие объекта не должно считаться ошибкой, можно использовать PySys_GetOptionalAttr() вместо этой функции.

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

PyObject *PySys_GetAttrString(const char *name)¶

Часть Stable ABI начиная с версии 3.15.

То же, что и PySys_GetAttr(), но name задаётся как const char* строка байтов в кодировке UTF-8, а не как PyObject*.

Если отсутствие объекта не должно считаться ошибкой, можно использовать PySys_GetOptionalAttrString() вместо этой функции.

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

int PySys_GetOptionalAttr(PyObject *name, PyObject **result)¶

Часть Stable ABI начиная с версии 3.15.

Вариант PySys_GetAttr(), который не вызывает исключение, если объект не существует.

Устанавливает *result в новую сильную ссылку на объект и возвращает 1, если объект существует.
Устанавливает *result в NULL и возвращает 0 без установки исключения, если объект не существует.
Устанавливает исключение, устанавливает *result в NULL и возвращает -1, если произошла ошибка.

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

int PySys_GetOptionalAttrString(const char *name, PyObject **result)¶: Часть Stable ABI начиная с версии 3.15.
То же, что и PySys_GetOptionalAttr(), но name задаётся как const char* строка байтов в кодировке UTF-8, а не как PyObject*.

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

PyObject *PySys_GetObject(const char *name)¶

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

Аналогично PySys_GetAttrString(), но возвращает заимствованную ссылку и возвращает NULL без установки исключения при ошибке.

Сохраняет исключение, которое было установлено до вызова.

int PySys_SetObject(const char *name, PyObject *v)¶: Часть Stable ABI.
Устанавливает name в модуле sys равным v, если v не равно NULL; в противном случае name удаляется из модуля sys. Возвращает 0 в случае успеха, -1 при ошибке.

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

Часть Stable ABI.

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

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

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

void PySys_WriteStderr(const char *format, ...)¶: Часть Stable ABI.
Аналогично PySys_WriteStdout(), но выводит в sys.stderr или stderr вместо этого.

void PySys_FormatStdout(const char *format, ...)¶: Часть Stable ABI.
Функция подобна PySys_WriteStdout(), но форматирует сообщение с помощью PyUnicode_FromFormatV() и не обрезает сообщение до произвольной длины.

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

void PySys_FormatStderr(const char *format, ...)¶: Часть Stable ABI.
Аналогично PySys_FormatStdout(), но выводит в sys.stderr или stderr вместо этого.

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

PyObject *PySys_GetXOptions()¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI начиная с версии 3.7.
Возвращает текущий словарь опций -X, аналогично sys._xoptions. При ошибке возвращается NULL и устанавливается исключение.

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

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

Часть Stable ABI, начиная с версии 3.13.

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

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

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

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

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

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

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

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

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

int PySys_AuditTuple(const char *event, PyObject *args)¶: Часть Stable ABI, начиная с версии 3.13.
Аналогично PySys_Audit(), но передаёт аргументы как объект Python. args должен быть tuple. Чтобы не передавать аргументы, args может быть NULL.

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

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)¶

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

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

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

Функция-перехватчик всегда вызывается с присоединённым состоянием потока интерпретатором Python, который вызвал событие.

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

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

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)¶: Тип функции-перехватчика. event – это строковый аргумент события (в стиле C), передаваемый в PySys_Audit() или PySys_AuditTuple(). args гарантированно является PyTupleObject. userData – аргумент, передаваемый в PySys_AddAuditHook().

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

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

void Py_FatalError(const char *message)¶

Часть Stable ABI.

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

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

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

void Py_Exit(int status)¶: Часть Stable ABI.
Завершает текущий процесс. Вызывает Py_FinalizeEx(), а затем вызывает стандартную функцию библиотеки C exit(status). Если Py_FinalizeEx() указывает на ошибку, код завершения устанавливается в 120.

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

int Py_AtExit(void (*func)())¶: Часть Stable ABI.
Регистрирует функцию очистки, которая будет вызвана с помощью Py_FinalizeEx(). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. При успешной регистрации Py_AtExit() возвращает 0; при неудаче – -1. Последняя зарегистрированная функция очистки вызывается первой. Каждая функция очистки будет вызвана не более одного раза. Поскольку внутренняя финализация Python завершится до вызова функции очистки, func не должна вызывать никакие API Python.

См. также

PyUnstable_AtExit() для передачи аргумента void *data.