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

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

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

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

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

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

Режим UTF-8 в Python

Режим 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 в качестве текстовой кодировки; для sys.stdin и sys.stdout включён обработчик ошибок surrogateescape (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 включается, если при запуске Python локаль LC_CTYPE имеет значение C или POSIX (см. функцию PyConfig_Read()).

Режим можно включить или отключить с помощью параметра командной строки -X utf8 и переменной окружения PYTHONUTF8.

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

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

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

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

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

os.ctermid()

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

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

os.environ

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

Это отображение фиксируется при первом импорте модуля 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().

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

См. также

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

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

os.environb

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

environb доступен только в том случае, если supports_bytes_environ имеет значение True.

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

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

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)

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

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

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

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

os.fsdecode(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 должен быть объектом bytes. Обратите внимание, что, поскольку 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 элементами. Значение целевой версии развёртывания, MACOSX_DEPLOYMENT_TARGET, можно получить с помощью sysconfig.get_config_var().

os.getlogin()

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

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

os.getpgid(pid)

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

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

os.getpgrp()

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

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

os.getpid()

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

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

os.getppid()

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

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

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

os.getpriority(which, who)

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

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

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

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

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

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

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

os.PRIO_DARWIN_THREAD

os.PRIO_DARWIN_PROCESS

os.PRIO_DARWIN_BG

os.PRIO_DARWIN_NONUI

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

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

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

os.getresuid()

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

Доступность: Unix, кроме WASI, macOS и iOS.

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

os.getresgid()

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

Доступность: Unix, кроме WASI, macOS и iOS.

Добавлено в версии 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:

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(), чтобы задать идентификатор группы процессов pgrp для процесса с идентификатором pid. Семантику см. в руководстве 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, macOS и iOS.

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

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

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

Доступность: Unix, кроме WASI, Android, macOS и iOS.

Добавлено в версии 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, если собственный тип переменных окружения ОС — bytes (например, False в Windows).

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

os.umask(mask, /)

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

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

os.uname()

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

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

См. также

sys.platform, предоставляющий более точную детализацию.

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

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

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

class os.uname_result

Имя системы и сведения о ней, возвращаемые функцией os.uname(). Эти атрибуты соответствуют элементам, описанным в uname(2).

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

sysname

Имя операционной системы.

nodename

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

release

Выпуск операционной системы.

version

Версия операционной системы.

machine

Идентификатор оборудования.

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)

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

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

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

См. также

Функцию setns().

Флаги функции unshare(), если они поддерживаются реализацией. Точное действие и доступность флагов описаны в справочной странице Linux unshare(2).

os.CLONE_FILES

os.CLONE_FS

os.CLONE_NEWCGROUP

os.CLONE_NEWIPC

os.CLONE_NEWNET

os.CLONE_NEWNS

os.CLONE_NEWPID

os.CLONE_NEWTIME

os.CLONE_NEWUSER

os.CLONE_NEWUTS

os.CLONE_SIGHAND

os.CLONE_SYSVSEM

os.CLONE_THREAD

os.CLONE_VM

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

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

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

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

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

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

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

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

os.close(fd)

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

Примечание

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

os.closerange(fd_low, fd_high, /)

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

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

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

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

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

Копирование выполняется без дополнительных затрат на передачу данных из ядра в пользовательское пространство и обратно в ядро. Кроме того, некоторые файловые системы могут реализовать дополнительные оптимизации, например использовать reflink (то есть два или более inode, указывающих на одни и те же блоки диска с копированием при записи; поддерживаются файловыми системами 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, если включён режим UTF-8 Python, возвращает 'UTF-8' вместо кодировки устройства.

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

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. Возможные значения mode см. в документации для chmod(). Начиная с 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 и iOS.

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_result, как и statvfs(). Начиная с Python 3.3 эта функция эквивалентна os.statvfs(fd).

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

os.fsync(fd)

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

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

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

os.ftruncate(fd, length, /)

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

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

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

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

os.get_blocking(fd, /)

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

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

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

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

В Windows функция поддерживает только каналы.

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

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

os.grantpt(fd, /)

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

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

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

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

os.isatty(fd, /)

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

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

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

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

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

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

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

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

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

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

os.login_tty(fd, /)

Подготавливает tty, файловым дескриптором которого является fd, для нового сеанса входа в систему. Делает вызывающий процесс лидером сеанса; назначает tty управляющим терминалом, 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() объектов, подобных файлам; задают, как смещать указатель позиции в файле.

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

os.openpty()

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

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

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

os.pipe()

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

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

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

os.pipe2(flags, /)

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

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

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

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

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

Доступность: Unix, но не macOS и iOS.

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

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

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

Доступность: Unix, но не macOS и iOS.

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

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

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

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

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

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

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

• RWF_HIPRI
• RWF_NOWAIT

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

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

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

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

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

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

os.RWF_NOWAIT

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

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

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

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

os.RWF_HIPRI

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

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

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

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

os.ptsname(fd, /)

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

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

• RWF_DSYNC
• RWF_SYNC
• RWF_APPEND

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

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

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

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

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

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

os.RWF_DSYNC

Предоставляет эквивалент флага O_DSYNC 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, возвращается пустой объект bytes.

Примечание

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

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

os.readinto(fd, buffer, /)

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

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

Возвращает 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. Возвращает количество отправленных байтов. При достижении конца файла возвращает 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, /)

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

