`os` – Различные интерфейсы операционной системы

Исходный код: Lib/os.py

Этот модуль предоставляет переносимый способ использования функциональности, зависящей от операционной системы. Если вам нужно просто прочитать или записать файл, обратитесь к open(); если требуется работать с путями, используйте модуль os.path; а если нужно прочитать все строки из всех файлов, указанных в командной строке, используйте модуль fileinput. Для создания временных файлов и каталогов обратитесь к модулю tempfile, а для высокоуровневой работы с файлами и каталогами – к модулю shutil.

Примечания о доступности этих функций:

Дизайн всех встроенных модулей Python, зависящих от операционной системы, таков: пока доступна одинаковая функциональность, используется единый интерфейс; например, функция os.stat(path) возвращает информацию stat о пути в одном и том же формате (который происходит от интерфейса POSIX).
Расширения, характерные для конкретной операционной системы, также доступны через модуль os, но их использование, конечно, угрожает переносимости.
Все функции, принимающие пути или имена файлов, принимают как объекты bytes, так и строки, и возвращают объект того же типа, если возвращается путь или имя файла.
На VxWorks os.popen, os.fork, os.execv и os.spawn*p* не поддерживаются.
На платформах WebAssembly, Android и iOS большие части модуля os недоступны или ведут себя иначе. API, связанные с процессами (например, fork(), execve()) и ресурсами (например, nice()), недоступны. Другие, такие как getuid() и getpid(), эмулируются или являются заглушками. Платформы WebAssembly также не поддерживают сигналы (например, kill(), wait()).

Примечание

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

exception os.error¶: Псевдоним для встроенного исключения OSError.

os.name¶: Имя импортированного модуля, зависящего от операционной системы. В настоящее время зарегистрированы следующие имена: 'posix', 'nt', 'java'.

Смотрите также

sys.platform имеет более мелкую гранулярность. os.uname() предоставляет информацию о версии, зависящую от системы.

Модуль platform предоставляет подробные проверки идентичности системы.

File Names, Command Line Arguments, and Environment VariablesИмена файлов, аргументы командной строки и переменные окружения

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

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

Изменено в версии 3.1: В некоторых системах преобразование с использованием кодировки файловой системы может завершиться ошибкой. В этом случае Python использует обработчик ошибок кодирования surrogateescape, что означает, что не поддающиеся декодированию байты заменяются на символ Юникода U+DCxx при декодировании, и затем они снова преобразуются в исходный байт при кодировании.

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

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

Python UTF-8 ModeРежим UTF-8 Python

Добавлено в версии 3.7: См. PEP 540 для получения дополнительных сведений.

Изменено в версии 3.15: Режим UTF-8 Python теперь включён по умолчанию (PEP 686). Его можно отключить, установив PYTHONUTF8=0 в качестве переменной окружения или с помощью параметра командной строки -X utf8=0.

Режим UTF-8 Python игнорирует кодировку локали и принудительно использует кодировку 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. Однако по умолчанию они по-прежнему используют строгий обработчик ошибок, так что попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не приведёт к бессмысленным данным.

Режим UTF-8 Python включён по умолчанию. Его можно отключить с помощью параметра командной строки -X utf8=0 или PYTHONUTF8=0 переменной окружения. Режим UTF-8 Python можно отключить только при запуске Python. Его значение можно прочитать из sys.flags.utf8_mode.

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

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

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

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

os.ctermid()¶: Возвращает имя файла, соответствующее управляющему терминалу процесса.

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

os.environ¶

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

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

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

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

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

Примечание

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

Примечание

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

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

Смотрите также

Функция os.reload_environ().

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

os.environb¶

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

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

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

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

os.reload_environ()¶: Отображения os.environ и os.environb являются кешем переменных окружения на момент запуска Python. Поэтому изменения в текущем окружении процесса не отражаются, если они сделаны вне Python или с помощью os.putenv() или os.unsetenv(). Используйте os.reload_environ() для обновления os.environ и os.environb с учётом таких изменений в текущем окружении процесса.

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

Эта функция не является потокобезопасной. Вызов её в то время, когда окружение изменяется в другом потоке, приводит к неопределённому поведению. Чтение из os.environ или os.environb, или вызов os.getenv() во время перезагрузки может вернуть пустой результат.

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

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

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

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

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

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

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

os.getgrouplist(user, group, /)¶: Возвращает список идентификаторов групп, к которым принадлежит user. Если group нет в списке, он включается; обычно group указывается как поле идентификатора группы из записи пароля для user, так как этот идентификатор группы иначе может быть пропущен.

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

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

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

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

Примечание

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

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

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

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

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

os.getpgrp()¶: Возвращает идентификатор текущей группы процессов.

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

os.getpid()¶

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

На WASI эта функция является заглушкой; подробнее см. платформы WebAssembly.

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

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

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

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

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

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

os.PRIO_PROCESS¶
os.PRIO_PGRP¶
os.PRIO_USER¶: Параметры для функций getpriority() и setpriority().

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

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

os.PRIO_DARWIN_THREAD¶
os.PRIO_DARWIN_PROCESS¶
os.PRIO_DARWIN_BG¶
os.PRIO_DARWIN_NONUI¶: Параметры для функций getpriority() и setpriority().

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

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

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

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

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

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

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

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

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

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

На WASI эта функция является заглушкой; подробнее см. платформы WebAssembly.

os.initgroups(username, gid, /)¶: Вызывает системный вызов initgroups() для инициализации списка доступа групп со всеми группами, в которые входит указанное имя пользователя, а также указанный идентификатор группы.

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

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

os.putenv(key, value, /)¶

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

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

См. также функцию os.reload_environ().

Примечание

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

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

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

os.setegid(egid, /)¶: Устанавливает эффективный идентификатор группы текущего процесса.

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

os.seteuid(euid, /)¶: Устанавливает эффективный идентификатор пользователя текущего процесса.

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

os.setgid(gid, /)¶: Устанавливает идентификатор группы текущего процесса.

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

os.setgroups(groups, /)¶: Устанавливает список дополнительных идентификаторов групп, связанных с текущим процессом, в groups. groups должен быть последовательностью, и каждый элемент должен быть целым числом, идентифицирующим группу. Эта операция обычно доступна только суперпользователю.

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

Примечание

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

os.setns(fd, nstype=0)¶

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

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

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

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

Этот пример перепривязывает поток к сетевому пространству имён процесса init:

python

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

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

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

Смотрите также

Функция unshare().

os.setpgrp()¶: Вызывает системный вызов setpgrp() или setpgrp(0, 0) в зависимости от того, какая версия реализована (если таковая имеется). Смотрите руководство Unix для получения информации о семантике.

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

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

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

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

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

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

os.setregid(rgid, egid, /)¶: Устанавливает реальный и эффективный идентификаторы группы текущего процесса.

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

os.setresgid(rgid, egid, sgid, /)¶: Устанавливает реальный, эффективный и сохранённый идентификаторы группы текущего процесса.

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

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

os.setresuid(ruid, euid, suid, /)¶: Устанавливает реальный, эффективный и сохранённый идентификаторы пользователя текущего процесса.

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

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

os.setreuid(ruid, euid, /)¶: Устанавливает реальный и эффективный идентификаторы пользователя текущего процесса.

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

os.getsid(pid, /)¶: Вызывает системный вызов getsid(). Семантика описана в руководстве Unix.

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

os.setsid()¶: Вызывает системный вызов setsid(). Семантика описана в руководстве Unix.

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

os.setuid(uid, /)¶: Устанавливает идентификатор пользователя текущего процесса.

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

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

os.supports_bytes_environ¶: True, если собственный тип окружения ОС – байты (например, False в Windows).

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

os.umask(mask, /)¶

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

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

os.uname()¶

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

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

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

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

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

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

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

os.unsetenv(key, /)¶

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

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

См. также функцию os.reload_environ().

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

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

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

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

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

Смотрите также

Функция setns().

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

os.CLONE_FILES¶
os.CLONE_FS¶
os.CLONE_NEWCGROUP¶
os.CLONE_NEWIPC¶
os.CLONE_NEWNET¶
os.CLONE_NEWNS¶
os.CLONE_NEWPID¶
os.CLONE_NEWTIME¶
os.CLONE_NEWUSER¶
os.CLONE_NEWUTS¶
os.CLONE_SIGHAND¶
os.CLONE_SYSVSEM¶
os.CLONE_THREAD¶
os.CLONE_VM¶

File Object CreationСоздание файловых объектов

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

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

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

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

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

python

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

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

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

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

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

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

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

Примечание

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

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

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

os.device_encoding(fd)¶

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

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

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

os.dup(fd, /)¶

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

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

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

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

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

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

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

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

os.fchmod(fd, mode)¶

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

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

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

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

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

os.fchown(fd, uid, gid)¶

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

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

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

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

os.fdatasync(fd)¶: Принудительно записывает файл с файловым дескриптором fd на диск. Не выполняет принудительное обновление метаданных.

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

