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.

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.

os.environb

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

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

Введено в версии 3.2.

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

os.chdir(path)

os.fchdir(fd)

os.getcwd()

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

os.fsencode(filename)

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

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

Введено в версии 3.2.

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

os.fsdecode(filename)

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

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

Введено в версии 3.2.

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

os.fspath(path)

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

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

Введено в версии 3.6.

class os.PathLike

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

Введено в версии 3.6.

abstractmethod __fspath__()

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

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

os.getenv(key, default=None)

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

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

Доступность: большинство вариантов Unix, Windows.

os.getenvb(key, default=None)

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

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

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

os.geteuid()

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

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

os.getgid()

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

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

os.getgrouplist(user, group)

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

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

Введено в версии 3.3.

os.getgroups()

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

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

Примечание

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

os.getpgid(pid)

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

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

os.getpgrp()

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

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

os.getpid()

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

os.getppid()

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

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

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

os.getpriority(which, who)

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

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

Введено в версии 3.3.

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

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

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

Введено в версии 3.3.

os.getresuid()

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

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

Введено в версии 3.2.

os.getresgid()

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

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

Введено в версии 3.2.

os.getuid()

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

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

os.initgroups(username, gid)

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

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

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

os.seteuid(euid)

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

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

os.setgid(gid)

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

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

os.setgroups(groups)

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

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

Примечание

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

os.setpgrp()

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

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

os.setpgid(pid, pgrp)

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

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

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.

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

os.setregid(rgid, egid)

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

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

os.setresgid(rgid, egid, sgid)

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

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

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

os.setresuid(ruid, euid, suid)

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

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

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

os.setreuid(ruid, euid)

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

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

os.getsid(pid)

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

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

os.setsid()

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

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

os.setuid(uid)

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

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

os.strerror(code)

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

os.supports_bytes_environ

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

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

os.umask(mask)

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

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.

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

Эти функции создают новые объекты файлов. (См. также 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. Файлы, на которые указывают src и dst, должны находиться в одной файловой системе, в противном случае возникает OSError с errno, установленным в errno.EXDEV.

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

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

Доступность: ядро 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: стандартный ввод, 1: стандартный вывод, 2: стандартная ошибка) новый дескриптор файла является наследуемым.

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

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

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

Изменено в версии 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.

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.

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.

Введено в версии 3.5.

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.lseek(fd, pos, how)

Установить текущую позицию дескриптора файла fd в позицию pos, модифицированную значением how: SEEK_SET или 0 для установки позиции относительно начала файла; SEEK_CUR или 1 для установки относительно текущей позиции; SEEK_END или 2 для установки относительно конца файла. Возвращает новую позицию курсора в байтах, начиная с начала файла.

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

Параметры функции lseek(). Их значения равны 0, 1 и 2 соответственно.

Введено в версии 3.3: Некоторые операционные системы могут поддерживать дополнительные значения, например, os.SEEK_HOLE или os.SEEK_DATA.

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

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

Описание значений флагов и режимов см. в документации C-runtime; константы флагов (например, 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.

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

os.pipe()

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

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

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

os.pipe2(flags)

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

Доступность: некоторые варианты Unix.

Новое в версии 3.3.

os.posix_fallocate(fd, offset, len)

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

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

Новое в версии 3.3.

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

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

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

Новое в версии 3.3.

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

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

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

Новое в версии 3.3.

os.pread(fd, n, offset)

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

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

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

Новое в версии 3.3.

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

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

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

• RWF_HIPRI
• RWF_NOWAIT

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

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

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

Доступность: Linux 2.6.30 и новее, FreeBSD 6.0 и новее, OpenBSD 2.7 и новее, AIX 7.1 и новее. Использование флагов требует Linux 4.6 или новее.

Новое в версии 3.7.

os.RWF_NOWAIT

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

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

Доступность: Linux 4.14 и новее.

Новое в версии 3.7.

os.RWF_HIPRI

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

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

Доступность: Linux 4.6 и новее.

Новое в версии 3.7.

os.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.7 или более поздняя версия.

Введено в версии 3.7.

os.RWF_DSYNC

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

Доступность: Linux 4.7 и более поздние версии.

Введено в версии 3.7.

os.RWF_SYNC

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

Доступность: Linux 4.7 и более поздние версии.

Введено в версии 3.7.

os.RWF_APPEND

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

Примечание

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

Введено в версии 3.3.

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

os.set_blocking(fd, blocking)

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

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

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

Введено в версии 3.5.

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

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

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

Введено в версии 3.3.

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.

os.tcsetpgrp(fd, pg)

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

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

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, или может быть включенной логической суммой одного или нескольких значений 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.

Добавлена в версии 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 константы или соответствующее целое значение). Все остальные биты игнорируются.

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

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

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

