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

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

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

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

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

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

Режим Python UTF-8

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

• Использует UTF-8 в качестве кодировки файловой системы.
• sys.getfilesystemencoding() возвращает 'utf-8'.
• locale.getpreferredencoding() возвращает 'utf-8' (аргумент do_setlocale не оказывает влияния).
• sys.stdin, sys.stdout и sys.stderr все используют UTF-8 в качестве кодировки текста с включенным surrogateescape обработчиком ошибок для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace как в режиме по умолчанию, учитывающем локаль).
• В Unix, os.device_encoding() возвращает 'utf-8' вместо кодировки устройства.

Обратите внимание, что стандартные настройки потоков в режиме UTF-8 могут быть переопределены с помощью PYTHONIOENCODING (так же, как и в режиме по умолчанию, учитывающем локаль).

Вследствие изменений в API более низкого уровня, другие API более высокого уровня также демонстрируют разное поведение по умолчанию:

• Аргументы командной строки, переменные окружения и имена файлов декодируются в текст с использованием кодировки UTF-8.
• os.fsdecode() и os.fsencode() используют кодировку UTF-8.
• open(), io.open() и codecs.open() по умолчанию используют кодировку UTF-8. Однако они по-прежнему используют обработчик ошибок strict по умолчанию, поэтому попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не произведёт бессмысленные данные.

Режим Python UTF-8 включается, если переменная локали LC_CTYPE равна C или POSIX при запуске Python (см. функцию PyConfig_Read()).

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

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

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

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

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

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

os.ctermid()

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

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

os.environ

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

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

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

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

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

Примечание

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

Примечание

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

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

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

os.environb

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

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

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

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

os.chdir(path)

os.fchdir(fd)

os.getcwd()

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

os.fsencode(filename)

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

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

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

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

os.fsdecode(filename)

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

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

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

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

os.fspath(path)

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

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

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

class os.PathLike

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

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

abstractmethod __fspath__()

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

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

os.getenv(key, default=None)

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

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

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

os.getenvb(key, default=None)

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

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

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

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

os.get_exec_path(env=None)

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

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

os.getegid()

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

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

os.geteuid()

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

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

os.getgid()

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

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

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

os.getgrouplist(user, group, /)

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

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

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

os.getgroups()

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

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

Примечание

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

os.getlogin()

Возвращает имя пользователя, вошедшего в систему на управляющем терминале процесса. Для большинства целей полезнее использовать getpass.getuser(), так как последний проверяет переменные окружения LOGNAME или USERNAME, чтобы определить пользователя, и в качестве резервного варианта использует 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). См. документацию для getgroups() для случаев, когда она может не возвращать тот же список групп, который был установлен вызовом setgroups().

os.setns(fd, nstype=0)

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

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

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

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

В этом примере нить переназначается в пространство имен сети init процесса:

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

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

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

См. также

Функцию unshare().

os.setpgrp()

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

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

os.setpgid(pid, pgrp, /)

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

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

os.setpriority(which, who, priority)

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

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

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

os.setregid(rgid, egid, /)

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

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

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

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

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

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

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

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

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

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

os.setreuid(ruid, euid, /)

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

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

os.getsid(pid, /)

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

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

os.setsid()

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

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

os.setuid(uid, /)

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

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

os.strerror(code, /)

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

os.supports_bytes_environ

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

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

os.umask(mask, /)

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

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

os.uname()

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

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

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

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

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

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

os.unsetenv(key, /)

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

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

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

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

os.unshare(flags)

Отделить части контекста выполнения процесса и переместить их в новый созданный namespace. Подробнее см. страницу руководства unshare(2). Аргумент flags — это битовая маска, объединяющая нулевые или несколько констант CLONE_*, определяющая, какие части контекста выполнения следует отделить от существующих ассоциаций и переместить в новый namespace. Если аргумент 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.

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

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

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

Примечание

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

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

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

os.device_encoding(fd)

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

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

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

os.dup(fd, /)

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

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

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

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

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

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

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

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

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

os.fchmod(fd, mode)

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

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

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

