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

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

os.environb

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

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

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

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

os.chdir(path)

os.fchdir(fd)

os.getcwd()

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

os.fsencode(filename)

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

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

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

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

os.fsdecode(filename)

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

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

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

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

os.fspath(path)

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

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

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

class os.PathLike

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

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

abstractmethod __fspath__()

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

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

os.getenv(key, default=None)

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

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

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

os.getenvb(key, default=None)

Возвращает значение переменной окружения key в виде байтов, если она существует, или default, если нет. key должен быть объектом 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.

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

os.getresgid()

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

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

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

os.getuid()

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

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

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

os.initgroups(username, gid, /)

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

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

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

os.putenv(key, value, /)

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

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

Примечание

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

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

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

os.setegid(egid, /)

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

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

os.seteuid(euid, /)

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

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

os.setgid(gid, /)

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

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

os.setgroups(groups, /)

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

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

Примечание

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

os.setns(fd, nstype=0)

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

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

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

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

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

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

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

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

См. также

Функция unshare().

os.setpgrp()

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

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

os.setpgid(pid, pgrp, /)

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

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

os.setpriority(which, who, priority)

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

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

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

os.setregid(rgid, egid, /)

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

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

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

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

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

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

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

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

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

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

os.setreuid(ruid, euid, /)

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

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

os.getsid(pid, /)

Вызвать системный вызов getsid(). Семантику см. в руководстве Unix.

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

os.setsid()

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

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

os.setuid(uid, /)

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

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

os.strerror(code, /)

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

os.supports_bytes_environ

True, если нативный тип операционной системы для окружения — bytes (например, False в Windows).

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

os.umask(mask, /)

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

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

os.uname()

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

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

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

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

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

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

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

os.unsetenv(key, /)

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

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

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

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

os.unshare(flags)

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

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

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

См. также

Функция setns().

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

os.fpathconf(fd, name, /)

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

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

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

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

os.fstat(fd)

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

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

См. также

Функцию stat().

os.fstatvfs(fd, /)

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

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

os.fsync(fd)

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

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

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

os.ftruncate(fd, length, /)

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

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

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

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

os.get_blocking(fd, /)

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

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

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

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

В Windows функция доступна только для каналов.

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

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

os.grantpt(fd, /)

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

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

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

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

os.isatty(fd, /)

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

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

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

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

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

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

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

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

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

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

os.login_tty(fd, /)

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

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

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

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

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

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

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

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

Читает не более n байт из файлового дескриптора fd с позиции offset, не изменяя смещение файла.

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

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

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

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

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

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

В Windows эта функция доступна только для каналов.

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

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

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

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

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

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

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

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

os.SPLICE_F_MOVE

os.SPLICE_F_NONBLOCK

os.SPLICE_F_MORE

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

os.readv(fd, buffers, /)

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

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

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

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

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

os.tcgetpgrp(fd, /)

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

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

os.tcsetpgrp(fd, pg, /)

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

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

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

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

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

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

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

  С помощью os.supports_follow_symlinks можно проверить, поддерживается ли на вашей платформе аргумент 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.

Изменено в версии 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: Добавлена поддержка файлового дескриптора и аргумента follow_symlinks в Windows.

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

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

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

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

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

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

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

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

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

os.chroot(path)

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

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

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

os.fchdir(fd)

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

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

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

os.getcwd()

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

os.getcwdb()

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

Изменено в версии 3.8: Теперь в 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. Если путь является символической ссылкой, изменения применяются к самой ссылке, а не к целевому объекту. Возможные значения 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 для указания путей относительно дескрипторов каталогов, а также работу без перехода по символическим ссылкам.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)

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

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

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

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

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

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

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

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

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

name

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

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

path

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

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

inode()

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

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

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

is_dir(*, follow_symlinks=True)

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

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

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

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

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

is_file(*, follow_symlinks=True)

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

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

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

is_symlink()

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

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

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

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

is_junction()

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

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

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

stat(*, follow_symlinks=True)

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См. также

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

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

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

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

class os.stat_result

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

Атрибуты:

st_mode

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

st_ino

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

• номер inode в 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

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

st_flags

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

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

st_gen

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

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

st_fstype

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

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

st_rsize

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

st_creator

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

st_type

Тип файла.

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

st_file_attributes

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

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

st_reparse_tag

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.supports_dir_fd

Объект set, указывающий, какие функции модуля os принимают открытый файловый дескриптор для параметра dir_fd. На разных платформах доступны разные возможности, и функциональность, которую Python использует для реализации параметра dir_fd, доступна не на всех поддерживаемых 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.

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

