os — Разнообразные интерфейсы операционной системы

Имена файлов, аргументы командной строки и переменные среды

В Python имена файлов, аргументы командной строки и переменные среды представляются с помощью типа строки. В некоторых системах необходимо выполнить декодирование этих строк в байты и обратно, прежде чем передавать их операционной системе. Python использует кодировку и обработчик ошибок файловой системы для выполнения этого преобразования (см. sys.getfilesystemencoding()).

кодировка и обработчик ошибок файловой системы настраиваются при запуске Python функцией PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors объекта PyConfig.

кодировка файловой системы должна гарантировать успешное декодирование всех байтов ниже 128. Если кодировка файловой системы не обеспечивает этой гарантии, функции API могут вызвать исключение UnicodeError.

См. также кодировку локали.

Режим Python UTF-8

Режим Python UTF-8 игнорирует кодировку локали и принудительно использует кодировку UTF-8:

• Используйте UTF-8 в качестве кодировки файловой системы.
• sys.getfilesystemencoding() возвращает 'utf-8'.
• locale.getpreferredencoding() возвращает 'utf-8' (аргумент do_setlocale не имеет эффекта).
• sys.stdin, sys.stdout и sys.stderr все используют UTF-8 в качестве кодировки текста с включённым surrogateescape обработчиком ошибок для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace как и в режиме, учитывающем локаль по умолчанию).
• В Unix, os.device_encoding() возвращает 'utf-8' вместо кодировки устройства.

Обратите внимание, что стандартные настройки потоков в режиме UTF-8 могут быть переопределены с помощью PYTHONIOENCODING (точно так же, как и в режиме, учитывающем локаль по умолчанию).

Вследствие изменений в этих API низкого уровня, другие API высокого уровня также демонстрируют разное поведение по умолчанию:

• Аргументы командной строки, переменные среды и имена файлов декодируются в текст с помощью кодировки UTF-8.
• os.fsdecode() и os.fsencode() используют кодировку UTF-8.
• open(), io.open() и codecs.open() используют кодировку UTF-8 по умолчанию. Однако они по-прежнему используют обработчик ошибок strict по умолчанию, поэтому попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не произведёт бессмысленные данные.

Режим Python UTF-8 включен, если локали LC_CTYPE равна C или POSIX при запуске Python (см. функцию PyConfig_Read()).

Он может быть включен или выключен с помощью опции командной строки -X utf8 и переменной среды PYTHONUTF8.

Если переменная среды PYTHONUTF8 вообще не задана, интерпретатор по умолчанию использует текущие настройки локали, кроме случаев, когда текущая локали распознаётся как устаревшая локали на основе ASCII (как описано для PYTHONCOERCECLOCALE), и принуждение локали либо отключено, либо не выполняется. В таких устаревших локалях интерпретатор по умолчанию включит режим UTF-8, если явно не указано обратное.

Режим Python UTF-8 может быть включён только при запуске Python. Его значение можно прочитать из sys.flags.utf8_mode.

См. также режим UTF-8 в Windows и кодировку и обработчик ошибок файловой системы.

Параметры процесса

Эти функции и элементы данных предоставляют информацию и выполняют операции над текущим процессом и пользователем.

os.ctermid()

Возвращает имя файла, соответствующее управляющему терминалу процесса.

Доступность: Unix, не WASI.

os.environ

Объект отображения, где ключи и значения — строки, представляющие среду процесса. Например, environ['HOME'] — это путь к вашему домашнему каталогу (на некоторых платформах), что эквивалентно getenv("HOME") в C.

Это отображение сохраняется при первом импорте модуля os, обычно во время запуска Python в рамках обработки site.py. Изменения среды, внесённые после этого момента, не отражаются в os.environ, за исключением изменений, сделанных путём непосредственного изменения os.environ.

Это отображение можно использовать как для изменения, так и для запроса среды. putenv() будет вызван автоматически при изменении отображения.

В Unix ключи и значения используют кодировку sys.getfilesystemencoding() и обработчик ошибок 'surrogateescape'. Используйте environb, если требуется другая кодировка.

В Windows ключи преобразуются в верхний регистр. Это также относится к получению, установке или удалению элемента. Например, environ['monty'] = 'python' отображает ключ 'MONTY' со значением 'python'.

Примечание

Прямое вызов putenv() не изменяет os.environ, поэтому лучше изменять os.environ.

Примечание

На некоторых платформах, включая FreeBSD и macOS, установка environ может привести к утечке памяти. Обратитесь к документации системы для putenv().

Можно удалять элементы из этого отображения, чтобы сбросить переменные окружения. unsetenv() будет вызван автоматически при удалении элемента из os.environ, а также при вызове одного из методов pop() или clear().

Изменено в версии 3.9: Обновлено для поддержки операторов слияния (PEP 584) (|) и обновления (|=).

os.environb

Байтовая версия environ: объект отображения, где и ключи, и значения — объекты bytes, представляющие среду процесса. environ и environb синхронизированы (изменение environb обновляет environ и наоборот).

environb доступен только если supports_bytes_environ равно True.

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

Изменено в версии 3.9: Обновлено для поддержки операторов слияния (PEP 584) (|) и обновления (|=).

os.chdir(path)

os.fchdir(fd)

os.getcwd()

Эти функции описаны в Файлы и каталоги.

os.fsencode(filename)

Кодирует путь-подобный объект filename в кодировку и обработчик ошибок файловой системы; возвращает bytes без изменений.

fsdecode() — обратная функция.

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

Изменено в версии 3.6: Добавлена поддержка объектов, реализующих интерфейс os.PathLike.

os.fsdecode(filename)

Декодирует путь-подобный объект filename из кодировки и обработчика ошибок файловой системы; возвращает str без изменений.

fsencode() — обратная функция.

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

Изменено в версии 3.6: Добавлена поддержка объектов, реализующих интерфейс os.PathLike.

os.fspath(path)

Возвращает представление пути в файловой системе.

Если передано str или bytes, оно возвращается без изменений. В противном случае вызывается __fspath__(), и его значение возвращается, если это объект str или bytes. Во всех остальных случаях возбуждается исключение TypeError.

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

class os.PathLike

Абстрактный базовый класс для объектов, представляющих путь в файловой системе, например, pathlib.PurePath.

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

abstractmethod __fspath__()

Возвращает представление пути в файловой системе для объекта.

Метод должен возвращать только объект str или bytes, при этом предпочтительным является str.

os.getenv(key, default=None)

Возвращает значение переменной окружения key в виде строки, если она существует, или default, если нет. key — строка. Обратите внимание, что поскольку getenv() использует os.environ, отображение getenv() также фиксируется при импорте, и функция может не отражать будущие изменения окружения.

В Unix ключи и значения декодируются с помощью sys.getfilesystemencoding() и обработчика ошибок 'surrogateescape'. Используйте os.getenvb(), если вы хотите использовать другое кодирование.

Доступность: Unix, Windows.

os.getenvb(key, default=None)

Возвращает значение переменной окружения key в виде байтов, если она существует, или default, если нет. key должен быть объектом типа байты. Обратите внимание, что поскольку getenvb() использует os.environb, отображение getenvb() также фиксируется при импорте, и функция может не отражать будущие изменения окружения.

getenvb() доступно только если supports_bytes_environ равно True.

Доступность: Unix.

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

os.get_exec_path(env=None)

Возвращает список каталогов, которые будут проверяться при поиске исполняемого файла с заданным именем, аналогично оболочке, при запуске процесса. env, если указан, должен быть словарем переменных окружения для поиска пути PATH. По умолчанию, когда env равен None, используется environ.

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

os.getegid()

Возвращает эффективный идентификатор группы текущего процесса. Соответствует биту «установления идентификатора» для файла, выполняемого в текущем процессе.

Доступность: Unix, не WASI.

os.geteuid()

Возвращает эффективный идентификатор пользователя текущего процесса.

Доступность: Unix, не WASI.

os.getgid()

Возвращает реальный идентификатор группы текущего процесса.

Доступность: Unix.

Функция является заглушкой в WASI, см. Платформы WebAssembly для получения дополнительной информации.

os.getgrouplist(user, group, /)

Возвращает список идентификаторов групп, к которым принадлежит user. Если group отсутствует в списке, он включается; обычно group задаётся как поле идентификатора группы из записи пароля для user, так как в противном случае этот идентификатор группы может быть потенциально опущен.

Доступность: Unix, не WASI.

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

os.getgroups()

Возвращает список дополнительных идентификаторов групп, связанных с текущим процессом.

Доступность: Unix, не WASI.

Примечание

В macOS поведение getgroups() несколько отличается от других платформ Unix. Если интерпретатор Python был скомпилирован с целевым уровнем выпуска 10.5 или ранее, getgroups() возвращает список эффективных идентификаторов групп, связанных с текущим процессом пользователя; этот список ограничен заданным числом записей системы, как правило, 16, и может быть изменён вызовами setgroups(), если соответствующие привилегии предоставлены. Если скомпилирован с целевым уровнем выпуска, большим 10.5, getgroups() возвращает текущий список доступа к группам для пользователя, связанного с эффективным идентификатором пользователя процесса; список доступа к группам может меняться в течение времени жизни процесса, он не изменяется вызовами setgroups(), и его длина не ограничена 16. Значение целевого уровня выпуска MACOSX_DEPLOYMENT_TARGET можно получить с помощью sysconfig.get_config_var().

os.getlogin()

Возвращает имя пользователя, вошедшего в систему на управляющем терминале процесса. Для большинства целей более полезно использовать getpass.getuser(), так как последний проверяет переменные окружения LOGNAME или USERNAME для определения пользователя и обращается к pwd.getpwuid(os.getuid())[0] для получения имени пользователя текущего реального идентификатора пользователя.

Доступность: Unix, Windows, не WASI.

os.getpgid(pid)

Возвращает идентификатор группы процессов процесса с идентификатором pid. Если pid равно 0, возвращается идентификатор группы процессов текущего процесса.

Доступность: Unix, не WASI.

os.getpgrp()

Возвращает идентификатор текущей группы процессов.

Доступность: Unix, не WASI.

os.getpid()

Возвращает текущий идентификатор процесса.

Функция является заглушкой в WASI, см. Платформы WebAssembly для получения дополнительной информации.

os.getppid()

Возвращает идентификатор родительского процесса. Когда родительский процесс завершился, в Unix возвращается идентификатор процесса init (1), в Windows — всё ещё тот же идентификатор, который может быть повторно использован другим процессом.

Доступность: Unix, Windows, не WASI.

Изменено в версии 3.2: Добавлена поддержка Windows.

os.getpriority(which, who)

Получить приоритет планирования программы. Значение which равно одному из PRIO_PROCESS, PRIO_PGRP или PRIO_USER, а who интерпретируется относительно which (идентификатор процесса для PRIO_PROCESS, идентификатор группы процессов для PRIO_PGRP и идентификатор пользователя для PRIO_USER). Нулевое значение who обозначает (соответственно) вызывающий процесс, группу процессов вызывающего процесса или реальный идентификатор пользователя вызывающего процесса.

Доступность: Unix, не WASI.

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

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

Параметры для функций getpriority() и setpriority().

Доступность: Unix, не WASI.

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

os.PRIO_DARWIN_THREAD

os.PRIO_DARWIN_PROCESS

os.PRIO_DARWIN_BG

os.PRIO_DARWIN_NONUI

Параметры для функций getpriority() и setpriority().

Доступность: macOS

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

os.getresuid()

Возвращает кортеж (ruid, euid, suid), обозначающий реальные, эффективные и сохранённые идентификаторы пользователей текущего процесса.

Доступность: Unix, не WASI.

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

os.getresgid()

Возвращает кортеж (rgid, egid, sgid), обозначающий реальные, эффективные и сохранённые идентификаторы групп текущего процесса.

Доступность: Unix, не WASI.

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

os.getuid()

Возвращает реальный идентификатор пользователя текущего процесса.

Доступность: Unix.

Функция является заглушкой на WASI, см. Платформы WebAssembly для получения дополнительной информации.

os.initgroups(username, gid, /)

Вызывает системную функцию initgroups() для инициализации списка доступа к группам всеми группами, к которым принадлежит указанное имя пользователя, плюс указанный идентификатор группы.

Доступность: Unix, не WASI, не Android.

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

os.putenv(key, value, /)

Устанавливает переменную среды с именем key в строку value. Такие изменения среды влияют на дочерние процессы, запущенные с помощью os.system(), popen() или fork() и execv().

Присвоение значения элементам в os.environ автоматически переводится в соответствующие вызовы putenv(); однако, вызовы putenv() не обновляют os.environ, поэтому предпочтительнее присваивать значения элементам os.environ. Это также относится к getenv() и getenvb(), которые соответственно используют os.environ и os.environb в своих реализациях.

Примечание

На некоторых платформах, включая FreeBSD и macOS, установка environ может привести к утечкам памяти. Обратитесь к документации системы для putenv().

Вызывает событие аудита аудита os.putenv с аргументами key, value.

Изменено в версии 3.9: Функция теперь всегда доступна.

os.setegid(egid, /)

Устанавливает эффективный идентификатор группы текущего процесса.

Доступность: Unix, не WASI, не Android.

os.seteuid(euid, /)

Устанавливает эффективный идентификатор пользователя текущего процесса.

Доступность: Unix, не WASI, не Android.

os.setgid(gid, /)

Устанавливает идентификатор группы текущего процесса.

Доступность: Unix, не WASI, не Android.

os.setgroups(groups, /)

Устанавливает список дополнительных идентификаторов групп, связанных с текущим процессом, на groups. groups должен быть последовательностью, а каждый элемент должен быть целым числом, определяющим группу. Обычно эта операция доступна только суперпользователю.

Доступность: Unix, не WASI.

Примечание

На macOS длина groups может не превышать максимального количества эффективных идентификаторов групп, определённых системой, обычно 16. См. документацию по getgroups() для случаев, когда она может не возвращать тот же список групп, который был задан с помощью setgroups().

os.setns(fd, nstype=0)

Переустанавливает текущую нить с пространством имён Linux. См. страницы руководства setns(2) и namespaces(7) для получения более подробной информации.

Если fd ссылается на /proc/pid/ns/ ссылку, setns() переустанавливает вызывающую нить в пространстве имён, связанном с этой ссылкой, и nstype можно установить в одно из констант CLONE_NEW* для наложения ограничений на операцию (0 означает без ограничений).

Начиная с Linux 5.8, fd может ссылаться на дескриптор файла PID, полученный из pidfd_open(). В этом случае setns() переустанавливает вызывающую нить в одно или несколько тех же пространств имён, что и нить, на которую ссылается fd. Это подчинено любым ограничениям, наложенным nstype, который представляет собой битовую маску, объединяющую одно или несколько из констант CLONE_NEW*, например, setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID). Принадлежности вызывающего процесса к неопределённым пространствам имён остаются неизменными.

fd может быть любым объектом с методом fileno() или сырым дескриптором файла.

В этом примере нить переустанавливается в пространство имён сети процесса init.

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

Доступность: Linux >= 3.0 с glibc >= 2.14.

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

См. также

Функция unshare().

os.setpgrp()

Вызов системного вызова setpgrp() или setpgrp(0, 0) в зависимости от реализованной версии (если есть). См. руководство Unix для семантики.

Доступность: Unix, не WASI.

os.setpgid(pid, pgrp, /)

Вызов системного вызова setpgid() для установки идентификатора группы процессов процесса с идентификатором pid в группу процессов с идентификатором pgrp. См. руководство по Unix для семантики.

Доступность: Unix, не WASI.

os.setpriority(which, who, priority)

Установить приоритет планирования программы. Значение which равно одному из PRIO_PROCESS, PRIO_PGRP или PRIO_USER, а who интерпретируется относительно which (идентификатор процесса для PRIO_PROCESS, идентификатор группы процессов для PRIO_PGRP и идентификатор пользователя для PRIO_USER). Нулевое значение who обозначает (соответственно) вызывающий процесс, группу процессов вызывающего процесса или реальный идентификатор пользователя вызывающего процесса. priority — значение в диапазоне от -20 до 19. Значение по умолчанию — 0; более низкие приоритеты приводят к более благоприятному планированию.

Доступность: Unix, не WASI.

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

os.setregid(rgid, egid, /)

Установить реальный и эффективный идентификаторы группы текущего процесса.

Доступность: Unix, не WASI, не Android.

os.setresgid(rgid, egid, sgid, /)

Установить реальный, эффективный и сохранённый идентификаторы группы текущего процесса.

Доступность: Unix, не WASI, не Android.

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

os.setresuid(ruid, euid, suid, /)

Установить реальный, эффективный и сохранённый идентификаторы пользователей текущего процесса.

Доступность: Unix, не WASI, не Android.

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

os.setreuid(ruid, euid, /)

Установить реальный и эффективный идентификаторы пользователей текущего процесса.

Доступность: Unix, не WASI, не Android.

os.getsid(pid, /)

Вызов системного вызова getsid(). См. руководство по Unix для семантики.

Доступность: Unix, не WASI.

os.setsid()

Вызов системного вызова setsid(). См. руководство по Unix для семантики.

Доступность: Unix, не WASI.

os.setuid(uid, /)

Установить идентификатор пользователя текущего процесса.

Доступность: Unix, не WASI, не Android.

os.strerror(code, /)

Возвращает сообщение об ошибке, соответствующее коду ошибки в code. На платформах, где strerror() возвращает NULL при передаче неизвестного номера ошибки, генерируется ValueError.

os.supports_bytes_environ

True если тип среды нативного ОС — байты (например, False в Windows).

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

os.umask(mask, /)

Установить текущую числовую маску umask и вернуть предыдущую маску umask.

Функция является заглушкой на WASI, см. Платформы WebAssembly для получения дополнительной информации.

os.uname()

Возвращает информацию, идентифицирующую текущую операционную систему. Результат — объект с пятью атрибутами:

• sysname — имя операционной системы
• nodename — имя машины в сети (определяется реализацией)
• release — выпуск операционной системы
• version — версия операционной системы
• machine — идентификатор оборудования

Для обеспечения обратной совместимости этот объект также итерируется, ведя себя как пятерка кортежей, содержащих sysname, nodename, release, version, и machine в указанном порядке.

В некоторых системах nodename обрезается до 8 символов или до ведущего компонента; лучший способ получить имя хоста — socket.gethostname() или даже socket.gethostbyaddr(socket.gethostname()).

