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

PyObject *PyOS_FSPath(PyObject *path)¶

Return value: New reference. Part of the Stable ABI since version 3.6.

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

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

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

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

void PyOS_BeforeFork()¶

Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

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

void PyOS_AfterFork_Parent()¶

Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

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

void PyOS_AfterFork_Child()¶

Part of the Stable ABI on platforms with fork() since version 3.7.

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

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

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

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

См.также

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

void PyOS_AfterFork()¶

Part of the Stable ABI on platforms with fork().

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

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

int PyOS_CheckStack()¶

Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.

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

PyOS_sighandler_t PyOS_getsig(int i)¶

Part of the Stable ABI.

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

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)¶

Part of the Stable ABI.

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

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

Part of the Stable ABI since version 3.7.

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

Эту функцию не следует вызывать напрямую: используйте API PyConfig с функцией 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() для освобождения памяти. Если размер не равен 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().

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

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

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

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

Part of the Stable ABI since version 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().

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

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

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

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

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

PyObject *PySys_GetObject(const char *name)¶

Return value: Borrowed reference. Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

void PySys_ResetWarnOptions()¶

Part of the Stable ABI.

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

void PySys_AddWarnOption(const wchar_t *s)¶

Part of the Stable ABI.

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

void PySys_AddWarnOptionUnicode(PyObject *unicode)¶

Part of the Stable ABI.

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

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

void PySys_SetPath(const wchar_t *path)¶

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

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

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

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

Part of the Stable ABI.

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

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

void PySys_AddXOption(const wchar_t *s)¶

Part of the Stable ABI since version 3.7.

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

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

PyObject *PySys_GetXOptions()¶

Return value: Borrowed reference. Part of the Stable ABI since version 3.7.

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

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

int PySys_Audit(const char *event, const char *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 (другие ошибки не будут заглушены).

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

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

Вызывает auditing event sys.addaudithook без аргументов.

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

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

void Py_FatalError(const char *message)¶

Part of the Stable ABI.

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

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

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

void Py_Exit(int status)¶

Part of the Stable ABI.

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

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

int Py_AtExit(void (*func)())¶

Part of the Stable ABI.

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