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

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

fsdecode() выполняет обратное преобразование.

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

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

os.fsdecode(filename)

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

fsencode() выполняет обратное преобразование.

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

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

os.fspath(path)

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

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

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

class os.PathLike

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

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

abstractmethod __fspath__()

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

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

os.getenv(key, default=None)

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

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

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

os.getenvb(key, default=None)

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

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

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

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

os.get_exec_path(env=None)

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

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

os.getegid()

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

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

os.geteuid()

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

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

os.getgid()

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

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

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

os.getgrouplist(user, group, /)

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

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

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

os.getgroups()

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

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

Примечание

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

os.getlogin()

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

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

os.getpgid(pid)

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

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

os.getpgrp()

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

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

os.getpid()

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

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

os.getppid()

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

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

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

os.getpriority(which, who)

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

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

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

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

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

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

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

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

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

os.getresgid()

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

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

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

os.getuid()

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

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

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

os.initgroups(username, gid, /)

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

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

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

os.putenv(key, value, /)

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

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

Примечание

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

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

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

os.setegid(egid, /)

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

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

os.seteuid(euid, /)

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

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

os.setgid(gid, /)

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

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

os.setgroups(groups, /)

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

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

Примечание

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

os.setns(fd, nstype=0)

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

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

Начиная с Linux 5.8, fd может ссылаться на файловый дескриптор PID, полученный с помощью pidfd_open(). В этом случае setns() повторно связывает вызывающий поток с одним или несколькими из тех же пространств имён, что и поток, на который ссылается fd. При этом учитываются ограничения, заданные в nstype — битовой маске, объединяющей одну или несколько констант CLONE_NEW* constants, например 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, не Emscripten и не WASI.

os.setpgid(pid, pgrp, /)

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

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

os.setpriority(which, who, priority)

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

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

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

os.setregid(rgid, egid, /)

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

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

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

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

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

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

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

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

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

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

os.setreuid(ruid, euid, /)

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

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

os.getsid(pid, /)

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

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

os.setsid()

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

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

os.setuid(uid, /)

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

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

os.strerror(code, /)

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

os.supports_bytes_environ

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

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

os.umask(mask, /)

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

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

os.uname()

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

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

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

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

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

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

os.unsetenv(key, /)

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

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

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

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

os.unshare(flags)

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

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

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

См. также

Функцию setns().

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

os.CLONE_FILES

os.CLONE_FS

os.CLONE_NEWCGROUP

os.CLONE_NEWIPC

os.CLONE_NEWNET

os.CLONE_NEWNS

os.CLONE_NEWPID

os.CLONE_NEWTIME

os.CLONE_NEWUSER

os.CLONE_NEWUTS

os.CLONE_SIGHAND

os.CLONE_SYSVSEM

os.CLONE_THREAD

os.CLONE_VM

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

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

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

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

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

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

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

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

os.close(fd)

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

Примечание

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

os.closerange(fd_low, fd_high, /)

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

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

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

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

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

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

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

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

Примечание

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

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

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

os.device_encoding(fd)

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

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

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

os.dup(fd, /)

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

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

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

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

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

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

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

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

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

os.fchmod(fd, mode)

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

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

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

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

os.fchown(fd, uid, gid)

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

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

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

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

os.fdatasync(fd)

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

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

Примечание

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

os.fpathconf(fd, name, /)

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

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

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

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

os.fstat(fd)

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

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

См. также

Функцию stat().

os.fstatvfs(fd, /)

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

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

os.fsync(fd)

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

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

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

os.ftruncate(fd, length, /)

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

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

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

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

os.get_blocking(fd, /)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

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

SEEK_SET

Сместить позицию в файле относительно его начала.

SEEK_CUR

Сместить позицию в файле относительно текущей позиции.

SEEK_END

Сместить позицию в файле относительно его конца.

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

os.SEEK_HOLE

os.SEEK_DATA

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

SEEK_DATA

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