В macOS, iOS и Android это возвращает имя и версию ядра (т.е., 'Darwin' в macOS и iOS; 'Linux' в Android). platform.uname() можно использовать для получения имени и версии операционной системы, ориентированной на пользователя, в iOS и Android.

Доступность: Unix.

Изменено в версии 3.3: Тип возвращаемого значения изменён с кортежа на похожий на кортеж объект с именованными атрибутами.

os.unsetenv(key, /)

Снять (удалить) переменную среды с именем key. Такие изменения среды влияют на дочерние процессы, запущенные с помощью os.system(), popen() или fork() и execv().

Удаление элементов в os.environ автоматически переводится в соответствующий вызов unsetenv(); однако вызовы unsetenv() не обновляют os.environ, поэтому предпочтительнее удалять элементы os.environ.

Вызывает событие аудита os.unsetenv с аргументом key.

Изменено в версии 3.9: Функция теперь всегда доступна и также доступна в Windows.

os.unshare(flags)

Отсоединить части контекста выполнения процесса и переместить их в вновь созданное пространство имён. См. страницу руководства unshare(2) для получения дополнительных сведений. Аргумент flags — битовая маска, объединяющая ноль или более констант CLONE_*, определяющая, какие части контекста выполнения должны быть отсоединены от существующих ассоциаций и перемещены в новое пространство имён. Если аргумент flags равен 0, изменения в контексте выполнения вызывающего процесса не производятся.

Доступность: Linux >= 2.6.16.

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

См. также

Функцию setns().

Флаги для функции unshare(), если их поддерживает реализация. См. unshare(2) в руководстве Linux для точного эффекта и доступности.

os.CLONE_FILES

os.CLONE_FS

os.CLONE_NEWCGROUP

os.CLONE_NEWIPC

os.CLONE_NEWNET

os.CLONE_NEWNS

os.CLONE_NEWPID

os.CLONE_NEWTIME

os.CLONE_NEWUSER

os.CLONE_NEWUTS

os.CLONE_SIGHAND

os.CLONE_SYSVSEM

os.CLONE_THREAD

os.CLONE_VM

Создание объектов файла

Эти функции создают новые объекты файла. (См. также open() для открытия дескрипторов файлов.)

os.fdopen(fd, *args, **kwargs)

Возвращает открытый объект файла, связанный с дескриптором файла fd. Это псевдоним встроенной функции open() и принимает те же аргументы. Единственное отличие состоит в том, что первый аргумент функции fdopen() всегда должен быть целым числом.

Операции с дескрипторами файлов

Эти функции работают с потоками ввода-вывода, ссылающимися с помощью дескрипторов файлов.

Дескрипторы файлов — это небольшие целые числа, соответствующие файлу, который был открыт текущим процессом. Например, стандартный ввод обычно имеет дескриптор 0, стандартный вывод — 1, а стандартная ошибка — 2. Дальнейшие файлы, открытые процессом, будут назначены 3, 4, 5 и так далее. Название «дескриптор файла» немного вводит в заблуждение; в системах Unix дескрипторы файлов также используются для сокетов и каналов.

Метод fileno() можно использовать для получения дескриптора файла, связанного с объектом файла, при необходимости. Обратите внимание, что непосредственное использование дескриптора файла обойдёт методы объекта файла, игнорируя такие аспекты, как внутреннее буферирование данных.

os.close(fd)

Закрыть дескриптор файла fd.

Примечание

Эта функция предназначена для ввода-вывода низкого уровня и должна применяться к дескриптору файла, возвращаемому функциями os.open() или pipe(). Для закрытия «объекта файла», возвращённого встроенной функцией open() или функциями popen() или fdopen(), используйте его метод close().

os.closerange(fd_low, fd_high, /)

Закрыть все дескрипторы файлов от fd_low (включительно) до fd_high (исключительно), игнорируя ошибки. Эквивалентно (но намного быстрее):

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

Скопировать count байт из дескриптора файла src, начиная с смещения offset_src, в дескриптор файла dst, начиная с смещения offset_dst. Если offset_src равно None, то src читается с текущей позиции; соответственно для offset_dst.

В ядрах Linux, младше 5.3, файлы, на которые ссылаются src и dst, должны находиться в одной файловой системе, в противном случае возникает исключение OSError с установленным errno на значение errno.EXDEV.

Эта копия выполняется без дополнительных затрат на передачу данных из ядра в пользовательское пространство, а затем обратно в ядро. Кроме того, некоторые файловые системы могут реализовать дополнительные оптимизации, такие как использование ссылок на ссылки (то есть два или более индексов, которые делят указатели на одни и те же блоки диска копирования при записи; поддерживаются файловые системы btrfs и XFS) и копирование на стороне сервера (в случае NFS).

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

Возвращаемое значение — количество скопированных байт. Оно может быть меньше запрошенного.

Примечание

В Linux, os.copy_file_range() не следует использовать для копирования диапазона псевдофайла из специальной файловой системы, такой как procfs и sysfs. Он всегда скопирует ноль байт и вернёт 0, как если бы файл был пустым, из-за известной проблемы ядра Linux.

Доступность: Linux >= 4.5 с glibc >= 2.27.

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

os.device_encoding(fd)

Возвращает строку, описывающую кодировку устройства, связанного с fd, если оно подключено к терминалу; в противном случае возвращает None.

В Unix, если включен режим Python UTF-8, возвращает 'UTF-8' вместо кодировки устройства.

Изменено в версии 3.10: В Unix функция теперь реализует режим Python UTF-8.

os.dup(fd, /)

Возвращает дубликат дескриптора файла fd. Новый дескриптор файла является не наследуемым.

В Windows, при дублировании стандартного потока (0: stdin, 1: stdout, 2: stderr), новый дескриптор файла является наследуемым.

Доступность: не WASI.

Изменено в версии 3.4: Новый дескриптор файла теперь не наследуемый.

os.dup2(fd, fd2, inheritable=True)

Дублирует дескриптор файла fd в fd2, предварительно закрывая последний, если необходимо. Возвращает fd2. Новый дескриптор файла по умолчанию является наследуемым, или ненаследуемым, если inheritable равно False.

Доступность: не WASI.

Изменено в версии 3.4: Добавлен необязательный параметр inheritable.

Изменено в версии 3.7: Возвращает fd2 при успехе. Ранее всегда возвращалось None.

os.fchmod(fd, mode)

Изменить режим файла, заданного fd, на числовой mode. См. документацию для chmod() для возможных значений mode. Начиная с Python 3.3, это эквивалентно os.chmod(fd, mode).

Вызывает событие аудита аудита os.chmod с аргументами path, mode, dir_fd.

Доступность: Unix, Windows.

Функция ограничена на WASI, см. платформы WebAssembly для получения дополнительной информации.

Изменено в версии 3.13: Добавлена поддержка в Windows.

os.fchown(fd, uid, gid)

Изменить владельца и группу файла, заданного fd, на числовые uid и gid. Чтобы оставить одно из идентификаторов неизменным, установите его в -1. См. chown(). Начиная с Python 3.3, это эквивалентно os.chown(fd, uid, gid).

Вызывает событие аудита аудита os.chown с аргументами path, uid, gid, dir_fd.

Доступность: Unix.

Функция ограничена на WASI, см. платформы WebAssembly для получения дополнительной информации.

os.fdatasync(fd)

Принудительно записывает файл с дескриптором fd на диск. Не принуждает к обновлению метаданных.

Доступность: Unix.

Примечание

Эта функция недоступна в MacOS.

os.fpathconf(fd, name, /)

Возвращает системную конфигурационную информацию, относящуюся к открытому файлу. name задаёт конфигурационное значение для извлечения; это может быть строка, являющаяся именем определённого системного значения; эти имена указаны в ряде стандартов (POSIX.1, Unix 95, Unix 98 и других). Некоторые платформы также определяют дополнительные имена. Известные имена операционной системы указаны в словаре pathconf_names. Для конфигурационных переменных, не включённых в это отображение, в качестве name также может быть передано целое число.

Если name является строкой и не найдено, то генерируется исключение ValueError. Если конкретное значение для name не поддерживается системной платформой, даже если оно включено в pathconf_names, генерируется OSError с кодом ошибки errno.EINVAL.

Начиная с Python 3.3, это эквивалентно os.pathconf(fd, name).

Доступность: Unix.

os.fstat(fd)

Получить состояние дескриптора файла fd. Возвращает объект stat_result.

Начиная с Python 3.3, это эквивалентно os.stat(fd).

См. также

Функцию stat().

os.fstatvfs(fd, /)

Возвращает информацию о файловой системе, содержащей файл, связанный с дескриптором файла fd, подобно statvfs(). Начиная с Python 3.3, это эквивалентно os.statvfs(fd).

Доступность: Unix.

os.fsync(fd)

Принудительная запись файла с дескриптором fd на диск. В Unix это вызывает функцию fsync(); в Windows — функцию MS _commit().

Если вы начинаете с буферизованного Python-объекта файла f, сначала выполните f.flush(), а затем os.fsync(f.fileno()), чтобы убедиться, что все внутренние буферы, связанные с f, записаны на диск.

Доступность: Unix, Windows.

os.ftruncate(fd, length, /)

Усечение файла, соответствующего дескриптору файла fd, так, чтобы его размер был не больше length байт. Начиная с Python 3.3, это эквивалентно os.truncate(fd, length).

Вызывает событие аудита os.truncate с аргументами fd, length.

Доступность: Unix, Windows.

Изменено в версии 3.5: Добавлена поддержка Windows

os.get_blocking(fd, /)

Получить режим блокировки дескриптора файла: False если установлен флаг O_NONBLOCK, True если флаг сброшен.

См. также set_blocking() и socket.socket.setblocking().

Доступность: Unix, Windows.

Функция ограничена на WASI, см. WebAssembly-платформы для получения дополнительной информации.

В Windows функция ограничена каналами.

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

Изменено в версии 3.12: Добавлена поддержка каналов в Windows.

os.grantpt(fd, /)

Предоставить доступ к устройству-рабу псевдотерминала, связанному с устройством-мастером псевдотерминала, которому относится дескриптор файла fd. Дескриптор файла fd не закрывается при ошибке.

Вызывает функцию стандартной библиотеки C grantpt().

Доступность: Unix, не WASI.

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

os.isatty(fd, /)

Возвращает True если дескриптор файла fd открыт и подключен к устройству tty(-подобному), иначе False.

os.lockf(fd, cmd, len, /)

Применить, проверить или снять POSIX-блокировку на открытом дескрипторе файла. fd — открытый дескриптор файла. cmd определяет команду — один из F_LOCK, F_TLOCK, F_ULOCK или F_TEST. len определяет часть файла для блокировки.

Вызывает событие аудита os.lockf с аргументами fd, cmd, len.

Доступность: Unix.

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

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

Флаги, определяющие действие lockf().

Доступность: Unix.

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

os.login_tty(fd, /)

Подготовить tty, для которого fd является дескриптором файла, для новой сессии входа в систему. Сделать вызывающий процесс лидером сессии; сделать tty управляющим tty, stdin, stdout и stderr вызывающего процесса; закрыть fd.

Доступность: Unix, не WASI.

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

os.lseek(fd, pos, whence, /)

Установить текущую позицию дескриптора файла fd на позицию pos, модифицированную whence, и вернуть новую позицию в байтах, относительно начала файла. Допустимые значения для whence:

• SEEK_SET или 0 — установить pos относительно начала файла
• SEEK_CUR или 1 — установить pos относительно текущей позиции файла
• SEEK_END или 2 — установить pos относительно конца файла
• SEEK_HOLE — установить pos на следующее место данных, относительно pos
• SEEK_DATA — установить pos на следующее пустое место, относительно pos

Изменено в версии 3.3: Добавлена поддержка SEEK_HOLE и SEEK_DATA.

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

Параметры функции lseek() и метода seek() для объекта file-like, для установки показателя позиции файла.

SEEK_SET

Настройка позиции файла относительно начала файла.

SEEK_CUR

Настройка позиции файла относительно текущей позиции файла.

SEEK_END

Настройка позиции файла относительно конца файла.

Их значения соответственно 0, 1 и 2.

os.SEEK_HOLE

os.SEEK_DATA

Параметры функции lseek() и метода seek() для объектов типа «файл» для поиска данных и дыр в разреженных файлах.

SEEK_DATA

Настройка смещения файла на следующее местоположение, содержащее данные, относительно позиции поиска.

SEEK_HOLE

Настройка смещения файла на следующее местоположение, содержащее дыру, относительно позиции поиска. Дыра определяется как последовательность нулей.

Примечание

Эти операции имеют смысл только для файловых систем, которые их поддерживают.

Доступность: Linux >= 3.1, macOS, Unix

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

os.open(path, flags, mode=0o777, *, dir_fd=None)

Открывает файл path и устанавливает различные флаги в соответствии с flags, а также, возможно, режим в соответствии с mode. При вычислении mode сначала вычитается текущее значение umask. Возвращает дескриптор файла для вновь открытого файла. Новый дескриптор файла не наследуется.

Описание значений флагов и режимов см. в документации C-среды выполнения; константы флагов (например, O_RDONLY и O_WRONLY) определены в модуле os. В частности, в Windows для открытия файлов в двоичном режиме необходимо добавить O_BINARY.

Эта функция может поддерживать пути, относящиеся к дескрипторам каталогов с параметром dir_fd.

Вызывает событие аудита аудита open с аргументами path, mode, flags.

Изменено в версии 3.4: Новый дескриптор файла теперь не наследуется.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода. Для обычного использования используйте встроенную функцию open(), которая возвращает объект типа «файл» с методами read() и write() (и многими другими). Чтобы обернуть дескриптор файла в объект типа «файл», используйте fdopen().

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.5: Если системный вызов прерывается, а обработчик сигнала не вызывает исключение, функция теперь повторно пытается выполнить системный вызов вместо повышения исключения InterruptedError (см. PEP 475 для обоснования).

Изменено в версии 3.6: Принимает объект типа «путь».

Следующие константы являются вариантами для параметра flags функции open(). Их можно объединить с помощью побитового оператора OR |. Некоторые из них недоступны на всех платформах. Для описания их доступности и использования обратитесь к справочной странице open(2) в Unix или к MSDN в Windows.

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

Вышеперечисленные константы доступны в Unix и Windows.

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

Вышеперечисленные константы доступны только в Unix.

Изменено в версии 3.3: Добавлена константа O_CLOEXEC.

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

Вышеперечисленные константы доступны только в Windows.

os.O_EVTONLY

os.O_FSYNC

os.O_SYMLINK

os.O_NOFOLLOW_ANY

Вышеперечисленные константы доступны только в macOS.

Изменено в версии 3.10: Добавлены константы O_EVTONLY, O_FSYNC, O_SYMLINK и O_NOFOLLOW_ANY.

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

Вышеперечисленные константы являются расширениями и не присутствуют, если они не определены в библиотеке C.

Изменено в версии 3.4: Добавлена O_PATH на системах, которые её поддерживают. Добавлена O_TMPFILE, доступная только в ядре Linux 3.11 и новее.

os.openpty()

Открывает новую пару псевдотерминалов. Возвращает пару дескрипторов файлов (master, slave) для pty и tty соответственно. Новые дескрипторы файлов не наследуются. Для (немного) более портативного подхода используйте модуль pty.

Доступность: Unix, не WASI.

Изменено в версии 3.4: Новые дескрипторы файлов теперь не наследуются.

os.pipe()

Создаёт канал. Возвращает пару дескрипторов файлов (r, w) для чтения и записи соответственно. Новый дескриптор файла не наследуется.

Доступность: Unix, Windows.

Изменено в версии 3.4: Новые дескрипторы файлов теперь не наследуются.

os.pipe2(flags, /)

Создаёт канал с атомарно установленным флагом flags. flags может быть сформирован путём побитового объединения одного или нескольких значений: O_NONBLOCK, O_CLOEXEC. Возвращает пару дескрипторов файлов (r, w) для чтения и записи соответственно.

Доступность: Unix, не WASI.

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

os.posix_fallocate(fd, offset, len, /)

Обеспечивает выделение достаточного дискового пространства для файла, указанного дескриптором fd, начиная с позиции offset и продолжая на len байт.

Доступность: Unix.

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

os.posix_fadvise(fd, offset, len, advice, /)

Объявляет намерение доступа к данным в определённом шаблоне, что позволяет ядру выполнять оптимизации. Рекомендация применяется к области файла, указанной дескриптором fd, начиная с позиции offset и продолжая на len байт. advice - одно из значений POSIX_FADV_NORMAL, POSIX_FADV_SEQUENTIAL, POSIX_FADV_RANDOM, POSIX_FADV_NOREUSE, POSIX_FADV_WILLNEED или POSIX_FADV_DONTNEED.

Доступность: Unix.

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

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

Флаги, которые могут быть использованы в advice в posix_fadvise(), указывающие на предполагаемый шаблон доступа.

Доступность: Unix.

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

os.pread(fd, n, offset, /)

Считывает не более n байт из дескриптора файла fd по позиции offset, не изменяя текущую позицию файла.

Возвращает байтовую строку, содержащую прочитанные байты. Если достигнут конец файла, возвращается пустой байтовый объект.

Доступность: Unix.

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

os.posix_openpt(oflag, /)

Открывает и возвращает дескриптор файла для устройства виртуального терминала (master).

Вызывает функцию C-библиотеки posix_openpt(). Аргумент oflag используется для установки флагов состояния файла и режимов доступа, как указано в руководстве по posix_openpt() вашей системы.

Возвращённый дескриптор файла не наследуется. Если на системе доступно значение O_CLOEXEC, оно добавляется к oflag.

Доступность: Unix, не WASI.

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

os.preadv(fd, buffers, offset, flags=0, /)

Считывает данные из дескриптора файла fd по позиции offset в изменяемые байтовые объекты buffers, не изменяя текущую позицию файла. Данные передаются в каждый буфер до заполнения, а затем переходят к следующему буферу для хранения оставшихся данных.

Аргумент flags содержит побитовое объединение нуля или более следующих флагов:

• RWF_HIPRI
• RWF_NOWAIT

Возвращает общее количество фактически считанных байт, которое может быть меньше общей ёмкости всех объектов.

Операционная система может установить ограничение (sysconf() значение 'SC_IOV_MAX') на количество используемых буферов.

Объединяет функциональность os.readv() и os.pread().

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Использование флагов требует Linux >= 4.6.

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

os.RWF_NOWAIT