os.chroot(path)

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

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

Изменено в версии 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.

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

os.lchmod(path, mode)

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

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

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

Изменено в версии 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.

Изменено в версии 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.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() для их установки.

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

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

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

Введено в версии 3.3: Аргумент dir_fd.

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

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.

Новая в версии 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.

Новая в версии 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.

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

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' если они пустые. Поднимает 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 перехватывается и не поднимается.

stat(*, follow_symlinks=True)

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

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

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

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

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

Новое в версии 3.5.

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

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

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

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

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

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

Пример:

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

См. также

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

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

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

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

class os.stat_result

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

Атрибуты:

st_mode

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

st_ino

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

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

st_dev

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

st_nlink

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

st_uid

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

st_gid

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

st_size

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

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

st_atime

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

st_mtime

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

st_ctime

Зависит от платформы:

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

st_atime_ns

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

st_mtime_ns

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

st_ctime_ns

Зависит от платформы:

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

Примечание

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

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

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

st_blocks

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

st_blksize

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

st_rdev

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

st_flags

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

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

st_gen

Номер версии файла.

st_birthtime

Время создания файла.

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

st_fstype

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

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

st_rsize

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

st_creator

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

st_type

Тип файла.

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

st_file_attributes

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

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.3: Добавлены члены st_atime_ns, st_mtime_ns и st_ctime_ns.

Новые возможности в версии 3.5: Добавлен член st_file_attributes в Windows.

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

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 (разрешает принудительные блокировки на FS), ST_WRITE (запись в файл/директорию/символическую ссылку), ST_APPEND (только для добавления файл), ST_IMMUTABLE (неизменяемый файл), ST_NOATIME (не обновлять время доступа), ST_NODIRATIME (не обновлять время доступа к каталогу), ST_RELATIME (обновление времени доступа относительно времени изменения/времени последнего изменения).

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

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

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

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

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

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

Новые возможности в версии 3.7: Добавлен f_fsid.

os.supports_dir_fd

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

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

os.stat in os.supports_dir_fd

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

Новые возможности в версии 3.3.

os.supports_effective_ids

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

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

os.access in os.supports_effective_ids

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

Новые возможности в версии 3.3.

os.supports_fd

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

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

os.chdir in os.supports_fd

Новые возможности в версии 3.3.

os.supports_follow_symlinks

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

Чтобы проверить, принимает ли конкретная функция False в качестве параметра follow_symlinks, используйте оператор in с supports_follow_symlinks. Например, данное выражение оценивается как True если можно указать 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.

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

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

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

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

os.sync()

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

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

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

os.truncate(path, length)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ошибка возникает, если указаны кортежи как для times, так и для ns.

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

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

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

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

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

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(), за исключением того, что возвращает 4-кортеж (dirpath, dirnames, filenames, dirfd), и поддерживает dir_fd.

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

Доступность: Linux 3.17 или новее с glibc 2.27 или новее.

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

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

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

Доступность: Linux 3.17 или новее с glibc 2.27 или новее. Флаги MFD_HUGE* доступны только начиная с Linux 4.14.

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

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

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

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

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

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

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

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

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

Пример:

import os

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

Доступность: Linux 2.6.27 или новее с glibc 2.8 или новее.

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

os.eventfd_read(fd)

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

Доступность: См. eventfd()

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

os.eventfd_write(fd, value)

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

Доступность: См. eventfd()

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

os.EFD_CLOEXEC

Устанавливает флаг закрытия при выполнении для нового дескриптора файла eventfd().

Доступность: См. eventfd()

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

os.EFD_NONBLOCK

Устанавливает флаг O_NONBLOCK для нового дескриптора файла eventfd().

Доступность: См. eventfd()

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

os.EFD_SEMAPHORE

Предоставляет семафорную семантику для чтения из дескриптора файла eventfd(). При чтении внутренний счётчик уменьшается на единицу.

Доступность: Linux 2.6.30 или новее с glibc 2.8 или новее.

Добавлена в версии 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 см. документацию Майкрософт.

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

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

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

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

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

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

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

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

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

os._exit(n)

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

Примечание

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

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

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

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

