Документация Python неофициальный перевод

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

PyObject* PyOS_FSPath(PyObject *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 если включён режим UTF-8 Python;

  • ASCII если локаль LC_CTYPE равна "C", nl_langinfo(CODESET) возвращает кодировку ASCII (или псевдоним), а функции mbstowcs() и wcstombs() используют кодировку ISO-8859-1.

  • текущая кодировка локали.

Возвращает указатель на новую выделенную строку широких символов; для освобождения памяти используйте PyMem_RawFree(). Если size не равен 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 если включён режим UTF-8 Python;

  • ASCII если локаль LC_CTYPE равна "C", nl_langinfo(CODESET) возвращает кодировку ASCII (или псевдоним), а функции mbstowcs() и wcstombs() используют кодировку ISO-8859-1.

  • текущая кодировка локали.

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

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

Если 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 равен нулю;

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

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

PyObject *PySys_GetObject(const char *name)
Возвращаемое значение: заимствованная ссылка.

Возвращает объект 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(), но она не может быть вызвана, пока среда выполнения не будет достаточно инициализирована для создания объектов Unicode.

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()
Возвращаемое значение: заимствованная ссылка.

Возвращает текущий словарь опций -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 в список активных хуков аудита.\nВозвращает ноль при успехе\nи ненулевое значение при ошибке. Если среда выполнения уже инициализирована, также устанавливает\nошибку при неудаче. Хуки, добавленные через этот API, вызываются для всех\nинтерпретаторов, созданных средой выполнения.

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

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

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

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

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

Новое в версии 3.8.

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

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.