Не ожидать данных, которые не доступны немедленно. Если этот флаг задан, вызов системы возвращает результат мгновенно, если необходимо считать данные с носителя или ожидать блокировки.

Если некоторые данные были успешно прочитаны, возвращается количество прочитанных байт. Если байты не были прочитаны, возвращается -1 и устанавливается errno в errno.EAGAIN.

Доступность: Linux >= 4.14.

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

os.RWF_HIPRI

Высокий приоритет чтения/записи. Позволяет файловым системам на основе блоков использовать опросный режим устройства, что обеспечивает более низкую задержку, но может использовать дополнительные ресурсы.

В настоящее время в Linux эта функция доступна только для дескрипторов файлов, открытых с флагом O_DIRECT.

Доступность: Linux >= 4.6.

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

os.ptsname(fd, /)

Возвращает имя устройства slave виртуального терминала, связанного с устройством master виртуального терминала, к которому относится дескриптор файла fd. Дескриптор файла fd не закрывается при ошибке.

Вызывает рекурсивную функцию C-библиотеки ptsname_r() если она доступна; в противном случае, вызывает функцию C-библиотеки ptsname(), которая не гарантирует потокобезопасность.

Доступность: Unix, не WASI.

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

os.pwrite(fd, str, offset, /)

Записывает байтовую строку в str в дескриптор файла fd по позиции offset, не изменяя текущую позицию файла.

Возвращает количество фактически записанных байт.

Доступность: Unix.

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

os.pwritev(fd, buffers, offset, flags=0, /)

Записать содержимое buffers в дескриптор файла fd по смещению offset, не изменяя текущее смещение файла. buffers должно быть последовательностью объектов типа байтов. Буферы обрабатываются в порядке массива. Весь контент первого буфера записывается перед переходом ко второму и так далее.

Аргумент flags содержит битовую ИЛИ одного или нескольких следующих флагов:

• RWF_DSYNC
• RWF_SYNC
• RWF_APPEND

Возвращает общее количество записанных байтов.

Операционная система может установить ограничение (sysconf() значение 'SC_IOV_MAX') на количество используемых буферов.

Комбинирует функциональность os.writev() и os.pwrite().

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Использование флагов требует Linux >= 4.6.

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

os.RWF_DSYNC

Обеспечивает эквивалент флага O_DSYNC для каждой записи. Действие этого флага относится только к диапазону данных, записанных системным вызовом.

Доступность: Linux >= 4.7.

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

os.RWF_SYNC

Обеспечивает эквивалент флага O_SYNC для каждой записи. Действие этого флага относится только к диапазону данных, записанных системным вызовом.

Доступность: Linux >= 4.7.

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

os.RWF_APPEND

Обеспечивает эквивалент флага O_APPEND для каждой записи. Этот флаг имеет смысл только для os.pwritev(), и его действие относится только к диапазону данных, записанных системным вызовом. Аргумент offset не влияет на операцию записи; данные всегда добавляются в конец файла. Однако, если аргумент offset равен -1, текущее смещение файла обновляется.

Доступность: Linux >= 4.16.

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

os.read(fd, n, /)

Прочитать не более n байтов из дескриптора файла fd.

Возвращает строку байтов, содержащую прочитанные байты. Если достигнут конец файла, связанного с fd, возвращается пустой объект байтов.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода и должна применяться к дескриптору файла, возвращённому os.open() или pipe(). Для чтения «объекта файла», возвращенного встроенной функцией open() или popen() или fdopen(), или sys.stdin, используйте его методы read() или readline().

Изменено в версии 3.5: Если системный вызов прерывается, а обработчик сигнала не вызывает исключение, функция теперь повторно пытается выполнить системный вызов вместо того, чтобы генерировать исключение InterruptedError (см. PEP 475 для обоснования).

os.sendfile(out_fd, in_fd, offset, count)

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

Скопировать count байтов из дескриптора файла in_fd в дескриптор файла out_fd, начиная с offset. Возвращает количество отправленных байтов. При достижении EOF возвращает 0.

Первая форма записи поддерживается всеми платформами, которые определяют sendfile().

В Linux, если offset задано как None, байты читаются из текущей позиции in_fd, и позиция in_fd обновляется.

Вторая форма записи может быть использована на macOS и FreeBSD, где headers и trailers - произвольные последовательности буферов, которые записываются до и после данных из in_fd. Возвращает то же, что и в первом случае.

На macOS и FreeBSD, значение 0 для count указывает на отправку до достижения конца in_fd.

Все платформы поддерживают сокеты как дескрипторы файлов out_fd, а некоторые платформы также поддерживают другие типы (например, обычные файлы, каналы).

Приложений, работающих на нескольких платформах, не следует использовать аргументы headers, trailers и flags.

Доступность: Unix, не WASI.

Примечание

Для более высокого уровня обертки над sendfile(), см. socket.socket.sendfile().

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

Изменено в версии 3.9: Параметры out и in были переименованы в out_fd и in_fd.

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

Параметры для функции sendfile(), если их поддерживает реализация.

Доступность: Unix, не WASI.

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

os.SF_NOCACHE

Параметр для функции sendfile(), если его поддерживает реализация. Данные не будут кешироваться в виртуальной памяти и будут освобождены после этого.

Доступность: Unix, не WASI.

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

os.set_blocking(fd, blocking, /)

Установите режим блокировки для указанного дескриптора файла. Установите флаг O_NONBLOCK, если блокировка False, в противном случае снимите флаг.

См. также get_blocking() и socket.socket.setblocking().

Доступность: Unix, Windows.

Функция ограничена на WASI, см. Платформы WebAssembly для получения дополнительной информации.

В Windows эта функция ограничена каналами (pipes).

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

Изменено в версии 3.12: Добавлена поддержка каналов (pipes) в Windows.

os.splice(src, dst, count, offset_src=None, offset_dst=None)

Переместите count байтов из дескриптора файла src, начиная с смещения offset_src, в дескриптор файла dst, начиная со смещения offset_dst. По крайней мере, один из дескрипторов файлов должен ссылаться на канал (pipe). Если offset_src None, то src считывается из текущей позиции; соответственно для offset_dst. Смещение, связанное с дескриптором файла, который ссылается на канал (pipe), должно быть None. Файлы, на которые указывают src и dst, должны находиться в одной файловой системе, в противном случае возбуждается OSError с errno, установленным в errno.EXDEV.

Это копирование выполняется без дополнительных затрат на передачу данных из ядра в адресное пространство пользователя и обратно в ядро. Кроме того, некоторые файловые системы могут реализовывать дополнительные оптимизации. Копирование выполняется так, как если бы оба файла были открыты в двоичном режиме.

При успешном выполнении возвращает количество скопированных байтов в или из канала (pipe). Возвращаемое значение 0 означает конец входных данных. Если src ссылается на канал (pipe), это означает, что данных для передачи не было, и блокировка не имеет смысла, так как нет писателей, подключённых к выходному концу канала.

Доступность: Linux >= 2.6.17 с glibc >= 2.5

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

os.SPLICE_F_MOVE

os.SPLICE_F_NONBLOCK

os.SPLICE_F_MORE

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

os.readv(fd, buffers, /)

Считывание из дескриптора файла fd в ряд изменяемых объектов типа байты buffers. Данные передаются в каждый буфер до его заполнения, а затем переходят к следующему буферу в последовательности, чтобы сохранить остальную часть данных.

Возвращает общее количество реально прочитанных байтов, которое может быть меньше общей ёмкости всех объектов.

Операционная система может установить ограничение (sysconf() значение 'SC_IOV_MAX') на количество используемых буферов.

Доступность: Unix.

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

os.tcgetpgrp(fd, /)

Возвращает группу процессов, связанную с терминалом, заданным fd (открытым дескриптором файла, возвращаемым os.open()).

Доступность: Unix, не WASI.

os.tcsetpgrp(fd, pg, /)

Устанавливает группу процессов, связанную с терминалом, заданным fd (открытым дескриптором файла, возвращаемым os.open()), на pg.

Доступность: Unix, не WASI.

os.ttyname(fd, /)

Возвращает строку, которая определяет терминальное устройство, связанное с дескриптором файла fd. Если fd не связан с терминальным устройством, генерируется исключение.

Доступность: Unix.

os.unlockpt(fd, /)

Разблокировать подчиненное псевдотерминальное устройство, связанное с мастером псевдотерминального устройства, которому принадлежит дескриптор файла fd. Дескриптор файла fd не закрывается при ошибке.

Вызывает функцию стандартной библиотеки C unlockpt().

Доступность: Unix, не WASI.

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

os.write(fd, str, /)

Записать строку байтов в str в дескриптор файла fd.

Возвращает количество фактически записанных байтов.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода и должна применяться к дескриптору файла, как возвращаемого os.open() или pipe(). Чтобы записать в “объект файла”, возвращаемый встроенной функцией open() или popen() или fdopen(), или sys.stdout или sys.stderr, используйте его метод write().

Изменено в версии 3.5: Если системный вызов прерван, а обработчик сигнала не вызывает исключение, функция теперь повторно пытается выполнить системный вызов вместо поднятия исключения InterruptedError (см. PEP 475 для обоснования).

os.writev(fd, buffers, /)

Запись содержимого buffers в дескриптор файла fd. buffers должен быть последовательностью объектов типа байты. Буферы обрабатываются в порядке массива. Весь контент первого буфера записывается перед переходом ко второму и так далее.

Возвращает общее количество фактически записанных байтов.

Операционная система может установить ограничение (sysconf() значение 'SC_IOV_MAX') на количество используемых буферов.

Доступность: Unix.

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

Файлы и каталоги

На некоторых платформах Unix многие из этих функций поддерживают один или несколько из этих параметров:

• указание дескриптора файла: Обычно аргумент path, передаваемый функциям модуля os, должен быть строкой, указывающей путь к файлу. Однако некоторые функции теперь в качестве альтернативы принимают открытый дескриптор файла в качестве аргумента path. Функция затем будет работать с файлом, на который ссылается дескриптор. (Для систем POSIX Python будет вызывать вариант функции с префиксом f (например, вызывать fchdir вместо chdir).)

  Вы можете проверить, поддерживается ли для конкретной функции на вашей платформе указание path в виде дескриптора файла, используя os.supports_fd. Если эта функциональность недоступна, её использование вызовет NotImplementedError.

  Если функция также поддерживает аргументы dir_fd или follow_symlinks, использование одного из них при указании path в качестве дескриптора файла является ошибкой.

• пути, относительные к дескрипторам каталогов: Если dir_fd не None, он должен быть дескриптором файла, относящимся к каталогу, а путь для обработки должен быть относительным; путь затем будет относительным к этому каталогу. Если путь абсолютный, dir_fd игнорируется. (Для систем POSIX Python будет вызывать вариант функции с суффиксом at и, возможно, префиксом f (например, вызывать faccessat вместо access).)

  Вы можете проверить, поддерживается ли для конкретной функции на вашей платформе dir_fd, используя os.supports_dir_fd. Если она недоступна, её использование вызовет NotImplementedError.

• не следовать символичным ссылкам: Если follow_symlinks равно False, и последний элемент пути для обработки является символичной ссылкой, функция будет работать с самой символичной ссылкой, а не с файлом, на который она указывает. (Для систем POSIX Python вызовет вариант функции l....)

  Вы можете проверить, поддерживается ли для конкретной функции на вашей платформе follow_symlinks, используя os.supports_follow_symlinks. Если она недоступна, её использование вызовет NotImplementedError.

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

Использует реальный uid/gid для проверки доступа к path. Обратите внимание, что большинство операций используют эффективный uid/gid, поэтому эта функция может использоваться в среде suid/sgid для проверки, имеет ли вызывающий пользователь указанный доступ к path. mode должен быть F_OK для проверки существования path, или он может быть результатом логического ИЛИ одного или нескольких значений R_OK, W_OK и X_OK для проверки разрешений. Возвращает True, если доступ разрешён, False — если нет. См. страницу руководства Unix access(2) для получения дополнительной информации.

Эта функция может поддерживать указание путей, относительных к дескрипторам каталогов и не следовать символичным ссылкам.

Если effective_ids равно True, access() будет выполнять проверки доступа, используя эффективный uid/gid вместо реального uid/gid. effective_ids может не поддерживаться на вашей платформе; вы можете проверить, доступен ли он, используя os.supports_effective_ids. Если он недоступен, его использование вызовет NotImplementedError.

Примечание

Использование access() для проверки авторизации пользователя, например, для открытия файла до его фактического открытия с помощью open(), создаёт уязвимость безопасности, так как пользователь может воспользоваться коротким промежутком времени между проверкой и открытием файла для его изменения. Лучше использовать техники EAFP. Например:

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

Лучше записать так:

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

Примечание

Операции ввода-вывода могут завершиться неудачей даже в том случае, когда access() указывает, что они будут успешны, особенно для операций с сетевыми файловыми системами, которые могут иметь семантику разрешений, выходящую за рамки обычной модели битов разрешений POSIX.

Изменено в версии 3.3: Добавлены параметры dir_fd, effective_ids и follow_symlinks.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.F_OK

os.R_OK

os.W_OK

os.X_OK

Значения для передачи в качестве параметра mode функции access() для проверки существования, возможности чтения, записи и выполнения path, соответственно.

os.chdir(path)

Изменить текущую рабочую директорию на path.

Эта функция может поддерживать указание дескриптора файла. Дескриптор должен ссылаться на открытый каталог, а не на открытый файл.

Эта функция может вызывать OSError и его подклассы, такие как FileNotFoundError, PermissionError и NotADirectoryError.

Вызывает событие аудита os.chdir с аргументом path.

Изменено в версии 3.3: Добавлена поддержка указания path в виде дескриптора файла на некоторых платформах.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.chflags(path, flags, *, follow_symlinks=True)

Установите флаги пути path в числовое значение flags. flags может принимать комбинацию (побитовое ИЛИ) следующих значений (как определено в модуле stat):

• stat.UF_NODUMP
• stat.UF_IMMUTABLE
• stat.UF_APPEND
• stat.UF_OPAQUE
• stat.UF_NOUNLINK
• stat.UF_COMPRESSED
• stat.UF_HIDDEN
• stat.SF_ARCHIVED
• stat.SF_IMMUTABLE
• stat.SF_APPEND
• stat.SF_NOUNLINK
• stat.SF_SNAPSHOT

Эта функция может поддерживать неследование символических ссылок.

Вызывает событие аудита аудита os.chflags с аргументами path, flags.

Доступность: Unix, не WASI.

Изменено в версии 3.3: Добавлен параметр follow_symlinks.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

Изменить режим пути path на числовое значение mode. mode может принимать одно из следующих значений (как определено в модуле stat) или их побитовое ИЛИ:

• stat.S_ISUID
• stat.S_ISGID
• stat.S_ENFMT
• stat.S_ISVTX
• stat.S_IREAD
• stat.S_IWRITE
• stat.S_IEXEC
• stat.S_IRWXU
• stat.S_IRUSR
• stat.S_IWUSR
• stat.S_IXUSR
• stat.S_IRWXG
• stat.S_IRGRP
• stat.S_IWGRP
• stat.S_IXGRP
• stat.S_IRWXO
• stat.S_IROTH
• stat.S_IWOTH
• stat.S_IXOTH

Эта функция может поддерживать указание дескриптора файла, пути, относительные к дескрипторам каталогов и неследование символических ссылок.

Примечание

Хотя Windows поддерживает chmod(), вы можете установить только флаг только для чтения файла с его помощью (через stat.S_IWRITE и stat.S_IREAD константы или соответствующее целое значение). Все остальные биты игнорируются. Значение по умолчанию для follow_symlinks равно False в Windows.

Функция ограничена на WASI, см. Платформы WebAssembly для получения дополнительной информации.

Вызывает событие аудита аудита os.chmod с аргументами path, mode, dir_fd.

Изменено в версии 3.3: Добавлена поддержка указания пути path как открытого дескриптора файла и аргументов dir_fd и follow_symlinks.

Изменено в версии 3.6: Принимает объект, подобный пути.

Изменено в версии 3.13: Добавлена поддержка дескриптора файла и аргумента follow_symlinks в Windows.

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

Изменить владельца и группу пути path на числовые значения uid и gid. Чтобы оставить одно из идентификаторов неизменным, установите его в -1.

Эта функция может поддерживать указание дескриптора файла, пути, относительные к дескрипторам каталогов и неследование символических ссылок.

См. shutil.chown() для функции более высокого уровня, которая принимает имена помимо числовых идентификаторов.

Вызывает событие аудита аудита os.chown с аргументами path, uid, gid, dir_fd.

Доступность: Unix.

Функция ограничена на WASI, см. Платформы WebAssembly для получения дополнительной информации.

Изменено в версии 3.3: Добавлена поддержка указания пути path как открытого дескриптора файла и аргументов dir_fd и follow_symlinks.

Изменено в версии 3.6: Поддерживает объект, подобный пути.

os.chroot(path)

Изменить корневой каталог текущего процесса на path.

Доступность: Unix, не WASI, не Android.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.fchdir(fd)

Изменить текущий рабочий каталог на каталог, представленный дескриптором файла fd. Дескриптор должен ссылаться на открытый каталог, а не на открытый файл. Начиная с Python 3.3, это эквивалентно os.chdir(fd).

Вызывает событие аудита аудита os.chdir с аргументом path.

Доступность: Unix.

os.getcwd()

Возвращает строку, представляющую текущий рабочий каталог.

os.getcwdb()

Возвращает строку байтов, представляющую текущую рабочую директорию.

Изменено в версии 3.8: Функция теперь использует кодировку UTF-8 в Windows вместо кодовой страницы ANSI: см. PEP 529 для обоснования. Функция больше не устарела в Windows.

os.lchflags(path, flags)

Устанавливает флаги path на числовые flags, как в chflags(), но не следует символичным ссылкам. С Python 3.3, это эквивалентно os.chflags(path, flags, follow_symlinks=False).

Вызывает событие аудита os.chflags с аргументами path, flags.

Доступность: Unix, не WASI.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.lchmod(path, mode)

Изменяет режим path на числовое значение mode. Если path — символическая ссылка, это влияет на символическую ссылку, а не на целевой объект. См. документацию для chmod() для возможных значений mode. С Python 3.3, это эквивалентно os.chmod(path, mode, follow_symlinks=False).

lchmod() не является частью POSIX, но реализации Unix могут его иметь, если изменение режима символических ссылок поддерживается.