Эта функция всегда поддерживает пути относительно дескрипторов каталогов и отказ от перехода по символьным ссылкам. Обратите внимание: в отличие от других функций, значение follow_symlinks по умолчанию для fwalk() — 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-битным беззнаковым целым числом. Обратите внимание: начальное значение ограничено 32-битным беззнаковым целым числом, хотя счётчик событий является 64-битным беззнаковым целым числом с максимальным значением 2⁶⁴-2.

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

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

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

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

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

Пример:

import os

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

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

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

os.eventfd_read(fd)

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

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

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

os.eventfd_write(fd, value)

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

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

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

os.EFD_CLOEXEC

Устанавливает флаг 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* следует сбросить их с помощью sys.stdout.flush() или os.fsync().

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

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

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

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

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

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

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

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

os._exit(n)

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

Примечание

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

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

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

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

os.EX_IOERR

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

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

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

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

os.EX_NOPERM

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

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

os.EX_CONFIG

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

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

os.EX_NOTFOUND

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

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

os.fork()

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

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

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

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

Если в приложении, вызывающем 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, не iOS.

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

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

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

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

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

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

Примечание

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

popen() — это простая оболочка над subprocess.Popen. Используйте subprocess.Popen или subprocess.run(), чтобы управлять такими параметрами, как кодировки.

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

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

Большинству пользователей следует использовать subprocess.run() вместо posix_spawn().

Позиционные аргументы, передаваемые только по позиции, path, args и env, аналогичны аргументам execve(). Для 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 для поиска программного файла. При замене окружения (с помощью одного из вариантов spawn*e, описанных в следующем абзаце) источником переменной PATH становится новое окружение. Остальные варианты — spawnl(), spawnle(), spawnv() и spawnve() — не используют переменную PATH для поиска исполняемого файла; path должен содержать подходящий абсолютный или относительный путь.

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

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

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

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

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

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

spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не являются потокобезопасными в Windows; вместо них рекомендуется использовать модуль subprocess.

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

os.P_NOWAIT

os.P_NOWAITO

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

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

os.P_WAIT

Возможное значение параметра mode для семейства функций spawn*. Если указано в качестве mode, функции spawn* не возвращают управление, пока новый процесс не завершится, и возвращают код завершения процесса при успешном выполнении или -signal, если процесс завершён сигналом.

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

os.P_DETACH

os.P_OVERLAY

Возможные значения параметра mode для семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH аналогично P_NOWAIT, но новый процесс отсоединяется от консоли вызвавшего процесса. Если используется P_OVERLAY, текущий процесс заменяется; функция spawn* не возвращает управление.

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

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

Запускает файл с помощью связанного с ним приложения.

Если параметр operation не указан, функция действует так же, как двойной щелчок по файлу в проводнике Windows или передача имени файла в качестве аргумента команде start в интерактивной командной оболочке: файл открывается в приложении, с которым связано его расширение (если такое приложение есть).

Если задан другой параметр operation, он должен быть «глаголом команды», указывающим, что следует сделать с файлом. Распространённые глаголы, документированные Microsoft: 'open', 'print' и 'edit' (для файлов), а также 'explore' и 'find' (для каталогов).

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

По умолчанию рабочий каталог наследуется, но его можно переопределить аргументом cwd. Он должен содержать абсолютный путь. Относительный 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 или документацию MSDN по GetProcessTimes в 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 — это комбинация флагов, объединённых операцией OR. Если она содержит WNOHANG и нет дочерних процессов, соответствующих запрошенному состоянию, возвращается (0, 0). В противном случае, если нет подходящих дочерних процессов, завершения которых можно ожидать, возникает исключение ChildProcessError. Можно использовать и другие параметры: WUNTRACED и WCONTINUED.

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

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

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

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

os.wait3(options)

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

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

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

os.wait4(pid, options)

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

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

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

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

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

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

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

Примечание

P_PIDFD доступен только в Linux версии 5.4 и выше.

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

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

os.WCONTINUED

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

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

os.WEXITED

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

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

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

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

os.WSTOPPED

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

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

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

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

os.WUNTRACED

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

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

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

os.WNOHANG

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

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

os.WNOWAIT

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

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

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

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

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

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

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

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

os.waitstatus_to_exitcode(status)

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

В Unix:

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

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

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

См. также

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

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

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

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

os.WCOREDUMP(status, /)

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

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

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

os.WIFCONTINUED(status)

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

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

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

os.WIFSTOPPED(status)

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

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

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

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

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

os.WSTOPSIG(status)

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

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

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

os.WTERMSIG(status)

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

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

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

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

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

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

os.SCHED_OTHER

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

os.SCHED_BATCH

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

os.SCHED_IDLE

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

os.SCHED_SPORADIC

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

os.SCHED_FIFO