Примечание

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

os.fpathconf(fd, name, /)¶

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

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

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

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

os.fstat(fd)¶

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

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

Смотрите также

Функция stat().

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

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

os.fsync(fd)¶

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

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

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

os.ftruncate(fd, length, /)¶

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

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

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

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

os.get_blocking(fd, /)¶

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

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

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

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

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

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

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

os.grantpt(fd, /)¶

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

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

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

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

os.isatty(fd, /)¶: Возвращает True, если файловый дескриптор fd открыт и подключён к (псевдо)терминальному устройству, иначе 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 управляющим терминалом, stdin, stdout и stderr вызывающего процесса; закрывает fd.

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

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

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

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

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

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

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

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

SEEK_SET: Настраивает позицию в файле относительно его начала.
SEEK_CUR: Корректирует позицию в файле относительно текущей позиции.
SEEK_END: Корректирует позицию в файле относительно конца файла.

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

os.SEEK_HOLE¶

os.SEEK_DATA¶

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

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

Примечание

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

Следующие константы являются опциями для параметра flags функции open(). Их можно комбинировать с помощью оператора побитового ИЛИ |. Некоторые из них доступны не на всех платформах. За описанием их доступности и использования обращайтесь к странице руководства 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 Kernel 3.11 или новее.

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

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

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

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

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

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

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

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

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

os.posix_fallocate(fd, offset, len, /)¶: Гарантирует выделение достаточного дискового пространства для файла, указанного fd, начиная со смещения offset и длиной len байт.

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

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

