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

PyObject *PyOS_FSPath(PyObject *path)
Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.6.

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

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

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

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

void PyOS_BeforeFork()
Part of the Стабильный 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 Стабильный 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 Стабильный 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 Стабильный ABI on platforms with fork().

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

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

int PyOS_CheckStack()
Part of the Стабильный ABI on platforms with USE_STACKCHECK since version 3.7.

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

typedef void (*PyOS_sighandler_t)(int)
Part of the Стабильный ABI.
PyOS_sighandler_t PyOS_getsig(int i)
Part of the Стабильный ABI.

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

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Part of the Стабильный ABI.

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

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
Part of the Стабильный 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 при ошибке декодирования или при ошибке выделения памяти. Если размер не равен NULL, *size устанавливается на (size_t)-1 при ошибке памяти или устанавливается на (size_t)-2 при ошибке декодирования.

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

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

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

Добавлено в версии 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 Стабильный 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 доступной для кода на C. Все они работают с dict модуля текущего интерпретатора sys, который содержится во внутренней структуре состояния потока.

PyObject *PySys_GetObject(const char *name)
Возвращаемое значение: Заимствованная ссылка. Part of the Стабильный ABI.

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

int PySys_SetObject(const char *name, PyObject *v)
Part of the Стабильный ABI.

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

void PySys_ResetWarnOptions()
Part of the Стабильный ABI.

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

void PySys_AddWarnOption(const wchar_t *s)
Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметр PyConfig.warnoptions, см. Python Initialization Configuration.

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

Не рекомендуется, начиная с версии 3.11.

void PySys_AddWarnOptionUnicode(PyObject *unicode)
Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметр PyConfig.warnoptions, см. Python Initialization Configuration.

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

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

Не рекомендуется, начиная с версии 3.11.

void PySys_SetPath(const wchar_t *path)
Part of the Стабильный ABI.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать настройки PyConfig.module_search_paths и PyConfig.module_search_paths_set, см. Python Initialization Configuration.

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

Не рекомендуется, начиная с версии 3.11.

void PySys_WriteStdout(const char *format, ...)
Part of the Стабильный ABI.

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

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

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

void PySys_WriteStderr(const char *format, ...)
Part of the Стабильный ABI.

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

void PySys_FormatStdout(const char *format, ...)
Part of the Стабильный ABI.

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

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

void PySys_FormatStderr(const char *format, ...)
Part of the Стабильный ABI.

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

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

void PySys_AddXOption(const wchar_t *s)
Part of the Стабильный ABI since version 3.7.

Этот API сохранен для обеспечения обратной совместимости: вместо него следует использовать параметр PyConfig.xoptions, см. Python Initialization Configuration.

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

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

Не рекомендуется, начиная с версии 3.11.

PyObject *PySys_GetXOptions()
Возвращаемое значение: Заимствованная ссылка. Part of the Стабильный ABI since version 3.7.

Возвращает текущий словарь параметров -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: Требуется : c:type:Py_ssize_t для символов формата #. Ранее было выдано неизбежное предупреждение об устаревании.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

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

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

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

Функция перехвата всегда вызывается с использованием 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(). args гарантированно будет PyTupleObject. userData - это аргумент, передаваемый в PySys_AddAuditHook().

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

Управление технологическим процессом

void Py_FatalError(const char *message)
Part of the Стабильный ABI.

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

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

Изменено в версии 3.9: Автоматически запишите название функции в журнал.

void Py_Exit(int status)
Part of the Стабильный ABI.

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

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

int Py_AtExit(void (*func)())
Part of the Стабильный ABI.

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

Вернуться на верх