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

Исходный код: Lib/os.py

Этот модуль предоставляет переносимый способ использования функциональности, зависящей от операционной системы. Если вы хотите просто прочитать или записать файл, см. open(), если вы хотите манипулировать путями, см. модуль os.path, а если вы хотите прочитать все строки во всех файлах в командной строке, см. модуль fileinput. Для создания временных файлов и каталогов см. модуль tempfile, а для работы с файлами и каталогами высокого уровня см. модуль shutil.

Примечания о доступности этих функций:

Конструкции всех встроенных модулей операционной системы Python таковы, что, пока доступна та же функциональность, используется тот же интерфейс; например, функция os.stat(path) возвращает информацию о статистике path в том же формате (который происходит от интерфейса POSIX).
Расширения, характерные для конкретной операционной системы, также доступны через модуль os, но их использование, конечно, представляет угрозу для переносимости.
Все функции, принимающие имена путей или файлов, принимают как байтовые, так и строковые объекты и возвращают объект того же типа, если возвращается путь или имя файла.

Примечание

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

exception os.error: Псевдоним встроенного исключения OSError.

os.name: Имя модуля, зависящего от операционной системы, импортированного. В настоящее время зарегистрированы следующие имена: 'posix', 'nt', 'java'.

См. также

sys.platform имеет более тонкую гранулярность. os.uname() предоставляет информацию о версии, зависящую от системы.

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

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

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

Изменено в версии 3.1: В некоторых системах преобразование с использованием кодировки файловой системы может завершиться ошибкой. В этом случае Python использует обработчик ошибок кодирования surrogateescape, что означает, что нераспознаваемые байты заменяются символом Юникода U+DCxx при декодировании, и эти символы снова преобразуются в исходный байт при кодировании.

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

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

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

os.ctermid()

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

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

os.environ

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

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

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

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

Примечание

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

Примечание

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

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

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

os.environb

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

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

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

os.chdir(path)
os.fchdir(fd)
os.getcwd(): Эти функции описаны в Файлы и каталоги.

os.fsencode(filename)

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

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

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

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

os.fsdecode(filename)

Декодирует объект-путь filename из кодировки файловой системы с обработчиком ошибок 'surrogateescape' или 'strict' в Windows; возвращает 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, default и результат — строки.

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

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

os.getenvb(key, default=None)

Возвращает значение переменной окружения key, если она существует, или default, если нет. key, default и результат — байты.

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.

Примечание