См. также 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 всё же может блокироваться, поскольку передаваемые файловые дескрипторы могут блокировать выполнение.
• Если указан 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.

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

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

os.F_OK

os.R_OK

os.W_OK

os.X_OK

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

os.chdir(path)

Изменяет текущий рабочий каталог на path.

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

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

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

См. также

Менеджер контекста contextlib.chdir(), который при входе в контекст изменяет текущий рабочий каталог, а при выходе восстанавливает предыдущий.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)

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

Доступность: Unix, кроме WASI и Android.

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

os.fchdir(fd)

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

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

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

os.getcwd()

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

os.getcwdb()

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

Изменено в версии 3.8: Теперь функция в Windows использует кодировку UTF-8 вместо кодовой страницы 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 является символической ссылкой, изменения применяются к самой ссылке, а не к целевому объекту. Возможные значения mode см. в документации к chmod(). Начиная с 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)

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

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

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

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

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

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

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

os.listdir(path='.')

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

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

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

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

Примечание

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

См. также

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

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

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

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

os.listdrives()

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

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

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

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

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

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

os.listmounts(volume)

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

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

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

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

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

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

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

os.listvolumes()

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

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

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

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

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

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

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

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

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

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

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

См. также

Функцию stat().

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

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

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

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

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

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

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

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

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

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

Также можно создавать временные каталоги; см. функцию tempfile.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). Для 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.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: В Windows принимает объект, подобный пути и объект bytes.

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

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 — непустой каталог, возникает исключение OSError. Если оба объекта — файлы, dst будет заменён без предупреждения, если у пользователя есть соответствующие права. В некоторых вариантах Unix операция может завершиться неудачно, если src и dst находятся в разных файловых системах. При успешном выполнении переименование будет атомарной операцией (это требование POSIX).

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

Для перезаписи целевого объекта с одинаковым поведением на разных платформах используйте replace().

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

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

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

os.renames(old, new)

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')

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

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

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

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

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

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

scandir.close()

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

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

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

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

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

Примечание

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

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

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

Функция принимает объект, подобный пути.

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

class os.DirEntry

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

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

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

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

Чтобы объект можно было непосредственно использовать как объект, подобный пути, os.DirEntry реализует интерфейс PathLike.

Объекты DirEntry являются обобщёнными относительно типа пути (str или bytes).

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

name

Имя файла элемента без пути, относительно аргумента path функции scandir().

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

path

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

Атрибут path будет иметь тип bytes, если аргумент path функции scandir() имеет тип 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, если этот элемент является точкой соединения (даже если она не работает); возвращает False, если элемент указывает на обычный каталог, файл любого типа, символическую ссылку либо если он больше не существует.

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

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

stat(*, follow_symlinks=True)

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См. также

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

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

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

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

class os.stat_result

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

Атрибуты:

st_mode

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

st_ino

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

• номер индексного дескриптора в Unix;
• индекс файла в Windows.

st_dev

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

st_nlink

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

st_uid

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

st_gid

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

st_size

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

Временные метки:

st_atime

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

st_mtime

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

st_ctime

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

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

st_atime_ns

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

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

st_mtime_ns

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

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

st_ctime_ns

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

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

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

st_birthtime

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

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

st_birthtime_ns

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

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

Примечание

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

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

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

st_blocks

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

st_blksize

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

st_rdev

Тип устройства, если это устройство индексного дескриптора.

st_flags

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

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

st_gen

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

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

st_fstype

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

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

st_rsize

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

st_creator

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

st_type

Тип файла.

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

st_file_attributes

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

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

st_reparse_tag

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

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

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

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

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

Изменено в версии 3.8: В Windows добавлен элемент st_reparse_tag.

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

В Windows добавлен элемент st_birthtime.

os.statvfs(path)

Выполняет системный вызов statvfs(3) для указанного пути. Возвращаемое значение — объект statvfs_result, атрибуты которого описывают файловую систему по указанному пути и соответствуют элементам структуры statvfs.

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

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

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

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

