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

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)

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

void PyOS_BeforeFork()

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

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

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

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

void PyOS_AfterFork_Parent()

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

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

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

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

void PyOS_AfterFork_Child()

Функция для обновления внутреннего состояния интерпретатора после разветвления процесса. Её нужно вызывать из дочернего процесса после вызова 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()

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

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

int PyOS_CheckStack()

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

PyOS_sighandler_t PyOS_getsig(int i)

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

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

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

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

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

Кодирование: от высшего приоритета к низшему:

  • 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)

Кодирует строку широких символов в кодировку локали с помощью обработчика ошибок surrogateescape: суррогатные символы в диапазоне 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. Функция перехвата всегда вызывается с хранимым интерпретатором Python GIL, вызвавшем событие.

См. 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 будет завершена перед функцией очистки, func не должен вызывать API Python.