os.posix_fadvise(fd, offset, len, advice, /)¶: Объявляет намерение обращаться к данным в определённом шаблоне, что позволяет ядру выполнять оптимизации. Совет (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.posix_openpt(oflag, /)¶

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

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

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

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

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

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

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

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

RWF_HIPRI
RWF_NOWAIT
RWF_DONTCACHE

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

Операционная система может установить ограничение (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.RWF_DONTCACHE¶: Использовать некэшированный буферизованный ввод-вывод.

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

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

os.RWF_ATOMIC¶: Атомарная запись данных. Требует выравнивания в соответствии с единицей атомарной записи устройства.

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

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

os.ptsname(fd, /)¶

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

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

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

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

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

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

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

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

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

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

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

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

RWF_DSYNC
RWF_SYNC
RWF_APPEND
RWF_DONTCACHE
RWF_ATOMIC

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

Операционная система может установить ограничение (значение 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 os.open() для каждой записи. Действие этого флага распространяется только на диапазон данных, записываемых системным вызовом.

Поддержка: Linux >= 4.7.

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

os.RWF_SYNC¶: Предоставляет эквивалент флага O_SYNC os.open() для каждой записи. Действие этого флага распространяется только на диапазон данных, записываемых системным вызовом.

Поддержка: Linux >= 4.7.

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

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

Поддержка: 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.readinto(fd, buffer, /)¶

Читает из файлового дескриптора fd в изменяемый буферный объект buffer.

buffer должен быть изменяемым и байтоподобным. В случае успеха возвращает количество прочитанных байт. Может быть прочитано меньше байт, чем размер буфера. Базовый системный вызов будет повторен при прерывании сигналом, если только обработчик сигнала не вызывает исключение. Другие ошибки не повторяются, и будет вызвана ошибка.

Возвращает 0, если fd находится в конце файла или если предоставленный buffer имеет длину 0 (что может использоваться для проверки ошибок без чтения данных). Никогда не возвращает отрицательное значение.

Примечание

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

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

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

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

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

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

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

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

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

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

Кроссплатформенные приложения не должны использовать аргументы headers, trailers и flags.

Поддержка: Unix, не WASI.

Примечание

Для высокоуровневой обёртки sendfile() см. socket.socket.sendfile().

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

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

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

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

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

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

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

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

os.set_blocking(fd, blocking, /)¶

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

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

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

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

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

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

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

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

Переносит count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst.

Поведение при сращивании можно изменить, указав значение flags. Могут использоваться любые из следующих переменных, комбинируемые с помощью побитового ИЛИ (оператор |):

Если указан SPLICE_F_MOVE, ядру предлагается перемещать страницы вместо копирования, но страницы всё равно могут быть скопированы, если ядро не может переместить их из канала.
Если указан SPLICE_F_NONBLOCK, ядру предлагается не блокироваться при вводе-выводе. Это делает операции сращивания каналов неблокирующими, но splice всё равно может блокироваться, поскольку сращиваемые файловые дескрипторы могут быть блокирующими.
Если указан SPLICE_F_MORE, это указывает ядру, что в последующем вызове splice будет передано больше данных.

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

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

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

Смотрите также

Справочная страница splice(2).

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

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

os.SPLICE_F_MOVE¶
os.SPLICE_F_NONBLOCK¶
os.SPLICE_F_MORE¶: Добавлено в версии 3.10.

os.readv(fd, buffers, /)¶

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

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

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

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

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

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

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

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

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

os.ttyname(fd, /)¶: Возвращает строку, которая определяет устройство терминала, связанное с файловым дескриптором fd. Если fd не связан с устройством терминала, возбуждается исключение.

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

os.unlockpt(fd, /)¶

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

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

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

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

os.write(fd, str, /)¶

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

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

Примечание

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

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

os.writev(fd, buffers, /)¶

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

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

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

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

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

Querying the size of a terminalЗапрос размера терминала

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

os.get_terminal_size(fd=STDOUT_FILENO, /)¶

Возвращает размер окна терминала в виде (columns, lines), кортежа типа terminal_size.

Необязательный аргумент fd (по умолчанию STDOUT_FILENO, или стандартный вывод) указывает, какой файловый дескриптор следует опросить.

Если файловый дескриптор не подключён к терминалу, возбуждается OSError.

shutil.get_terminal_size() – это высокоуровневая функция, которую следует использовать в обычных случаях; os.get_terminal_size – это низкоуровневая реализация.

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

class os.terminal_size¶

Подкласс кортежа, содержащий (columns, lines) размера окна терминала.

columns¶: Ширина окна терминала в символах.

lines¶: Высота окна терминала в символах.

Inheritance of File DescriptorsНаследование файловых дескрипторов

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

Файловый дескриптор имеет флаг «наследуемости», который указывает, может ли файловый дескриптор быть унаследован дочерними процессами. Начиная с Python 3.4, файловые дескрипторы, созданные Python, по умолчанию не наследуются.

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

В Windows ненаследуемые дескрипторы (handles) и файловые дескрипторы закрываются в дочерних процессах, за исключением стандартных потоков (файловые дескрипторы 0, 1 и 2: stdin, stdout и stderr), которые всегда наследуются. При использовании функций spawn* все наследуемые дескрипторы и все наследуемые файловые дескрипторы наследуются. При использовании модуля subprocess все файловые дескрипторы, кроме стандартных потоков, закрываются, а наследуемые дескрипторы наследуются только если параметр close_fds равен False.

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

os.get_inheritable(fd, /)¶: Получить флаг «наследуемости» указанного файлового дескриптора (логическое значение).

os.set_inheritable(fd, inheritable, /)¶: Установить флаг «наследуемости» указанного файлового дескриптора.

os.get_handle_inheritable(handle, /)¶: Получить флаг «наследуемости» указанного дескриптора (handle) (логическое значение).

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

os.set_handle_inheritable(handle, inheritable, /)¶: Установить флаг «наследуемости» указанного дескриптора (handle).

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

Files and DirectoriesФайлы и каталоги

На некоторых платформах 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. Например:

python

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

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

python

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)¶: Изменяет корневой каталог текущего процесса на path.

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

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

os.fchdir(fd)¶

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

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

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

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

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

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

os.lchflags(path, flags)¶

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

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

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

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

os.lchmod(path, mode)¶

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

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

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

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

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

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

os.lchown(path, uid, gid)¶

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

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

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')¶

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

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

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

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

Примечание

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

Смотрите также

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

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

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

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

Изменено в версии 3.15: os.listdir(-1) теперь завершается ошибкой с OSError(errno.EBADF) вместо получения списка текущего каталога.

os.listdrives()¶

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

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

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

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

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

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

os.listmounts(volume)¶

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

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

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

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

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

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

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

os.listvolumes()¶

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

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

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

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

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

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

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

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

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

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

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

Смотрите также

Функция stat().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Порождает событие аудита 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, не 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.S_IFCHR и stat.S_IFBLK параметр device определяет вновь создаваемый специальный файл устройства (вероятно, с помощью os.makedev()); в противном случае он игнорируется.

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

Доступность: Unix, не 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.NODEV¶: Несуществующее устройство.

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

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 является объектом bytes (напрямую или косвенно), результатом будет объект bytes.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)¶

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

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

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

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

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

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

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

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

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

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

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

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

os.renames(old, new)¶

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')¶

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

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

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

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

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

scandir.close()¶

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

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

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

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

python

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.

Изменено в версии 3.15: os.scandir(-1) теперь завершается ошибкой OSError(errno.EBADF) вместо перечисления текущего каталога.

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¶

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

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

path¶

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

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

inode()¶

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

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

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

is_dir(*, follow_symlinks=True)¶

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

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

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

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

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

is_file(*, follow_symlinks=True)¶

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

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

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

is_symlink()¶

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

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

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

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

is_junction()¶

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

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

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

stat(*, follow_symlinks=True)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

python

>>> 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 отключает следование по всем точкам повторной обработки, замещающим имена (name surrogate). Если операционная система достигает точки повторной обработки, которую она не может обработать, stat теперь возвращает информацию для исходного пути, как если бы было указано follow_symlinks=False, вместо возбуждения ошибки.

class os.stat_result¶

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

Атрибуты:

st_mode¶: Режим файла: тип файла и биты режима файла (права доступа).

st_ino¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

st_blocks¶: Количество блоков по 512 байт, выделенных для файла. Может быть меньше st_size/512, если файл содержит дырки (holes).

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

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

st_flags¶: Определяемые пользователем флаги для файла.

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

st_gen¶: Номер поколения файла.

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

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

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

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

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

st_type¶: Тип файла.

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

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

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

st_reparse_tag¶: Когда у st_file_attributes установлен FILE_ATTRIBUTE_REPARSE_POINT, это поле содержит тег, идентифицирующий тип точки повторной обработки. Смотрите константы IO_REPARSE_TAG_* в модуле stat.

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

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

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

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

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

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

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

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

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

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

os.statx(path, mask, *, flags=0, dir_fd=None, follow_symlinks=True)¶

Получает статус файла или файлового дескриптора, выполняя системный вызов statx() по указанному пути.

path – это объект, подобный пути или открытый файловый дескриптор. mask – это комбинация констант модуля STATX_*, задающая запрашиваемую информацию. flags – это комбинация констант модуля AT_STATX_* и/или AT_NO_AUTOMOUNT. Возвращает объект statx_result, чей атрибут stx_mask указывает фактически полученную информацию (которая может отличаться от mask).

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

Смотрите также

Страница руководства statx(2).

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

class os.statx_result¶

Информация о файле, возвращаемая os.statx().

statx_result имеет следующие атрибуты:

stx_atime¶

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

Равно None, если STATX_ATIME отсутствует в stx_mask.

stx_atime_ns¶

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

Равно None, если STATX_ATIME отсутствует в stx_mask.

stx_atomic_write_segments_max¶

Максимальное количество iovec для прямого ввода-вывода с защитой от разрывов при записи.

Равно None, если STATX_WRITE_ATOMIC отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра на время сборки >= 6.11.

stx_atomic_write_unit_max¶

Максимальный размер для прямого ввода-вывода с защитой от разрывов при записи.

Равно None, если STATX_WRITE_ATOMIC отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра на время сборки >= 6.11.

stx_atomic_write_unit_max_opt¶

Максимальный оптимизированный размер для прямого ввода-вывода с защитой от разрывов при записи.

Равно None, если STATX_WRITE_ATOMIC отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра на время сборки >= 6.16.

stx_atomic_write_unit_min¶

Минимальный размер для прямого ввода-вывода с защитой от разрывов при записи.

Равно None, если STATX_WRITE_ATOMIC отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра на время сборки >= 6.11.

stx_attributes¶: Битовая маска констант STATX_ATTR_*, определяющих атрибуты этого файла.

stx_attributes_mask¶: Маска, указывающая, какие биты в stx_attributes поддерживаются VFS и файловой системой.

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

stx_blocks¶

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

Равно None, если STATX_BLOCKS отсутствует в stx_mask.

stx_btime¶

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

Равно None, если STATX_BTIME отсутствует в stx_mask.

stx_btime_ns¶

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

Равно None, если STATX_BTIME отсутствует в stx_mask.

stx_ctime¶

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

Равно None, если STATX_CTIME отсутствует в stx_mask.

stx_ctime_ns¶

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

Равно None, если STATX_CTIME отсутствует в stx_mask.

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

stx_dev_major¶: Старший номер устройства, на котором находится этот файл.

stx_dev_minor¶: Младший номер устройства, на котором находится этот файл.

stx_dio_mem_align¶

Требование к выравниванию буфера памяти при прямом вводе-выводе.

Равно None, если STATX_DIOALIGN отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра времени сборки >= 6.1.

stx_dio_offset_align¶

Требование к выравниванию смещения файла при прямом вводе-выводе.

Равно None, если STATX_DIOALIGN отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра времени сборки >= 6.1.

stx_dio_read_offset_align¶

Требование к выравниванию смещения файла при прямом вводе-выводе для чтения.

Равно None, если STATX_DIO_READ_ALIGN отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками API пользовательского пространства ядра времени сборки >= 6.14.

stx_gid¶

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

Равно None, если STATX_GID отсутствует в stx_mask.

stx_ino¶

Номер инода.

Равно None, если STATX_INO отсутствует в stx_mask.

stx_mask¶: Битовая маска STATX_* констант, определяющая полученную информацию, которая может отличаться от запрошенной.

stx_mnt_id¶

Идентификатор точки монтирования.

Равно None, если STATX_MNT_ID отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками userspace API ядра времени сборки >= 5.8.

stx_mode¶

Режим файла: тип файла и биты режима (права доступа).

Равно None, если STATX_TYPE | STATX_MODE отсутствует в stx_mask.

stx_mtime¶

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

Равно None, если STATX_MTIME отсутствует в stx_mask.

stx_mtime_ns¶

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

Равно None, если STATX_MTIME отсутствует в stx_mask.

stx_nlink¶

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

Равно None, если STATX_NLINK отсутствует в stx_mask.

stx_rdev¶: Тип устройства, если индексный дескриптор является устройством.

stx_rdev_major¶: Старший номер устройства, которое представляет этот файл.

stx_rdev_minor¶: Младший номер устройства, которое представляет этот файл.

stx_size¶

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

Равно None, если STATX_SIZE отсутствует в stx_mask.

stx_subvol¶

Идентификатор подтома.

Равно None, если STATX_SUBVOL отсутствует в stx_mask.

Доступность: Linux >= 4.11 с glibc >= 2.28 и заголовками userspace API ядра времени сборки >= 6.10.

stx_uid¶

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

Равно None, если STATX_UID отсутствует в stx_mask.

Смотрите также

Страница руководства statx(2).

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

os.STATX_TYPE¶
os.STATX_MODE¶
os.STATX_NLINK¶
os.STATX_UID¶
os.STATX_GID¶
os.STATX_ATIME¶
os.STATX_MTIME¶
os.STATX_CTIME¶
os.STATX_INO¶
os.STATX_SIZE¶
os.STATX_BLOCKS¶
os.STATX_BASIC_STATS¶
os.STATX_BTIME¶
os.STATX_MNT_ID¶
os.STATX_DIOALIGN¶
os.STATX_MNT_ID_UNIQUE¶
os.STATX_SUBVOL¶
os.STATX_WRITE_ATOMIC¶
os.STATX_DIO_READ_ALIGN¶: Битовые флаги для использования в параметре mask функции os.statx(). Некоторые из этих флагов могут быть доступны, даже если соответствующие им члены в statx_result недоступны.

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

os.AT_STATX_FORCE_SYNC¶: Флаг для функции os.statx(). Указывает ядру возвращать актуальную информацию, даже если это требует значительных затрат (например, требует обращения к серверу для файла в сетевой файловой системе).

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

os.AT_STATX_DONT_SYNC¶: Флаг для функции os.statx(). Запрашивает, чтобы ядро возвращало кешированную информацию, если это возможно.

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

os.AT_STATX_SYNC_AS_STAT¶: Флаг для функции os.statx(). Этот флаг определён как 0, поэтому он не оказывает никакого эффекта, но может использоваться, чтобы явно указать, что не передаётся ни AT_STATX_FORCE_SYNC, ни AT_STATX_DONT_SYNC. В отсутствие двух других флагов ядро обычно возвращает информацию настолько свежую, как если бы был вызван os.stat().

Доступность: Linux >= 4.11 с glibc >= 2.28.

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

os.AT_NO_AUTOMOUNT¶: Если последний компонент пути представляет собой точку автомонтирования, то операции выполняются над этой точкой, а не выполняется само автомонтирование. В Linux os.stat(), os.fstat() и os.lstat() всегда работают так.

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

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

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 (обновлять atime относительно mtime/ctime).

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

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

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

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

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

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

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

os.supports_dir_fd¶

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

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

python

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 на локальной платформе:

python

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 на локальной платформе:

python

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() на локальной платформе:

python

os.stat in os.supports_follow_symlinks

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

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

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

Параметр src указывает на цель ссылки (файл или каталог, на который указывает ссылка), а dst – это имя создаваемой ссылки.

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

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

Примечание

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

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

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

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

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

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

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

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

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

os.sync()¶: Принудительная запись всего на диск.

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

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

os.truncate(path, length)¶

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

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

Вызывает событие аудита 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, он должен быть кортежем из двух элементов вида (atime_ns, mtime_ns), где каждый элемент – целое число, выражающее наносекунды.
Если times не равен None, он должен быть кортежем из двух элементов вида (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: Принимает объект, подобный пути.

Изменено в версии 3.15: Принимает любые вещественные числа в качестве times, а не только целые числа или числа с плавающей запятой.

os.walk(top, topdown=True, onerror=None, followlinks=False)¶

Создаёт имена файлов в дереве каталогов, обходя дерево сверху вниз или снизу вверх. Для каждого каталога в дереве с корнем в каталоге top (включая сам top) возвращает кортеж из трёх элементов (dirpath, dirnames, filenames).

dirpath – строка, путь к каталогу. dirnames – список имён подкаталогов в dirpath (включая символические ссылки на каталоги, и исключая '.' и '..'). filenames – список имён файлов, не являющихся каталогами, в dirpath. Обратите внимание, что имена в списках не содержат компонентов пути. Чтобы получить полный путь (начинающийся с top) к файлу или каталогу в dirpath, выполните os.path.join(dirpath, name). Отсортированы ли списки, зависит от файловой системы. Если файл удалён из или добавлен в каталог dirpath во время создания списков, не определено, будет ли имя этого файла включено.

Если необязательный аргумент topdown равен True или не указан, кортеж для каталога создаётся до кортежей для любых его подкаталогов (каталоги создаются сверху вниз). Если topdown равен False, кортеж для каталога создаётся после кортежей для всех его подкаталогов (каталоги создаются снизу вверх). Независимо от значения topdown, список подкаталогов извлекается до того, как будут созданы кортежи для каталога и его подкаталогов.

Когда topdown равен True, вызывающий может изменить список dirnames на месте (возможно, используя del или присваивание среза), и walk() будет рекурсивно обходить только те подкаталоги, имена которых остались в dirnames; это можно использовать для сокращения поиска, установления определённого порядка обхода или даже для уведомления walk() о каталогах, которые вызывающий создаёт или переименовывает до того, как он возобновит walk() снова. Изменение dirnames, когда topdown равен False, не влияет на поведение walk, потому что в режиме снизу вверх каталоги в dirnames создаются до того, как будет создан сам dirpath.

По умолчанию ошибки от вызова scandir() игнорируются. Если указан необязательный аргумент onerror, он должен быть функцией; она будет вызвана с одним аргументом, экземпляром OSError. Она может сообщить об ошибке, чтобы продолжить обход, или вызвать исключение, чтобы прервать обход. Обратите внимание, что имя файла доступно как атрибут filename объекта исключения.

По умолчанию walk() не будет обходить символические ссылки, указывающие на каталоги. Установите followlinks в True, чтобы посещать каталоги, на которые указывают символические ссылки, в системах, поддерживающих их.

Примечание

Имейте в виду, что установка followlinks в True может привести к бесконечной рекурсии, если ссылка указывает на родительский каталог самой себя. walk() не отслеживает уже посещённые каталоги.

Примечание

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

Этот пример выводит количество байт, занимаемое файлами (не каталогами) в каждом каталоге внутри начального каталога, за исключением того, что он не заглядывает в подкаталог __pycache__:

python

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # не заходить в каталоги __pycache__

В следующем примере (простая реализация shutil.rmtree()) обход дерева снизу вверх необходим, rmdir() не позволяет удалять каталог до того, как каталог будет пуст:

python

# Удалить всё доступное из каталога, указанного в "top",
# при условии отсутствия символических ссылок.
# ВНИМАНИЕ: Это опасно! Например, если top == '/', это
# может удалить все ваши файлы на диске.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

Возбуждает событие аудита os.walk с аргументами top, topdown, onerror, followlinks.

Изменено в версии 3.5: Эта функция теперь вызывает os.scandir() вместо os.listdir(), что делает её быстрее за счёт уменьшения количества вызовов os.stat().

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

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)¶

Эта функция ведёт себя точно так же, как walk(), за исключением того, что возвращает кортеж из 4 элементов (dirpath, dirnames, filenames, dirfd) и поддерживает dir_fd.

dirpath, dirnames и filenames идентичны выводу walk(), а dirfd – это файловый дескриптор, ссылающийся на каталог dirpath.

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

Примечание

Поскольку fwalk() возвращает файловые дескрипторы, они действительны только до следующего шага итерации, поэтому следует их дублировать (например, с помощью dup()), если нужно сохранить их дольше.

python

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/xml'):
    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 '__pycache__' in dirs:
        dirs.remove('__pycache__')  # не заходить в каталоги __pycache__

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

python

# Удалить всё доступное из каталога, указанного в "top",
# при условии отсутствия символических ссылок.
# ВНИМАНИЕ: Это опасно! Например, если top == '/', это
# может удалить все ваши файлы на диске.
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() и подобные. См. man-страницу eventfd(2) для получения дополнительной информации. По умолчанию новый дескриптор файла является ненаследуемым.

initval – это начальное значение счётчика событий. Начальное значение должно быть 32-битным целым без знака. Обратите внимание, что начальное значение ограничено 32-битным unsigned int, хотя счётчик событий является 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.

Пример:

python

import os

# семафор с начальным значением '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFD_CLOEXEC)
try:
    # захватить семафор
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # освободить семафор
        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¶: Устанавливает флаг close-on-exec для нового файлового дескриптора 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.

Timer File DescriptorsТаймерные файловые дескрипторы

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

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

os.timerfd_create(clockid, /, *, flags=0)¶

Создаёт и возвращает таймерный файловый дескриптор (timerfd).

Файловый дескриптор, возвращаемый timerfd_create(), поддерживает:

Метод read() файлового дескриптора можно вызвать с размером буфера 8. Если таймер сработал один или несколько раз, read() возвращает количество срабатываний в порядке байтов хоста, которое может быть преобразовано в int с помощью int.from_bytes(x, byteorder=sys.byteorder).

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

clockid должно быть допустимым идентификатором часов (clock ID), как определено в модуле time:

time.CLOCK_REALTIME
time.CLOCK_MONOTONIC
time.CLOCK_BOOTTIME (начиная с Linux 3.15 для timerfd_create)

Если clockid равно time.CLOCK_REALTIME, используются настраиваемые системные часы реального времени. Если системные часы изменяются, настройки таймера необходимо обновить. Чтобы отменить таймер при изменении системных часов, см. TFD_TIMER_CANCEL_ON_SET.

Если clockid равно time.CLOCK_MONOTONIC, используются ненастраиваемые монотонно возрастающие часы. Даже если системные часы изменяются, настройка таймера не будет затронута.

Если clockid равно time.CLOCK_BOOTTIME, то же самое, что и time.CLOCK_MONOTONIC, за исключением того, что включает время, в течение которого система была приостановлена.

Поведение файлового дескриптора можно изменить, указав значение flags. Можно использовать любую из следующих переменных, комбинируя их с помощью побитового ИЛИ (оператор |):

TFD_NONBLOCK
TFD_CLOEXEC

Если TFD_NONBLOCK не установлен как флаг, read() блокируется до истечения таймера. Если он установлен как флаг, read() не блокируется, но если с момента последнего вызова read не было срабатываний, read() вызывает OSError с errno, установленным в errno.EAGAIN.

TFD_CLOEXEC всегда устанавливается автоматически Python.

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

Смотрите также

Справочная страница timerfd_create(2).

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)¶

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

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