class os.statvfs_result

Статистика файловой системы, возвращаемая функциями os.statvfs() и os.fstatvfs(). Подробнее см. statvfs(3).

f_bsize

Размер блока.

f_frsize

Размер фрагмента.

f_blocks

Количество блоков размером f_frsize, которое может содержать файловая система.

f_bfree

Количество свободных блоков.

f_bavail

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

f_files

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

f_ffree

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

f_favail

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

f_flag

Битовая маска флагов монтирования. Определены следующие флаги: ST_RDONLY, ST_NOSUID, ST_NODEV, ST_NOEXEC, ST_SYNCHRONOUS, ST_MANDLOCK, ST_WRITE, ST_APPEND, ST_IMMUTABLE, ST_NOATIME, ST_NODIRATIME и ST_RELATIME.

f_namemax

Максимальная длина имени файла в файловой системе. Могут действовать ограничения конкретной ОС, например Windows MAX_PATH, а также ограничения, описанные в pathname(7) для Linux.

f_fsid

Идентификатор файловой системы.

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

В statvfs_result.f_flag используются следующие флаги.

os.ST_RDONLY

Файловая система доступна только для чтения.

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

os.ST_NOSUID

Биты setuid/setgid отключены или не поддерживаются.

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

os.ST_NODEV

Запретить доступ к специальным файлам устройств.

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

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

os.ST_NOEXEC

Запретить выполнение программ.

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

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

os.ST_SYNCHRONOUS

Запись немедленно синхронизируется.

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

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

os.ST_MANDLOCK

Разрешить обязательные блокировки в файловой системе.

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

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

os.ST_WRITE

Запись в файл/каталог/символическую ссылку.

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

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

os.ST_APPEND

Файл, доступный только для добавления данных.

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

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

os.ST_IMMUTABLE

Неизменяемый файл.

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

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

os.ST_NOATIME

Не обновлять время доступа.

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

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

os.ST_NODIRATIME

Не обновлять время доступа к каталогам.

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

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

os.ST_RELATIME

Обновлять время доступа относительно времени изменения содержимого/метаданных.

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

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

os.supports_dir_fd

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

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

os.stat in os.supports_dir_fd

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

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

os.supports_effective_ids

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

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

os.access in os.supports_effective_ids

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

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

os.supports_fd

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

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

os.chdir in os.supports_fd

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

os.supports_follow_symlinks

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

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

os.stat in os.supports_follow_symlinks

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

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

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

Параметр 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, он должен быть 2-кортежем вида (atime_ns, mtime_ns), в котором каждый элемент — это целое число, задающее время в наносекундах.
• Если times не равен None, он должен быть 2-кортежем вида (atime, mtime), в котором каждый элемент — это целое число или число с плавающей точкой, задающее время в секундах.
• Если times равен None и ns не указан, это эквивалентно указанию ns=(atime_ns, mtime_ns), где оба значения времени соответствуют текущему времени.

Указывать кортежи одновременно для times и ns нельзя.

Обратите внимание, что при последующем вызове stat() могут быть возвращены не совсем те значения времени, которые были здесь установлены: это зависит от точности, с которой операционная система записывает время доступа и изменения; см. stat(). Чтобы сохранить точные значения времени, лучше всего использовать поля st_atime_ns и st_mtime_ns объекта результата os.stat() с параметром ns функции utime().

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

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__')  # don't visit __pycache__ directories

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

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

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

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

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

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

Работает точно так же, как walk(), но возвращает 4-кортеж (dirpath, dirnames, filenames, dirfd) и поддерживает dir_fd.

dirpath, dirnames и filenames соответствуют выходным данным walk(), а dirfd — это дескриптор файла, ссылающийся на каталог dirpath.

Эта функция всегда поддерживает пути относительно дескрипторов каталогов и отказ от следования по символическим ссылкам. Однако обратите внимание, что, в отличие от других функций, значение по умолчанию fwalk() для follow_symlinks — False.

Примечание

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

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

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__')  # don't visit __pycache__ directories

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

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

Вызывает событие аудита os.fwalk с аргументами top, topdown, onerror, follow_symlinks, dir_fd.

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

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

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

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

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

Создаёт анонимный файл и возвращает дескриптор файла, ссылающийся на него. Параметр flags должен быть одной из доступных в системе констант os.MFD_* (или их комбинацией, объединённой побитовой операцией ИЛИ). По умолчанию новый дескриптор файла не наследуется.

Значение name используется как имя файла и отображается как цель соответствующей символической ссылки в каталоге /proc/self/fd/. Перед отображаемым именем всегда добавляется memfd:; оно используется только для отладки. Имена не влияют на поведение дескриптора файла, поэтому несколько файлов могут иметь одинаковые имена без каких-либо побочных эффектов.

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

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

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

