Утилиты операционной системы¶
-
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()
, чтобы закодировать символьную строку обратно в байтовую строку.См.также
Функции
PyUnicode_DecodeFSDefaultAndSize()
иPyUnicode_DecodeLocaleAndSize()
.Добавлено в версии 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.
-
typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)¶
Управление технологическим процессом¶
-
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()
, а затем вызывается стандартная библиотечная функция Cexit(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.