Поведение таймера можно изменить, указав значение flags. Можно использовать любые из следующих переменных, комбинируя их с помощью побитового ИЛИ (оператор |):

TFD_TIMER_ABSTIME
TFD_TIMER_CANCEL_ON_SET

Таймер отключается установкой initial в ноль (0). Если initial больше или равен нулю, таймер включается. Если initial меньше нуля, возбуждается исключение OSError с errno, установленным в errno.EINVAL

По умолчанию таймер срабатывает по истечении initial секунд. (Если initial равен нулю, таймер сработает немедленно.)

Однако если установлен флаг TFD_TIMER_ABSTIME, таймер срабатывает, когда часы таймера (заданные clockid в timerfd_create()) достигают initial секунд.

Интервал таймера задаётся вещественным числом interval. Если interval равен нулю, таймер срабатывает только один раз, при первом истечении времени. Если interval больше нуля, таймер срабатывает каждый раз по истечении interval секунд с момента предыдущего срабатывания. Если interval меньше нуля, возбуждается OSError с errno, установленным в errno.EINVAL

Если флаг TFD_TIMER_CANCEL_ON_SET установлен вместе с TFD_TIMER_ABSTIME и часы для этого таймера являются time.CLOCK_REALTIME, таймер помечается как отменяемый, если системные часы реального времени изменяются скачкообразно. Чтение дескриптора прерывается с ошибкой ECANCELED.