Эти флаги можно передать функции memfd_create().

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

Флаги MFD_HUGE* доступны только начиная с Linux 4.14.

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

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

Создаёт и возвращает дескриптор файла события. Дескрипторы файлов поддерживают обычные вызовы read() и write() с размером буфера 8, а также select(), poll() и подобные функции. Дополнительную информацию см. на странице руководства eventfd(2). По умолчанию новый дескриптор файла не наследуется.

initval — начальное значение счётчика событий. Начальное значение должно быть 32-разрядным беззнаковым целым числом. Обратите внимание, что, хотя счётчик событий является 64-разрядным беззнаковым целым числом с максимальным значением 2⁶⁴-2, начальное значение ограничено 32-разрядным беззнаковым целым числом.

Параметр flags может быть сформирован из EFD_CLOEXEC, EFD_NONBLOCK и EFD_SEMAPHORE.

Если указан EFD_SEMAPHORE и счётчик событий не равен нулю, eventfd_read() возвращает 1 и уменьшает значение счётчика на единицу.

Если EFD_SEMAPHORE не указан и счётчик событий не равен нулю, eventfd_read() возвращает текущее значение счётчика событий и сбрасывает его в ноль.

Если счётчик событий равен нулю и EFD_NONBLOCK не указан, eventfd_read() блокируется.

eventfd_write() увеличивает счётчик событий. Запись блокируется, если в результате операции значение счётчика превысит 2⁶⁴-2.

Пример:

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFD_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

Доступность: Linux >= 2.6.27 с glibc >= 2.8

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

os.eventfd_read(fd)

Считывает значение из дескриптора файла eventfd() и возвращает 64-разрядное беззнаковое целое число. Функция не проверяет, что fd является eventfd().

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

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

os.eventfd_write(fd, value)

Добавляет значение к дескриптору файла eventfd(). value должно быть 64-разрядным беззнаковым целым числом. Функция не проверяет, что fd является eventfd().

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

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

os.EFD_CLOEXEC

Устанавливает флаг 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.

Управление процессами

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

Различные функции exec* принимают список аргументов для новой программы, загружаемой в процесс. В каждом случае первый из этих аргументов передаётся новой программе в качестве её собственного имени, а не как аргумент, который пользователь мог ввести в командной строке. Для программиста на C это argv[0], передаваемый программе в main(). Например, os.execv('/bin/echo', ['foo', 'bar']) выведет в стандартный вывод только bar; foo будет проигнорирован.

os.abort()

Посылает текущему процессу сигнал SIGABRT. В Unix поведение по умолчанию — создать дамп ядра; в Windows процесс немедленно возвращает код выхода 3. Учтите, что вызов этой функции не вызывает обработчик сигналов Python, зарегистрированный для SIGABRT с помощью signal.signal().

os.add_dll_directory(path)

Добавляет путь в список путей поиска DLL.

Этот список путей поиска используется при разрешении зависимостей импортируемых модулей расширения (сам модуль ищется через sys.path), а также модулем ctypes.

Чтобы удалить каталог, вызовите close() у возвращённого объекта или используйте его в инструкции with.

Подробнее о загрузке DLL см. в документации Microsoft.

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

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

Добавлено в версии 3.8: В предыдущих версиях CPython DLL искались с использованием поведения по умолчанию для текущего процесса. Это приводило к несогласованности: например, каталог PATH или текущий рабочий каталог искались не всегда, а функции ОС, например AddDllDirectory, не оказывали никакого эффекта.

В версии 3.8 два основных способа загрузки DLL теперь явно переопределяют поведение для всего процесса, чтобы обеспечить согласованность. Сведения об обновлении библиотек см. в примечаниях по переносу.

os.execl(path, arg0, arg1, ...)

os.execle(path, arg0, arg1, ..., env)

os.execlp(file, arg0, arg1, ...)

os.execlpe(file, arg0, arg1, ..., env)

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

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

Текущий процесс заменяется немедленно. Открытые файловые объекты и дескрипторы не сбрасываются, поэтому, если в этих открытых файлах могут быть буферизованные данные, перед вызовом функции exec* их следует сбросить с помощью flush() или os.fsync().

Варианты функций exec* с «l» и «v» различаются способом передачи аргументов командной строки. Варианты с «l» могут быть наиболее удобны, если количество параметров фиксировано на момент написания кода: отдельные параметры просто становятся дополнительными параметрами функций execl*(). Варианты с «v» подходят, когда количество параметров переменно, а аргументы передаются списком или кортежем в параметре args. В обоих случаях аргументы дочернего процесса должны начинаться с имени выполняемой команды, однако это не проверяется.