Вызывает событие аудита os.chmod с аргументами path, mode, dir_fd.

Доступность: Unix, Windows, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

Изменено в версии 3.6: Принимает объект, подобный пути.

Изменено в версии 3.13: Добавлена поддержка в Windows.

os.lchown(path, uid, gid)

Изменяет владельца и группу path на числовые uid и gid. Эта функция не будет следовать символическим ссылкам. С Python 3.3, это эквивалентно os.chown(path, uid, gid, follow_symlinks=False).

Вызывает событие аудита os.chown с аргументами path, uid, gid, dir_fd.

Доступность: Unix.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

Создает жёсткую ссылку на src с именем dst.

Эта функция может поддерживать указание src_dir_fd и/или dst_dir_fd для предоставления путей, относительных к дескрипторам каталогов, и не следования символическим ссылкам.

Вызывает событие аудита os.link с аргументами src, dst, src_dir_fd, dst_dir_fd.

Доступность: Unix, Windows.

Изменено в версии 3.2: Добавлена поддержка Windows.

Изменено в версии 3.3: Добавлены параметры src_dir_fd, dst_dir_fd и follow_symlinks.

Изменено в версии 3.6: Принимает объект, подобный пути для src и dst.

os.listdir(path='.')

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

path может быть объектом, подобным пути. Если path имеет тип bytes (прямо или косвенно через интерфейс PathLike), имена файлов, возвращаемые, также будут типа bytes; во всех других случаях они будут типа str.

Эта функция также может поддерживать указание дескриптора файла; дескриптор файла должен ссылаться на каталог.

Вызывает событие аудита os.listdir с аргументом path.

Примечание

Для кодирования str имён файлов в bytes, используйте fsencode().

См. также

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

Изменено в версии 3.2: Параметр path стал необязательным.

Изменено в версии 3.3: Добавлена поддержка указания path в виде открытого дескриптора файла.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.listdrives()

Возвращает список, содержащий имена дисков в системе Windows.

Имя диска обычно выглядит как 'C:\\'. Не каждое имя диска будет ассоциировано с томом, и некоторые могут быть недоступны по разным причинам, включая права доступа, сетевое подключение или отсутствие носителя. Эта функция не проверяет доступ.

Может вызвать OSError, если произошла ошибка при сборе имён дисков.

Вызывает событие аудита os.listdrives без аргументов.

Доступность: Windows

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

os.listmounts(volume)

Возвращает список, содержащий точки монтирования для тома в системе Windows.

volume должен быть представлен путём GUID, подобным тем, что возвращаются os.listvolumes(). Тома могут быть смонтированы в нескольких местах или вообще не смонтированы. В последнем случае список будет пустым. Точки монтирования, которые не связаны с томом, не будут возвращены этой функцией.

Точки монтирования, возвращаемые этой функцией, будут абсолютными путями и могут быть длиннее имени диска.

Вызывает OSError, если том не распознаётся или при сборе путей произошла ошибка.

Вызывает событие аудита os.listmounts с аргументом volume.

Доступность: Windows

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

os.listvolumes()

Возвращает список томов в системе.

Тома обычно представлены путём GUID, который выглядит как \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\. К файлам обычно можно получить доступ через путь GUID, при наличии разрешений. Однако пользователи обычно с ними не знакомы, поэтому рекомендуется использовать эту функцию для получения точек монтирования с помощью os.listmounts().

Может вызвать OSError, если при сборе томов произошла ошибка.

Вызывает событие аудита auditing event os.listvolumes без аргументов.

Доступность: Windows

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

os.lstat(path, *, dir_fd=None)

Выполняет эквивалентную операцию системного вызова lstat() для данного пути. Аналогично stat(), но не следует за символическими ссылками. Возвращает объект stat_result.

На платформах, не поддерживающих символические ссылки, это псевдоним для stat().

Начиная с Python 3.3, это эквивалентно os.stat(path, dir_fd=dir_fd, follow_symlinks=False).

Эта функция также может поддерживать пути, относительные к дескрипторам каталогов.

См. также

Функция stat().

Изменено в версии 3.2: Добавлена поддержка символических ссылок Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.8: В Windows теперь открываются точки переадресации, представляющие другой путь (заместители имен), включая символические ссылки и узлы соединения каталогов. Другие типы точек переадресации обрабатываются операционной системой так же, как и для stat().

os.mkdir(path, mode=0o777, *, dir_fd=None)

Создаёт каталог с именем path с числовым режимом mode.

Если каталог уже существует, генерируется исключение FileExistsError. Если родительский каталог в пути не существует, генерируется исключение FileNotFoundError.

На некоторых системах mode игнорируется. Где используется, сначала применяется текущее значение umask. Если установлены биты, отличные от последних 9 (то есть последних 3 цифр в восьмеричном представлении mode), их значение зависит от платформы. На некоторых платформах они игнорируются, и вы должны явно вызвать chmod() для их установки.

В Windows режим mode 0o700 обрабатывается специально, чтобы применить управление доступом к новому каталогу таким образом, чтобы доступ имели только текущий пользователь и администраторы. Другие значения mode игнорируются.

Эта функция также может поддерживать пути, относительные к дескрипторам каталогов.

Также можно создавать временные каталоги; см. модуль tempfile и функцию tempfile.mkdtemp().

Вызывает событие аудита auditing event os.mkdir с аргументами path, mode, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.13: В Windows теперь обрабатывается режим mode 0o700.

os.makedirs(name, mode=0o777, exist_ok=False)

Функция рекурсивного создания каталогов. Подобно mkdir(), но создаёт все промежуточные каталоги, необходимые для создания целевого.

Параметр mode передаётся в mkdir() для создания целевого каталога; см. описание mkdir() для его интерпретации. Чтобы установить биты разрешений файлов для любых вновь созданных родительских каталогов, можно установить umask перед вызовом makedirs(). Бит разрешений существующих родительских каталогов не изменяются.

Если exist_ok равно False (по умолчанию), исключение FileExistsError генерируется, если целевой каталог уже существует.

Примечание

makedirs() может сработать некорректно, если элементы пути для создания включают pardir (например, “..” в системах Unix).

Функция правильно обрабатывает пути UNC.

Вызывает событие аудита auditing event os.mkdir с аргументами path, mode, dir_fd.

Изменено в версии 3.2: Добавлен параметр exist_ok.

Изменено в версии 3.4.1: До Python 3.4.1, если exist_ok было True и каталог уже существовал, makedirs() по-прежнему генерировало бы ошибку, если mode не соответствовал режиму существующего каталога. Поскольку это поведение было невозможно безопасно реализовать, оно было удалено в Python 3.4.1. См. bpo-21082.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.7: Аргумент mode больше не влияет на биты разрешений файлов вновь созданных промежуточных каталогов.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

Создаёт FIFO (именованную трубу) с именем path с числовым режимом mode. Текущее значение umask сначала маскируется из режима.

Эта функция также может поддерживать пути, относительные к дескрипторам каталогов.

FIFO — это трубы, к которым можно получить доступ как к обычным файлам. FIFO существует до тех пор, пока они не будут удалены (например, с помощью os.unlink()). Обычно FIFOs используются в качестве точки встречи между процессами типа «клиент» и «сервер»: сервер открывает FIFO для чтения, а клиент открывает его для записи. Обратите внимание, что mkfifo() не открывает FIFO — он просто создаёт точку встречи.

Доступность: Unix, не WASI.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект-путь.

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

Создать файловый узел (файл, специальный файл устройства или именованную трубу) с именем path. mode определяет как права доступа, так и тип создаваемого узла, комбинируясь (побитовое ИЛИ) с одним из stat.S_IFREG, stat.S_IFCHR, stat.S_IFBLK, и stat.S_IFIFO (эти константы доступны в stat). Для stat.S_IFCHR и stat.S_IFBLK, device определяет создаваемый специальный файл устройства (вероятно, используя os.makedev()), в противном случае он игнорируется.

Эта функция также может поддерживать пути, относительные к дескрипторам каталогов.

Доступность: Unix, не WASI.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.major(device, /)

Извлечь номер устройства (major) из номера сырого устройства (обычно поле st_dev или st_rdev из stat).

os.minor(device, /)

Извлечь номер устройства (minor) из номера сырого устройства (обычно поле st_dev или st_rdev из stat).

os.makedev(major, minor, /)

Собрать номер сырого устройства из номеров устройства (major) и (minor).

os.pathconf(path, name)

Возвращает информацию о конфигурации системы, относящуюся к именованному файлу. name указывает конфигурационное значение для извлечения; это может быть строка, являющаяся именем определённого системного значения; эти имена указаны в ряде стандартов (POSIX.1, Unix 95, Unix 98 и другие). Некоторые платформы также определяют дополнительные имена. Известные имена хост-операционной системы указаны в словаре pathconf_names. Для конфигурационных переменных, не включённых в это отображение, для name также принимается целое число.

Если name является строкой и не известен, генерируется ValueError. Если конкретное значение для name не поддерживается хост-системой, даже если оно включено в pathconf_names, генерируется OSError с errno.EINVAL в качестве номера ошибки.

Эта функция может поддерживать указание дескриптора файла.

Доступность: Unix.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.pathconf_names

Словарь, сопоставляющий имена, принятые pathconf() и fpathconf(), с целочисленными значениями, определенными для этих имен хост-операционной системой. Это можно использовать для определения набора имен, известных системе.

Доступность: Unix.

os.readlink(path, *, dir_fd=None)

Возвращает строку, представляющую путь, на который указывает символическая ссылка. Результат может быть либо абсолютным, либо относительным именем пути; если оно относительное, его можно преобразовать в абсолютное имя пути, используя os.path.join(os.path.dirname(path), result).

Если path — объект типа строка (прямо или косвенно через интерфейс PathLike), результат также будет объектом типа строка, и вызов может вызвать UnicodeDecodeError. Если path — объект типа байты (прямой или косвенный), результат будет объектом типа байты.

Эта функция также может поддерживать пути, относительные к дескрипторам каталогов.

При попытке разрешить путь, который может содержать ссылки, используйте realpath() для правильной обработки рекурсии и различий между платформами.

Доступность: Unix, Windows.

Изменено в версии 3.2: Добавлена поддержка символических ссылок Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект, подобный пути на Unix.

Изменено в версии 3.8: Принимает объект, подобный пути и объект типа байты на Windows.

Добавлена поддержка соединений каталогов, и изменено на возвращение пути замены (который обычно включает префикс \\?\), а не необязательное поле «имя для печати», которое возвращалось ранее.

os.remove(path, *, dir_fd=None)

Удалить (стереть) файл path. Если path — каталог, генерируется OSError. Используйте rmdir() для удаления каталогов. Если файл не существует, генерируется FileNotFoundError.

Эта функция может поддерживать пути, относительные к дескрипторам каталогов.

В Windows, при попытке удалить файл, который используется, генерируется исключение; в Unix, запись в каталоге удаляется, но выделенное хранилище для файла не становится доступным, пока исходный файл не перестанет использоваться.

Эта функция семантически идентична unlink().

Вызывает событие аудита аудита os.remove с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.removedirs(name)

Рекурсивно удаляет каталоги. Работает подобно rmdir(), за исключением того, что если лист каталога удаляется успешно, removedirs() пытается последовательно удалить каждый родительский каталог, упомянутый в path, до тех пор, пока не будет генерировано исключение (которое игнорируется, поскольку это обычно означает, что родительский каталог не пустой). Например, os.removedirs('foo/bar/baz') сначала удалит каталог 'foo/bar/baz', а затем удалит 'foo/bar' и 'foo', если они пустые. Генерирует OSError, если лист каталога не удалось удалить успешно.

Вызывает событие аудита аудита os.remove с аргументами path, dir_fd.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Переименовать файл или директорию src в dst. Если dst существует, операция завершится ошибкой с подклассом OSError в ряде случаев:

В Windows, если dst существует, всегда будет поднята ошибка FileExistsError. Операция может завершиться ошибкой, если src и dst находятся на разных файловых системах. Используйте shutil.move() для поддержки перемещений между разными файловыми системами.

В Unix, если src — файл, а dst — директория, или наоборот, будет поднята ошибка IsADirectoryError или NotADirectoryError соответственно. Если оба — директории, и dst пуста, dst будет молча заменена. Если dst — непустая директория, будет поднята ошибка OSError. Если оба — файлы, dst будет молча заменена, если у пользователя есть соответствующие права. Операция может завершиться ошибкой на некоторых Unix-системах, если src и dst находятся на разных файловых системах. При успешном выполнении переименование будет атомарной операцией (требование POSIX).

Эта функция может поддерживать указание src_dir_fd и/или dst_dir_fd для задания путей, относительных к дескрипторам каталогов.

Если вы хотите переписывать назначения в кроссплатформенном режиме, используйте replace().

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Изменено в версии 3.3: Добавлены параметры src_dir_fd и dst_dir_fd.

Изменено в версии 3.6: Принимает объект пути для src и dst.

os.renames(old, new)

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

Примечание

Эта функция может завершиться ошибкой, если у вас недостаточно прав для удаления листовой директории или файла.

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Изменено в версии 3.6: Принимает объект пути для old и new.

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Переименовать файл или директорию src в dst. Если dst является непустой директорией, будет поднята ошибка OSError. Если dst существует и является файлом, он будет молча заменен, если у пользователя есть необходимые права. Операция может завершиться ошибкой, если src и dst находятся на разных файловых системах. При успешном выполнении переименование будет атомарной операцией (требование POSIX).

Эта функция может поддерживать указание src_dir_fd и/или dst_dir_fd для задания путей, относительных к дескрипторам каталогов.

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

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

Изменено в версии 3.6: Принимает объект пути для src и dst.

os.rmdir(path, *, dir_fd=None)

Удалить (стереть) директорию path. Если директория не существует или не пуста, будет поднята ошибка FileNotFoundError или OSError соответственно. Для удаления целых древовидных структур директорий можно использовать shutil.rmtree().

Эта функция может поддерживать пути, относительные к дескрипторам каталогов.

Вызывает событие аудита os.rmdir с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект пути.

os.scandir(path='.')

Возвращает итератор объектов os.DirEntry, соответствующих записям в каталоге, заданном параметром path. Записи возвращаются в произвольном порядке, и специальные записи '.' и '..' не включаются. Если файл удаляется или добавляется в каталог после создания итератора, включение записи о нём не гарантируется.

Использование scandir() вместо listdir() может значительно повысить производительность кода, которому также необходимы информация о типе файла или атрибутах файла, потому что объекты os.DirEntry предоставляют эту информацию, если операционная система предоставляет её при сканировании каталога. Все методы объектов os.DirEntry могут выполнять системный вызов, но is_dir() и is_file() обычно требуют системного вызова только для символических ссылок; os.DirEntry.stat() всегда требует системного вызова в Unix, но только для символических ссылок в Windows.

path может быть объектом-путем. Если path имеет тип bytes (прямо или косвенно через интерфейс PathLike), тип атрибутов name и path каждого объекта os.DirEntry будет bytes; во всех остальных случаях — str.

Эта функция также может поддерживать указание дескриптора файла; дескриптор файла должен ссылаться на каталог.

Вызывает событие аудита os.scandir с аргументом path.

Итератор scandir() поддерживает протокол менеджера контекста и имеет следующий метод:

scandir.close()

Закрывает итератор и освобождает выделенные ресурсы.

Этот метод вызывается автоматически при исчерпании итератора, при его удалении сборщиком мусора или при ошибке во время итерации. Однако рекомендуется вызывать его явно или использовать оператор with.

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

Следующий пример демонстрирует простое использование scandir() для отображения всех файлов (исключая каталоги) в заданном path, не начинающихся с '.'. Вызов entry.is_file() обычно не выполняет дополнительного системного вызова:

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

Примечание

В системах на основе Unix scandir() использует системные функции opendir() и readdir(). В Windows — функции Win32 FindFirstFileW и FindNextFileW.

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

Изменено в версии 3.6: Добавлена поддержка протокола менеджера контекста и метода close(). Если итератор scandir() не исчерпан и не закрыт явно, в его деструкторе будет выведено предупреждение ResourceWarning.

Функция принимает объект-путь.

Изменено в версии 3.7: Добавлена поддержка дескрипторов файлов в Unix.

class os.DirEntry

Объект, возвращаемый scandir() для отображения пути к файлу и других атрибутов файла для записи каталога.

scandir() предоставит как можно больше информации без выполнения дополнительных системных вызовов. При выполнении системного вызова stat() или lstat(), объект os.DirEntry кэширует результат.

Экземпляры os.DirEntry не предназначены для хранения в долгоживущих структурах данных; если вам известно, что метаданные файла изменились или прошло много времени с момента вызова scandir(), вызовите os.stat(entry.path), чтобы получить актуальную информацию.

Поскольку методы os.DirEntry могут вызывать системные вызовы, они также могут генерировать OSError. Если вам нужен очень точный контроль над ошибками, вы можете перехватить OSError при вызове одного из методов os.DirEntry и обработать их соответствующим образом.

Для непосредственного использования в качестве объекта-пути os.DirEntry реализует интерфейс PathLike.

Атрибуты и методы экземпляра os.DirEntry следующие:

name

Базовое имя файла записи, относительно аргумента path для scandir().

Атрибут name будет bytes если аргумент path для scandir() имеет тип bytes и str в противном случае. Используйте fsdecode() для декодирования имен файлов в байтах.

path

Полное имя записи: эквивалентно os.path.join(scandir_path, entry.name), где scandir_path — аргумент path для scandir(). Путь является абсолютным только если аргумент path для scandir() был абсолютным. Если аргумент path для scandir() был дескриптором файла, атрибут path такой же, как атрибут name.

Атрибут path будет bytes если аргумент path для scandir() имеет тип bytes и str в противном случае. Используйте fsdecode() для декодирования имен файлов в байтах.

inode()

Возвращает номер узла записи.

Результат кэшируется в объекте os.DirEntry. Используйте os.stat(entry.path, follow_symlinks=False).st_ino для получения актуальной информации.

При первом вызове (без кэширования) на Windows требуется системный вызов, а на Unix — нет.

is_dir(*, follow_symlinks=True)

Возвращает True, если запись является каталогом или символической ссылкой, указывающей на каталог; возвращает False, если запись является или указывает на любой другой тип файла или если она больше не существует.

Если follow_symlinks равно False, возвращает True только если эта запись является каталогом (без следования символическим ссылкам); возвращает False если запись является другим типом файла или если она больше не существует.

