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, не Emscripten, не 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’s merge) (|) и обновления (update) (|=).

os.environb

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

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

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

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

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()

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

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

os.geteuid()

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

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

os.getgid()

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

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

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

os.getgrouplist(user, group, /)

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

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

Введено в версии 3.3.

os.getgroups()

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

Доступность: Unix, не Emscripten, не 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 для определения пользователя и возвращает имя пользователя текущего реального идентификатора пользователя.

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

os.getpgid(pid)

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

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

os.getpgrp()

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

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

os.getpid()

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

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

os.getppid()

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

Доступность: Unix, Windows, не Emscripten, не 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, не Emscripten, не WASI.

Введено в версии 3.3.

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

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

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

Введено в версии 3.3.

os.getresuid()

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

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

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

os.getresgid()

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

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

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

os.getuid()

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

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

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

os.initgroups(username, gid, /)

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

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

Добавлена в версии 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, не Emscripten, не WASI.

os.seteuid(euid, /)

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

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

os.setgid(gid, /)

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

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

os.setgroups(groups, /)

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

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

Примечание

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

os.setpgrp()

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

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

os.setpgid(pid, pgrp, /)

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

Доступность: Unix, не Emscripten, не 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, не Emscripten, не WASI.

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

os.setregid(rgid, egid, /)

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

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

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

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

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

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

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

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

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

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

os.setreuid(ruid, euid, /)

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

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

os.getsid(pid, /)

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

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

os.setsid()

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

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

os.setuid(uid, /)

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

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

os.strerror(code, /)

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

os.supports_bytes_environ

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

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

os.umask(mask, /)

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

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

os.uname()

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

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

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

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

Доступность: 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.

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

Эти функции создают новые объекты файла. (См. также 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. Файлы, на которые указывают src и dst, должны находиться на одной файловой системе, иначе возникает OSError с errno, установленным в errno.EXDEV.

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

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

Доступность: 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: стандартный ввод, 1: стандартный вывод, 2: стандартная ошибка), новый дескриптор файла является наследуемым.

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

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

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

Дублировать дескриптор файла fd в fd2, предварительно закрыв 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.

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

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.

Функция ограничена в Emscripten и 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.

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

Введено в версии 3.5.

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, не Emscripten, не 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() для объектов, похожих на файл, для корректировки указателя позиции файла.

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-runtime; константы флагов (например, 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(). Их можно комбинировать с помощью побитового оператора ИЛИ |. Некоторые из них недоступны на всех платформах. Для описания их доступности и использования см. руководство 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, не Emscripten, не WASI.

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

os.pipe()

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

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

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

os.pipe2(flags, /)

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

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

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

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

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

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

Добавлена в версии 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, не изменяя текущий смещение файла.

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

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

Введено в версии 3.3.

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

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

Аргумент 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.pwrite(fd, str, offset, /)

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

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

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

Введено в версии 3.3.

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

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

Аргумент 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. Возвращает количество отправленных байтов. При достижении конца файла возвращается 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, не Emscripten, не 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, не Emscripten, не WASI.

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

os.SF_NOCACHE

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

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

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

os.set_blocking(fd, blocking, /)

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

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

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

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

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

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

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

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

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

Доступность: 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.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, не Emscripten, не 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 или соответствующее целое значение). Все остальные биты игнорируются.

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

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

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

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

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.

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

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

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

os.chroot(path)

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

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

Изменено в версии 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, не Emscripten, не 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, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

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

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, не Emscripten.

Изменено в версии 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.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(), чтобы установить их.

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

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

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

Добавлена в версии 3.3: Аргумент dir_fd.

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

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

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

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

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

Примечание

makedirs() может столкнуться с ошибкой, если в пути для создания элементов пути содержится pardir (например, «..» в системах UNIX).

Эта функция корректно обрабатывает пути UNC.

Вызывает событие аудита аудита 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()). Обычно FIFO используются в качестве места встречи между процессами типа «клиент» и «сервер»: сервер открывает FIFO для чтения, а клиент — для записи. Обратите внимание, что mkfifo() не открывает FIFO — он просто создаёт точку встречи.

Доступность: Unix, не Emscripten, не 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, не Emscripten, не WASI.

Введено в версии 3.3: Аргумент dir_fd.

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

