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

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

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

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

• Дизайн всех встроенных модулей, зависящих от операционной системы Python, таков, что, пока доступна та же функциональность, используется тот же интерфейс; например, функция os.stat(path) возвращает информацию stat о path в том же формате (который, как оказалось, возник из интерфейса POSIX).
• Расширения, специфичные для конкретной операционной системы, также доступны через модуль os, но их использование, конечно, угрожает переносимости.
• Все функции, принимающие имена путей или файлов, принимают как объекты типа bytes, так и строковые объекты и возвращают объект того же типа, если возвращается путь или имя файла.
• Примечание «Доступность: Unix» означает, что эта функция обычно встречается в системах Unix. Это не гарантирует ее существование в конкретной операционной системе.
• Если не указано отдельно, все функции, которые заявляют о «Доступности: Unix», поддерживаются в Mac OS X, которая основана на ядре Unix.

exception os.error

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

os.name

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

См. также

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

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

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

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

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

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

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

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 и результат — это str.

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

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

os.getenvb(key, default=None)

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

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

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

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

os.get_exec_path(env=None)

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

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

os.getegid()

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

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

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

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, Windows.

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

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

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

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

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

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

Дескрипторы файлов — это небольшие целые числа, соответствующие файлу, открытому текущим процессом. Например, стандартный ввод обычно имеет дескриптор файла 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, если необходимо. Дескриптор файла fd2 является наследуемым по умолчанию, или не наследуемым, если inheritable равно False.

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

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

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

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

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

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

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

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

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

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

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

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

os.openpty()

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

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

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

os.pipe()

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

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

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

os.pipe2(flags)

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

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

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

os.posix_fallocate(fd, offset, len)

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

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

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

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

os.pread(fd, buffersize, offset)

Читает из дескриптора файла fd в позиции offset. Он будет читать до buffersize байтов. Смещение файла остаётся неизменным.

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

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

os.pwrite(fd, str, offset)

Запись bytestring в дескриптор файла fd с offset, не изменяя смещения файла.

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

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

os.read(fd, n)

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

Примечание

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

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

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

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

Копирование count байтов из дескриптора файла in в дескриптор файла out, начиная с offset. Возвращает количество отправленных байтов. При достижении конца файла возвращает 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. readv() будет переносить данные в каждый буфер до тех пор, пока он не заполнится, а затем переходить к следующему буферу в последовательности, чтобы содержать остальную часть данных. readv() возвращает общее количество прочитанных байтов (которое может быть меньше общего объёма всех объектов).

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

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

os.tcgetpgrp(fd)

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

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

os.tcsetpgrp(fd, pg)

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

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

os.ttyname(fd)

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

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

os.write(fd, str)

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

Примечание

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

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

os.writev(fd, buffers)

Записывает содержимое buffers в дескриптор файла fd. buffers должен быть последовательностью объектов bytes-like. Буферы обрабатываются в порядке массива. Весь контент первого буфера записывается, прежде чем переходить ко второму и так далее. Операционная система может установить ограничение (значение sysconf() SC_IOV_MAX) на количество используемых буферов.

writev() записывает содержимое каждого объекта в дескриптор файла и возвращает общее количество записанных байтов.

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

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

16.1.4.1. Запрос размера терминала

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

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

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

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

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

На некоторых платформах 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 соответственно.

os.chdir(path)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Новая в версии 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() для способов его интерпретации.

Если exist_ok равно False (по умолчанию), исключение OSError генерируется, если целевой каталог уже существует.

Примечание

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

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 — каталог, возбуждается OSError. Используйте 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: Принимает объект-путь.

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

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

Эта функция может поддерживать указание 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).

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

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

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

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

Удалить (стереть) директорию path. Работает только если директория пуста, иначе, будет поднято исключение 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.

Функция принимает объект-путь.

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 будет bytes, если аргумент path scandir() имеет тип bytes, и str в противном случае. Используйте fsdecode() для декодирования имен файлов в байтах.

inode()

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

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

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

is_dir(*, follow_symlinks=True)

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

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

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

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

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

is_file(*, follow_symlinks=True)

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

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

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

is_symlink()

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

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

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

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