Результат кэшируется в объекте os.DirEntry, с отдельным кэшем для follow_symlinks True и False. Используйте os.stat() вместе с stat.S_ISDIR() для получения актуальной информации.

При первом (некэшированном) вызове системный вызов не требуется в большинстве случаев. В частности, для нессылок ни Windows, ни Unix не требуют системного вызова, за исключением некоторых файловых систем Unix, таких как сетевые файловые системы, которые возвращают dirent.d_type == DT_UNKNOWN. Если запись является символической ссылкой, системный вызов потребуется для следования ссылке, за исключением случаев, когда follow_symlinks равно False.

Этот метод может генерировать OSError, например, PermissionError, но FileNotFoundError перехватывается и не генерируется.

is_file(*, follow_symlinks=True)

Возвращает True, если запись является файлом или символической ссылкой, указывающей на файл; возвращает False, если запись является или указывает на каталог или другой объект, не являющийся файлом, или если она больше не существует.

Если follow_symlinks равно False, возвращает True только если эта запись является файлом (без следования символическим ссылкам); возвращает False если запись является каталогом или другим объектом, не являющимся файлом, или если она больше не существует.

Результат кэшируется в объекте os.DirEntry. Кэширование, выполняемые системные вызовы и генерируемые исключения такие же, как у is_dir().

is_symlink()

Возвращает True, если запись является символической ссылкой (даже если прервана); возвращает False, если запись указывает на каталог или любой тип файла или если она больше не существует.

Результат кэшируется в объекте os.DirEntry. Используйте os.path.islink() для получения актуальной информации.

При первом (некэшированном) вызове системный вызов не требуется в большинстве случаев. В частности, ни Windows, ни Unix не требуют системного вызова, за исключением некоторых файловых систем Unix, таких как сетевые файловые системы, которые возвращают dirent.d_type == DT_UNKNOWN.

Этот метод может генерировать OSError, например, PermissionError, но FileNotFoundError перехватывается и не генерируется.

is_junction()

Возвращает True, если запись является узлом (даже если прерван); возвращает False, если запись указывает на обычный каталог, любой тип файла, символическую ссылку или если она больше не существует.

Результат кэшируется в объекте os.DirEntry. Используйте os.path.isjunction() для получения актуальной информации.

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

stat(*, follow_symlinks=True)

Возвращает объект stat_result для этой записи. Этот метод по умолчанию следует символическим ссылкам; для получения статуса символической ссылки добавьте аргумент follow_symlinks=False.

В Unix этот метод всегда требует системного вызова. В Windows он требует системного вызова только если follow_symlinks равно True и запись является точкой перенаправления (например, символической ссылкой или узлом каталога).

В Windows атрибуты st_ino, st_dev и st_nlink объекта stat_result всегда устанавливаются в ноль. Используйте os.stat() для получения этих атрибутов.

Результат кэшируется в объекте os.DirEntry, с отдельным кэшем для follow_symlinks True и False. Используйте os.stat() для получения актуальной информации.

Обратите внимание на хорошее соответствие между несколькими атрибутами и методами os.DirEntry и pathlib.Path. В частности, атрибут name имеет то же значение, что и методы is_dir(), is_file(), is_symlink(), is_junction() и stat().

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

Изменено в версии 3.6: Добавлена поддержка интерфейса PathLike. Добавлена поддержка путей типа bytes в Windows.

Изменено в версии 3.12: Атрибут st_ctime результата stat на Windows устарел. Время создания файла корректно доступно как st_birthtime, а в будущем st_ctime может быть изменено на возврат нуля или времени изменения метаданных, если оно доступно.

os.stat(path, *, dir_fd=None, follow_symlinks=True)

Получение статуса файла или дескриптора файла. Выполняет эквивалент системного вызова stat() для данного пути. path может быть указан как строка или байты — непосредственно или косвенно через интерфейс PathLike — или как открытый дескриптор файла. Возвращает объект stat_result.

Эта функция обычно следует символичным ссылкам; чтобы получить статус символичной ссылки, добавьте аргумент follow_symlinks=False, или используйте lstat().

Эта функция может поддерживать указание дескриптора файла и не следование символичным ссылкам.

В Windows, передача follow_symlinks=False отключит следование всем точке переименования имен-заменителей, включая символичные ссылки и узлы каталогов. Другие типы точек переименования, которые не похожи на ссылки или которые операционная система не может отследить, будут открыты непосредственно. При слежении за цепочкой нескольких ссылок это может привести к возвращению исходной ссылки вместо не-ссылки, которая препятствовала полному прохождению. Чтобы получить результаты stat для конечного пути в этом случае, используйте функцию os.path.realpath() для разрешения имени пути насколько это возможно и вызовите lstat() на результате. Это не относится к висячим символичным ссылкам или узлам каталогов, которые приведут к обычным исключениям.

Пример:

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

См. также

fstat() и lstat() функции.

Изменено в версии 3.3: Добавлены параметры dir_fd и follow_symlinks, указывающие дескриптор файла вместо пути.

Изменено в версии 3.6: Принимает объект пути.

Изменено в версии 3.8: В Windows теперь отслеживаются все точки переименования, которые могут быть разрешены операционной системой, а передача follow_symlinks=False отключает отслеживание всех точек переименования с заменой имен. Если операционная система достигает точки переименования, которую она не может отследить, stat теперь возвращает информацию об исходном пути, как если бы follow_symlinks=False было указано вместо того, чтобы генерировать ошибку.

class os.stat_result

Объект, чьи атрибуты соответствуют примерно членам структуры stat. Он используется для результата os.stat(), os.fstat() и os.lstat().

Атрибуты:

st_mode

Режим файла: тип файла и биты режима файла (разрешения).

st_ino

Зависит от платформы, но если не равно нулю, однозначно идентифицирует файл для заданного значения st_dev. Обычно:

• номер узла на Unix,
• индекс файла в Windows

st_dev

Идентификатор устройства, на котором находится этот файл.

st_nlink

Количество жёстких ссылок.

st_uid

Идентификатор пользователя владельца файла.

st_gid

Идентификатор группы владельца файла.

st_size

Размер файла в байтах, если это обычный файл или символическая ссылка. Размер символической ссылки — длина пути, который она содержит, без завершающего нулевого байта.

Отметки времени:

st_atime

Время последнего доступа, выраженное в секундах.

st_mtime

Время последнего изменения содержимого, выраженное в секундах.

st_ctime

Время последнего изменения метаданных, выраженное в секундах.

Изменено в версии 3.12: st_ctime устарело в Windows. Используйте st_birthtime для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как и на других платформах.

st_atime_ns

Время последнего доступа, выраженное в наносекундах в виде целого числа.

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

st_mtime_ns

Время последнего изменения содержимого, выраженное в наносекундах в виде целого числа.

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

st_ctime_ns

Время последнего изменения метаданных, выраженное в наносекундах в виде целого числа.

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

Изменено в версии 3.12: st_ctime_ns устарело в Windows. Используйте st_birthtime_ns для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как и на других платформах.

st_birthtime

Время создания файла, выраженное в секундах. Этот атрибут не всегда доступен и может вызвать AttributeError.

Изменено в версии 3.12: st_birthtime теперь доступен в Windows.

st_birthtime_ns

Время создания файла, выраженное в наносекундах в виде целого числа. Этот атрибут не всегда доступен и может вызвать AttributeError.

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

Примечание

Точное значение и разрешение атрибутов st_atime, st_mtime, st_ctime и st_birthtime зависят от операционной системы и файловой системы. Например, в Windows с файловыми системами FAT32, st_mtime имеет разрешение 2 секунды, а st_atime — только 1 день. Для получения подробностей см. документацию вашей операционной системы.

Аналогично, хотя st_atime_ns, st_mtime_ns, st_ctime_ns и st_birthtime_ns всегда выражаются в наносекундах, многие системы не обеспечивают наносекундной точности. На системах, которые обеспечивают наносекундную точность, плавающей точкой, используемой для хранения st_atime, st_mtime, st_ctime и st_birthtime не удаётся сохранить всю её точность, в результате она будет немного неточной. Если вам нужны точные отметки времени, вы всегда должны использовать st_atime_ns, st_mtime_ns, st_ctime_ns и st_birthtime_ns.

На некоторых Unix-системах (таких как Linux) могут быть доступны следующие атрибуты:

st_blocks

Количество блоков по 512 байт, выделенных для файла. Это может быть меньше, чем st_size/512, когда файл имеет пробелы.

st_blksize

«Предпочтительный» размер блока для эффективной работы с файловой системой. Запись в файл меньшими блоками может привести к неэффективному чтению-модификации-записи.

st_rdev

Тип устройства, если узел — устройство.

st_flags

Пользовательские флаги для файла.

На других Unix-системах (например, FreeBSD) следующие атрибуты могут быть доступны (но могут быть заполнены только если root пытается их использовать):

st_gen

Номер версии файла.

В Solaris и производных системах также могут быть доступны следующие атрибуты:

st_fstype

Строка, которая однозначно идентифицирует тип файловой системы, содержащей файл.

В macOS системах также могут быть доступны следующие атрибуты:

st_rsize

Фактический размер файла.

st_creator

Создатель файла.

st_type

Тип файла.

В системах Windows также доступны следующие атрибуты:

st_file_attributes

Атрибуты файла Windows: dwFileAttributes член структуры BY_HANDLE_FILE_INFORMATION возвращаемой GetFileInformationByHandle(). См. константы FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> в модуле stat.

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

st_reparse_tag

Когда st_file_attributes имеет установленный FILE_ATTRIBUTE_REPARSE_POINT, это поле содержит тег, определяющий тип перенаправления. См. константы IO_REPARSE_TAG_* в модуле stat.

Стандартный модуль stat определяет функции и константы, полезные для извлечения информации из структуры stat. (В Windows некоторые элементы заполняются значениями по умолчанию.)

Для обратной совместимости экземпляр stat_result также доступен как кортеж из как минимум 10 целых чисел, представляющих самые важные (и переносимые) члены структуры stat, в порядке st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. Некоторые реализации могут добавить дополнительные элементы в конец. Для совместимости со старыми версиями Python, обращение к stat_result как к кортежу всегда возвращает целые числа.

Изменено в версии 3.5: В Windows теперь индекс файла возвращается как st_ino, если доступен.

Изменено в версии 3.7: Добавлен член st_fstype для Solaris/производных систем.

Изменено в версии 3.8: Добавлен член st_reparse_tag в Windows.

Изменено в версии 3.8: В Windows член st_mode теперь идентифицирует специальные файлы как S_IFCHR, S_IFIFO или S_IFBLK соответственно.

Изменено в версии 3.12: В Windows st_ctime устарело. В конечном итоге он будет содержать время последнего изменения метаданных для согласованности с другими платформами, но пока всё ещё содержит время создания. Используйте st_birthtime для времени создания.

В Windows st_ino теперь может составлять до 128 бит, в зависимости от файловой системы. Раньше он не превышал 64 бит, а более крупные идентификаторы файлов упаковывались произвольно.

В Windows st_rdev больше не возвращает значение. Ранее он содержал то же, что и st_dev, что было неправильно.

Добавлен член st_birthtime в Windows.

os.statvfs(path)

Выполняет системный вызов statvfs() для данного пути. Возвращаемое значение — объект, чьи атрибуты описывают файловую систему по данному пути и соответствуют членам структуры statvfs, а именно: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_fsid.

Для флагов битов атрибута f_flag определены две константы модуля: если ST_RDONLY установлено, файловая система смонтирована только для чтения, и если ST_NOSUID установлено, семантика битов setuid/setgid отключена или не поддерживается.

Для систем на основе GNU/glibc определены дополнительные константы модуля. Это ST_NODEV (запретить доступ к специальным файлам устройства), ST_NOEXEC (запретить выполнение программы), ST_SYNCHRONOUS (записи синхронизируются сразу), ST_MANDLOCK (разрешить обязательные блокировки на FS), ST_WRITE (запись в файл/каталог/символическую ссылку), ST_APPEND (только для добавления файл), ST_IMMUTABLE (неизменяемый файл), ST_NOATIME (не обновлять время доступа), ST_NODIRATIME (не обновлять время доступа к каталогам), ST_RELATIME (обновлять atime относительно mtime/ctime).

Эта функция может поддерживать указание дескриптора файла.

Доступность: Unix.

Изменено в версии 3.2: Были добавлены константы ST_RDONLY и ST_NOSUID.

Изменено в версии 3.3: Добавлена поддержка указания path как открытого дескриптора файла.

Изменено в версии 3.4: Были добавлены константы ST_NODEV, ST_NOEXEC, ST_SYNCHRONOUS, ST_MANDLOCK, ST_WRITE, ST_APPEND, ST_IMMUTABLE, ST_NOATIME, ST_NODIRATIME, и ST_RELATIME.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.7: Добавлен атрибут f_fsid.

os.supports_dir_fd

Объект set, указывающий, какие функции в модуле os принимают открытый дескриптор файла в качестве параметра dir_fd. Разные платформы предоставляют разные возможности, и базовая функциональность, используемая Python для реализации параметра dir_fd, недоступна на всех поддерживаемых платформах. Для согласованности функции, которые могут поддерживать dir_fd, всегда позволяют указать параметр, но будут генерировать исключение, если функциональность используется, когда она не доступна локально. (Указание None для dir_fd всегда поддерживается на всех платформах.)

Чтобы проверить, принимает ли конкретная функция открытый дескриптор файла в качестве параметра dir_fd, используйте оператор in на supports_dir_fd. Например, это выражение вычисляется как True если os.stat() принимает открытые дескрипторы файлов для dir_fd на локальной платформе:

os.stat in os.supports_dir_fd

В настоящее время параметры dir_fd работают только на платформах Unix; на Windows они не работают.

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

os.supports_effective_ids

Объект set, указывающий, разрешает ли os.access() указание True в качестве параметра effective_ids на локальной платформе. (Указание False для effective_ids всегда поддерживается на всех платформах.) Если локальная платформа поддерживает это, набор будет содержать os.access(); в противном случае он будет пустым.

Это выражение вычисляется как True если os.access() поддерживает effective_ids=True на локальной платформе:

os.access in os.supports_effective_ids

В настоящее время effective_ids поддерживается только на платформах Unix; он не работает в Windows.

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

os.supports_fd

Объект set, указывающий, какие функции в модуле os позволяют указать параметр path в виде дескриптора открытого файла на локальной платформе. Разные платформы предоставляют разные возможности, и базовая функциональность Python для принятия дескрипторов открытых файлов в качестве аргументов path недоступна на всех поддерживаемых платформах.

Чтобы определить, позволяет ли конкретная функция указать дескриптор открытого файла для параметра path, используйте оператор in над supports_fd. Например, это выражение вычисляется в True , если функция os.chdir() принимает дескрипторы открытых файлов для path на вашей локальной платформе:

os.chdir in os.supports_fd

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

os.supports_follow_symlinks

Объект set, указывающий, какие функции в модуле os принимают False в качестве параметра follow_symlinks на локальной платформе. Разные платформы предоставляют разные возможности, и базовая функциональность Python для реализации follow_symlinks недоступна на всех поддерживаемых платформах. Для обеспечения согласованности функции, которые могут поддерживать follow_symlinks, всегда позволяют указать этот параметр, но выбросят исключение, если эта функциональность недоступна локально. (Указание True для follow_symlinks всегда поддерживается на всех платформах.)

Чтобы проверить, принимает ли конкретная функция False в качестве параметра follow_symlinks, используйте оператор in над supports_follow_symlinks. Например, это выражение вычисляется в True , если вы можете указать follow_symlinks=False при вызове os.stat() на локальной платформе:

os.stat in os.supports_follow_symlinks

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

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

Создаёт символическую ссылку, указывающую на src и именованную как dst.

В Windows символическая ссылка представляет собой либо файл, либо директорию и не изменяет тип в зависимости от целевого объекта. Если целевой объект существует, тип символической ссылки будет соответствовать типу целевого объекта. В противном случае, символическая ссылка будет создана как директория, если target_is_directory равно True, или как ссылка на файл (по умолчанию) в противном случае. На платформах, отличных от Windows, target_is_directory игнорируется.

Функция может поддерживать пути, относительные к дескрипторам директорий.

Примечание

В более новых версиях Windows 10, пользователи без привилегий могут создавать символические ссылки, если включен режим разработчика. Когда режим разработчика недоступен/выключен, необходимы привилегии SeCreateSymbolicLinkPrivilege, или процесс должен выполняться с правами администратора.

OSError возникает, когда функция вызывается пользователем без привилегий.

Вызывает событие аудита auditing event os.symlink с аргументами src, dst, dir_fd.

Доступность: Unix, Windows.

Функция ограничена на WASI, см. Платформы WebAssembly для получения дополнительной информации.

Изменено в версии 3.2: Добавлена поддержка символических ссылок для Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd, и теперь поддерживается target_is_directory на платформах, отличных от Windows.

Изменено в версии 3.6: Принимает объект, подобный пути для src и dst.

Изменено в версии 3.8: Добавлена поддержка символических ссылок без повышения привилегий в Windows с режимом разработчика.

os.sync()

Принудительная запись всего содержимого на диск.

Доступность: Unix.

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

os.truncate(path, length)

Укорачивает файл по пути path, так чтобы его размер был не более length байт.

Функция может поддерживать указание дескриптора файла.

Вызывает событие аудита auditing event os.truncate с аргументами path, length.

Доступность: Unix, Windows.

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

Изменено в версии 3.5: Добавлена поддержка Windows

Изменено в версии 3.6: Принимает объект, подобный пути.

os.unlink(path, *, dir_fd=None)

Удаляет файл по пути path. Эта функция семантически идентична remove(); имя unlink — это её традиционное имя в Unix. Пожалуйста, ознакомьтесь с документацией remove() для получения дополнительной информации.

Вызывает событие аудита auditing event os.remove с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

Устанавливает время доступа и изменения файла по пути path.

Функция utime() принимает два необязательных параметра, times и ns. Они определяют устанавливаемые значения времени для path и используются следующим образом:

• Если ns указан, он должен быть кортежем длиной 2 вида (atime_ns, mtime_ns), где каждый элемент — целое число, представляющее наносекунды.
• Если times не None, он должен быть кортежем длиной 2 вида (atime, mtime), где каждый элемент — целое число или число с плавающей точкой, представляющее секунды.
• Если times None и ns не указан, это эквивалентно указанию ns=(atime_ns, mtime_ns), где оба времени — текущее время.