Функция ограничена на 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 управляющим tty, stdin, stdout и stderr вызывающего процесса; закрывает fd.

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

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

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

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

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

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

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

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

SEEK_SET

Корректировка позиции файла относительно начала файла.

SEEK_CUR

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

SEEK_END

Корректировка позиции файла относительно конца файла.

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

os.SEEK_HOLE

os.SEEK_DATA

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

SEEK_DATA

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

SEEK_HOLE

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

Примечание

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

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

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

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

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

Описание значений флагов и режимов см. в документации времени выполнения C; константы флагов (например, 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(). Их можно объединять с помощью побитового оператора OR |. Некоторые из них недоступны на всех платформах. Для описания их доступности и использования см. справочную страницу open(2) на Unix или MSDN в Windows.

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

Вышеперечисленные константы доступны в Unix и Windows.

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

Вышеперечисленные константы доступны только в Unix.

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

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

Вышеперечисленные константы доступны только в Windows.

os.O_EVTONLY

os.O_FSYNC

os.O_SYMLINK

os.O_NOFOLLOW_ANY

Вышеперечисленные константы доступны только в macOS.

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

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

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

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

os.openpty()

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

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

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

os.pipe()

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

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

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

os.pipe2(flags, /)

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

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

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

os.RWF_APPEND

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

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

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

os.read(fd, n, /)

Прочитать не более n байт из файла с дескриптором fd.

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.tcgetpgrp(fd, /)

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

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

os.tcsetpgrp(fd, pg, /)

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

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

os.ttyname(fd, /)

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

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

os.write(fd, str, /)

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

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

Примечание

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

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

os.writev(fd, buffers, /)

Запись содержимого buffers в дескриптор файла fd. buffers должен быть последовательностью объектов типа 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. mode должен быть F_OK для проверки существования path, или он может быть результатом объединения по оператору OR одного или нескольких значений R_OK, W_OK и X_OK для проверки разрешений. Возвращает True, если доступ разрешен, и False в противном случае. См. страницу руководства Unix access(2) для получения дополнительной информации.

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

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

Примечание

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

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

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

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

Примечание

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

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

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

os.F_OK

os.R_OK

os.W_OK

os.X_OK

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

os.chdir(path)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)

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

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

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

os.fchdir(fd)

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

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

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

os.getcwd()

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

os.getcwdb()

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

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

os.lchflags(path, flags)

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

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

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

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

os.lchmod(path, mode)

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

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

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

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

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

os.lchown(path, uid, gid)

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

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

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')

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

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

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

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

Примечание

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

См. также

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

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

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

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

os.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 режим 0o700 обрабатывается специально, чтобы применить контроль доступа к новому каталогу таким образом, что доступ имеют только текущий пользователь и администраторы. Другие значения mode игнорируются.

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

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

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

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

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

Изменено в версии 3.12.4: В Windows теперь обрабатывается режим 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 будет молча заменён. Если 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()

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

Результат кешируется в объекте 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 для этой записи. Этот метод по умолчанию следует символическим ссылкам; чтобы выполнить stat на символической ссылке, добавьте аргумент follow_symlinks=False.

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См. также

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

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

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

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

class os.stat_result

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

Атрибуты:

st_mode

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

st_ino

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

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

st_dev

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

st_nlink

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

st_uid

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

st_gid

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

st_size

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

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

st_atime

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

st_mtime

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

st_ctime

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

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

st_atime_ns

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

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

st_mtime_ns

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

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

st_ctime_ns

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

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

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

st_birthtime

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

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

st_birthtime_ns

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

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

Примечание

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

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

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

st_blocks

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

st_blksize

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

st_rdev

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

st_flags

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

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

st_gen

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

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

st_fstype

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

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

st_rsize

Действительный размер файла.

st_creator

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

st_type

Тип файла.

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

st_file_attributes

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

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

st_reparse_tag

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

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

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

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

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

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

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

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

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

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

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

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

A множество объектов, указывающих, какие функции в модуле 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

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

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

os.stat in os.supports_follow_symlinks

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