stat(*, follow_symlinks=True)

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

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

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

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

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

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

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

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

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

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

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

Пример:

>>> 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, выраженное в наносекундах как целое число.

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

Примечание

Точное значение и разрешение атрибутов 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

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

На системах 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, если он доступен.

os.stat_float_times([newvalue])

Определить, представляют ли stat_result временные метки как объекты с плавающей точкой. Если newvalue равно True, будущие вызовы stat() возвращают значения с плавающей точкой, если оно равно False, будущие вызовы возвращают целые числа. Если newvalue опущено, возвращается текущее значение.

Для совместимости со старыми версиями Python доступ к stat_result в виде кортежа всегда возвращает целые числа.

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

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

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

Устарело начиная с версии 3.3.

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_flag определены две константы модуля: если установлен ST_RDONLY, файловая система смонтирована только для чтения, а если установлен ST_NOSUID, семантика битов setuid/setgid отключена или не поддерживается.

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

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

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

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

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

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

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

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.

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 указан, он должен быть кортежем из двух элементов вида (atime_ns, mtime_ns), где каждый элемент — целое число, представляющее наносекунды.
• Если times не None, он должен быть кортежем из двух элементов вида (atime, mtime), где каждый элемент — целое число или число с плавающей точкой, представляющее секунды.
• Если times задан, а 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: Принимает объект-путь.

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

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

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

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

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

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

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

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

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

os.abort()

Сгенерировать сигнал SIGABRT для текущего процесса. В Unix по умолчанию поведение заключается в создании дампа ядра; в 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 для поиска программы file. Когда среда заменяется (с помощью одного из вариантов exec*e, обсуждаемых в следующем абзаце), новая среда используется в качестве источника переменной PATH. Другие варианты, execl(), execle(), execv() и execve(), не будут использовать переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь.

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

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

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

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

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

os._exit(n)

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

Примечание

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

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

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

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

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

Доступность: 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) или соответствующую документацию API платформы Windows. В Windows известны только user и system; другие атрибуты равны нулю.

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

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

os.wait()

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

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

os.waitid(idtype, id, options)

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

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

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

os.P_PID

os.P_PGID

os.P_ALL

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

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

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

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

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

os.wait3(options)

Аналогично waitpid(), за исключением того, что аргумент идентификатора процесса не указан, и возвращается кортеж из 3 элементов, содержащий PID дочернего процесса, код завершения и информацию об использовании ресурсов. См. resource.getrusage() для подробностей о информации об использовании ресурсов. Аргумент options такой же, как и предоставляемый 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.

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

os.WIFCONTINUED(status)

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

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

os.WIFSTOPPED(status)

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

Если WIFEXITED(status) истинно, возвращает целое число, переданное в системный вызов exit(2). В противном случае возвращаемое значение не имеет смысла.

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

os.WSTOPSIG(status)

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

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

os.WTERMSIG(status)

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

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

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

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

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

os.SCHED_OTHER

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

os.SCHED_BATCH

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

os.SCHED_IDLE

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

os.SCHED_SPORADIC

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

os.SCHED_FIFO

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

os.SCHED_RR

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

os.SCHED_RESET_ON_FORK

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

class os.sched_param(sched_priority)

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

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

sched_priority

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

os.sched_get_priority_min(policy)

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

os.sched_get_priority_max(policy)

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

os.sched_setscheduler(pid, policy, param)

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

os.sched_getscheduler(pid)

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

os.sched_setparam(pid, param)

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

os.sched_getparam(pid)

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

os.sched_rr_get_interval(pid)

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

os.sched_yield()

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

os.sched_setaffinity(pid, mask)

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

os.sched_getaffinity(pid)

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

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

os.confstr(name)

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

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

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

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

os.confstr_names

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

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

os.cpu_count()

Возвращает количество процессоров в системе. Возвращает None если количество процессоров определить невозможно.

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

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

os.getloadavg()

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

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

os.sysconf(name)

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

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

os.sysconf_names

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

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

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

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

os.curdir

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

os.pardir

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

os.sep

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

os.altsep

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

os.extsep

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

os.pathsep

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

os.defpath

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

os.linesep

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

os.devnull

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

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

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

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

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

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.