Ошибка возникает при указании кортежей как для times, так и для ns.

Обратите внимание, что точные установленные значения времени могут не быть возвращены последующим вызовом stat(), в зависимости от разрешения, с которым ваша операционная система записывает время доступа и изменения; см. stat(). Лучший способ сохранить точные значения времени — использовать поля st_atime_ns и st_mtime_ns из результата os.stat() с параметром ns для функции utime().

Функция может поддерживать указание дескриптора файла, пути, относительные к дескрипторам директорий и не следование символическим ссылкам.

Вызывает событие аудита auditing event os.utime с аргументами path, times, ns, dir_fd.

Изменено в версии 3.3: Добавлена поддержка указания path в виде дескриптора открытого файла, а также параметры dir_fd, follow_symlinks и ns.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.walk(top, topdown=True, onerror=None, followlinks=False)

Генерирует имена файлов в дереве каталогов, переходя по дереву сверху вниз или снизу вверх. Для каждого каталога в дереве с корнем в каталоге top (включая сам top) возвращается тройка (dirpath, dirnames, filenames).

dirpath — строка, путь к каталогу. dirnames — список имён подкаталогов в dirpath (включая символические ссылки на каталоги, и исключая '.' и '..'). filenames — список имён файлов, которые не являются каталогами, в dirpath. Обратите внимание, что имена в списках не содержат компонентов пути. Чтобы получить полный путь (который начинается с top) к файлу или каталогу в dirpath, выполните os.path.join(dirpath, name). Отсортированы ли списки, зависит от файловой системы. Если файл удаляется или добавляется в каталог dirpath во время генерации списков, включение имени этого файла не определено.

Если необязательный аргумент topdown имеет значение True или не указан, тройка для каталога генерируется до троек для его подкаталогов (каталоги генерируются сверху вниз). Если topdown имеет значение False, тройка для каталога генерируется после троек для всех его подкаталогов (каталоги генерируются снизу вверх). Независимо от значения topdown, список подкаталогов извлекается до генерации кортежей для каталога и его подкаталогов.

Когда topdown имеет значение True, вызывающая сторона может изменить список dirnames на месте (возможно, используя del или присваивание срезом), и walk() будет рекурсивно вызываться только в подкаталоги, чьи имена остаются в dirnames; это можно использовать для обрезки поиска, наложения определённого порядка посещения или даже для информирования walk() о каталогах, которые создаёт или переименовывает вызывающая сторона, прежде чем она возобновит walk() снова. Изменение dirnames, когда topdown имеет значение False , не влияет на поведение обхода, потому что в режиме снизу вверх каталоги в dirnames генерируются до генерации самого dirpath.

По умолчанию ошибки от вызова scandir() игнорируются. Если задан необязательный аргумент onerror, он должен быть функцией; она будет вызвана с одним аргументом, экземпляром OSError. Она может сообщить об ошибке, чтобы продолжить обход, или вызвать исключение, чтобы прервать обход. Обратите внимание, что имя файла доступно в качестве атрибута filename объекта исключения.

По умолчанию walk() не будет обходить символические ссылки, которые разрешаются в каталоги. Установите followlinks в значение True, чтобы посещать каталоги, на которые указывают символические ссылки, на системах, которые их поддерживают.

Примечание

Следует помнить, что установка followlinks в значение True может привести к бесконечной рекурсии, если ссылка указывает на родительский каталог по отношению к себе. walk() не отслеживает каталоги, которые она уже посетила.

Примечание

Если вы передаёте относительный путь, не изменяйте текущий рабочий каталог между возобновлениями walk(). walk() никогда не меняет текущий каталог и предполагает, что её вызывающая сторона этого тоже не делает.

Этот пример отображает количество байтов, занимаемых файлами, которые не являются каталогами, в каждом каталоге под начальным каталогом, за исключением того, что он не смотрит в подкаталоги CVS:

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

В следующем примере (простая реализация shutil.rmtree()) обход дерева снизу вверх необходим, поскольку rmdir() не позволяет удалить каталог до тех пор, пока он не будет пустым:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

Вызывает событие аудита аудита os.walk с аргументами top, topdown, onerror, followlinks.

Изменено в версии 3.5: Эта функция теперь вызывает os.scandir() вместо os.listdir(), что делает её быстрее за счёт уменьшения количества вызовов os.stat().

Изменено в версии 3.6: Принимает объект, подобный пути.

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

Это ведет себя точно так же, как walk(), за исключением того, что возвращает 4-кортеж (dirpath, dirnames, filenames, dirfd), и поддерживает dir_fd.

dirpath, dirnames и filenames идентичны выводу walk(), а dirfd — дескриптор файла, ссылающийся на каталог dirpath.

Эта функция всегда поддерживает пути, относительные к дескрипторам каталогов и не следование за символическими ссылками. Однако обратите внимание, что, в отличие от других функций, значение по умолчанию для fwalk() follow_symlinks равно False.

Примечание

Поскольку fwalk() возвращает дескрипторы файлов, они действительны только до следующего шага итерации, поэтому вы должны дублировать их (например, с помощью dup()), если хотите сохранить их дольше.

Этот пример отображает количество байтов, занимаемых файлами, которые не являются каталогами, в каждом каталоге под начальным каталогом, за исключением того, что он не смотрит в подкаталоги CVS:

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

В следующем примере обход дерева снизу вверх необходим: rmdir() не позволяет удалить каталог до тех пор, пока он не будет пустым:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

Вызывает событие аудита аудита os.fwalk с аргументами top, topdown, onerror, follow_symlinks, dir_fd.

Доступность: Unix.

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

Изменено в версии 3.6: Принимает объект, подобный пути.

Изменено в версии 3.7: Добавлена поддержка путей bytes.

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

Создаёт анонимный файл и возвращает дескриптор файла, который на него указывает. flags должен быть одним из os.MFD_* констант, доступных в системе (или битовой комбинацией их). По умолчанию новый дескриптор файла не наследуется.

Имя, указанное в name, используется как имя файла и будет отображено в качестве цели соответствующей символической ссылки в каталоге /proc/self/fd/. Отображаемое имя всегда начинается с memfd: и служит только для отладки. Имена не влияют на поведение дескриптора файла, и поэтому несколько файлов могут иметь одинаковое имя без каких-либо побочных эффектов.

Доступность: Linux >= 3.17 с glibc >= 2.27.

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

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

Эти флаги можно передать в функцию memfd_create().

Доступность: Linux >= 3.17 с glibc >= 2.27

Флаги MFD_HUGE* доступны начиная с Linux 4.14.

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

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

Создаёт и возвращает дескриптор файла события. Дескриптор файла поддерживает прямые read() и write() с размером буфера 8, select(), poll() и аналогичные. См. страницу руководства eventfd(2) для получения дополнительной информации. По умолчанию новый дескриптор файла является не наследуемым.

initval — начальное значение счётчика событий. Начальное значение должно быть 32-битным беззнаковым целым числом. Обратите внимание, что начальное значение ограничено 32-битным беззнаковым целым числом, хотя счётчик событий — это беззнаковое 64-битное целое число с максимальным значением 2⁶⁴-2.

flags может быть составлен из EFD_CLOEXEC, EFD_NONBLOCK и EFD_SEMAPHORE.

Если указан EFD_SEMAPHORE, а счётчик событий не равен нулю, eventfd_read() возвращает 1 и уменьшает счётчик на единицу.

Если EFD_SEMAPHORE не указан, а счётчик событий не равен нулю, eventfd_read() возвращает текущее значение счётчика событий и сбрасывает счётчик до нуля.

Если счётчик событий равен нулю и EFD_NONBLOCK не указан, eventfd_read() блокируется.

eventfd_write() увеличивает счётчик событий. Запись блокируется, если операция записи увеличит счётчик до значения, большего 2⁶⁴-2.

Пример:

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.eventfd_read(fd)

Читает значение из дескриптора файла eventfd() и возвращает 64-битное беззнаковое целое число. Функция не проверяет, является ли fd дескриптором eventfd().

Доступность: Linux >= 2.6.27

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

os.eventfd_write(fd, value)

Добавляет значение к дескриптору файла eventfd(). value должно быть 64-битным беззнаковым целым числом. Функция не проверяет, является ли fd дескриптором eventfd().

Доступность: Linux >= 2.6.27

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

os.EFD_CLOEXEC

Устанавливает флаг закрытия при выполнении для нового дескриптора файла eventfd().

Доступность: Linux >= 2.6.27

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

os.EFD_NONBLOCK

Устанавливает флаг O_NONBLOCK для нового дескриптора файла eventfd().

Доступность: Linux >= 2.6.27

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

os.EFD_SEMAPHORE

Обеспечивает семафорноподобную семантику для чтения из дескриптора файла eventfd(). При чтении внутренний счётчик уменьшается на единицу.

Доступность: Linux >= 2.6.30

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

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

Эти функции могут использоваться для создания и управления процессами.

Различные функции exec* принимают список аргументов для новой программы, загруженной в процесс. В каждом случае первый из этих аргументов передается новой программе как ее собственное имя, а не как аргумент, который пользователь мог ввести в командной строке. Для программиста на C это argv[0] передаваемый в main() программы. Например, os.execv('/bin/echo', ['foo', 'bar']) будет выводить только bar в стандартный вывод; foo будет казаться игнорируемым.

os.abort()

Генерирует сигнал SIGABRT для текущего процесса. В Unix по умолчанию создается дамп ядра; в Windows процесс сразу возвращает код выхода 3. Обратите внимание, что вызов этой функции не вызовет обработчик сигнала Python, зарегистрированный для SIGABRT с signal.signal().

os.add_dll_directory(path)

Добавляет путь к пути поиска DLL.

Этот путь поиска используется при разрешении зависимостей импортированных модулей расширения (сам модуль разрешается через sys.path), а также ctypes.

Удалите каталог, вызвав close() на возвращенном объекте или используя его в операторе with.

Для получения дополнительной информации о загрузке DLL см. документацию Microsoft.

Вызывает событие аудита аудита os.add_dll_directory с аргументом path.

Доступность: Windows.

Добавлена в версии 3.8: Предыдущие версии CPython разрешали DLL с использованием поведения по умолчанию для текущего процесса. Это приводило к несоответствиям, например, иногда искали PATH или текущую рабочую директорию, а функции ОС, такие как AddDllDirectory , не имели эффекта.

В версии 3.8 два основных способа загрузки DLL теперь явно переопределяют поведение на уровне процесса для обеспечения согласованности. См. заметки о портировании для получения информации об обновлении библиотек.

os.execl(path, arg0, arg1, ...)

os.execle(path, arg0, arg1, ..., env)

os.execlp(file, arg0, arg1, ...)

os.execlpe(file, arg0, arg1, ..., env)

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

Эти функции выполняют новую программу, заменяя текущий процесс; они не возвращаются. В Unix новый исполняемый файл загружается в текущий процесс и будет иметь тот же идентификатор процесса, что и вызывающий. Ошибки будут отображаться как исключения OSError.

Текущий процесс заменяется немедленно. Объекты открытых файлов и дескрипторы не сбрасываются, поэтому, если могут быть данные, буферизованные в этих открытых файлах, необходимо сбросить их, используя sys.stdout.flush() или os.fsync(), перед вызовом функции exec*.

Варианты функций exec* с “l” и “v” отличаются по тому, как передаются аргументы командной строки. Варианты с “l” могут быть проще в работе, если количество параметров фиксировано во время написания кода; отдельные параметры просто становятся дополнительными параметрами для функций execl*(). Варианты с “v” удобны, когда количество параметров изменяется, и аргументы передаются в списке или кортеже как параметр args. В любом случае, аргументы дочернего процесса должны начинаться с имени запускаемой команды, но это не проверяется.

Варианты, включающие “p” в конце (execlp(), execlpe(), execvp() и execvpe()) будут использовать переменную среды PATH для поиска файла программы file. При замене окружения (используя один из вариантов exec*e, обсуждаемых в следующем абзаце), новое окружение используется в качестве источника переменной PATH. Другие варианты, execl(), execle(), execv() и execve(), не будут использовать переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь. Относительные пути должны включать по крайней мере один слеш, даже в Windows, так как простые имена не будут разрешаться.

Для execle(), execlpe(), execve() и execvpe() (обратите внимание, что все они заканчиваются на “e”), параметр env должен быть отображением, используемым для определения переменных окружения для нового процесса (они используются вместо переменных окружения текущего процесса); функции execl(), execlp(), execv() и execvp() вызывают наследование окружения текущего процесса новым процессом.

Для execve() на некоторых платформах path также может быть указан как открытый дескриптор файла. Эта функциональность может не поддерживаться на вашей платформе; вы можете проверить ее наличие с помощью os.supports_fd. Если она недоступна, ее использование вызовет NotImplementedError.

Вызывает событие аудита аудита os.exec с аргументами path, args, env.

Доступность: Unix, Windows, не WASI, не Android, не iOS.

Изменено в версии 3.3: Добавлена поддержка указания path в виде открытого дескриптора файла для execve().

Изменено в версии 3.6: Принимает объект-путь.

os._exit(n)

Завершает процесс со статусом n без вызова обработчиков завершения, сброса буферов stdio и т.д.

Примечание

Стандартный способ завершения — sys.exit(n). _exit() обычно используется только в дочернем процессе после fork().

Следующие коды выхода определены и могут использоваться с _exit(), хотя они и не обязательны. Обычно они используются для системных программ, написанных на Python, таких как программа доставки внешних команд почтового сервера.

os.EX_OK

Код выхода, означающий отсутствие ошибок. Может быть взят из определенного значения EXIT_SUCCESS на некоторых платформах. Обычно имеет значение ноль.

Доступность: Unix, Windows.

os.EX_USAGE

Код выхода, означающий, что команда использовалась неправильно, например, при указании неправильного числа аргументов.

Доступность: Unix, не WASI.

os.EX_DATAERR

Код выхода, означающий, что входные данные были неверными.

Доступность: Unix, не WASI.

os.EX_NOINPUT

Код выхода, означающий, что входной файл не существовал или был нечитаемым.

Доступность: Unix, не WASI.

os.EX_NOUSER

Код выхода, означающий, что указанный пользователь не существует.

Доступность: Unix, не WASI.

os.EX_NOHOST

Код выхода, означающий, что указанный хост не существует.

Доступность: Unix, не WASI.

os.EX_UNAVAILABLE

Код выхода, означающий, что необходимая служба недоступна.

Доступность: Unix, не WASI.

os.EX_SOFTWARE

Код выхода, означающий, что была обнаружена внутренняя ошибка программного обеспечения.

Доступность: Unix, не WASI.

os.EX_OSERR

Код выхода, означающий, что была обнаружена ошибка операционной системы, например, невозможность выполнить виртуальный вызов или создать канал.

Доступность: Unix, не WASI.

os.EX_OSFILE

Код выхода, означающий, что какой-то системный файл не существовал, не мог быть открыт или имел какой-то другой вид ошибки.

Доступность: Unix, не WASI.

os.EX_CANTCREAT

Код выхода, означающий, что указанный пользователем выходной файл не мог быть создан.

Доступность: Unix, не WASI.

os.EX_IOERR

Код выхода, означающий, что произошла ошибка при выполнении операций ввода-вывода с каким-то файлом.

Доступность: Unix, не WASI.

os.EX_TEMPFAIL

Код выхода, означающий, что произошла временная ошибка. Это указывает на то, что это может не быть реальной ошибкой, например, сетевое соединение, которое не удалось установить во время повторной операции.

Доступность: Unix, не WASI.

os.EX_PROTOCOL

Код выхода, означающий, что обмен протоколом был незаконным, недопустимым или не понят.

Доступность: Unix, не WASI.

os.EX_NOPERM

Код выхода, означающий, что для выполнения операции не было достаточных прав (но не предназначен для проблем с файловой системой).

Доступность: Unix, не WASI.

os.EX_CONFIG

Код выхода, означающий, что произошла какая-то ошибка конфигурации.

Доступность: Unix, не WASI.

os.EX_NOTFOUND

Код выхода, означающий что-то вроде «запись не найдена».

Доступность: Unix, не WASI.

os.fork()

Создает дочерний процесс. Возвращает 0 в дочернем процессе и идентификатор процесса дочернего процесса в родительском процессе. При возникновении ошибки возбуждается OSError.

Обратите внимание, что на некоторых платформах, включая FreeBSD <= 6.3 и Cygwin, есть известные проблемы при использовании fork() из потока.

Вызывает событие аудита аудита os.fork без аргументов.

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

Если вы используете TLS-сокеты в приложении, вызывающем fork(), обратите внимание на предупреждение в документации ssl.

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

В macOS использование этой функции небезопасно при смешивании с API системы более высокого уровня, в том числе с использованием urllib.request.

Изменено в версии 3.8: Вызов fork() в подинтерпретаторе больше не поддерживается (RuntimeError возбуждается).

Изменено в версии 3.12: Если Python может определить, что у вашего процесса несколько потоков, os.fork() теперь возбуждает DeprecationWarning.

Мы выбрали отображение этого как предупреждения, при возможности обнаружения, чтобы лучше информировать разработчиков о проблеме проектирования, которую POSIX-платформа специально отмечает как неподдерживаемую. Даже в коде, который, кажется, работает, никогда не было безопасно смешивать потоки с os.fork() на POSIX-платформах. Сам интерпретатор CPython всегда выполнял API-вызовы, которые небезопасны для использования в дочернем процессе, когда в родительском процессе существовали потоки (например, malloc и free).

Пользователи macOS или пользователи реализаций libc или malloc, отличные от обычно встречающихся в glibc, в настоящее время относятся к тем, кто с большей вероятностью столкнётся с тупиками при запуске такого кода.

См. это обсуждение о несовместимости fork с потоками для технических деталей о том, почему мы поднимаем эту давнюю проблему совместимости с платформами перед разработчиками.

Доступность: POSIX, не WASI, не Android, не iOS.

os.forkpty()

Создать дочерний процесс, используя новый псевдотерминал в качестве управляющего терминала дочернего процесса. Возвращает пару (pid, fd), где pid — 0 в дочернем процессе, новый идентификатор процесса дочернего процесса в родительском процессе, а fd — дескриптор файла главного конца псевдотерминала. Для более портабельного подхода используйте модуль pty. В случае ошибки возникает исключение OSError.

Вызывает событие аудита auditing event os.forkpty без аргументов.

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