os.major(device, /)

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

os.minor(device, /)

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

os.makedev(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.

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

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 с аргументами 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 перехватывается и не генерируется.

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() и stat().

Введено в версии 3.5.

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

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

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

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

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

В Windows передача follow_symlinks=False отключит следование всем переименованиям имени, которые включают символичных ссылки и узлы каталогов. Другие типы переименований, которые не похожи на ссылки или которые операционная система не может отслеживать, будут открыты напрямую. При слежении за цепочкой нескольких ссылок это может привести к тому, что исходная ссылка будет возвращена вместо ссылки, которая не позволила полностью проследить путь. Чтобы получить результаты статуса для конечного пути в этом случае, используйте функцию 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

Зависит от платформы:

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

st_atime_ns

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

st_mtime_ns

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

st_ctime_ns

Зависит от платформы:

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

Примечание

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

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

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

st_blocks

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

st_blksize

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

st_rdev

Тип устройства, если это устройство inode.

st_flags

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

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

st_gen

Номер генерации файла.

st_birthtime

Время создания файла.

В 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.

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.3: Добавлены члены st_atime_ns, st_mtime_ns и st_ctime_ns.

Новые возможности в версии 3.5: Добавлен член st_file_attributes на Windows.

Изменено в версии 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 соответственно.

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 (разрешение обязательных блокировок на ФС), ST_WRITE (запись в файл/каталог/символическую ссылку), ST_APPEND (только для добавления файла), ST_IMMUTABLE (неизменяемый файл), ST_NOATIME (не обновлять время доступа), ST_NODIRATIME (не обновлять время доступа к каталогам), ST_RELATIME (обновление времени доступа относительно времени изменения/последнего изменения).

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

Доступность: 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 недоступна на всех поддерживаемых платформах Python. Для обеспечения согласованности функции, которые могут поддерживать 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 недоступна на всех поддерживаемых платформах Python.

Чтобы определить, разрешает ли конкретная функция указание открытого дескриптора файла в качестве параметра 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 недоступна на всех поддерживаемых платформах Python. Для обеспечения согласованности функции, которые могут поддерживать 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 генерируется, когда функция вызывается пользователем без привилегий.

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

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

Функция ограничена в Emscripten и 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 байт.

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

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

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

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

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

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

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

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

Вызывает событие аудита 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().

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

Вызывает событие аудита 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), она возвращает кортеж из 3 элементов (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.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.

Эта функция всегда поддерживает пути, относительные к дескрипторам каталогов и не следование за символическими ссылками. Однако обратите внимание, что, в отличие от других функций, значение по умолчанию для follow_symlinks в fwalk() равно 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 для поиска файла программы. Когда среда заменяется (используя один из вариантов exec*e, обсуждаемых в следующем абзаце), новая среда используется как источник переменной PATH. Другие варианты, execl(), execle(), execv() и execve(), не будут использовать переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь.

Для execle(), execlpe(), execve() и execvpe() (обратите внимание, что они все заканчиваются на “e”), параметр env должен быть отображением, используемым для определения переменных среды для нового процесса (они используются вместо среды текущего процесса); функции execl(), execlp(), execv() и execvp() заставляют новый процесс унаследовать среду текущего процесса.

Для execve() на некоторых платформах path также может быть указан как открытый дескриптор файла. Эта функциональность может быть не поддерживаема на вашей платформе; вы можете проверить её доступность с помощью os.supports_fd. Если она недоступна, использование её вызовет NotImplementedError.

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

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

Введено в версии 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, не Emscripten, не WASI.

os.EX_DATAERR

Код выхода, означающий, что входные данные были некорректны.

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

os.EX_NOINPUT

Код выхода, означающий, что входной файл не существовал или не был доступен для чтения.

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

os.EX_NOUSER

Код выхода, означающий, что указанный пользователь не существует.

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

os.EX_NOHOST

Код выхода, означающий, что указанный хост не существует.

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

os.EX_UNAVAILABLE

Код выхода, означающий, что необходимая служба недоступна.

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

Код выхода, означающий, что указанный пользователем выходной файл не может быть создан.

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

os.EX_IOERR

Код выхода, означающий, что произошла ошибка при выполнении ввода-вывода с некоторым файлом.

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

Код выхода, означающий, что обмен протоколом был незаконным, недействительным или не понят.

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

os.EX_NOPERM

Код выхода, означающий, что для выполнения операции недостаточно прав (но не предназначен для проблем с файловой системой).

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

os.EX_CONFIG

Код выхода, означающий, что произошла какая-то ошибка конфигурации.

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

os.EX_NOTFOUND

Код выхода, означающий что-то вроде «запись не найдена».

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

os.fork()

Создает дочерний процесс. Возвращает 0 в дочернем процессе и идентификатор процесса дочернего процесса в родительском. Если произошла ошибка, возникает OSError.

Обратите внимание, что на некоторых платформах, включая FreeBSD <= 6.3 и Cygwin, существуют известные проблемы при использовании fork() из потока.

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

Предупреждение

В macOS использование этой функции небезопасно при совместном использовании с API системного уровня, что включает использование urllib.request.

Изменено в версии 3.8: Вызов fork() в подинтерпретаторе больше не поддерживается (RuntimeError генерируется).

Предупреждение

См. ssl для приложений, использующих модуль SSL с fork().

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

os.forkpty()

Создает дочерний процесс, используя новый псевдотерминал в качестве управляющего терминала дочернего процесса. Возвращает пару (pid, fd), где pid — 0 в дочернем процессе, новый идентификатор процесса дочернего процесса в родительском, а fd — дескриптор файла главного конца псевдотерминала. Для более переносимого подхода используйте модуль pty. Если произошла ошибка, возникает OSError.

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

Предупреждение

В macOS использование этой функции небезопасно при совместном использовании с API системного уровня, что включает использование urllib.request.

Изменено в версии 3.8: Вызов forkpty() в подинтерпретаторе больше не поддерживается (RuntimeError генерируется).

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

os.kill(pid, sig, /)

Отправить сигнал sig процессу pid. Константы для конкретных сигналов, доступных на платформе, определены в модуле signal.

Windows: Сигналы signal.CTRL_C_EVENT и signal.CTRL_BREAK_EVENT — это специальные сигналы, которые можно отправлять только консольным процессам, совместно использующим одно окно консоли, например, некоторым дочерним процессам. Любое другое значение для sig приведёт к безусловному завершению процесса через API TerminateProcess, и код выхода будет установлен в sig. Windows-версия kill() дополнительно принимает дескрипторы процессов для завершения.

См. также signal.pthread_kill().

Вызывает событие аудита аудита os.kill с аргументами pid, sig.

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

Введено в версии 3.2: Поддержка Windows.

os.killpg(pgid, sig, /)

Отправить сигнал sig группе процессов pgid.

Вызывает событие аудита аудита os.killpg с аргументами pgid, sig.

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

os.nice(increment, /)

Добавить increment к “вежливости” процесса. Вернуть новую вежливость.

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

os.pidfd_open(pid, flags=0)

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

См. страницу руководства pidfd_open(2) для получения более подробной информации.

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

Введено в версии 3.9.

os.plock(op, /)

Заблокировать сегменты программы в памяти. Значение op (определенное в <sys/lock.h>) определяет, какие сегменты блокируются.

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

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; см. документацию этого класса для более мощных способов управления и взаимодействия с дочерними процессами.

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

Примечание

Режим UTF-8 Python влияет на кодировки, используемые для 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().

Параметр 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).