Linux управляет системными часами как UTC. Переход на летнее время осуществляется только изменением часового сдвига и не вызывает скачкообразного изменения системных часов.

Скачкообразное изменение системных часов вызывается следующими событиями:

settimeofday
clock_settime
установка даты и времени системы с помощью команды date

Возвращает кортеж из двух элементов (next_expiration, interval) предыдущего состояния таймера до выполнения этой функции.

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)¶: Аналогично timerfd_settime(), но использует время в наносекундах. Эта функция управляет тем же интервальным таймером, что и timerfd_settime().

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.timerfd_gettime(fd, /)¶

Возвращает кортеж из двух чисел с плавающей запятой (next_expiration, interval).

next_expiration обозначает относительное время до следующего срабатывания таймера, независимо от того, установлен ли флаг TFD_TIMER_ABSTIME.

interval обозначает интервал таймера. Если ноль, таймер сработает только один раз, по истечении next_expiration секунд.

Смотрите также

timerfd_gettime(2)

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.timerfd_gettime_ns(fd, /)¶: Аналогично timerfd_gettime(), но возвращает время в наносекундах.

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.TFD_NONBLOCK¶: Флаг для функции timerfd_create(), который устанавливает флаг состояния O_NONBLOCK для нового файлового дескриптора таймера. Если TFD_NONBLOCK не установлен как флаг, read() блокируется.

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.TFD_CLOEXEC¶: Флаг для функции timerfd_create(). Если TFD_CLOEXEC установлен как флаг, устанавливает флаг close-on-exec для нового файлового дескриптора.

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.TFD_TIMER_ABSTIME¶: Флаг для функций timerfd_settime() и timerfd_settime_ns(). Если этот флаг установлен, initial интерпретируется как абсолютное значение на часах таймера (в секундах UTC или наносекундах с начала эпохи Unix).

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.TFD_TIMER_CANCEL_ON_SET¶: Флаг для функций timerfd_settime() и timerfd_settime_ns() вместе с TFD_TIMER_ABSTIME. Таймер отменяется при скачкообразном изменении времени базовых часов.

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

Linux extended attributesРасширенные атрибуты Linux

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

Все эти функции доступны только в Linux.

os.getxattr(path, attribute, *, follow_symlinks=True)¶

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

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

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

Изменено в версии 3.6: Принимает path-подобный объект для path и attribute.

os.listxattr(path=None, *, follow_symlinks=True)¶

Возвращает список расширенных атрибутов файловой системы для path. Атрибуты в списке представлены в виде строк, декодированных с использованием кодировки файловой системы. Если path равен None, listxattr() будет проверять текущий каталог.

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

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

Изменено в версии 3.15: os.listxattr(-1) теперь завершается ошибкой с OSError(errno.EBADF), а не перечисляет расширенные атрибуты текущего каталога.

os.removexattr(path, attribute, *, follow_symlinks=True)¶

Удаляет расширенный атрибут файловой системы attribute из path. attribute должен быть bytes или str (напрямую или косвенно через интерфейс PathLike). Если это строка, она кодируется с помощью кодировки файловой системы и обработчика ошибок.

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

Изменено в версии 3.6: Принимает path-подобный объект для path и attribute.

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)¶

Устанавливает расширенный атрибут файловой системы attribute для path в значение value. attribute должен быть bytes или str без встроенных NUL (напрямую или косвенно через интерфейс PathLike). Если это str, он кодируется с помощью кодировки файловой системы и обработчика ошибок. flags может быть XATTR_REPLACE или XATTR_CREATE. Если указан XATTR_REPLACE и атрибут не существует, будет вызвано ENODATA. Если указан XATTR_CREATE и атрибут уже существует, атрибут не будет создан и будет вызвано EEXISTS.

Примечание

Ошибка в версиях ядра Linux ниже 2.6.39 приводила к игнорированию аргумента flags в некоторых файловых системах.

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

Изменено в версии 3.6: Принимает path-подобный объект для path и attribute.

os.XATTR_SIZE_MAX¶: Максимальный размер значения расширенного атрибута. В настоящее время в Linux это 64 КБ.

os.XATTR_CREATE¶: Это возможное значение аргумента flags в setxattr(). Оно означает, что операция должна создать атрибут.

os.XATTR_REPLACE¶: Это возможное значение для аргумента flags в setxattr(). Оно указывает, что операция должна заменить существующий атрибут.

Process ManagementУправление процессами

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

Различные функции 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.

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

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

Текущий процесс заменяется немедленно. Открытые файловые объекты и дескрипторы не сбрасываются, поэтому, если в этих открытых файлах могут быть буферизованы данные, их следует сбросить с помощью flush() или os.fsync() перед вызовом функции exec*.

Варианты «l» и «v» функций exec* различаются способом передачи аргументов командной строки. Варианты «l», вероятно, проще всего использовать, если количество параметров фиксировано на момент написания кода; отдельные параметры просто становятся дополнительными параметрами функций execl*(). Варианты «v» хороши, когда количество параметров переменное, при этом аргументы передаются в виде списка или кортежа в параметре args. В любом случае аргументы дочернего процесса должны начинаться с имени запускаемой команды, но это не является обязательным.

Варианты, содержащие «p» ближе к концу (execlp(), execlpe(), execvp() и execvpe()), используют переменную окружения PATH для поиска программы file. Когда окружение заменяется (с помощью одного из вариантов exec*e, обсуждаемых в следующем абзаце), новое окружение используется как источник переменной PATH. Другие варианты – execl(), execle(), execv() и execve() – не используют переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь. Относительные пути должны содержать хотя бы один слэш, даже в Windows, так как простые имена не будут разрешены.

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

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

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

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

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

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

os._exit(n)¶: Завершает процесс с кодом состояния n, не вызывая обработчики очистки, не сбрасывая буферы stdio и т.д.

Примечание

Стандартный способ завершения – sys.exit(n). _exit() обычно должен использоваться только в дочернем процессе после fork().

Следующие коды завершения определены и могут использоваться с _exit(), хотя они не обязательны. Обычно они применяются в системных программах, написанных на Python, например, во внешней программе доставки команд почтового сервера.

Примечание

Некоторые из них могут быть недоступны на всех платформах Unix из-за некоторых различий. Эти константы определены там, где они определены базовой платформой.

os.EX_OK¶: Код завершения, означающий, что ошибок не произошло. На некоторых платформах может быть взят из определённого значения EXIT_SUCCESS. Обычно равен нулю.

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

os.EX_USAGE¶: Код завершения, означающий, что команда была использована неправильно, например, когда указано неверное количество аргументов.

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

os.EX_DATAERR¶: Код завершения, означающий, что входные данные были некорректны.

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

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

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

os.EX_NOUSER¶: Код завершения, означающий, что указанный пользователь не существовал.

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

os.EX_NOHOST¶: Код завершения, означающий, что указанный хост не существовал.

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

os.EX_UNAVAILABLE¶: Код завершения, означающий, что требуемая служба недоступна.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.fork()¶

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

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

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

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

Если в приложении, вызывающем fork(), используются TLS-сокеты, см. предупреждение в документации ssl.

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

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

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

Изменено в версии 3.12: Если Python может обнаружить, что процесс имеет несколько потоков, os.fork() теперь выбрасывает DeprecationWarning.

Мы решили показывать это предупреждение, когда это возможно обнаружить, чтобы лучше информировать разработчиков о проблеме проектирования, которую платформа POSIX явно отмечает как неподдерживаемую. Даже в коде, который кажется работающим, на платформах POSIX никогда не было безопасно смешивать многопоточность с os.fork(). Сама среда выполнения CPython всегда выполняла вызовы API, которые небезопасны для использования в дочернем процессе, когда в родительском существовали потоки (например, malloc и free).

Пользователи macOS, а также пользователи библиотек libc или malloc, отличных от тех, что обычно встречаются в glibc, входят в число тех, кто уже с большей вероятностью столкнётся с взаимными блокировками при выполнении такого кода.

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

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

os.forkpty()¶

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

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

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

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

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

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

Изменено в версии 3.12: Если Python может обнаружить, что процесс имеет несколько потоков, теперь это возбуждает DeprecationWarning. Подробное объяснение см. в os.fork().

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

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

os.kill(pid, sig, /)¶

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

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

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

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

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

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

os.killpg(pgid, sig, /)¶

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

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

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

os.nice(increment, /)¶: Добавляет increment к значению «niceness» процесса. Возвращает новое значение niceness.

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

os.pidfd_open(pid, flags=0)¶

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

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

Доступность: Linux >= 5.3, Android >= build-time API level 31

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

os.PIDFD_NONBLOCK¶: Этот флаг указывает, что файловый дескриптор будет неблокирующим. Если процесс, на который ссылается файловый дескриптор, ещё не завершился, то попытка ожидания на файловом дескрипторе с помощью waitid(2) немедленно вернёт ошибку EAGAIN вместо блокирования.

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

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

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

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