В macOS использование этой функции небезопасно при совместном использовании с API-интерфейсами более высокого уровня, включая использование urllib.request.

Изменено в версии 3.8: Вызов forkpty() в подинтерпретаторе больше не поддерживается (RuntimeError).

Изменено в версии 3.12: Если Python может определить, что ваш процесс имеет несколько потоков, теперь это вызывает DeprecationWarning. См. более подробное объяснение в os.fork().

Доступность: Unix, не WASI, не Android, не iOS.

os.kill(pid, sig, /)

Отправка сигнала sig процессу pid. Константы для конкретных сигналов, доступных на платформе хоста, определены в модуле signal.

Windows: Сигналы signal.CTRL_C_EVENT и signal.CTRL_BREAK_EVENT являются специальными сигналами, которые могут быть отправлены только консольным процессам, которые используют общее консольное окно, например, некоторым дочерним процессам. Любое другое значение для sig приведет к безусловному завершению процесса с помощью API TerminateProcess, и код завершения будет установлен на sig.

См. также signal.pthread_kill().

Вызывает событие аудита auditing event os.kill с аргументами pid, sig.

Доступность: Unix, Windows, не WASI, не iOS.

Изменено в версии 3.2: Добавлена поддержка Windows.

os.killpg(pgid, sig, /)

Отправить сигнал sig группе процессов pgid.

Вызывает событие аудита auditing event os.killpg с аргументами pgid, sig.

Доступность: Unix, не WASI, не iOS.

os.nice(increment, /)

Добавить increment к «уровню приоритета» процесса. Возвращает новый уровень приоритета.

Доступность: Unix, не WASI.

os.pidfd_open(pid, flags=0)

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

См. страницу справки pidfd_open(2) для получения дополнительной информации.

Доступность: Linux >= 5.3, Android >= build-time API level 31

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

os.PIDFD_NONBLOCK

Этот флаг указывает, что дескриптор файла будет неблокирующим. Если процесс, на который ссылается дескриптор файла, еще не завершен, то попытка ожидания дескриптора файла с помощью waitid(2) немедленно вернёт ошибку EAGAIN вместо блокировки.

Доступность: Linux >= 5.10

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

os.plock(op, /)

Заблокировать сегменты программы в памяти. Значение op (определяется в <sys/lock.h>) определяет, какие сегменты будут заблокированы.

Доступность: Unix, не WASI, не iOS.

os.popen(cmd, mode='r', buffering=-1)

Открыть канал для команд cmd. Возвращаемое значение — открытый файл объекта, подключённый к каналу, который можно читать или записывать в зависимости от того, является ли mode 'r' (по умолчанию) или 'w'. Аргумент buffering имеет то же значение, что и соответствующий аргумент встроенной функции open(). Возвращаемый объект файла читает или записывает строковые значения, а не байты.

Метод close возвращает None, если дочерний процесс завершился успешно, или код возврата дочернего процесса, если произошла ошибка. В системах POSIX, если код возврата положительный, он представляет собой значение возврата процесса, сдвинутое влево на один байт. Если код возврата отрицательный, процесс был завершён сигналом, заданным отрицательным значением кода возврата. (Например, возвращаемое значение может быть - signal.SIGKILL , если дочерний процесс был убит.) В системах Windows возвращаемое значение содержит целое число возвращаемое дочерним процессом.

В Unix, waitstatus_to_exitcode() можно использовать для преобразования результата метода close (состояние выхода) в код выхода, если он не None. В системах Windows результат метода close непосредственно является кодом выхода (или None).

Это реализовано с использованием subprocess.Popen; см. документацию этого класса для более мощных способов управления и общения с дочерними процессами.

Доступность: не WASI, не Android, не iOS.

Примечание

Режим Python UTF-8 влияет на кодировки, используемые для cmd и содержимого канала.

popen() — это простой обёртку вокруг subprocess.Popen. Используйте subprocess.Popen или subprocess.run() для управления параметрами, такими как кодировки.

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Оборачивает API библиотеки C posix_spawn() для использования из Python.

Большинство пользователей должны использовать subprocess.run() вместо posix_spawn().

Позиционные-только аргументы path, args и env аналогичны execve(). env может быть None, в этом случае используется окружение текущего процесса.

Параметр path — путь к исполняемому файлу. path должен содержать каталог. Используйте posix_spawnp(), чтобы передать исполняемый файл без каталога.

Аргумент file_actions может быть последовательностью кортежей, описывающих действия, которые необходимо выполнить над определёнными дескрипторами файлов в дочернем процессе между этапами fork() и exec() реализации библиотеки C. Первый элемент каждого кортежа должен быть одним из трёх указателей типов, перечисленных ниже, описывающих оставшиеся элементы кортежа:

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

Выполняет os.dup2(os.open(path, flags, mode), fd).

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

Выполняет os.close(fd).

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

Выполняет os.dup2(fd, new_fd).

os.POSIX_SPAWN_CLOSEFROM

(os.POSIX_SPAWN_CLOSEFROM, fd)

Выполняет os.closerange(fd, INF).

Эти кортежи соответствуют вызовам API библиотеки C posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose(), posix_spawn_file_actions_adddup2(), и posix_spawn_file_actions_addclosefrom_np() для подготовки к самому вызову posix_spawn().

Аргумент setpgroup установит группу процессов дочернего процесса в указанное значение. Если указанное значение равно 0, идентификатор группы процессов дочернего процесса будет таким же, как его идентификатор процесса. Если значение setpgroup не указано, дочерний процесс унаследует идентификатор группы процессов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETPGROUP.

Если аргумент resetids равен True, он сбросит эффективный идентификатор пользователя (UID) и эффективный идентификатор группы (GID) дочернего процесса до реального UID и GID родительского процесса. Если аргумент равен False, дочерний процесс сохраняет эффективный UID и GID родителя. В любом случае, если биты разрешения на изменение UID и GID включены в исполняемом файле, их действие перекроет установку эффективного UID и GID. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_RESETIDS.

Если аргумент setsid равен True, он создаст новый идентификатор сеанса для posix_spawn. setsid требует флага POSIX_SPAWN_SETSID или POSIX_SPAWN_SETSID_NP . В противном случае будет поднято исключение NotImplementedError.

Аргумент setsigmask установит маску сигналов в указанный набор сигналов. Если параметр не используется, дочерний процесс унаследует маску сигналов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGMASK.

Аргумент sigdef сбросит обработчики всех сигналов в указанном наборе. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGDEF.

Аргумент scheduler должен быть кортежем, содержащим (необязательную) политику планировщика и экземпляр sched_param с параметрами планировщика. Значение None вместо политики планировщика указывает, что она не предоставляется. Этот аргумент является комбинацией флагов библиотеки C POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDULER.

Вызывает событие аудита аудита os.posix_spawn с аргументами path, argv, env.

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

Изменено в версии 3.13: Параметр env принимает None. os.POSIX_SPAWN_CLOSEFROM доступен на платформах, где существует posix_spawn_file_actions_addclosefrom_np().

Доступность: Unix, не WASI, не Android, не iOS.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Оборачивает API библиотеки C posix_spawnp() для использования из Python.

Аналогично posix_spawn(), за исключением того, что система ищет файл executable в списке каталогов, указанном переменной окружения PATH (так же, как и для execvp(3)).

Вызывает событие аудита аудита os.posix_spawn с аргументами path, argv, env.

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

Доступность: POSIX, не WASI, не Android, не iOS.

См. документацию posix_spawn().

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

Регистрирует вызываемые объекты для выполнения, когда новый дочерний процесс создается с помощью os.fork() или аналогичных API клонирования процессов. Параметры необязательны и только ключевые слова. Каждый параметр определяет различную точку вызова.

• before — функция, вызываемая перед созданием дочернего процесса.
• after_in_parent — функция, вызываемая из родительского процесса после создания дочернего процесса.
• after_in_child — функция, вызываемая из дочернего процесса.

Эти вызовы выполняются только в том случае, если ожидается возврат управления в интерпретатор Python. Типичный запуск с помощью subprocess не вызовет их, так как дочерний процесс не будет повторно входить в интерпретатор.

Функции, зарегистрированные для выполнения перед созданием вилки, вызываются в обратном порядке регистрации. Функции, зарегистрированные для выполнения после создания вилки (либо в родительском, либо в дочернем процессе), вызываются в порядке регистрации.

Обратите внимание, что вызовы fork() стороннего кода C могут не вызвать эти функции, если не вызовут явным образом PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child().

Нет способа аннулировать регистрацию функции.

Доступность: Unix, не WASI, не Android, не iOS.

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

os.spawnl(mode, path, ...)

os.spawnle(mode, path, ..., env)

os.spawnlp(mode, file, ...)

os.spawnlpe(mode, file, ..., env)

os.spawnv(mode, path, args)

os.spawnve(mode, path, args, env)

os.spawnvp(mode, file, args)

os.spawnvpe(mode, file, args, env)

Запустить программу path в новом процессе.

(Обратите внимание, что модуль subprocess предоставляет более мощные возможности для запуска новых процессов и получения их результатов; использование этого модуля предпочтительнее использования этих функций. Обратите особое внимание на раздел Замена устаревших функций модулем subprocess.)

Если mode равен P_NOWAIT, эта функция возвращает идентификатор процесса нового процесса; если mode равен P_WAIT, возвращает код завершения процесса, если он завершился нормально, или -signal, где signal — сигнал, который убил процесс. В Windows идентификатор процесса фактически будет дескриптором процесса, поэтому его можно использовать с функцией waitpid().

Обратите внимание на VxWorks, эта функция не возвращает -signal при убийстве нового процесса. Вместо этого она вызывает исключение OSError.

Варианты с “l” и “v” функций spawn* отличаются тем, как передаются аргументы командной строки. Варианты с “l” могут быть проще в работе, если количество параметров фиксировано при написании кода; отдельные параметры просто становятся дополнительными параметрами для функций spawnl*(). Варианты с “v” хороши, когда количество параметров переменное, и аргументы передаются в списке или кортеже как параметр args. В любом случае, аргументы для дочернего процесса должны начинаться с имени выполняемой команды.

Варианты, включающие второе “p” в конце (spawnlp(), spawnlpe(), spawnvp() и spawnvpe()) будут использовать переменную среды PATH для поиска программы file. При замене среды (используя один из вариантов spawn*e, обсуждаемых в следующем абзаце) новая среда используется в качестве источника переменной PATH. Другие варианты, spawnl(), spawnle(), spawnv() и spawnve(), не будут использовать переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь.

Для spawnle(), spawnlpe(), spawnve() и spawnvpe() (обратите внимание, что они все заканчиваются на “e”), параметр env должен быть отображением, которое используется для определения переменных среды для нового процесса (они используются вместо среды текущего процесса); функции spawnl(), spawnlp(), spawnv() и spawnvp() заставляют новый процесс унаследовать среду текущего процесса. Обратите внимание, что ключи и значения в словаре env должны быть строками; некорректные ключи или значения приведут к ошибке функции с возвращаемым значением 127.

Например, следующие вызовы spawnlp() и spawnvpe() эквивалентны:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

Вызывает событие аудита аудита os.spawn с аргументами mode, path, args, env.

Доступность: Unix, Windows, не WASI, не Android, не iOS.

spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не являются потокобезопасными в Windows; рекомендуется использовать модуль subprocess.

Изменено в версии 3.6: Принимает объект-путь объект-путь.

os.P_NOWAIT

os.P_NOWAITO

Возможные значения для параметра mode семейства функций spawn*. Если задано любое из этих значений, функции spawn* вернут значение как только новый процесс будет создан, вернув идентификатор процесса.

Доступность: Unix, Windows.

os.P_WAIT

Возможные значения для параметра mode семейства функций spawn*. Если это значение задано как mode, функции spawn* не вернут значение, пока новый процесс не завершит работу, и вернут код завершения процесса, если выполнение прошло успешно, или -signal если процесс был убит сигналом.

Доступность: Unix, Windows.

os.P_DETACH

os.P_OVERLAY

Возможные значения для параметра mode семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH похож на P_NOWAIT, но новый процесс отделён от консоли вызывающего процесса. Если используется P_OVERLAY, текущий процесс будет заменён; функция spawn* не вернёт значение.

Доступность: Windows.

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

Запустить файл с помощью соответствующего приложения.

Когда operation не указано, это действует так же, как двойной щелчок по файлу в проводнике Windows или передача имени файла в качестве аргумента команде start из интерактивной командной оболочки: файл открывается с помощью любого приложения (если таковое имеется), связанного с его расширением.

Когда указано другое operation, оно должно быть «глаголом команды», указывающим, что нужно сделать с файлом. Общие глаголы, документированные Microsoft, — это 'open', 'print' и 'edit' (для использования с файлами), а также 'explore' и 'find' (для использования с каталогами).

При запуске приложения укажите arguments, которые нужно передать в качестве одной строки. Этот аргумент может не иметь эффекта при использовании этой функции для запуска документа.

Текущий рабочий каталог наследуется, но может быть переопределён аргументом cwd. Это должен быть абсолютный путь. Относительный путь будет разрешён относительно этого аргумента.

Используйте show_cmd для переопределения стандартного стиля окна. Влияние этого параметра зависит от запускаемого приложения. Значения являются целыми числами, поддерживаемыми функцией Win32 ShellExecute().

startfile() возвращает как только соответствующее приложение запущено. Нет возможности подождать закрытия приложения и получить код завершения приложения. Параметр path относительный к текущему каталогу или cwd. Если вы хотите использовать абсолютный путь, убедитесь, что первый символ не является косой чертой ('/') Используйте pathlib или функцию os.path.normpath() для обеспечения правильной кодировки путей для Win32.

Для снижения накладных расходов при запуске интерпретатора функция Win32 ShellExecute() не разрешается до первого вызова этой функции. Если функция не может быть разрешена, будет поднято исключение NotImplementedError.

Вызывает событие аудита аудита os.startfile с аргументами path, operation.

Вызывает событие аудита аудита os.startfile/2 с аргументами path, operation, arguments, cwd, show_cmd.

Доступность: Windows.

Изменено в версии 3.10: Добавлены аргументы arguments, cwd и show_cmd, а также событие аудита os.startfile/2.

os.system(command)

Выполняет команду (строку) в дочерней оболочке. Это реализуется путём вызова стандартной C-функции system(), и имеет те же ограничения. Изменения в sys.stdin и т. д. не отражаются в среде выполняемой команды. Если command генерирует вывод, он будет отправлен на стандартный поток вывода интерпретатора. C стандарт не определяет значение возвращаемого значения C-функции, поэтому возвращаемое значение Python-функции зависит от системы.

В Unix возвращаемое значение — это код завершения процесса, закодированный в формате, указанном для wait().

В Windows возвращаемое значение — это значение, возвращённое системной оболочкой после выполнения command. Оболочка задаётся переменной среды Windows COMSPEC: обычно cmd.exe, которая возвращает код завершения выполненной команды; на системах, использующих неродную оболочку, см. документацию вашей оболочки.

Модуль subprocess предоставляет более мощные средства для запуска новых процессов и получения их результатов; использование этого модуля предпочтительнее использования этой функции. См. раздел Замена устаревших функций модулем subprocess в документации subprocess для полезных рецептов.

В Unix функция waitstatus_to_exitcode() может быть использована для преобразования результата (кода завершения) в код завершения. В Windows результат напрямую является кодом завершения.

Вызывает событие аудита аудита os.system с аргументом command.

Доступность: Unix, Windows, не WASI, не Android, не iOS.

os.times()

Возвращает текущие глобальные времена работы процесса. Результат — объект с пятью атрибутами:

• user - время пользователя
• system - системное время
• children_user - время пользователя всех дочерних процессов
• children_system - системное время всех дочерних процессов
• elapsed - прошедшее реальное время с момента фиксированной точки в прошлом

Для обратной совместимости этот объект также ведет себя как пятиэлементный кортеж, содержащий user, system, children_user, children_system, и elapsed в указанном порядке.

См. страницу руководства Unix times(2) и страницу руководства times(3) в Unix или MSDN GetProcessTimes в Windows. В Windows известны только user и system; другие атрибуты равны нулю.

Доступность: Unix, Windows.

Изменено в версии 3.3: Тип возвращаемого значения изменён с кортежа на подобный кортежу объект с именованными атрибутами.

os.wait()

Ожидает завершения дочернего процесса и возвращает кортеж, содержащий его идентификатор процесса (pid) и указание на код завершения: 16-битное число, младший байт которого — номер сигнала, который убил процесс, а старший байт — код завершения (если номер сигнала равен нулю); старший бит младшего байта установлен, если был создан файл core.

Если нет дочерних процессов, которые можно ожидать, поднимается исключение ChildProcessError.

waitstatus_to_exitcode() может быть использована для преобразования кода завершения в код выхода.

Доступность: Unix, не WASI, не Android, не iOS.

См. также

Другие функции wait*() , описанные ниже, могут использоваться для ожидания завершения конкретного дочернего процесса и имеют больше опций. waitpid() — единственная, доступная также в Windows.

os.waitid(idtype, id, options, /)

Ожидание завершения дочернего процесса.

idtype может быть P_PID, P_PGID, P_ALL или (на Linux) P_PIDFD. Интерпретация id зависит от него; см. их отдельные описания.

options — это логическое ИЛИ комбинация флагов. Необходимо указать хотя бы один из флагов WEXITED, WSTOPPED или WCONTINUED; WNOHANG и WNOWAIT — это дополнительные необязательные флаги.

Значение результата — объект, представляющий данные, содержащиеся в siginfo_t структуре, с указанными атрибутами:

• si_pid (идентификатор процесса)
• si_uid (действительный идентификатор пользователя дочернего процесса)
• si_signo (всегда SIGCHLD)
• si_status (код завершения или номер сигнала, в зависимости от si_code)
• si_code (см. CLD_EXITED для возможных значений)

Если указан WNOHANG и нет совпадающих дочерних процессов в нужном состоянии, возвращается None. В противном случае, если нет подходящих дочерних процессов, которые можно ожидать, генерируется исключение ChildProcessError.

Доступность: Unix, не WASI, не Android, не iOS.

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

Изменено в версии 3.13: Эта функция теперь доступна и для macOS.

os.waitpid(pid, options, /)

Подробности этой функции отличаются на Unix и Windows.

На Unix: Ожидание завершения дочернего процесса, заданного идентификатором процесса pid, и возвращение кортежа, содержащего его идентификатор процесса и указание на код завершения (кодированное так же, как для wait()). Семантика вызова зависит от значения целого числа options, которое должно быть 0 для нормальной работы.