Эти кортежи соответствуют вызовам API библиотеки C posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose(), и posix_spawn_file_actions_adddup2(), используемым для подготовки к самому вызову posix_spawn().

Аргумент setpgroup установит группу процессов дочернего процесса в указанное значение. Если указанное значение равно 0, идентификатор группы процессов дочернего процесса будет таким же, как его идентификатор процесса. Если аргумент setpgroup не задан, дочерний процесс унаследует идентификатор группы процессов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETPGROUP.

Если аргумент resetids равен True, он сбросит эффективный идентификатор пользователя и эффективный идентификатор группы дочернего процесса до реального идентификатора пользователя и реального идентификатора группы родительского процесса. Если аргумент равен False, дочерний процесс сохраняет эффективный идентификатор пользователя и эффективный идентификатор группы родителя. В любом случае, если биты разрешения установки идентификатора пользователя и установки идентификатора группы установлены в исполняемом файле, их действие перекроет установку эффективного идентификатора пользователя и эффективного идентификатора группы. Этот аргумент соответствует флагу библиотеки 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.

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

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, не Emscripten, не WASI.

См. документацию 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, не Emscripten, не WASI.

Введено в версии 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.

Варианты функций spawn* с «l» и «v» отличаются тем, как передаются аргументы командной строки. Варианты с «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, не Emscripten, не WASI.

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 не указано или 'open', это работает так же, как двойной щелчок по файлу в проводнике Windows или передача имени файла в качестве аргумента команде start из интерактивной командной оболочки: файл открывается с помощью любого приложения (если таковое есть), связанного с его расширением.