os.sync()

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

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

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

os.truncate(path, length)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ошибочно указывать кортежи для обоих параметров times и ns.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

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

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

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

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

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

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

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

Это поведение точно такое же, как у walk(), за исключением того, что она возвращает четвёрку (dirpath, dirnames, filenames, dirfd), и она поддерживает dir_fd.

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

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

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

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

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

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

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

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

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

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

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

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.

Вызывает событие аудита auditing event 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. Windows-версия kill() дополнительно принимает дескрипторы процессов, которые необходимо завершить.

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

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

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

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

os.killpg(pgid, sig, /)

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

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

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

Позиционные аргументы path, args и env аналогичны execve().

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

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

Первый элемент каждого кортежа должен быть одним из трёх указанных ниже типов, описывающих оставшиеся элементы кортежа:

os.POSIX_SPAWN_OPEN

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

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

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

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

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

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

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

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

Если аргумент resetids равен True, он сбросит эффективные UID и GID дочернего процесса на реальные UID и GID родительского процесса. Если аргумент равен False, дочерний процесс сохранит эффективные UID и GID родителя. В любом случае, если биты разрешения установки UID и GID установлены в исполняемом файле, их эффект перекроет установку эффективных 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 — это логическое ИЛИ комбинация флагов. Требуется хотя бы один из флагов WEXITED, WSTOPPED или WCONTINUED; WNOHANG и WNOWAIT — дополнительные необязательные флаги.

Возвращаемое значение — объект, представляющий данные, содержащиеся в siginfo_t структуре, с такими атрибутами:

• si_pid (идентификатор процесса)
• si_uid (действительный идентификатор пользователя дочернего процесса)
• si_signo (всегда SIGCHLD)
• si_status (код завершения или номер сигнала, в зависимости от si_code )
• si_code (см. CLD_EXITED для возможных значений)

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

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

Примечание

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

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

os.waitpid(pid, options, /)

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

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

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

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

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

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

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

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

os.wait3(options)

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

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

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

os.wait4(pid, options)

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

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

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

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

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

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

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

Примечание

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

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

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

os.WCONTINUED

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

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

os.WEXITED

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

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

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

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

os.WSTOPPED

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

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

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

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

os.WUNTRACED

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

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

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

os.WNOHANG

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

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

os.WNOWAIT

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

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

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

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

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

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

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

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

os.waitstatus_to_exitcode(status)

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

На Unix:

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

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

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

См. также

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

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

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

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

os.WCOREDUMP(status, /)

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

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

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

os.WIFCONTINUED(status)

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

См. опцию WCONTINUED.

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

os.WIFSTOPPED(status)

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

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

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

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

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

os.WSTOPSIG(status)

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

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

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

os.WTERMSIG(status)

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

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

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

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

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

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

os.SCHED_OTHER

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

os.SCHED_BATCH

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

os.SCHED_IDLE

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

os.SCHED_SPORADIC

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

os.SCHED_FIFO

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

os.SCHED_RR

Политика планирования по круговому циклу.

os.SCHED_RESET_ON_FORK

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

class os.sched_param(sched_priority)

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

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

sched_priority

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

os.sched_get_priority_min(policy)

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

os.sched_get_priority_max(policy)

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

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

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

os.sched_getscheduler(pid, /)

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

os.sched_setparam(pid, param, /)

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

os.sched_getparam(pid, /)

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

os.sched_rr_get_interval(pid, /)

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

os.sched_yield()

Добровольно уступает процессор.

os.sched_setaffinity(pid, mask, /)

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

os.sched_getaffinity(pid, /)

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

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

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

os.confstr(name, /)

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

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

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

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

os.confstr_names

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

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

os.cpu_count()

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

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

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

os.getloadavg()

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

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

os.sysconf(name, /)

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

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

os.sysconf_names

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

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

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

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

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

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

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

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

os.urandom(size, /)

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

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

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

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

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

См. также

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

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

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

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

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

os.GRND_NONBLOCK

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

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

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

os.GRND_RANDOM

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

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