На Mac OS X поведение 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 возвращается идентификатор процесса init (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.

END_OF_DOCUMENT_MARKER

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

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

Примечание

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

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

os.setegid(egid)

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

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

os.seteuid(euid)

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

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

os.setgid(gid)

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

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

os.setgroups(groups)

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

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

Примечание

В Mac OS X длина 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 и возвращает предыдущую маску 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().

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

Доступность: большинство версий Unix.

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

Эта функция создаёт новые объекты файлов. (См. также 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.device_encoding(fd): Возвращает строку, описывающую кодировку устройства, связанного с fd, если оно подключено к терминалу; иначе возвращает None.

os.dup(fd)

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

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

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

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

os.fchown(fd, uid, gid)

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

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

Доступность: 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 указывает раздел файла, который нужно заблокировать.

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

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

Примечание

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

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

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

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

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

os.O_RDONLY
os.O_WRONLY
os.O_RDWR
os.O_APPEND
os.O_CREAT
os.O_EXCL
os.O_TRUNC: Вышеперечисленные константы доступны в Unix и Windows.

os.O_DSYNC
os.O_RSYNC
os.O_SYNC
os.O_NDELAY
os.O_NONBLOCK
os.O_NOCTTY
os.O_CLOEXEC: Вышеперечисленные константы доступны только в Unix.

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

os.O_BINARY
os.O_NOINHERIT
os.O_SHORT_LIVED
os.O_TEMPORARY
os.O_RANDOM
os.O_SEQUENTIAL
os.O_TEXT: Вышеперечисленные константы доступны только в Windows.

os.O_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 и новее.

END_OF_DOCUMENT_MARKER

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

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

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

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

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

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

RWF_HIPRI
RWF_NOWAIT

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

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

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

Доступность: Linux 2.6.30 и новее, FreeBSD 6.0 и новее, OpenBSD 2.7 и новее. Использование флагов требует 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

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

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

Доступность: Linux 2.6.30 и новее, FreeBSD 6.0 и новее, OpenBSD 2.7 и новее. Использование флагов требует 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.read(fd, n)

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

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

Примечание

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

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

os.sendfile(out, in, offset, count)

os.sendfile(out, in, offset, count, [headers, ][trailers, ]flags=0)

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

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

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

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

На Mac OS X и FreeBSD, значение 0 для count указывает на отправку до достижения конца in.

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

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

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

Примечание

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

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

os.set_blocking(fd, blocking)

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

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

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

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

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

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

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

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

os.readv(fd, buffers)

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

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

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

os.writev(fd, buffers)

Записать содержимое buffers в дескриптор файла fd. buffers должен быть последовательностью объектов-последовательностей байтов. Буферы обрабатываются в порядке массива. Содержимое первого буфера записывается полностью до перехода ко второму и т. д.

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

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

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

Получение размера терминала

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

os.get_terminal_size(fd=STDOUT_FILENO)

Возвращает размер окна терминала как (columns, lines), кортеж типа terminal_size.

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

Если дескриптор файла не подключен к терминалу, генерируется OSError.

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

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

class os.terminal_size

Подкласс кортежа, содержащий (columns, lines) размера окна терминала.

columns: Ширина окна терминала в символах.

lines: Высота окна терминала в символах.

Наследование дескрипторов файлов

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

Дескриптор файла имеет флаг «наследуемый», который указывает, может ли дескриптор файла быть унаследован дочерними процессами. С Python 3.4 дескрипторы файлов, созданные Python, по умолчанию не наследуются.

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

В Windows не наследуемые дескрипторы и дескрипторы файлов закрываются в дочерних процессах, за исключением стандартных потоков (дескрипторы 0, 1 и 2: stdin, stdout и stderr), которые всегда наследуются. Используя функции spawn*, все наследуемые дескрипторы и все наследуемые дескрипторы файлов наследуются. Используя модуль subprocess, все дескрипторы файлов, кроме стандартных потоков, закрываются, а наследуемые дескрипторы наследуются только если параметр close_fds равен False.

os.get_inheritable(fd): Получить флаг «наследуемый» указанного дескриптора файла (булево значение).

os.set_inheritable(fd, inheritable): Установить флаг «наследуемый» указанного дескриптора файла.

os.get_handle_inheritable(handle)

Получить флаг «наследуемый» указанного дескриптора (булево значение).

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

os.set_handle_inheritable(handle, inheritable)

Установить флаг «наследуемый» указанного дескриптора.

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

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

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

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

Вы можете проверить, поддерживается ли path в виде дескриптора файла на вашей платформе, используя os.supports_fd. Если она недоступна, ее использование вызовет NotImplementedError.

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

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

Вы можете проверить, поддерживается ли 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 соответственно.

END_OF_DOCUMENT_MARKER ```

os.chdir(path)

Изменить текущую рабочую директорию на path.

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

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

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

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

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

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

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

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

Добавлена в версии 3.3: Аргумент follow_symlinks.

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

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

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

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

Примечание

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

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

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

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

os.getcwd(): Возвращает строку, представляющую текущую рабочую директорию.

os.getcwdb(): Возвращает строку байтов, представляющую текущую рабочую директорию.

os.lchflags(path, flags)

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

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

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

os.lchmod(path, mode)

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

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

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

os.lchown(path, uid, gid)

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

Доступность: 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 для задания путей, относительных к дескрипторам каталогов, и не следования символическим ссылкам.

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

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

Примечание

Для кодирования имен файлов 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: Принимает объект пути для src и dst.

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

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

Если каталог уже существует, генерируется исключение FileExistsError.

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

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

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

Добавлена в версии 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-пути.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

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

В Windows, если dst существует, всегда будет поднята ошибка FileExistsError.

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

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

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

Новое в версии 3.3: Аргументы src_dir_fd и dst_dir_fd.

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

Итератор 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.

stat(*, follow_symlinks=True)

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

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

В Windows атрибуты stat_result, st_ino, st_dev и st_nlink всегда устанавливаются в ноль. Используйте 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().

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

Пример:

>>> 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: Принимает объект объекта пути.

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

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

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

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

st_type: Тип файла.

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

st_file_attributes: Атрибуты Windows файла: dwFileAttributes член структуры BY_HANDLE_FILE_INFORMATION, возвращаемой GetFileInformationByHandle(). См. константы FILE_ATTRIBUTE_* в модуле 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/производных от него.

os.statvfs(path)

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

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

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

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

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

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

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

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

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

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

os.supports_dir_fd

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

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

os.stat in os.supports_dir_fd

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

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

os.supports_effective_ids

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

Чтобы проверить, можете ли вы использовать параметр effective_ids для os.access(), используйте оператор in на supports_effective_ids, как показано ниже:

os.access in os.supports_effective_ids

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

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

os.supports_fd

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

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

os.chdir in os.supports_fd

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

os.supports_follow_symlinks

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

Чтобы проверить, разрешает ли конкретная функция использовать свой параметр follow_symlinks, используйте оператор in на supports_follow_symlinks. Например, это выражение определяет, доступен ли параметр follow_symlinks функции 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 6.0 (Vista). symlink() будет поднимать NotImplementedError на версиях Windows, более ранних 6.0.

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

Примечание

В Windows для успешного создания символических ссылок требуется привилегия SeCreateSymbolicLinkPrivilege. Эта привилегия обычно не предоставляется обычным пользователям, но доступна учетным записям, которые могут повысить привилегии до уровня администратора. Либо получение привилегии, либо запуск вашего приложения как администратора — способы успешного создания символических ссылок.

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

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

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

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

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

os.sync()

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

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

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

END_OF_DOCUMENT_MARKER

os.truncate(path, length)

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

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

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

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

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

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

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

Новая в версии 3.3: Параметр dir_fd.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если необязательный аргумент 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))

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

Расширенные атрибуты Linux

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

Эти функции доступны только в Linux.

os.getxattr(path, attribute, *, follow_symlinks=True)

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

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

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

os.listxattr(path=None, *, follow_symlinks=True)

Возвращает список атрибутов расширенной файловой системы для path. Атрибуты в списке представлены строками, декодированными с использованием кодировки файловой системы. Если path является None, listxattr() проверит текущий каталог.

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

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

os.removexattr(path, attribute, *, follow_symlinks=True)

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

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

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

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)

Устанавливает атрибут расширенной файловой системы attribute для path со значением value. attribute должно быть байтами или строкой без вложенных нулей (прямо или косвенно через интерфейс PathLike). Если это строка, она закодирована с использованием кодировки файловой системы. flags может быть XATTR_REPLACE или XATTR_CREATE. Если задан XATTR_REPLACE и атрибут не существует, EEXISTS будет поднята. Если задан XATTR_CREATE и атрибут уже существует, атрибут не будет создан, и ENODATA будет поднята.

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

Примечание

Ошибка в ядрах Linux версии ниже 2.6.39 привела к тому, что аргумент flags игнорировался в некоторых файловых системах.

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

os.XATTR_SIZE_MAX: Максимальный размер значения расширенного атрибута. В настоящее время в Linux он составляет 64 КБ.

os.XATTR_CREATE: Это возможное значение для аргумента flags в setxattr(). Оно указывает, что операция должна создать атрибут.

os.XATTR_REPLACE: Это возможное значение для аргумента flags в setxattr(). Оно указывает, что операция должна заменить существующий атрибут.

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

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

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

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

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

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

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

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

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

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

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

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

Варианты, включающие «p» в конце (execlp(), execlpe(), execvp() и execvpe()) будут использовать переменную среды PATH, чтобы найти файл программы. Когда среда заменяется (с помощью одного из вариантов 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.

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

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

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

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

Примечание

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

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

Примечание

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

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() из потока.

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

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

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

os.forkpty()

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

Доступность: некоторые варианты 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().

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

os.killpg(pgid, sig)

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

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

os.nice(increment)

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

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

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 возвращаемое значение содержит целочисленный код возврата подпроцесса со знаком.

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

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

Варианты функций 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 должны быть строками; неверные ключи или значения приведут к ошибке функции с возвращаемым значением %%%CODE_BLOCK_1125%%.

В качестве примера, следующие вызовы 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)

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

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

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

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

startfile() возвращает значение сразу после запуска связанного приложения. Нет возможности ожидать завершения приложения и нет способа получить его код завершения. Параметр path является относительным к текущему каталогу. Если требуется использовать абсолютный путь, убедитесь, что первая буква не является косой чертой ('/'); подлежащая Win32-функция ShellExecute() не работает, если это так. Используйте функцию os.path.normpath() для обеспечения правильной кодировки пути для Win32.

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

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

os.system(command)

Выполняет команду (строка) в дочерней оболочке. Реализация выполняется с помощью вызова стандартной C-функции system(), и имеет те же ограничения. Изменения в sys.stdin и т. д. не отражаются в среде выполняемой команды. Если команда command генерирует вывод, он будет отправлен в стандартный поток вывода интерпретатора.

В Unix, возвращаемое значение — код завершения процесса, закодированный в формате, указанном для wait(). Обратите внимание, что POSIX не определяет значение возвращаемого значения C-функции system(), поэтому возвращаемое значение функции Python зависит от системы.

В Windows, возвращаемое значение — это значение, возвращаемое оболочкой системы после выполнения команды command. Оболочка задается переменной среды Windows COMSPEC: обычно это cmd.exe, которая возвращает код завершения запущенной команды; в системах, использующих неродную оболочку, обратитесь к документации вашей оболочки.

Модуль subprocess предоставляет более мощные средства для запуска новых процессов и получения их результатов; использование этого модуля предпочтительнее использования этой функции. См. раздел Замена устаревших функций модулем subprocess в документации subprocess для полезных рецептов.

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

os.wait()

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

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

os.waitid(idtype, id, options)

Ожидает завершения одного или нескольких дочерних процессов. idtype может быть P_PID, P_PGID или P_ALL. id указывает pid, за которым нужно наблюдать. options формируется из OR-соединения одного или нескольких из 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.WEXITED

os.WSTOPPED

os.WNOWAIT

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

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

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

os.CLD_EXITED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_CONTINUED

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

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

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

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, возвращают подходящие дескрипторы процессов.

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

os.wait3(options)

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

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

os.wait4(pid, options)

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

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

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.

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

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

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

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

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, равное 0, означает вызывающий процесс. policy — одна из констант политик планирования, указанных выше. param — экземпляр sched_param.

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

END_OF_DOCUMENT_MARKER

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

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

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

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

os.getrandom(size, flags=0)

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

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

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

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

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

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

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

os.urandom(size)

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

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

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

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

В Windows используется 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.