os.EX_IOERR

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

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

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

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

os.EX_NOPERM

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

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

os.EX_CONFIG

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

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

os.EX_NOTFOUND

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

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

os.fork()

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

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

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

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

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

См. ssl для приложений, использующих модуль SSL с fork().

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

os.forkpty()

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

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

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

Доступность: некоторые варианты Unix.

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

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

Новое в версии 3.2: Поддержка Windows.

os.killpg(pgid, sig)

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

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

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

os.nice(increment)

Добавить increment к «вежливости» процесса. Возвращает новую вежливость.

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

os.pidfd_open(pid, flags=0)

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

См. страницу руководства pidfd_open(2) для получения дополнительной информации.

Доступность: Linux 5.3+

Новое в версии 3.9.

os.plock(op)

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

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

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

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

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

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

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

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

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

os.POSIX_SPAWN_OPEN

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

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

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

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

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавлена в версии 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. 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 не указан или 'open', это работает так же, как двойной щелчок по файлу в проводнике Windows или передача имени файла в качестве аргумента команде start в интерактивной командной оболочке: файл открывается с помощью любого приложения (если таковое имеется), связанного с его расширением.

Когда задан другой operation, он должен быть «глаголом команды», который определяет, что нужно сделать с файлом. Общие глаголы, документированные Microsoft, это '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.

os.times()

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

• user - время пользователя
• system - время системы
• children_user - время пользователя всех дочерних процессов
• children_system - время системы всех дочерних процессов
• elapsed - прошедшее реальное время с фиксированной точки в прошлом

Для совместимости с предыдущими версиями, этот объект также ведет себя как пятерка кортежей, содержащая user, system, children_user, children_system, и elapsed в таком порядке.

См. страницу руководства Unix times(2) и times(3) страницу руководства в Unix или GetProcessTimes MSDN в Windows. В Windows известны только user и system; другие атрибуты равны нулю.

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

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

os.wait()

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

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

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

См. также

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

os.waitid(idtype, id, options)

Дождаться завершения одного или нескольких дочерних процессов. idtype может быть P_PID, P_PGID, P_ALL или P_PIDFD в Linux. id указывает pid для ожидания. options строится путём объединения побитовым ИЛИ одного или нескольких из WEXITED, WSTOPPED или WCONTINUED, а также может быть объединено побитовым ИЛИ с WNOHANG или WNOWAIT. Возвращаемое значение — объект, представляющий данные, содержащиеся в структуре siginfo_t, а именно: si_pid, si_uid, si_signo, si_status, si_code или None если задано WNOHANG и нет дочерних процессов в состоянии ожидания.

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

Новое в версии 3.3.

os.P_PID

os.P_PGID

os.P_ALL

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

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

Новое в версии 3.3.

os.P_PIDFD

Это специфичный для Linux idtype, указывающий, что id — это дескриптор файла, который ссылается на процесс.

Доступность: Linux 5.4+

Новая в версии 3.9.

os.WEXITED

os.WSTOPPED

os.WNOWAIT

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

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

Новая в версии 3.3.

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

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

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

Новая в версии 3.3.

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

os.waitpid(pid, options)

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

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

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

Исключение OSError с значением errno возникает, когда вызов системной функции возвращает -1.

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

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

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

os.wait3(options)

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

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

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

os.wait4(pid, options)

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

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

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

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() функции.

Новая в версии 3.9.

os.WNOHANG

Опция для waitpid() для немедленного возвращения, если статус дочернего процесса недоступен немедленно. В этом случае функция возвращает (0, 0).

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

os.WCONTINUED

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

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

os.WUNTRACED

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

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

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

os.WCOREDUMP(status)

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

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

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

os.WIFCONTINUED(status)

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

См. опцию WCONTINUED.

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

os.WIFSTOPPED(status)

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

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

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

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

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

os.WSTOPSIG(status)

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

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

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

os.WTERMSIG(status)

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

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

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

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

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

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

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.

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

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

os.curdir

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

os.pardir

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

os.sep

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

os.altsep

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

os.extsep

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

os.pathsep

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

os.defpath

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

os.linesep

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

os.devnull

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

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

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

Введено в версии 3.3.

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

os.getrandom(size, flags=0)

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

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

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

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

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

Доступность: Linux 3.17 и новее.

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

os.urandom(size)

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

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

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

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

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

См. также

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

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

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

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

os.GRND_NONBLOCK

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

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

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

os.GRND_RANDOM

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

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