Документация 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)

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

void PyOS_AfterFork()

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

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;

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

  • текущая кодировка локали (локаль LC_CTYPE).

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

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

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

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

См. также

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

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

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

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

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

  • UTF-8 на macOS и Android;

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

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

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

Если error_pos не равно NULL, *error_pos устанавливается в индекс недопустимого символа при ошибке кодирования, в противном случае – в (size_t)-1.

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

См. также

Функции PyUnicode_EncodeFSDefault() и PyUnicode_EncodeLocale().

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

Системные функции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 в пустой список.

void PySys_AddWarnOption(wchar_t *s)

Добавляет s к sys.warnoptions.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

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

void PySys_SetPath(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().

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

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

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

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

Управление процессами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.