Если pid больше 0, waitpid() запрашивает информацию о состоянии этого конкретного процесса. Если pid равно 0, запрос касается состояния любого дочернего процесса в группе процессов текущего процесса. Если pid равно -1, запрос относится к любому дочернему процессу текущего процесса. Если pid меньше -1, запрос состояния любого процесса в группе процессов -pid (абсолютное значение pid).

options — это логическое ИЛИ комбинация флагов. Если он содержит WNOHANG, и нет совпадающих дочерних процессов в нужном состоянии, возвращается (0, 0). В противном случае, если нет подходящих дочерних процессов, которые можно ожидать, возникает исключение ChildProcessError. Другие используемые флаги — WUNTRACED и WCONTINUED.

На Windows: Ожидание завершения процесса, заданного дескриптором процесса pid, и возвращение кортежа, содержащего pid и его код завершения, сдвинутый влево на 8 бит (сдвиг упрощает кроссплатформенное использование функции). Значение pid, меньшее или равное 0, не имеет особого значения на Windows и вызывает исключение. Значение целого числа options не влияет на работу. pid может ссылаться на любой процесс, чей идентификатор известен, не обязательно на дочерний процесс. Функции spawn*, вызываемые с P_NOWAIT, возвращают подходящие дескрипторы процессов.

waitstatus_to_exitcode() может использоваться для преобразования кода завершения в код выхода.

Доступность: Unix, Windows, не WASI, не Android, не iOS.

Изменено в версии 3.5: Если системный вызов прерывается, а обработчик сигнала не генерирует исключение, функция теперь повторно пытается выполнить системный вызов вместо генерации исключения InterruptedError (см. PEP 475 для обоснования).

os.wait3(options)

Аналогично waitpid(), за исключением того, что аргумент идентификатора процесса не указан, и возвращается кортеж из 3 элементов, содержащий идентификатор процесса дочернего процесса, указание на код завершения и информацию об использовании ресурсов. Подробности о информации об использовании ресурсов см. в resource.getrusage(). Аргумент options такой же, как у waitpid() и wait4().

waitstatus_to_exitcode() можно использовать для преобразования кода завершения в код выхода.

Доступность: Unix, не WASI, не Android, не iOS.

os.wait4(pid, options)

Аналогично waitpid(), за исключением того, что возвращается кортеж из 3 элементов, содержащий идентификатор процесса дочернего процесса, указание на код завершения и информацию об использовании ресурсов. Подробности о информации об использовании ресурсов см. в resource.getrusage(). Аргументы wait4() такие же, как у waitpid().

waitstatus_to_exitcode() можно использовать для преобразования кода завершения в код выхода.

Доступность: Unix, не WASI, не Android, не iOS.

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

Возможные значения для idtype в waitid(). Они влияют на интерпретацию id:

• P_PID — ожидание дочернего процесса с PID id.
• P_PGID — ожидание любого дочернего процесса с идентификатором группы процессов id.
• P_ALL — ожидание любого дочернего процесса; id игнорируется.
• P_PIDFD — ожидание дочернего процесса, идентифицированного дескриптором файла id (дескриптор процесса, созданный с помощью pidfd_open()).

Доступность: Unix, не WASI, не Android, не iOS.

Примечание

P_PIDFD доступно только на Linux >= 5.4.

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

Добавлена в версии 3.9: константа P_PIDFD.

os.WCONTINUED

Этот флаг options для waitpid(), wait3(), wait4() и waitid() вызывает сообщение о дочерних процессах, если они были продолжены из остановленного состояния управления заданиями с момента последнего сообщения.

Доступность: Unix, не WASI, не Android, не iOS.

os.WEXITED

Этот флаг options для waitid() вызывает сообщение о дочерних процессах, которые завершились.

Другие wait* функции всегда сообщают о завершившихся дочерних процессах, поэтому этот параметр для них недоступен.

Доступность: Unix, не WASI, не Android, не iOS.

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

os.WSTOPPED

Этот флаг options для waitid() вызывает сообщение о дочерних процессах, которые были остановлены доставкой сигнала.

Этот параметр недоступен для других wait* функций.

Доступность: Unix, не WASI, не Android, не iOS.

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

os.WUNTRACED

Этот флаг options для waitpid(), wait3() и wait4() вызывает сообщение о дочерних процессах, которые также были остановлены, но их текущее состояние не сообщалось с момента остановки.

Этот параметр недоступен для waitid().

Доступность: Unix, не WASI, не Android, не iOS.

os.WNOHANG

Этот флаг options заставляет waitpid(), wait3(), wait4() и waitid() возвращаться немедленно, если статус ни одного дочернего процесса недоступен немедленно.

Доступность: Unix, не WASI, не Android, не iOS.

os.WNOWAIT

Этот флаг options заставляет waitid() оставить дочерний процесс в состоянии ожидания, чтобы позже вызов wait*() можно было использовать для получения информации о статусе дочернего процесса ещё раз.

Этот параметр недоступен для других wait* функций.

Доступность: Unix, не WASI, не Android, не iOS.

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

Это возможные значения для si_code в результате, возвращаемом waitid().

Доступность: Unix, не WASI, не Android, не iOS.

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

Изменено в версии 3.9: Добавлены значения CLD_KILLED и CLD_STOPPED.

os.waitstatus_to_exitcode(status)

Преобразовать статус ожидания в код выхода.

В Unix:

• Если процесс завершился нормально (если WIFEXITED(status) истинно), вернуть код завершения процесса (вернуть WEXITSTATUS(status)): результат больше или равен 0.
• Если процесс был завершен сигналом (если WIFSIGNALED(status) истинно), вернуть -signum где signum — номер сигнала, вызвавшего завершение процесса (вернуть -WTERMSIG(status)): результат меньше 0.
• В противном случае, вызвать ValueError.

В Windows вернуть status, сдвинутый вправо на 8 бит.

В Unix, если процесс отслеживается или если waitpid() был вызван с параметром WUNTRACED, вызывающий код должен сначала проверить, истинно ли WIFSTOPPED(status). Функцию не следует вызывать, если WIFSTOPPED(status) истинно.

См. также

WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG() функции.

Доступность: Unix, Windows, не WASI, не Android, не iOS.

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

Следующие функции принимают код состояния процесса, возвращаемый system(), wait() или waitpid() в качестве параметра. Они могут использоваться для определения состояния процесса.

os.WCOREDUMP(status, /)

Возвращает True, если для процесса был создан дамп ядра, иначе возвращает False.

Эта функция должна использоваться только если WIFSIGNALED() истинно.

Доступность: Unix, не WASI, не Android, не iOS.

os.WIFCONTINUED(status)

Возвращает True, если остановленный дочерний процесс был возобновлен с помощью доставки SIGCONT (если процесс был продолжен из остановленного состояния управления заданиями), иначе возвращает False.

См. параметр WCONTINUED.

Доступность: Unix, не WASI, не Android, не iOS.

os.WIFSTOPPED(status)

Возвращает True если процесс был остановлен по сигналу, в противном случае возвращает False.

WIFSTOPPED() возвращает True только если вызов waitpid() был выполнен с опцией WUNTRACED, или если процесс отслеживается (см. ptrace(2)).

Доступность: Unix, не WASI, не Android, не iOS.

os.WIFSIGNALED(status)

Возвращает True если процесс был завершен сигналом, в противном случае возвращает False.

Доступность: Unix, не WASI, не Android, не iOS.

os.WIFEXITED(status)

Возвращает True если процесс завершился нормально, то есть, вызвав exit() или _exit(), или вернувшись из main(); в противном случае возвращает False.

Доступность: Unix, не WASI, не Android, не iOS.

os.WEXITSTATUS(status)

Возвращает код завершения процесса.

Эта функция должна использоваться только если WIFEXITED() истинно.

Доступность: Unix, не WASI, не Android, не iOS.

os.WSTOPSIG(status)

Возвращает сигнал, который привел к остановке процесса.

Эта функция должна использоваться только если WIFSTOPPED() истинно.

Доступность: Unix, не WASI, не Android, не iOS.

os.WTERMSIG(status)

Возвращает номер сигнала, который привел к завершению процесса.

Эта функция должна использоваться только если WIFSIGNALED() истинно.

Доступность: Unix, не WASI, не Android, не iOS.

Интерфейс к планировщику

Эти функции контролируют, как операционная система выделяет процессорное время процессу. Они доступны только на некоторых Unix-платформах. Для более подробной информации обратитесь к Unix manpages.

Следующие политики планирования доступны, если они поддерживаются операционной системой.

os.SCHED_OTHER

Политика планирования по умолчанию.

os.SCHED_BATCH

Политика планирования для процессороемких процессов, которая пытается сохранить интерактивность остальной части компьютера.

os.SCHED_IDLE

Политика планирования для задач фонового режима с очень низким приоритетом.

os.SCHED_SPORADIC

Политика планирования для спорадических серверных программ.

os.SCHED_FIFO

Политика планирования «первым пришёл — первым обслужен».

os.SCHED_RR

Политика планирования круговой очереди.

os.SCHED_RESET_ON_FORK

Этот флаг можно объединить с любой другой политикой планирования. При разветвлении процесса с этим флагом установленным, политика планирования и приоритет потомка сбрасываются до значения по умолчанию.

class os.sched_param(sched_priority)

Этот класс представляет настраиваемые параметры планирования, используемые в sched_setparam(), sched_setscheduler() и sched_getparam(). Он неизменяемый.

В настоящее время существует только один возможный параметр:

sched_priority

Приоритет планирования для политики планирования.

os.sched_get_priority_min(policy)

Получить минимальное значение приоритета для policy. policy — одна из констант политики планирования выше.

os.sched_get_priority_max(policy)

Получить максимальное значение приоритета для policy. policy — одна из констант политики планирования выше.

os.sched_setscheduler(pid, policy, param, /)

Установить политику планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. policy — одна из констант политики планирования выше. param — экземпляр sched_param.

os.sched_getscheduler(pid, /)

Возвращает политику планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. Результат — одна из констант политики планирования выше.

os.sched_setparam(pid, param, /)

Установить параметры планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. param — экземпляр sched_param.

os.sched_getparam(pid, /)

Возвращает параметры планирования в виде экземпляра sched_param для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс.

os.sched_rr_get_interval(pid, /)

Возвращает квант времени круговой очереди в секундах для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс.

os.sched_yield()

Добровольно уступает процессор.

os.sched_setaffinity(pid, mask, /)

Ограничить процесс с PID pid (или текущий процесс, если ноль) набором процессоров. mask — итерируемый набор целых чисел, представляющий набор процессоров, к которым должен быть ограничен процесс.

os.sched_getaffinity(pid, /)

Возвращает набор процессоров, к которым ограничен процесс с PID pid.

Если pid равен нулю, возвращает набор процессоров, к которым ограничена вызывающая нить текущего процесса.

См. также функцию process_cpu_count().

Дополнительная системная информация

os.confstr(name, /)

Возвращает строковые значения конфигурации системы. name задает значение конфигурации для извлечения; это может быть строка, которая является именем определенного системного значения; эти имена определены в ряде стандартов (POSIX, Unix 95, Unix 98 и других). Некоторые платформы также определяют дополнительные имена. Имена, известные операционной системе хоста, представлены в виде ключей словаря confstr_names. Для конфигурационных переменных, не включенных в это отображение, также принимается целое число для name.

Если значение конфигурации, заданное name, не определено, возвращается None.

Если name является строкой и не известен, возникает ValueError. Если определенное значение для name не поддерживается системой хоста, даже если оно включено в confstr_names, возникает OSError с номером ошибки errno.EINVAL.

Доступность: Unix.

os.confstr_names

Словарь, сопоставляющий имена, принятые функцией confstr(), со значениями целых чисел, определенных для этих имен операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Доступность: Unix.

os.cpu_count()

Возвращает количество логических процессоров в системе. Возвращает None, если значение неопределено.

Функция process_cpu_count() может быть использована для получения количества логических процессоров, доступных вызывающей потоку текущего процесса.

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

Изменено в версии 3.13: Если указан -X cpu_count или установлена переменная окружения PYTHON_CPU_COUNT, функция cpu_count() возвращает переопределенное значение n.

os.getloadavg()

Возвращает количество процессов в очереди задач системы, усреднённое за последние 1, 5 и 15 минут, или вызывает исключение OSError, если среднее значение нагрузки получить невозможно.

Доступность: Unix.

os.process_cpu_count()

Возвращает количество логических процессоров, доступных вызывающему потоку текущего процесса. Возвращает None, если значение неопределено. Может быть меньше, чем cpu_count(), в зависимости от сродства к процессору.

Функция cpu_count() может быть использована для получения количества логических процессоров в системе.

Если указан -X cpu_count или установлена переменная окружения PYTHON_CPU_COUNT, функция process_cpu_count() возвращает переопределенное значение n.

См. также функцию sched_getaffinity().

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

os.sysconf(name, /)

Возвращает целочисленные значения конфигурации системы. Если значение конфигурации, заданное name, не определено, возвращается -1. Комментарии относительно параметра name для confstr() также применимы здесь; словарь, предоставляющий информацию об известных именах, задаётся sysconf_names.

Доступность: Unix.

os.sysconf_names

Словарь, сопоставляющий имена, принятые функцией sysconf(), со значениями целых чисел, определенных для этих имен операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Доступность: Unix.

Изменено в версии 3.11: Добавить 'SC_MINSIGSTKSZ' имя.

Следующие данные используются для поддержки операций манипулирования путями. Они определены для всех платформ.

Операции высокого уровня с именами путей определены в модуле os.path.

os.curdir

Строковая константа, используемая операционной системой для обозначения текущей директории. Это '.' для Windows и POSIX. Также доступно через os.path.

os.pardir

Строковая константа, используемая операционной системой для обозначения родительской директории. Это '..' для Windows и POSIX. Также доступно через os.path.

os.sep

Символ, используемый операционной системой для разделения компонентов имени пути. Это '/' для POSIX и '\\' для Windows. Обратите внимание, что знание этого не достаточно для анализа или конкатенации имён путей — используйте os.path.split() и os.path.join() — но это иногда полезно. Также доступно через os.path.

os.altsep

Альтернативный символ, используемый операционной системой для разделения компонентов имени пути, или None если существует только один разделитель. Это установлено в '/' на Windows-системах, где sep — это обратный слэш. Также доступно через os.path.

os.extsep

Символ, разделяющий имя файла и расширение, например, '.' в os.py. Также доступно через os.path.

os.pathsep

Символ, обычно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например, ':' для POSIX или ';' для Windows. Также доступно через os.path.

os.defpath

Стандартный путь поиска, используемый функциями exec*p* и spawn*p*, если в среде нет ключа 'PATH'. Также доступно через os.path.

os.linesep

Строка, используемая для разделения (или, точнее, завершения) строк на текущей платформе. Это может быть один символ, например '\n' для POSIX, или несколько символов, например, '\r\n' для Windows. Не используйте os.linesep в качестве разделителя строк при записи файлов, открытых в текстовом режиме (по умолчанию); используйте одиночный '\n' вместо этого на всех платформах.

os.devnull

Путь к файлу нулевого устройства. Например: '/dev/null' для POSIX, 'nul' для Windows. Также доступен через os.path.

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

Флаги для использования с функциями setdlopenflags() и getdlopenflags(). См. страницу руководства Unix dlopen(3), чтобы понять значение различных флагов.

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

Случайные числа

os.getrandom(size, flags=0)

Получить до size случайных байтов. Функция может вернуть меньше байтов, чем запрошено.

Эти байты могут быть использованы для инициализации генераторов случайных чисел в пользовательском пространстве или в криптографических целях.

getrandom() полагается на энтропию, собранную из драйверов устройств и других источников шума окружающей среды. Излишнее чтение больших объёмов данных негативно скажется на других пользователях устройств /dev/random и /dev/urandom.

Аргумент flags — это битовая маска, которая может содержать нулевое или более следующих значений, объединённых операцией «или»: os.GRND_RANDOM и GRND_NONBLOCK.

См. также страницу руководства Linux getrandom().

Доступность: Linux >= 3.17.

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

os.urandom(size, /)

Возвращает строку байтов size случайных байтов, пригодных для криптографического использования.

Эта функция возвращает случайные байты из специфичного для операционной системы источника случайности. Возвращаемые данные должны быть достаточно непредсказуемыми для криптографических приложений, хотя их точное качество зависит от реализации ОС.

В Linux, если доступна системная вызов getrandom(), он используется в режиме блокировки: блокируется до тех пор, пока пул энтропии urandom системы не будет инициализирован (собирается 128 бит энтропии ядром). См. PEP 524 для обоснования. В Linux функция getrandom() может использоваться для получения случайных байтов в режиме без блокировки (используя флаг GRND_NONBLOCK) или для ожидания, пока пул энтропии системы urandom будет инициализирован.

На подобной Unix-системе случайные байты читаются из устройства /dev/urandom. Если устройство /dev/urandom недоступно или не читаемо, генерируется исключение NotImplementedError.

В Windows используется BCryptGenRandom().

См. также

Модуль secrets предоставляет функции более высокого уровня. Для удобного интерфейса с генератором случайных чисел, предоставляемым вашей платформой, см. random.SystemRandom.

Изменено в версии 3.5: В Linux 3.17 и новее используется системный вызов getrandom(), если он доступен. В OpenBSD 5.6 и новее используется функция C getentropy(). Эти функции избегают использования внутреннего дескриптора файла.

Изменено в версии 3.5.2: В Linux, если системный вызов getrandom() блокируется (пул энтропии urandom ещё не инициализирован), происходит откат к чтению из /dev/urandom.

Изменено в версии 3.6: В Linux, getrandom() теперь используется в режиме блокировки для повышения безопасности.

Изменено в версии 3.11: В Windows используется BCryptGenRandom() вместо устаревшего CryptGenRandom().

os.GRND_NONBLOCK

По умолчанию при чтении из /dev/random, getrandom() блокируется, если случайные байты недоступны, а при чтении из /dev/urandom, он блокируется, если пул энтропии ещё не был инициализирован.

Если флаг GRND_NONBLOCK установлен, тогда getrandom() не блокируется в этих случаях, а сразу же генерирует исключение BlockingIOError.

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

os.GRND_RANDOM

Если этот бит установлен, то случайные байты берутся из пула /dev/random вместо пула /dev/urandom.

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