Варианты, в названии которых ближе к концу есть «p» (execlp(), execlpe(), execvp() и execvpe()), используют переменную окружения PATH для поиска файла программы. Если окружение заменяется (с помощью одного из вариантов exec*e, описанных в следующем абзаце), переменная PATH берётся из нового окружения. Другие варианты — execl(), execle(), execv() и execve() — не используют переменную PATH для поиска исполняемого файла; параметр path должен содержать подходящий абсолютный или относительный путь. Относительные пути должны содержать хотя бы одну косую черту, даже в Windows, поскольку поиск по одному только имени не выполняется.

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

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

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

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

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

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

os._exit(n)

Завершает процесс со статусом n, не вызывая обработчики очистки, не сбрасывая буферы stdio и т. д.

Примечание

Стандартный способ завершения — sys.exit(n). Обычно _exit() следует использовать только в дочернем процессе после вызова fork().

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

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

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

os.EX_IOERR

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

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

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

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

os.EX_NOPERM

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

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

os.EX_CONFIG

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

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

os.EX_NOTFOUND

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

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

os.fork()

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

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

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

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

Если в приложении, вызывающем fork(), используются сокеты TLS, ознакомьтесь с предупреждением в документации ssl.

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

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

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

Изменено в версии 3.12: Если Python может определить, что в процессе есть несколько потоков, os.fork() теперь вызывает предупреждение DeprecationWarning.

Если это можно определить, мы выдаём предупреждение, чтобы лучше информировать разработчиков о проблеме проектирования, которую платформа POSIX прямо обозначает как неподдерживаемую. Даже если код кажется работоспособным, совмещать потоки и os.fork() на платформах POSIX никогда не было безопасно. Среда выполнения CPython сама всегда вызывала API, небезопасные для использования в дочернем процессе, если в родительском процессе были потоки (например, malloc и free).

Пользователи macOS, а также пользователи реализаций libc или malloc, отличных от тех, что обычно встречаются в glibc, уже чаще сталкиваются с взаимными блокировками при выполнении такого кода.

Технические подробности о том, почему мы обращаем внимание разработчиков на эту давнюю проблему совместимости с платформами, см. в обсуждении несовместимости fork с потоками.

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

os.forkpty()

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

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

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

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

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

Изменено в версии 3.12: Если Python может определить, что в процессе есть несколько потоков, теперь вызывается предупреждение DeprecationWarning. Более подробное объяснение см. в разделе о os.fork().

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

os.kill(pid, sig, /)

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

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

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

Вызывает событие аудита 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. Возвращает новое значение «любезности».

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

os.pidfd_open(pid, flags=0)

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

Дополнительные сведения см. на странице руководства pidfd_open(2).

Доступность: Linux >= 5.3, Android >= уровень API 31, возвращаемый build-time

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

os.PIDFD_NONBLOCK

Этот флаг указывает, что файловый дескриптор будет неблокирующим. Если процесс, на который ссылается файловый дескриптор, ещё не завершился, попытка ожидания на этом дескрипторе с помощью waitid(2) немедленно вернёт ошибку EAGAIN, а не будет блокироваться.

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

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

os.plock(op, /)

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

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

os.popen(cmd, mode='r', buffering=-1)

Открывает канал для передачи данных команде cmd или от неё. Возвращаемое значение — открытый файловый объект, связанный с каналом, из которого можно читать или в который можно записывать в зависимости от того, равно ли значение mode 'r' (по умолчанию) или 'w'. Аргумент buffering имеет то же значение, что и соответствующий аргумент встроенной функции open(). Возвращённый файловый объект читает и записывает текстовые строки, а не байты.

Метод close возвращает None, если дочерний процесс завершился успешно, или код возврата дочернего процесса в случае ошибки. В системах POSIX положительный код возврата соответствует значению, возвращённому процессом и сдвинутому влево на один байт. Если код возврата отрицателен, процесс был завершён сигналом, значение которого равно коду возврата с обратным знаком. (Например, возвращаемое значение может быть равно - signal.SIGKILL, если дочерний процесс был принудительно завершён.) В системах Windows возвращаемое значение содержит знаковый целочисленный код возврата дочернего процесса.

В Unix для преобразования результата метода close (статуса выхода) в код выхода можно использовать waitstatus_to_exitcode(), если результат не равен None. В Windows результат метода close напрямую является кодом выхода (или None).

Реализация основана на subprocess.Popen; более широкие возможности управления дочерними процессами и обмена данными с ними описаны в документации этого класса.

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

Примечание

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