os.popen(cmd, mode='r', buffering=-1)¶

Открывает канал (pipe) к команде cmd или от неё. Возвращается открытый файловый объект, подключенный к каналу, который можно читать или записывать в зависимости от того, является ли mode 'r' (по умолчанию) или 'w'. Аргумент buffering имеет то же значение, что и соответствующий аргумент встроенной функции open(). Возвращаемый файловый объект читает или записывает текстовые строки, а не байты.

Метод close возвращает None, если подпроцесс завершился успешно, или код возврата подпроцесса, если произошла ошибка. В системах POSIX, если код возврата положительный, он представляет собой возвращаемое значение процесса, сдвинутое влево на один байт. Если код возврата отрицательный, процесс был завершён сигналом, заданным отрицательным значением кода возврата. (Например, возвращаемое значение может быть - signal.SIGKILL, если подпроцесс был убит.) В системах Windows возвращаемое значение содержит знаковый целочисленный код возврата от дочернего процесса.

В Unix waitstatus_to_exitcode() можно использовать для преобразования результата метода close (статус выхода) в код выхода, если он не равен None. В Windows результат метода close непосредственно является кодом выхода (или None).

Это реализовано с помощью subprocess.Popen; обратитесь к документации этого класса для получения более мощных способов управления подпроцессами и взаимодействия с ними.

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

Примечание

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

popen() – это простая обёртка вокруг subprocess.Popen. Используйте subprocess.Popen или subprocess.run() для управления такими параметрами, как кодировки.

Мягко устарело начиная с версии 3.14: Вместо этого рекомендуется использовать модуль subprocess.

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

Обёртывает API библиотеки C posix_spawn() для использования из Python.

Большинству пользователей следует использовать subprocess.run() вместо posix_spawn().

Позиционные аргументы path, args и env аналогичны аргументам execve(). env может быть None, в этом случае используется окружение текущего процесса.

Параметр path – это путь к исполняемому файлу. path должен содержать каталог. Используйте posix_spawnp(), чтобы передать исполняемый файл без каталога.

Аргумент file_actions может быть последовательностью кортежей, описывающих действия над определёнными файловыми дескрипторами в дочернем процессе между шагами fork() и exec() реализации библиотеки C. Первый элемент каждого кортежа должен быть одним из трёх перечисленных ниже типовых индикаторов, описывающих остальные элементы кортежа:

os.POSIX_SPAWN_OPEN¶

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

Выполняет os.dup2(os.open(path, flags, mode), fd).

os.POSIX_SPAWN_CLOSE¶

(os.POSIX_SPAWN_CLOSE, fd)

Выполняет os.close(fd).

os.POSIX_SPAWN_DUP2¶

(os.POSIX_SPAWN_DUP2, fd, new_fd)

Выполняет os.dup2(fd, new_fd).

os.POSIX_SPAWN_CLOSEFROM¶

(os.POSIX_SPAWN_CLOSEFROM, fd)

Выполняет os.closerange(fd, INF).

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

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

Если аргумент resetids равен True, он сбрасывает эффективный UID и GID дочернего процесса до реальных UID и GID родительского процесса. Если аргумент равен False, дочерний процесс сохраняет эффективные UID и GID родителя. В любом случае, если на исполняемом файле установлены биты разрешений set-user-ID и set-group-ID, их действие переопределит установку эффективных UID и GID. Этот аргумент соответствует флагу POSIX_SPAWN_RESETIDS библиотеки C.

Если аргумент setsid равен True, он создаёт новый идентификатор сессии для posix_spawn. setsid требует флаг POSIX_SPAWN_SETSID или POSIX_SPAWN_SETSID_NP. В противном случае возбуждается NotImplementedError.

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

Аргумент sigdef сбрасывает диспозицию всех сигналов в указанном наборе. Этот аргумент соответствует флагу POSIX_SPAWN_SETSIGDEF библиотеки C.

Аргумент scheduler должен быть кортежем, содержащим (необязательную) политику планировщика и экземпляр sched_param с параметрами планировщика. Значение None вместо политики планировщика означает, что она не предоставлена. Этот аргумент является комбинацией флагов C-библиотеки POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDULER.

Порождает событие аудита os.posix_spawn с аргументами path, argv, env.

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

Изменено в версии 3.13: Параметр env принимает None. os.POSIX_SPAWN_CLOSEFROM доступен на платформах, где существует posix_spawn_file_actions_addclosefrom_np().

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

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

Обёртка над C API библиотеки posix_spawnp() для использования из Python.

Аналогично posix_spawn(), за исключением того, что система ищет исполняемый файл в списке каталогов, заданном переменной окружения PATH (так же, как и для execvp(3)).

Порождает событие аудита os.posix_spawn с аргументами path, argv, env.

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

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

См. документацию posix_spawn().

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)¶

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

before – это функция, вызываемая перед порождением дочернего процесса.
after_in_parent – это функция, вызываемая из родительского процесса после порождения дочернего процесса.
after_in_child – это функция, вызываемая из дочернего процесса.

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

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

Обратите внимание, что вызовы fork(), выполняемые сторонним кодом на C, могут не вызывать эти функции, если только в нём не будут явно вызваны PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child().

Невозможно отменить регистрацию функции.

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

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

os.spawnl(mode, path, ...)¶

os.spawnle(mode, path, ..., env)¶

os.spawnlp(mode, file, ...)¶

os.spawnlpe(mode, file, ..., env)¶

os.spawnv(mode, path, args)¶

os.spawnve(mode, path, args, env)¶

os.spawnvp(mode, file, args)¶

os.spawnvpe(mode, file, args, env)¶

Выполняет программу path в новом процессе.

(Обратите внимание, что модуль subprocess предоставляет более мощные средства для запуска новых процессов и получения их результатов; предпочтительнее использовать этот модуль, а не данные функции. Обратите особое внимание на раздел Замена старых функций модулем подпроцесс.)

Если mode равен P_NOWAIT, эта функция возвращает идентификатор нового процесса; если mode равен P_WAIT, возвращает код возврата процесса, если он завершился нормально, или -signal, где signal – сигнал, который завершил процесс. В Windows идентификатор процесса на самом деле является дескриптором процесса, поэтому его можно использовать с функцией waitpid().

Примечание: на VxWorks эта функция не возвращает -signal, когда новый процесс завершается. Вместо этого она порождает исключение OSError.

Варианты с буквами «l» и «v» функций spawn* различаются способом передачи аргументов командной строки. Варианты «l», пожалуй, проще в использовании, если количество параметров фиксировано на момент написания кода; отдельные параметры просто становятся дополнительными аргументами функций spawnl*(). Варианты «v» удобны, когда количество параметров переменное – аргументы передаются в виде списка или кортежа в качестве параметра args. В любом случае аргументы дочернего процесса должны начинаться с имени запускаемой команды.

Варианты, содержащие вторую букву «p» ближе к концу (spawnlp(), spawnlpe(), spawnvp() и spawnvpe()), используют переменную окружения PATH для поиска программы file. Когда окружение заменяется (с использованием одного из вариантов spawn*e, описанных в следующем абзаце), новое окружение используется в качестве источника переменной PATH. Другие варианты – spawnl(), spawnle(), spawnv() и spawnve() – не используют переменную PATH для поиска исполняемого файла; path должен содержать подходящий абсолютный или относительный путь.

Для spawnle(), spawnlpe(), spawnve() и spawnvpe() (обратите внимание: все они заканчиваются на «e») параметр env должен быть отображением, которое используется для определения переменных окружения нового процесса (они используются вместо окружения текущего процесса); функции spawnl(), spawnlp(), spawnv() и spawnvp() заставляют новый процесс наследовать окружение текущего процесса. Обратите внимание, что ключи и значения в словаре env должны быть строками; недопустимые ключи или значения приведут к сбою функции, возвращаемое значение – 127.

В качестве примера, следующие вызовы spawnlp() и spawnvpe() эквивалентны:

python

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

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

Доступность: Unix, Windows; недоступна на WASI, Android, iOS.

spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не являются потокобезопасными в Windows; рекомендуем использовать модуль subprocess вместо них.

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

Мягко устарело начиная с версии 3.14: Вместо этого рекомендуется модуль subprocess.

os.P_NOWAIT¶
os.P_NOWAITO¶: Возможные значения для параметра mode семейства функций spawn*. Если указано одно из этих значений, функции spawn* вернутся сразу после создания нового процесса, возвращая идентификатор процесса.

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

os.P_WAIT¶: Возможное значение для параметра mode семейства функций spawn*. Если в качестве mode указано это значение, функции spawn* не вернутся, пока новый процесс не завершит выполнение, и вернут код возврата процесса в случае успешного выполнения, или -signal, если сигнал завершит процесс.

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