Когда задано другое значение operation, оно должно быть «глаголом команды», указывающим, что должно быть сделано с файлом. Общие глаголы, документированные Microsoft, это '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, не Emscripten, не WASI.

os.times()

Возвращает текущие глобальные времена процесса. Возвращаемое значение — объект с пятью атрибутами:

• user - время пользователя
• system - время системы
• children_user - время пользователя всех дочерних процессов
• children_system - время системы всех дочерних процессов
• elapsed - прошедшее реальное время с момента фиксированной точки в прошлом

Для обратной совместимости, этот объект также ведет себя как пятиэлементный кортеж, содержащий user, system, children_user, children_system, и elapsed в этом порядке.

См. страницу руководства Unix times(2) и times(3) страницу руководства в Unix или документацию GetProcessTimes MSDN в Windows. В Windows известны только user и system; другие атрибуты равны нулю.

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

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

os.wait()

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

Если нет дочерних процессов, которые можно дождаться, возникает исключение ChildProcessError.

waitstatus_to_exitcode() может быть использован для преобразования кода завершения в код выхода.

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

См. также

Другие функции 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, не Emscripten, не WASI.

Примечание

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

Новая в версии 3.3.

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, не Emscripten, не WASI.

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

os.wait3(options)

Аналогично waitpid(), за исключением того, что аргумент идентификатора процесса отсутствует, и возвращается кортеж из 3 элементов, содержащий идентификатор процесса дочернего процесса, указатель на код завершения и информацию об использовании ресурсов. Подробности о ресурсах см. в resource.getrusage(). Аргумент options такой же, как и для waitpid() и wait4().

waitstatus_to_exitcode() можно использовать для преобразования кода завершения в код выхода.

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

os.wait4(pid, options)

Аналогично waitpid(), за исключением того, что возвращается кортеж из 3 элементов, содержащий идентификатор процесса дочернего процесса, указатель на код завершения и информацию об использовании ресурсов. Подробности о ресурсах см. в resource.getrusage(). Аргументы wait4() такие же, как и для waitpid().

waitstatus_to_exitcode() можно использовать для преобразования кода завершения в код выхода.

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

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, не Emscripten, не WASI.

Примечание

P_PIDFD доступен только на Linux >= 5.4.

Новая в версии 3.3.

Новая в версии 3.9: Константа P_PIDFD.

os.WCONTINUED

Этот флаг options для waitpid(), wait3(), wait4() и waitid() приводит к тому, что дочерние процессы сообщаются, если они были возобновлены из приостановки группы задач после последнего сообщения.

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

os.WEXITED

Этот флаг options для waitid() вызывает сообщение о завершении дочерних процессов.

Другие wait* функции всегда сообщают о завершении дочерних процессов, поэтому этот параметр для них недоступен.

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

Введено в версии 3.3.

os.WSTOPPED

Этот флаг options для waitid() вызывает сообщение о том, что дочерние процессы были остановлены сигналом.

Этот параметр недоступен для других wait* функций.

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

Введено в версии 3.3.

os.WUNTRACED

Этот флаг options для waitpid(), wait3() и wait4() вызывает сообщение о дочерних процессах, которые были остановлены, но их текущее состояние не сообщалось с момента остановки.

Этот параметр недоступен для waitid().

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

os.WNOHANG

Этот флаг options вызывает waitpid(), wait3(), wait4() и waitid() чтобы сразу вернуться, если состояние дочернего процесса недоступно.

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

os.WNOWAIT

Этот флаг options вызывает waitid() оставить дочерний процесс в состоянии ожидания, чтобы впоследствии можно было использовать wait*() вызов для получения информации о статусе дочернего процесса.