SEEK_HOLE

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

Примечание

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

Указанные выше константы доступны в Unix и Windows.

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

Указанные выше константы доступны только в Unix.

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

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

Указанные выше константы доступны только в Windows.

os.O_EVTONLY

os.O_FSYNC

os.O_SYMLINK

os.O_NOFOLLOW_ANY

Указанные выше константы доступны только в macOS.

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

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

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

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

os.openpty()

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

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

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

os.pipe()

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

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

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

os.pipe2(flags, /)

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

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

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

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

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

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

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

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

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

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

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

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

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

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.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, возвращается пустой байтовый объект.

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

Обёртку более высокого уровня для sendfile() см. в socket.socket.sendfile().

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

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

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

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

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

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

os.SF_NOCACHE

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

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

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

os.set_blocking(fd, blocking, /)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Использует реальный uid/gid для проверки доступа к path. Обратите внимание: большинство операций использует эффективный uid/gid, поэтому эту процедуру можно применять в среде suid/sgid, чтобы проверить, есть ли у вызывающего пользователя указанный доступ к path. Для проверки существования 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, кроме Emscripten и WASI.

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)

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

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

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

os.fchdir(fd)

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

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

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

os.getcwd()

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

os.getcwdb()

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

Изменено в версии 3.8: Теперь в 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, кроме Emscripten и WASI.

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

os.lchmod(path, mode)

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

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

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

Доступность: Unix, кроме Linux, FreeBSD >= 1.3, NetBSD >= 1.3 и OpenBSD.

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

os.lchown(path, uid, gid)

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

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

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')

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

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

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

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

Примечание

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

См. также

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

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

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

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

os.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 tempfile.mkdtemp() модуля.

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

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

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

Изменено в версии 3.12.4: В 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, кроме Emscripten и WASI.

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

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

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

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

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

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

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

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

os.major(device, /)

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

os.minor(device, /)

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

os.makedev(major, minor, /)

Составляет необработанный номер устройства из старшего и младшего номеров устройства.

os.pathconf(path, name)

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

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

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

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

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

os.pathconf_names

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)

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

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

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

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

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

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

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

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

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

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

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

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

os.renames(old, new)

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')

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

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

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

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

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

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

scandir.close()

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

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

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

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

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

Примечание

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

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

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

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

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

class os.DirEntry

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

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

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

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

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

Экземпляр 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.

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

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

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

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

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

os.sync()

Принудительно записывает все данные на диск.

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

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

os.truncate(path, length)

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

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

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

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

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

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

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

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

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

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

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

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

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

Устанавливает время доступа и время изменения файла, указанного в path.

utime() принимает два необязательных параметра: times и ns. Они задают время для path и используются следующим образом:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

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

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

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

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

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

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

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

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

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

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

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

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

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

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

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

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

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

import os

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

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

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

os.eventfd_read(fd)

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

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

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

os.eventfd_write(fd, value)

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

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

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

os.EFD_CLOEXEC