Если аргумент resetids равен True, эффективные UID и GID дочернего процесса будут сброшены до реальных UID и GID родительского процесса. Если аргумент равен False, дочерний процесс сохраняет эффективные UID и GID родительского процесса. В обоих случаях, если для исполняемого файла включены биты разрешений set-user-ID и set-group-ID, их действие переопределит заданные эффективные UID и GID. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_RESETIDS.

Если аргумент setsid равен True, для posix_spawn будет создан новый идентификатор сеанса. Для setsid требуется флаг POSIX_SPAWN_SETSID или POSIX_SPAWN_SETSID_NP. В противном случае возникает исключение NotImplementedError.

Аргумент setsigmask задаёт маску сигналов указанным набором сигналов. Если параметр не используется, дочерний процесс наследует маску сигналов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGMASK.

Аргумент sigdef сбрасывает обработку всех сигналов из указанного набора. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGDEF.

Аргумент scheduler должен быть кортежем, содержащим (необязательную) политику планировщика и экземпляр sched_param с параметрами планировщика. Значение None вместо политики планировщика означает, что она не указана. Этот аргумент объединяет флаги библиотеки C POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDULER.

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

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

Изменено в версии 3.13: Параметр env принимает значение None. os.POSIX_SPAWN_CLOSEFROM доступен на платформах, где существует posix_spawn_file_actions_addclosefrom_np().

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

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Обёртка над API библиотеки C posix_spawnp() для использования из Python.

Аналогична posix_spawn(), за исключением того, что система ищет исполняемый файл executable в списке каталогов, заданном переменной окружения PATH (так же, как для execvp(3)).

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

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

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

См. документацию posix_spawn().

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

Регистрирует вызываемые объекты, которые будут выполнены при создании нового дочернего процесса с помощью os.fork() или аналогичных API клонирования процессов. Параметры необязательны и могут передаваться только по имени. Каждый из них задаёт отдельный момент вызова.

• before — функция, вызываемая перед созданием дочернего процесса.
• after_in_parent — функция, вызываемая в родительском процессе после создания дочернего процесса.
• after_in_child — функция, вызываемая в дочернем процессе.

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

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

Обратите внимание, что вызовы fork() из стороннего кода на C могут не вызывать эти функции, если этот код явно не вызывает PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child().

Отменить регистрацию функции невозможно.

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

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

os.spawnl(mode, path, ...)

os.spawnle(mode, path, ..., env)

os.spawnlp(mode, file, ...)

os.spawnlpe(mode, file, ..., env)

os.spawnv(mode, path, args)

os.spawnve(mode, path, args, env)

os.spawnvp(mode, file, args)

os.spawnvpe(mode, file, args, env)

Запускает программу path в новом процессе.

(Обратите внимание, что модуль subprocess предоставляет более широкие возможности для запуска новых процессов и получения их результатов; предпочтительнее использовать этот модуль, а не данные функции. Особое внимание обратите на раздел Замена старых функций модулем subprocess.)

Если mode равен P_NOWAIT, эта функция возвращает идентификатор нового процесса; если mode равен P_WAIT, возвращается код завершения процесса при нормальном завершении или -signal, где signal — сигнал, завершивший процесс. В Windows идентификатором процесса фактически будет дескриптор процесса, поэтому его можно использовать с функцией waitpid().

Обратите внимание: в VxWorks эта функция не возвращает -signal, если новый процесс завершён. Вместо этого возникает исключение OSError.

Варианты функций spawn* с буквами «l» и «v» отличаются способом передачи аргументов командной строки. Варианты «l» удобны, если число параметров известно при написании кода: отдельные параметры просто становятся дополнительными аргументами функций spawnl*(). Варианты «v» подходят, если число параметров переменно: аргументы передаются в виде списка или кортежа в параметре args. В обоих случаях первым аргументом дочернего процесса должно быть имя запускаемой команды.

Варианты, в названии которых ближе к концу есть вторая буква «p» (spawnlp(), spawnlpe(), spawnvp() и spawnvpe()), используют переменную окружения PATH для поиска файла программы file. При замене окружения (с помощью одного из вариантов spawn*e, описанных в следующем абзаце) в качестве источника переменной PATH используется новое окружение. Остальные варианты — spawnl(), spawnle(), spawnv() и spawnve() — не используют переменную PATH для поиска исполняемого файла; в path необходимо указать подходящий абсолютный или относительный путь.

Для spawnle(), spawnlpe(), spawnve() и spawnvpe() (обратите внимание, что все они оканчиваются на «e») параметр env должен быть отображением, используемым для определения переменных окружения нового процесса (они используются вместо окружения текущего процесса); функции spawnl(), spawnlp(), spawnv() и spawnvp() обеспечивают наследование новым процессом окружения текущего процесса. Обратите внимание, что ключи и значения словаря env должны быть строками; недопустимые ключи или значения приводят к сбою функции и возврату 127.