Этот параметр недоступен для других wait* функций.

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

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

Возможные значения si_code в результате, возвращаемом waitid().

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

Введено в версии 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, не Emscripten, не WASI.

Введено в версии 3.9.

Следующие функции принимают код состояния процесса, возвращаемый system(), wait() или waitpid() в качестве параметра. Они могут быть использованы для определения состояния процесса.

os.WCOREDUMP(status, /)

Возвращает True если для процесса был сгенерирован дамп ядра, иначе возвращает False.

Эта функция должна использоваться только если WIFSIGNALED() истинно.

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

os.WIFCONTINUED(status)

Возвращает True если остановленный дочерний процесс был возобновлён сигналом SIGCONT (если процесс был продолжен после остановки управления задачами), иначе возвращает False.

См. параметр WCONTINUED.

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

os.WIFSTOPPED(status)

Возвращает True если процесс был остановлен сигналом, иначе возвращает False.

WIFSTOPPED() возвращает True только если вызов waitpid() был сделан с параметром WUNTRACED или если процесс отслеживается (см. ptrace(2)).

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

os.WIFSIGNALED(status)

Возвращает True если процесс был завершен сигналом, иначе возвращает False.

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

os.WIFEXITED(status)

Возвращает True если процесс завершился нормально, вызвав exit() или _exit(), или вернувшись из main(); иначе возвращает False.

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

os.WEXITSTATUS(status)

Возвращает код завершения процесса.

Эта функция должна использоваться только если WIFEXITED() имеет значение true.

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

os.WSTOPSIG(status)

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

Эта функция должна использоваться только если WIFSTOPPED() имеет значение true.

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

os.WTERMSIG(status)

Возвращает номер сигнала, который привел к завершению процесса.

Эта функция должна использоваться только если WIFSIGNALED() имеет значение true.

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

Интерфейс к планировщику

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

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

os.SCHED_OTHER

Политика планирования по умолчанию.

os.SCHED_BATCH

Политика планирования для CPU-ёмких процессов, которая старается сохранить интерактивность остальных процессов на компьютере.

os.SCHED_IDLE

Политика планирования для фоновых задач с чрезвычайно низким приоритетом.

os.SCHED_SPORADIC

Политика планирования для спорадических серверных программ.

os.SCHED_FIFO

Политика планирования «Первый пришёл — первый ушёл».

os.SCHED_RR

Политика планирования с круговым обходом.

os.SCHED_RESET_ON_FORK

Этот флаг может быть объединён с любой другой политикой планирования. Когда процесс с этим флагом выполняет 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 равен нулю, возвращает набор процессоров, к которым ограничен вызывающий поток текущего процесса.

Разное системное информация

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 если количество неопределено.

Это число не эквивалентно количеству логических процессоров, которые может использовать текущий процесс. len(os.sched_getaffinity(0)) получает количество логических процессоров, к которому ограничен вызывающий поток текущего процесса.

Новая в версии 3.4.

os.getloadavg()

Возвращает количество процессов в очереди выполнения системы, усреднённых за последние 1, 5 и 15 минут, или поднимает исключение OSError, если усреднённое значение загрузки было недоступно.

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

os.sysconf(name, /)

Возвращает целочисленные значения системной конфигурации. Если значение конфигурации, указанное параметром name, не определено, возвращается -1. Комментарии к параметру name для confstr() также применимы здесь; словарь, предоставляющий информацию об известных именах, задаётся sysconf_names.

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

os.sysconf_names

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

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

Изменено в версии 3.11: Добавлен 'SC_MINSIGSTKSZ' name.

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

Операции более высокого уровня над именами путей определены в модуле 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.6.0: В Linux теперь используется getrandom() в режиме блокировки, чтобы повысить безопасность.

Изменено в версии 3.5.2: В Linux, если вызов getrandom() блокируется (пул энтропии urandom ещё не инициализирован), используется чтение /dev/urandom.

Изменено в версии 3.5: В Linux 3.17 и более поздних версиях, при доступности, используется вызов getrandom(). В OpenBSD 5.6 и более поздних версиях используется функция C getentropy(). Эти функции избегают использования внутреннего дескриптора файла.

Изменено в версии 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.