os.P_DETACH¶
os.P_OVERLAY¶: Возможные значения для параметра mode семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH аналогичен P_NOWAIT, но новый процесс отсоединяется от консоли вызывающего процесса. Если используется P_OVERLAY, текущий процесс будет заменен; функция spawn* не вернется.

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

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])¶

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

Если operation не указан, это действует как двойной щелчок по файлу в проводнике Windows или передача имени файла в качестве аргумента команде start в интерактивной командной оболочке: файл открывается в том приложении (если оно есть), с которым связано его расширение.

Если указан другой operation, это должен быть «командный глагол», определяющий, что должно быть сделано с файлом. Обычные глаголы, задокументированные Microsoft: 'open', 'print' и 'edit' (для файлов), а также 'explore' и 'find' (для каталогов).

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

Рабочий каталог по умолчанию наследуется, но может быть переопределен аргументом cwd. Он должен быть абсолютным путем. Относительный path будет разрешаться относительно этого аргумента.

Используйте 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 для полезных рецептов.

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

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

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

os.times()¶

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

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

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

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

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

os.wait()¶

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

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

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

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

Смотрите также

Другие функции wait*(), описанные ниже, можно использовать для ожидания завершения конкретного дочернего процесса, и они имеют больше возможностей. waitpid() – единственная функция, также доступная в Windows.

os.waitid(idtype, id, options, /)¶

Ожидает завершения дочернего процесса.

idtype может быть P_PID, P_PGID, P_ALL или (в Linux) P_PIDFD. Интерпретация id зависит от него; см. описания каждого из них.

options представляет собой OR-комбинацию флагов. Как минимум один из WEXITED, WSTOPPED или WCONTINUED обязателен; WNOHANG и WNOWAIT – дополнительные необязательные флаги.

Возвращаемое значение – объект, представляющий данные, содержащиеся в структуре siginfo_t, со следующими атрибутами:

si_pid (идентификатор процесса)
si_uid (реальный UID дочернего процесса)
si_signo (всегда SIGCHLD)
si_status (код выхода или номер сигнала, в зависимости от si_code)
si_code (возможные значения см. в CLD_EXITED)

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

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

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

Изменено в версии 3.13: Эта функция теперь также доступна на macOS.

os.waitpid(pid, options, /)¶

Подробности этой функции различаются в Unix и Windows.

В Unix: ожидает завершения дочернего процесса, заданного идентификатором процесса pid, и возвращает кортеж, содержащий его идентификатор процесса и показатель статуса завершения (кодируется как для wait()). Семантика вызова зависит от значения целочисленного параметра options, который для нормальной работы должен быть 0.

Если pid больше 0, waitpid() запрашивает информацию о статусе для этого конкретного процесса. Если pid равен 0, запрос относится к статусу любого дочернего процесса в группе процессов текущего процесса. Если pid равен -1, запрос относится к любому дочернему процессу текущего процесса. Если pid меньше -1, запрашивается статус любого процесса в группе процессов -pid (абсолютное значение pid).

options представляет собой комбинацию флагов по ИЛИ. Если он содержит WNOHANG и нет соответствующих дочерних процессов в запрошенном состоянии, возвращается (0, 0). В противном случае, если нет соответствующих дочерних процессов, которых можно было бы ожидать, возбуждается ChildProcessError. Другие опции, которые могут быть использованы: WUNTRACED и WCONTINUED.

В Windows: ожидает завершения процесса, заданного дескриптором процесса pid, и возвращает кортеж, содержащий pid и его статус завершения, сдвинутый влево на 8 бит (сдвиг упрощает кроссплатформенное использование функции). Значение pid, меньшее или равное 0, не имеет специального смысла в Windows и вызывает исключение. Значение целочисленного параметра options не влияет. pid может ссылаться на любой процесс, чей идентификатор известен, не обязательно дочерний. Функции spawn*, вызванные с P_NOWAIT, возвращают подходящие дескрипторы процессов.

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

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

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

os.wait3(options)¶

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

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

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

os.wait4(pid, options)¶

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

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

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

os.P_PID¶

os.P_PGID¶

os.P_ALL¶

os.P_PIDFD¶

Это возможные значения для idtype в waitid(). Они влияют на то, как интерпретируется id:

P_PID – ожидать дочерний процесс, чей PID равен id.
P_PGID – ожидать любой дочерний процесс, чей идентификатор группы процессов равен id.
P_ALL – ожидать любой дочерний процесс; id игнорируется.
P_PIDFD – ожидать дочерний процесс, идентифицируемый файловым дескриптором id (файловый дескриптор процесса, созданный с помощью pidfd_open()).

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

Примечание

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

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

Добавлено в версии 3.9: Константа P_PIDFD.

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

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

os.WEXITED¶

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

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

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

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

os.WSTOPPED¶

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

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

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

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

os.WUNTRACED¶

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

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

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

os.WNOHANG¶: Этот флаг options заставляет waitpid(), wait3(), wait4() и waitid() немедленно возвращаться, если статус дочернего процесса недоступен сразу.

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

os.WNOWAIT¶

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

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

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

os.CLD_EXITED¶
os.CLD_KILLED¶
os.CLD_DUMPED¶
os.CLD_TRAPPED¶
os.CLD_STOPPED¶
os.CLD_CONTINUED¶: Это возможные значения si_code в результате, возвращаемом waitid().

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

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

Изменено в версии 3.9: Добавлены значения CLD_KILLED и CLD_STOPPED.

os.waitstatus_to_exitcode(status)¶

Преобразует статус ожидания в код выхода.

В Unix:

Если процесс завершился нормально (если WIFEXITED(status) истинно), возвращается статус завершения процесса (возвращается WEXITSTATUS(status)): результат больше или равен 0.
Если процесс был завершён сигналом (если WIFSIGNALED(status) истинно), возвращается -signum, где signum – номер сигнала, вызвавшего завершение процесса (возвращается -WTERMSIG(status)): результат меньше 0.
В противном случае вызывается ValueError.

В Windows возвращает статус, сдвинутый вправо на 8 бит.

В Unix, если процесс трассируется или если waitpid() был вызван с опцией WUNTRACED, вызывающий должен сначала проверить, истинно ли WIFSTOPPED(status). Эта функция не должна вызываться, если WIFSTOPPED(status) истинно.

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

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

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

os.WCOREDUMP(status, /)¶

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

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

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

os.WIFCONTINUED(status)¶

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

Смотрите опцию WCONTINUED.

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

os.WIFSTOPPED(status)¶

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

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

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

os.WIFSIGNALED(status)¶: Возвращает True, если процесс был завершён сигналом, иначе возвращает False.

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

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

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

os.WEXITSTATUS(status)¶

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

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

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

os.WSTOPSIG(status)¶

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

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

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

os.WTERMSIG(status)¶

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

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

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

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

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

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

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

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

os.SCHED_BATCH¶: Политика планирования для процессов с интенсивным использованием процессора, которая стремится сохранить интерактивность остальной части компьютера.

os.SCHED_DEADLINE¶: Политика планирования для задач с ограничениями по срокам.

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

os.SCHED_IDLE¶: Политика планирования для фоновых задач с очень низким приоритетом.

os.SCHED_NORMAL¶: Псевдоним для SCHED_OTHER.

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

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

os.SCHED_FIFO¶: Политика планирования «первым пришёл – первым обслужен».

os.SCHED_RR¶: Политика планирования с циклическим перебором (round-robin).

os.SCHED_RESET_ON_FORK¶: Этот флаг можно комбинировать по ИЛИ с любой другой политикой планирования. Когда процесс с установленным этим флагом выполняет форк, политика планирования и приоритет его дочернего процесса сбрасываются на значения по умолчанию.

class os.sched_param(sched_priority)¶

Этот класс представляет настраиваемые параметры планирования, используемые в sched_setparam(), sched_setscheduler() и sched_getparam(). Он неизменяем.

На данный момент возможен только один параметр:

sched_priority¶: Приоритет планирования для политики планирования.

os.sched_get_priority_min(policy)¶: Возвращает минимальное значение приоритета для policy. policy – одна из констант политик планирования, приведённых выше.

os.sched_get_priority_max(policy)¶: Возвращает максимальное значение приоритета для policy. policy – одна из констант политики планирования, перечисленных выше.

os.sched_setscheduler(pid, policy, param, /)¶: Устанавливает политику планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. policy – одна из констант политики планирования, перечисленных выше. param – экземпляр sched_param.

os.sched_getscheduler(pid, /)¶: Возвращает политику планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. Результат – одна из констант политики планирования, перечисленных выше.

os.sched_setparam(pid, param, /)¶: Устанавливает параметры планирования для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс. param – экземпляр sched_param.

os.sched_getparam(pid, /)¶: Возвращает параметры планирования в виде экземпляра sched_param для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс.

os.sched_rr_get_interval(pid, /)¶: Возвращает квант времени при циклическом планировании (round-robin) в секундах для процесса с PID pid. Значение pid, равное 0, означает вызывающий процесс.