Устанавливает флаг 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 для поиска программного файла. Если окружение заменяется (с помощью одного из вариантов 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, кроме Emscripten и WASI.

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

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

os._exit(n)

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

Примечание

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

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

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

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

os.EX_IOERR

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

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

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

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

os.EX_NOPERM

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

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

os.EX_CONFIG

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

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

os.EX_NOTFOUND

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

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

os.fork()

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

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

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

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

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

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, кроме Emscripten и WASI.

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, кроме Emscripten и WASI.

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

os.killpg(pgid, sig, /)

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

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

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

os.nice(increment, /)

Увеличивает «приоритетность» процесса на значение increment. Возвращает новое значение приоритетности.

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

os.pidfd_open(pid, flags=0)

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

Подробнее см. справочную страницу pidfd_open(2).

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

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

os.PIDFD_NONBLOCK

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

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

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

os.plock(op, /)

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

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

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

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

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

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

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

Доступность: недоступно в Emscripten и WASI.

Примечание

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

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

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

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

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

Позиционные аргументы, которые можно указывать только позиционно: path, args и env, — аналогичны аргументам execve().

Параметр path — это путь к исполняемому файлу. Путь path должен содержать каталог. Чтобы передать исполняемый файл без каталога, используйте posix_spawnp().

Аргумент file_actions может быть последовательностью кортежей, описывающих действия с определёнными файловыми дескрипторами дочернего процесса между этапами fork() и exec() реализации библиотеки C. Первый элемент каждого кортежа должен быть одним из трёх указанных ниже индикаторов типа, определяющих оставшиеся элементы кортежа:

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

Выполняет os.dup2(os.open(path, flags, mode), fd).

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

Выполняет os.close(fd).

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

Выполняет os.dup2(fd, new_fd).

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

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

Если аргумент resetids равен True, эффективные 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.

Доступность: Unix; недоступно в Emscripten и WASI.

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

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

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

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

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

Доступность: POSIX; недоступно в Emscripten и WASI.

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

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

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

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

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

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

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

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

Доступность: Unix; недоступно в Emscripten и WASI.

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

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

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

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

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

os.spawnv(mode, path, args)

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

os.spawnvp(mode, file, args)

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

Выполняет программу path в новом процессе.

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

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

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

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

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

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

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

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

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

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

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

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

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

os.P_NOWAIT

os.P_NOWAITO

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

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

os.P_WAIT

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

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

os.P_DETACH

os.P_OVERLAY

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

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

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

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

Если параметр operation не указан, функция действует так же, как двойной щелчок по файлу в проводнике 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; недоступно в Emscripten и WASI.

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; недоступно в Emscripten и WASI.

См. также

Другие описанные ниже функции 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, не Emscripten, не WASI.

Примечание

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

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

os.waitpid(pid, options, /)

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

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

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

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

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

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

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

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

os.wait3(options)

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

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

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

os.wait4(pid, options)

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

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

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

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

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

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

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

Примечание

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

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

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

os.WCONTINUED

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

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

os.WEXITED

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

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

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

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

os.WSTOPPED

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

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

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

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

os.WUNTRACED

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

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

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

os.WNOHANG

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

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

os.WNOWAIT

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

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

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

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

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

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

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

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

os.waitstatus_to_exitcode(status)

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

В Unix:

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

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

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

См. также

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

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

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

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

os.WCOREDUMP(status, /)

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

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

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

os.WIFCONTINUED(status)

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

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

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

os.WIFSTOPPED(status)

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

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

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

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

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

os.WSTOPSIG(status)

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

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

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

os.WTERMSIG(status)

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

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

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

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

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

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

os.SCHED_OTHER

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

os.SCHED_BATCH

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

os.SCHED_IDLE

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

os.SCHED_SPORADIC

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

os.SCHED_FIFO

Политика планирования «первым пришёл — первым обслужен» (FIFO).

os.SCHED_RR

Политика планирования с циклическим распределением времени (round-robin).

os.SCHED_RESET_ON_FORK

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

class os.sched_param(sched_priority)

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

В настоящий момент доступен только один параметр:

sched_priority

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

os.sched_get_priority_min(policy)

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

os.sched_get_priority_max(policy)

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

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

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

os.sched_getscheduler(pid, /)

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

os.sched_setparam(pid, param, /)

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

os.sched_getparam(pid, /)

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

os.sched_rr_get_interval(pid, /)

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

os.sched_yield()

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

os.sched_setaffinity(pid, mask, /)

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

os.sched_getaffinity(pid, /)

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

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

Прочая информация о системе

os.confstr(name, /)

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

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

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

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

os.confstr_names

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

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

os.cpu_count()

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

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

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

os.getloadavg()

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

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

os.sysconf(name, /)

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

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

os.sysconf_names

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

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

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

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

Операции более высокого уровня над путями определены в модуле 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

Путь к устройству null. Например: '/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.