Например, следующие вызовы spawnlp() и spawnvpe() эквивалентны:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

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

Доступность: Unix, Windows, не 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 документации 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.

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

os.wait()

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

Если нет дочерних процессов, завершения которых можно ожидать, возникает исключение 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 (реальный идентификатор пользователя дочернего процесса)
• si_signo (всегда SIGCHLD)
• si_status (код завершения или номер сигнала в зависимости от si_code)
• si_code (возможные значения см. в описании CLD_EXITED)

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

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

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

Изменено в версии 3.13: Теперь эта функция доступна также в macOS.

os.waitpid(pid, options, /)

Подробности этой функции различаются в Unix и Windows.

В Unix: ожидает завершения дочернего процесса с идентификатором процесса pid и возвращает кортеж, содержащий его идентификатор процесса и признак состояния завершения (закодированный так же, как для wait()). Семантика вызова зависит от значения целого числа options, которое при обычной работе должно иметь значение 0.

Если pid больше 0, waitpid() запрашивает сведения о состоянии конкретного процесса. Если pid равен 0, запрашивается состояние любого дочернего процесса в группе процессов текущего процесса. Если pid равен -1, запрашивается состояние любого дочернего процесса текущего процесса. Если pid меньше -1, запрашивается состояние любого процесса в группе процессов -pid (абсолютное значение pid).

options — это комбинация флагов, объединённых побитовой операцией ИЛИ. Если она содержит WNOHANG и в запрошенном состоянии нет подходящих дочерних процессов, возвращается (0, 0). В противном случае, если нет подходящих дочерних процессов, завершения которых можно ожидать, возникает исключение ChildProcessError. Можно использовать и другие параметры: WUNTRACED и WCONTINUED.

В Windows: ожидает завершения процесса, заданного дескриптором процесса pid, и возвращает кортеж, содержащий pid и его статус завершения, сдвинутый влево на 8 бит (сдвиг упрощает переносимое использование функции). Значение pid, меньшее или равное 0, в Windows не имеет особого значения и вызывает исключение. Значение целого числа options не влияет на результат. pid может ссылаться на любой процесс с известным идентификатором, необязательно на дочерний процесс. Функции spawn*, вызванные с параметром P_NOWAIT, возвращают подходящие дескрипторы процессов.

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

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

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

os.wait3(options)

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

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

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

os.wait4(pid, options)

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

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

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

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

Это возможные значения idtype в waitid(). Они определяют, как интерпретируется id:

• P_PID — ожидать дочерний процесс, PID которого равен id.
• P_PGID — ожидать любой дочерний процесс, идентификатор группы процессов которого равен id.
• P_ALL — ожидать любой дочерний процесс; id игнорируется.
• P_PIDFD — ожидать дочерний процесс, указанный файловым дескриптором id (файловым дескриптором процесса, созданным с помощью pidfd_open()).

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

Примечание

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

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

Добавлено в версии 3.9: Константа P_PIDFD.

os.WCONTINUED

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

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

os.WEXITED

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

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

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

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

os.WSTOPPED

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

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

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

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

os.WUNTRACED

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

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

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

os.WNOHANG

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

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

os.WNOWAIT

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

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

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

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

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

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

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

Изменено в версии 3.9: Добавлены значения CLD_KILLED и CLD_STOPPED.

os.waitstatus_to_exitcode(status)

Преобразует статус ожидания в код завершения.

В Unix:

• Если процесс завершился нормально (если WIFEXITED(status) имеет значение true), возвращает статус завершения процесса (возвращает WEXITSTATUS(status)): результат больше или равен 0.
• Если процесс был завершён сигналом (если WIFSIGNALED(status) имеет значение true), возвращает -signum, где signum — номер сигнала, вызвавшего завершение процесса (возвращает -WTERMSIG(status)): результат меньше 0.
• В противном случае вызывает исключение ValueError.

В Windows возвращает status, сдвинутый вправо на 8 бит.

В Unix, если процесс отслеживается или если waitpid() был вызван с параметром WUNTRACED, вызывающий код должен сначала проверить, имеет ли WIFSTOPPED(status) значение true. Эту функцию нельзя вызывать, если WIFSTOPPED(status) имеет значение true.

См. также

Функции WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED() и WSTOPSIG().

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

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

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

os.WCOREDUMP(status, /)

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

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

Доступность: 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() имеет значение true.

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

os.WSTOPSIG(status)

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

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

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

os.WTERMSIG(status)

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

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

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

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

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

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

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

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