os.sched_yield()¶: Добровольно освобождает центральный процессор. Подробнее см. sched_yield(2).

os.sched_setaffinity(pid, mask, /)¶: Ограничивает процесс с PID pid (или текущий процесс, если ноль) набором CPU. mask – итерируемый объект целых чисел, представляющий набор CPU, к которому должен быть ограничен процесс.

os.sched_getaffinity(pid, /)¶

Возвращает набор CPU, к которому ограничен процесс с PID pid.

Если pid равно нулю, возвращает набор CPU, к которому ограничен вызывающий поток текущего процесса.

См. также функцию process_cpu_count().

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

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

Возвращает количество логических CPU в системе. Возвращает None, если не удаётся определить.

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

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

Изменено в версии 3.13: Если указан -X cpu_count или установлен PYTHON_CPU_COUNT, cpu_count() возвращает переопределённое значение n.

os.getloadavg()¶: Возвращает количество процессов в очереди выполнения системы, усреднённое за последние 1, 5 и 15 минут, или возбуждает OSError, если средняя загрузка не может быть получена.

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

os.process_cpu_count()¶

Возвращает количество логических процессоров, доступных вызывающему потоку текущего процесса. Возвращает None, если не определено. Может быть меньше cpu_count() в зависимости от привязки к процессорам (CPU affinity).

Функция cpu_count() может использоваться для получения количества логических процессоров в системе.

Если задан -X cpu_count или установлен PYTHON_CPU_COUNT, process_cpu_count() возвращает переопределённое значение n.

См. также функцию sched_getaffinity().

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

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

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

os.sysconf_names¶: Словарь, отображающий имена, принимаемые sysconf(), в целочисленные значения, определённые для этих имён операционной системой. Может использоваться для определения набора имён, известных системе.

Доступность: Unix.

Изменено в версии 3.11: Добавлено имя 'SC_MINSIGSTKSZ'.

Следующие значения данных используются для поддержки операций с путями. Они определены для всех платформ.

Операции более высокого уровня над именами путей определены в модуле os.path.

os.curdir¶: Строковая константа, используемая операционной системой для обозначения текущего каталога. Для Windows и POSIX это '.'. Также доступна через os.path.

os.pardir¶: Строковая константа, используемая операционной системой для обозначения родительского каталога. Для Windows и POSIX это '..'. Также доступна через os.path.

os.sep¶: Символ, используемый операционной системой для разделения компонентов пути. Для POSIX это '/', для Windows – '\\'. Обратите внимание, что знания этого недостаточно для разбора или объединения путей – используйте os.path.split() и os.path.join(), – но иногда это бывает полезно. Также доступен через os.path.

os.altsep¶: Альтернативный символ, используемый операционной системой для разделения компонентов пути, или None, если существует только один разделитель. В системах Windows, где sep является обратной косой чертой, установлен '/'. Также доступен через os.path.

os.extsep¶: Символ, отделяющий основное имя файла от расширения; например, '.' в os.py. Также доступен через os.path.

os.pathsep¶: Символ, обычно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например ':' для POSIX или ';' для Windows. Также доступен через os.path.

os.defpath¶: Путь поиска по умолчанию, используемый exec*p* и spawn*p*, если в окружении отсутствует ключ 'PATH'. Также доступен через os.path.

os.linesep¶: Строка, используемая для разделения (или, точнее, завершения) строк на текущей платформе. Это может быть один символ, например '\n' для POSIX, или несколько символов, например '\r\n' для Windows. Не используйте os.linesep в качестве разделителя строк при записи файлов, открытых в текстовом режиме (по умолчанию); вместо него на всех платформах используйте одиночный '\n'.

os.devnull¶: Путь к нулевому устройству. Например: '/dev/null' для POSIX, 'nul' для Windows. Также доступен через os.path.

os.RTLD_LAZY¶
os.RTLD_NOW¶
os.RTLD_GLOBAL¶
os.RTLD_LOCAL¶
os.RTLD_NODELETE¶
os.RTLD_NOLOAD¶
os.RTLD_DEEPBIND¶: Флаги для использования с функциями setdlopenflags() и getdlopenflags(). См. страницу руководства Unix dlopen(3) для пояснения значений различных флагов.

Добавлено в версии 3.3.

Random numbersСлучайные числа

os.getrandom(size, flags=0)¶

Возвращает до size случайных байт. Функция может вернуть меньше байт, чем запрошено.

Эти байты можно использовать для инициализации генераторов случайных чисел в пространстве пользователя или в криптографических целях.

getrandom() полагается на энтропию, собираемую из драйверов устройств и других источников шума окружения. Чрезмерное чтение больших объёмов данных отрицательно скажется на других пользователях устройств /dev/random и /dev/urandom.

Аргумент flags представляет собой битовую маску, которая может содержать ноль или более следующих значений, объединённых операцией OR: os.GRND_RANDOM и GRND_NONBLOCK.

См. также страницу руководства Linux getrandom().

Доступность: Linux >= 3.17.

Добавлено в версии 3.6.

os.urandom(size, /)¶

Возвращает строку байт длиной size случайных байт, подходящую для криптографического использования.

Эта функция возвращает случайные байты из источника случайности, зависящего от ОС. Возвращаемые данные должны быть достаточно непредсказуемыми для криптографических приложений, хотя их точное качество зависит от реализации ОС.

В Linux, если доступен системный вызов getrandom(), он используется в блокирующем режиме: блокировка до инициализации пула энтропии urandom (ядро собирает 128 бит энтропии). См. PEP 524 для обоснования. В Linux функция getrandom() может использоваться для получения случайных байт в неблокирующем режиме (с флагом GRND_NONBLOCK) или для опроса до момента инициализации пула энтропии urandom.

В Unix-подобных системах случайные байты читаются из устройства /dev/urandom. Если устройство /dev/urandom недоступно или нечитаемо, возникает исключение NotImplementedError.

В Windows используется BCryptGenRandom().

Смотрите также

Модуль secrets предоставляет функции более высокого уровня. Для простого интерфейса к генератору случайных чисел вашей платформы обратитесь к random.SystemRandom.

Изменено в версии 3.5: В Linux версии 3.17 и новее теперь используется системный вызов getrandom() при его доступности. На OpenBSD 5.6 и новее теперь используется функция C getentropy(). Эти функции позволяют избежать использования внутреннего файлового дескриптора.

Изменено в версии 3.5.2: В Linux, если системный вызов getrandom() блокируется (пул энтропии urandom ещё не инициализирован), происходит откат на чтение /dev/urandom.

Изменено в версии 3.6: В Linux getrandom() теперь используется в блокирующем режиме для повышения безопасности.

Изменено в версии 3.11: В Windows используется BCryptGenRandom() вместо CryptGenRandom(), который является устаревшим.

os.GRND_NONBLOCK¶

По умолчанию при чтении из /dev/random, getrandom() блокируется, если нет доступных случайных байтов, а при чтении из /dev/urandom блокируется, если пул энтропии ещё не инициализирован.

Если установлен флаг GRND_NONBLOCK, то getrandom() не блокируется в этих случаях, а вместо этого немедленно генерирует исключение BlockingIOError.

Добавлено в версии 3.6.

os.GRND_RANDOM¶: Если этот бит установлен, то случайные байты берутся из пула /dev/random вместо пула /dev/urandom.

Добавлено в версии 3.6.

os – Различные интерфейсы операционной системы​

File Names, Command Line Arguments, and Environment VariablesИмена файлов, аргументы командной строки и переменные окружения​

Python UTF-8 ModeРежим UTF-8 Python​

Process ParametersПараметры процесса​

File Object CreationСоздание файловых объектов​

File Descriptor OperationsОперации с файловыми дескрипторами​

Querying the size of a terminalЗапрос размера терминала​

Inheritance of File DescriptorsНаследование файловых дескрипторов​

Files and DirectoriesФайлы и каталоги​

Timer File DescriptorsТаймерные файловые дескрипторы​

Linux extended attributesРасширенные атрибуты Linux​

Process ManagementУправление процессами​

Interface to the schedulerИнтерфейс к планировщику​

Miscellaneous System InformationРазная системная информация​

Random numbersСлучайные числа​

`os` – Различные интерфейсы операционной системы

File Names, Command Line Arguments, and Environment VariablesИмена файлов, аргументы командной строки и переменные окружения

Python UTF-8 ModeРежим UTF-8 Python

Process ParametersПараметры процесса

File Object CreationСоздание файловых объектов

File Descriptor OperationsОперации с файловыми дескрипторами

Querying the size of a terminalЗапрос размера терминала

Inheritance of File DescriptorsНаследование файловых дескрипторов

Files and DirectoriesФайлы и каталоги

Timer File DescriptorsТаймерные файловые дескрипторы

Linux extended attributesРасширенные атрибуты Linux

Process ManagementУправление процессами

Interface to the schedulerИнтерфейс к планировщику

Miscellaneous System InformationРазная системная информация

Random numbersСлучайные числа