Политика планирования «первым пришёл — первым обслужен» (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, /)

Возвращает параметры планирования процесса с PID pid в виде экземпляра sched_param. Значение 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 (или текущий процесс, если указан 0) набором процессоров. mask — итерируемый объект с целыми числами, представляющими набор процессоров, к которым следует привязать процесс.

os.sched_getaffinity(pid, /)

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

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

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

Различные сведения о системе

os.confstr(name, /)

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

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

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

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

os.confstr_names

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

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

os.cpu_count()

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

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

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

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

os.getloadavg()

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

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

os.process_cpu_count()

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

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

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

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

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

os.sysconf(name, /)

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

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

os.sysconf_names

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

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

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

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

Операции более высокого уровня над путями определены в модуле os.path.

os.curdir

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

os.pardir

Строковая константа, используемая операционной системой для обозначения родительского каталога. В Windows и POSIX это '..'. Также доступна через os.path.

os.sep

Символ, используемый операционной системой для разделения компонентов пути. В POSIX это '/', а в Windows — '\\'. Обратите внимание: одного знания этого символа недостаточно для разбора или объединения путей — используйте os.path.split() и os.path.join(), — но иногда это бывает полезно. Также доступна через os.path.

os.altsep

Альтернативный символ, используемый операционной системой для разделения компонентов пути, или None, если существует только один символ-разделитель. В системах Windows, где sep — обратная косая черта, этому значению присваивается '/'. Также доступна через os.path.

os.extsep

Символ, разделяющий имя файла и расширение; например, '.' в os.py. Также доступна через os.path.

os.pathsep

Символ, традиционно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например ':' в POSIX или ';' в Windows. Также доступна через os.path.

os.defpath

Путь поиска по умолчанию, используемый функциями exec*p* и spawn*p*, если в окружении нет ключа 'PATH'. Также доступна через os.path.

os.linesep

Строка, используемая на текущей платформе для разделения (точнее, завершения) строк. Она может состоять из одного символа, например '\n' в POSIX, или нескольких символов, например '\r\n' в Windows. Не используйте os.linesep в качестве окончания строки при записи в файлы, открытые в текстовом режиме (по умолчанию); на всех платформах используйте вместо него один символ '\n'.

os.devnull

Путь к файлу нулевого устройства. Например: '/dev/null' в POSIX, 'nul' в Windows. Также доступна через os.path.

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

Флаги для использования с функциями setdlopenflags() и getdlopenflags(). Значения флагов см. в справочной странице Unix dlopen(3).

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

Случайные числа

os.getrandom(size, flags=0)

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

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

getrandom() использует энтропию, собираемую драйверами устройств и другими источниками случайных возмущений окружающей среды. Чтение неоправданно больших объёмов данных отрицательно влияет на других пользователей устройств /dev/random и /dev/urandom.

Аргумент flags — это битовая маска, которая может содержать побитовое объединение нуля или нескольких следующих значений: os.GRND_RANDOM и GRND_NONBLOCK.

См. также справочную страницу Linux для getrandom().

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

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

os.urandom(size, /)

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

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

В Linux, если доступен системный вызов getrandom(), он используется в блокирующем режиме: функция ожидает инициализации системного пула энтропии urandom (ядро собирает 128 бит энтропии). Обоснование см. в PEP 524. В Linux функцию getrandom() можно использовать для получения случайных байтов в неблокирующем режиме (с флагом GRND_NONBLOCK) или для ожидания инициализации системного пула энтропии urandom.

В Unix-подобных системах случайные байты считываются с устройства /dev/urandom. Если устройство /dev/urandom недоступно или не предназначено для чтения, возбуждается исключение NotImplementedError.

В Windows используется BCryptGenRandom().

См. также

Модуль secrets предоставляет функции более высокого уровня. Чтобы получить удобный интерфейс к генератору случайных чисел вашей платформы, см. random.SystemRandom.

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

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

Изменено в версии 3.6: В Linux теперь для повышения безопасности getrandom() используется в блокирующем режиме.

Изменено в версии 3.11: В Windows вместо устаревшего CryptGenRandom() используется BCryptGenRandom().

os.GRND_NONBLOCK

По умолчанию при чтении из /dev/random функция getrandom() блокирует выполнение, если случайные байты недоступны; при чтении из /dev/urandom она блокирует выполнение, если пул энтропии ещё не инициализирован.

Если установлен флаг GRND_NONBLOCK, в этих случаях getrandom() не блокирует выполнение, а немедленно возбуждает исключение BlockingIOError.

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

os.GRND_RANDOM

Если установлен этот бит, случайные байты берутся из пула /dev/random, а не из пула /dev/urandom.

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