os.SCHED_RESET_ON_FORK

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

class os.sched_param(sched_priority)

Этот класс представляет настраиваемые параметры планирования, используемые в sched_setparam(), sched_setscheduler() и sched_getparam(). Он неизменяемый.

В настоящее время возможен только один параметр:

sched_priority

Приоритет планирования для политики планирования.

os.sched_get_priority_min(policy)

Возвращает минимальное значение приоритета для policy. policy — одна из приведённых выше констант политики планирования.

os.sched_get_priority_max(policy)

Возвращает максимальное значение приоритета для policy. policy — одна из приведённых выше констант политики планирования.

os.sched_setscheduler(pid, policy, param, /)

Задаёт политику планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. policy — одна из приведённых выше констант политики планирования. param — экземпляр sched_param.

os.sched_getscheduler(pid, /)

Возвращает политику планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. Результат — одна из приведённых выше констант политики планирования.

os.sched_setparam(pid, param, /)

Задаёт параметры планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. param — экземпляр sched_param.

os.sched_getparam(pid, /)

Возвращает параметры планирования в виде экземпляра sched_param для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс.

os.sched_rr_get_interval(pid, /)

Возвращает квант времени циклического планирования в секундах для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс.

os.sched_yield()

Добровольно освобождает процессор. Подробности см. в sched_yield(2).

os.sched_setaffinity(pid, mask, /)

Ограничивает процесс с PID pid (или текущий процесс, если значение равно нулю) набором ЦП. mask — итерируемый объект целых чисел, представляющих набор ЦП, которым следует ограничить процесс.

os.sched_getaffinity(pid, /)

Возвращает набор ЦП, которыми ограничен процесс с PID pid.

Если pid равен нулю, возвращает набор ЦП, которыми ограничен вызывающий поток текущего процесса.

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

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

os.confstr(name, /)

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

Если конфигурационное значение, заданное параметром name, не определено, возвращается None.

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

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

os.confstr_names

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

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

os.cpu_count()

Возвращает количество логических ЦП в системе. Если определить количество не удаётся, возвращает None.

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

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

Изменено в версии 3.13: Если задан -X cpu_count или установлена переменная PYTHON_CPU_COUNT, cpu_count() возвращает переопределяющее значение n.

os.getloadavg()

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

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

os.process_cpu_count()

Возвращает количество логических ЦП, доступных вызывающему потоку текущего процесса. Если определить количество не удаётся, возвращает None. В зависимости от привязки к ЦП это значение может быть меньше, чем результат cpu_count().

Функцию cpu_count() можно использовать, чтобы получить количество логических ЦП в системе.

Если задан -X cpu_count или установлена переменная PYTHON_CPU_COUNT, process_cpu_count() возвращает переопределяющее значение n.

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

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

os.sysconf(name, /)

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

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

os.sysconf_names

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

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

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

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

Операции более высокого уровня для работы с путями определены в модуле os.path.

os.curdir

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

os.pardir

Строковая константа, используемая операционной системой для обозначения родительского каталога. В Windows и POSIX это '..'. Также доступна через os.path.

os.sep

Символ, используемый операционной системой для разделения компонентов пути. В POSIX это '/', а в Windows — '\\'. Обратите внимание: знания этого символа недостаточно для разбора или объединения путей — используйте os.path.split() и os.path.join(), — однако иногда это бывает полезно. Также доступна через os.path.

os.altsep

Дополнительный символ, используемый операционной системой для разделения компонентов пути, или None, если существует только один символ-разделитель. В системах Windows, где '/' — обратная косая черта, этому значению присваивается sep. Также доступна через os.path.

os.extsep

Символ, отделяющий имя файла от расширения; например, '.' в os.py. Также доступна через os.path.

os.pathsep

Символ, традиционно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например ':' в POSIX или ';' в Windows. Также доступна через os.path.

os.defpath

Путь поиска по умолчанию, используемый функциями exec*p* и spawn*p*, если в окружении нет ключа 'PATH'. Также доступна через os.path.

os.linesep

Строка, используемая на текущей платформе для разделения (или, точнее, завершения) строк. Это может быть один символ, например '\n' в POSIX, или несколько символов, например '\r\n' в Windows. Не используйте os.linesep в качестве символа конца строки при записи файлов, открытых в текстовом режиме (по умолчанию); на всех платформах используйте вместо этого один '\n'.

os.devnull

Путь к файлу нулевого устройства. Например: '/dev/null' в POSIX, 'nul' в Windows. Также доступен через os.path.

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

Флаги для использования с функциями setdlopenflags() и getdlopenflags(). Значение различных флагов описано на странице руководства Unix dlopen(3).

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