`sys.md`

166 строк · 16.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/c-api/sys.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Утилиты операционной системы89#### `PyObject* PyOS_FSPath(PyObject *path)`1011*Возвращаемое значение: новая ссылка.*1213Возвращает представление файловой системы для *пути*. Если объект является объектом [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), то его счётчик ссылок увеличивается. Если объект реализует интерфейс [`os.PathLike`](https://python-all.ru/3.6/library/os.html#os.PathLike), то [`__fspath__()`](https://python-all.ru/3.6/library/os.html#os.PathLike.__fspath__) возвращается, если он является объектом [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). В противном случае возбуждается [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError) и возвращается `NULL`.1415Новое в версии 3.6.1617#### `int Py_FdIsInteractive(FILE *fp, const char *filename)`1819Возвращает true (ненулевое значение), если стандартный файл ввода-вывода *fp* с именем *filename* считается интерактивным. Это верно для файлов, для которых `isatty(fileno(fp))` истинно. Если глобальный флаг `Py_InteractiveFlag` истинен, эта функция также возвращает true, если указатель *filename* равен *NULL* или если имя совпадает с одной из строк `'<stdin>'` или `'???'`.2021#### `void PyOS_AfterFork()`2223Функция для обновления некоторого внутреннего состояния после ветвления процесса; её следует вызвать в новом процессе, если интерпретатор Python будет продолжать использоваться. Если в новый процесс загружается новый исполняемый файл, эту функцию вызывать не нужно.2425#### `int PyOS_CheckStack()`2627Возвращает истину, когда интерпретатору не хватает места в стеке. Это надёжная проверка, но доступна только при определении `USE_STACKCHECK` (в настоящее время в Windows с использованием компилятора Microsoft Visual C++). `USE_STACKCHECK` будет определён автоматически; никогда не следует изменять это определение в своём коде.2829#### `PyOS_sighandler_t PyOS_getsig(int i)`3031Возвращает текущий обработчик сигнала для сигнала *i*. Это тонкая обёртка вокруг `sigaction()` или `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`.3233#### `PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)`3435Устанавливает обработчик сигнала для сигнала *i* равным *h*; возвращает старый обработчик сигнала. Это тонкая обёртка вокруг либо `sigaction()`, либо `signal()`. Не вызывайте эти функции напрямую! `PyOS_sighandler_t` – это псевдоним typedef для `void (*)(int)`.3637#### `wchar_t* Py_DecodeLocale(const char* arg, size_t *size)`3839Декодирует байтовую строку из кодировки локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.6/library/codecs.html#surrogateescape): недекодируемые байты декодируются как символы в диапазоне U+DC80..U+DCFF. Если последовательность байтов может быть декодирована как суррогатный символ, то такие байты экранируются с помощью обработчика ошибок surrogateescape вместо их декодирования.4041Кодировка (от высшего приоритета к низшему):4243- `UTF-8` на macOS и Android;44- `ASCII`, если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`.45- текущая кодировка локали (локаль `LC_CTYPE`).4647Возвращает указатель на новую выделенную строку широких символов; используйте [`PyMem_RawFree()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_RawFree) для освобождения памяти. Если size не равно `NULL`, запишите количество широких символов без учёта нулевого символа в `*size`.4849Возвращает `NULL` при ошибке декодирования или ошибке выделения памяти. Если *size* не равен `NULL`, `*size` устанавливается в `(size_t)-1` при ошибке памяти или в `(size_t)-2` при ошибке декодирования.5051Ошибки декодирования никогда не должны происходить, если только нет ошибки в библиотеке C.5253Используйте функцию [`Py_EncodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_EncodeLocale) для обратного кодирования строки символов в байтовую строку.5455> **См. также**56>57> Функции [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) и [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).5859Новое в версии 3.5.6061#### `char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)`6263Кодирует широкую символьную строку в кодировку локали с помощью [обработчика ошибок surrogateescape](https://python-all.ru/3.6/library/codecs.html#surrogateescape): суррогатные символы в диапазоне U+DC80..U+DCFF преобразуются в байты 0x80..0xFF.6465Кодировка (от высшего приоритета к низшему):6667- `UTF-8` на macOS и Android;68- `ASCII` если локаль `LC_CTYPE` равна `"C"`, `nl_langinfo(CODESET)` возвращает кодировку `ASCII` (или псевдоним), а функции `mbstowcs()` и `wcstombs()` используют кодировку `ISO-8859-1`.69- текущая кодировка локали.7071Возвращает указатель на вновь выделенную байтовую строку, используется [`PyMem_Free()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Free)\\nдля освобождения памяти. Возвращает `NULL` при ошибке кодирования или ошибке выделения\\nпамяти.7273Если error\_pos не равно `NULL`, `*error_pos` устанавливается в индекс недопустимого символа при ошибке кодирования, в противном случае – в `(size_t)-1`.7475Используйте функцию [`Py_DecodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_DecodeLocale) для обратного декодирования байтовой строки в строку широких символов.7677> **См. также**78>79> Функции [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) и [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeLocale).8081Новое в версии 3.5.8283# Системные функции8485Это служебные функции, предоставляющие функциональность модуля [`sys`](https://python-all.ru/3.6/library/sys.html#module-sys) коду на C. Все они работают со словарём модуля [`sys`](https://python-all.ru/3.6/library/sys.html#module-sys) текущего потока интерпретатора, который хранится во внутренней структуре состояния потока.8687#### `PyObject *PySys_GetObject(const char *name)`8889*Возвращаемое значение: заимствованная ссылка.*9091Возвращает объект *name* из модуля [`sys`](https://python-all.ru/3.6/library/sys.html#module-sys) или *NULL*, если он не существует, без установки исключения.9293#### `int PySys_SetObject(const char *name, PyObject *v)`9495Устанавливает *name* в модуле [`sys`](https://python-all.ru/3.6/library/sys.html#module-sys) в значение *v*, если только *v* не равно *NULL*; в этом случае *name* удаляется из модуля sys. Возвращает `0` при успехе, `-1` при ошибке.9697#### `void PySys_ResetWarnOptions()`9899Сбрасывает [`sys.warnoptions`](https://python-all.ru/3.6/library/sys.html#sys.warnoptions) в пустой список.100101#### `void PySys_AddWarnOption(wchar_t *s)`102103Добавляет *s* к [`sys.warnoptions`](https://python-all.ru/3.6/library/sys.html#sys.warnoptions).104105#### `void PySys_AddWarnOptionUnicode(PyObject *unicode)`106107Добавляет *unicode* к [`sys.warnoptions`](https://python-all.ru/3.6/library/sys.html#sys.warnoptions).108109#### `void PySys_SetPath(wchar_t *path)`110111Устанавливает [`sys.path`](https://python-all.ru/3.6/library/sys.html#sys.path) в объект списка путей, найденных в *path*, который должен быть списком путей, разделённых разделителем пути поиска платформы (`:` в Unix, `;` в Windows).112113#### `void PySys_WriteStdout(const char *format, ...)`114115Записывает выходную строку, описываемую *format*, в [`sys.stdout`](https://python-all.ru/3.6/library/sys.html#sys.stdout). Исключения не вызываются, даже если произошло усечение (см. ниже).116117*format* должен ограничивать общий размер форматированной выходной строки до 1000 байт или менее – после 1000 байт строка усекается. В частности, это означает, что не должно быть неограниченных форматов «%s»; их следует ограничивать с помощью «%.\<N\>s», где \<N\> – десятичное число, рассчитанное так, чтобы \<N\> плюс максимальный размер другого форматированного текста не превышал 1000 байт. Также следует остерегаться «%f», который может печатать сотни цифр для очень больших чисел.118119Если возникает проблема или [`sys.stdout`](https://python-all.ru/3.6/library/sys.html#sys.stdout) не задан, форматированное сообщение записывается в настоящий (на уровне C) *stdout*.120121#### `void PySys_WriteStderr(const char *format, ...)`122123Аналогично [`PySys_WriteStdout()`](https://python-all.ru/3.6/c-api/sys.html#c.PySys_WriteStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.6/library/sys.html#sys.stderr) или *stderr* вместо этого.124125#### `void PySys_FormatStdout(const char *format, ...)`126127Функция подобна PySys\_WriteStdout(), но форматирует сообщение с помощью [`PyUnicode_FromFormatV()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromFormatV) и не обрезает сообщение до произвольной длины.128129Новое в версии 3.2.130131#### `void PySys_FormatStderr(const char *format, ...)`132133Аналогично [`PySys_FormatStdout()`](https://python-all.ru/3.6/c-api/sys.html#c.PySys_FormatStdout), но выводит в [`sys.stderr`](https://python-all.ru/3.6/library/sys.html#sys.stderr) или *stderr* вместо этого.134135Новое в версии 3.2.136137#### `void PySys_AddXOption(const wchar_t *s)`138139Разбирает *s* как набор опций [`-X`](https://python-all.ru/3.6/using/cmdline.html#id5) и добавляет их в текущее отображение опций, возвращаемое функцией [`PySys_GetXOptions()`](https://python-all.ru/3.6/c-api/sys.html#c.PySys_GetXOptions).140141Новое в версии 3.2.142143#### `PyObject *PySys_GetXOptions()`144145*Возвращаемое значение: заимствованная ссылка.*146147Возвращает текущий словарь опций [`-X`](https://python-all.ru/3.6/using/cmdline.html#id5), аналогично [`sys._xoptions`](https://python-all.ru/3.6/library/sys.html#sys._xoptions). При ошибке возвращается *NULL* и устанавливается исключение.148149Новое в версии 3.2.150151# Управление процессами152153#### `void Py_FatalError(const char *message)`154155Выводит фатальное сообщение об ошибке и завершает процесс. Очистка не выполняется. Эту функцию следует вызывать только при обнаружении условия, которое делает опасным продолжение использования интерпретатора Python; например, когда управление объектами повреждено. В Unix вызывается стандартная функция библиотеки C `abort()`, которая пытается создать файл `core`.156157#### `void Py_Exit(int status)`158159Завершает текущий процесс. Вызывает [`Py_FinalizeEx()`](https://python-all.ru/3.6/c-api/init.html#c.Py_FinalizeEx), а затем вызывает стандартную функцию библиотеки C `exit(status)`. Если [`Py_FinalizeEx()`](https://python-all.ru/3.6/c-api/init.html#c.Py_FinalizeEx) указывает на ошибку, код завершения устанавливается в 120.160161Изменено в версии 3.6: Ошибки при финализации больше не игнорируются.162163#### `int Py_AtExit(void (*func)())`164165Регистрирует функцию очистки, которая будет вызвана с помощью [`Py_FinalizeEx()`](https://python-all.ru/3.6/c-api/init.html#c.Py_FinalizeEx). Функция очистки будет вызвана без аргументов и не должна возвращать значение. Можно зарегистрировать не более 32 функций очистки. При успешной регистрации [`Py_AtExit()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_AtExit) возвращает `0`; при неудаче – `-1`. Последняя зарегистрированная функция очистки вызывается первой. Каждая функция очистки будет вызвана не более одного раза. Поскольку внутренняя финализация Python завершится до вызова функции очистки, *func* не должна вызывать никакие API Python.166