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

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

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

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

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

Примечание

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

exception os.error

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

os.name

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

См.также

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

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

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

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

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

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

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

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

os.ctermid()

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

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

os.environ

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

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

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

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

Примечание

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

Примечание

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

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

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

os.environb

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

environb доступен, только если supports_bytes_environ — True.

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

os.chdir(path)
os.fchdir(fd)
os.getcwd()

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

os.fsencode(filename)

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

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

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

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

os.fsdecode(filename)

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

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

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

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

os.fspath(path)

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

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

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

class os.PathLike

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

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

abstractmethod __fspath__()

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

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

os.getenv(key, default=None)

Возвращает значение переменной среды key, если она существует, или default, если её нет. key, default и результатом будет str.

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

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

os.getenvb(key, default=None)

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

getenvb() доступен, только если supports_bytes_environ — True.

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

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

os.get_exec_path(env=None)

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

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

os.getegid()

Возвращает эффективный идентификатор группы текущего процесса. Это соответствует биту «set 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.putenv с аргументами key, value.

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

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

os.setpriority(which, who, priority)

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

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

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

os.setregid(rgid, egid)

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

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

os.setresgid(rgid, egid, sgid)

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

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

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

os.setresuid(ruid, euid, suid)

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

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

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

os.setreuid(ruid, euid)

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

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

os.getsid(pid)

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

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

os.setsid()

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

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

os.setuid(uid)

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

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

os.strerror(code)

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

os.supports_bytes_environ

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

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

os.umask(mask)

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

os.uname()

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

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

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

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

Доступность: последние разновидности Unix.

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

os.unsetenv(key)

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

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

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

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

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

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

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

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

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

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

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

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

os.close(fd)

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

Примечание

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

os.closerange(fd_low, fd_high)

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

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass
os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

Скопировать count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst. Если offset_src — None, то src считывается с текущей позиции; соответственно для offset_dst. Файлы, указанные src и dst, должны находиться в одной и той же файловой системе, в противном случае возникает OSError с errno, установленным на errno.EXDEV.

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

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

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

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

os.device_encoding(fd)

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

os.dup(fd)

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

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

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

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

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

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

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

os.fchmod(fd, mode)

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

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

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

os.fchown(fd, uid, gid)

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

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

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

os.fdatasync(fd)

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

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

Примечание

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

os.fpathconf(fd, name)

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

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

В Python 3.3 это эквивалентно os.pathconf(fd, name).

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

os.fstat(fd)

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

В Python 3.3 это эквивалентно os.stat(fd).

См.также

Функция stat().

os.fstatvfs(fd)

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

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

os.fsync(fd)

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

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

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

os.ftruncate(fd, length)

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

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

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

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

os.get_blocking(fd)

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

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

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

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

os.isatty(fd)

Возвращает True, если дескриптор файла fd открыт и подключен к tty (-подобному) устройству, иначе False.

os.lockf(fd, cmd, len)

Применить, проверить или снять блокировку POSIX для дескриптора открытого файла. fd — дескриптор открытого файла. cmd указывает используемую команду — одну из F_LOCK, F_TLOCK, F_ULOCK или F_TEST. len определяет блокируемый раздел файла.

Поднимает событие аудита os.lockf с аргументами fd, cmd, len.

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

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

os.F_LOCK
os.F_TLOCK
os.F_ULOCK
os.F_TEST

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

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

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

os.lseek(fd, pos, how)

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

os.SEEK_SET
os.SEEK_CUR
os.SEEK_END

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

os.O_RDONLY
os.O_WRONLY
os.O_RDWR
os.O_APPEND
os.O_CREAT
os.O_EXCL
os.O_TRUNC

Вышеупомянутые константы доступны в Unix и Windows.

os.O_DSYNC
os.O_RSYNC
os.O_SYNC
os.O_NDELAY
os.O_NONBLOCK
os.O_NOCTTY
os.O_CLOEXEC

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

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

os.O_BINARY
os.O_NOINHERIT
os.O_SHORT_LIVED
os.O_TEMPORARY
os.O_RANDOM
os.O_SEQUENTIAL
os.O_TEXT

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

os.O_ASYNC
os.O_DIRECT
os.O_DIRECTORY
os.O_NOFOLLOW
os.O_NOATIME
os.O_PATH
os.O_TMPFILE
os.O_SHLOCK
os.O_EXLOCK

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

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

os.openpty()

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

Доступность: some flavors of Unix.

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

os.pipe()

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

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

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

os.pipe2(flags)

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

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

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

os.posix_fallocate(fd, offset, len)

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL
os.POSIX_FADV_SEQUENTIAL
os.POSIX_FADV_RANDOM
os.POSIX_FADV_NOREUSE
os.POSIX_FADV_WILLNEED
os.POSIX_FADV_DONTNEED

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

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

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

os.pread(fd, n, offset)

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

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

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

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

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

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

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

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

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

Совместите функциональность os.readv() и os.pread().

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

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

os.RWF_NOWAIT

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

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

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

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

os.RWF_HIPRI

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

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

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

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

os.pwrite(fd, str, offset)

Записать байтовую строку в str в файловый дескриптор fd в позиции offset, не изменяя смещение файла.

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

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

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

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

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

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

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

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

Совмещает функциональность os.writev() и os.pwrite().

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

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

os.RWF_DSYNC

Предоставьте для каждой записи эквивалент флага O_DSYNC open(2). Этот эффект флага применяется только к диапазону данных, записанному системным вызовом.

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

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

os.RWF_SYNC

Предоставить для каждой записи эквивалент флага O_SYNC open(2). Этот эффект флага применяется только к диапазону данных, записанному системным вызовом.

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

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

os.read(fd, n)

Чтение не более n байт из файлового дескриптора fd.

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

os.set_blocking(fd, blocking)

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

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

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

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

os.SF_NODISKIO
os.SF_MNOWAIT
os.SF_SYNC

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

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

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

os.readv(fd, buffers)

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

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

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

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

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

os.tcgetpgrp(fd)

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

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

os.tcsetpgrp(fd, pg)

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

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

os.ttyname(fd)

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

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

os.write(fd, str)

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

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

Примечание

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

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

os.writev(fd, buffers)

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

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

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

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

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

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

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

os.get_terminal_size(fd=STDOUT_FILENO)

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

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

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

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

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

class os.terminal_size

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

columns

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

lines

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

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

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

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

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

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

os.get_inheritable(fd)

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

os.set_inheritable(fd, inheritable)

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

os.get_handle_inheritable(handle)

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

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

os.set_handle_inheritable(handle, inheritable)

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

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

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

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

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

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

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

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

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

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

Использовать настоящий uid/gid для проверки доступа к path. Обратите внимание, что большинство операций будет использовать эффективный uid/gid, поэтому эту процедуру можно использовать в среде suid/sgid для проверки наличия у вызывающего пользователя указанного доступа к path. mode должен быть F_OK для проверки существования path, или он может быть включающим ИЛИ одного или нескольких из R_OK, W_OK и X_OK для проверки разрешений. Возвращает True, если доступ разрешён, и False, если нет. См. дополнительную информацию на странице руководства Unix access(2).

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

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

Примечание

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

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

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

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

Примечание

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

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

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

os.F_OK
os.R_OK
os.W_OK
os.X_OK

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

os.chdir(path)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)

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

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

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

os.fchdir(fd)

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

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

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

os.getcwd()

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

os.getcwdb()

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

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

os.lchflags(path, flags)

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

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

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

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

os.lchmod(path, mode)

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

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

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

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

os.lchown(path, uid, gid)

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

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')

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

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

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

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

Примечание

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

См.также

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

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

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

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

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

Выполнить эквивалент системного вызова lstat() по заданному пути. Аналогично stat(), но не использует символические ссылки. Возвращает объект stat_result.

На платформах, не поддерживающих символические ссылки, это псевдоним stat().

В Python 3.3 это эквивалентно os.stat(path, dir_fd=dir_fd, follow_symlinks=False).

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

См.также

Функция stat().

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

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

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

Изменено в версии 3.8: В Windows теперь открываются точки повторной обработки, представляющие другой путь (суррогаты имени), включая символические ссылки и соединения каталогов. Другие виды точек повторной обработки разрешаются операционной системой, как для stat().

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

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

Если каталог уже существует, вызывается FileExistsError.

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

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

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

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

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

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

os.makedirs(name, mode=0o777, exist_ok=False)

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

Параметр mode передаётся в mkdir() для создания конечного каталога; см. описание mkdir(), чтобы узнать, как это интерпретируется. Чтобы установить биты прав доступа к файлам для любых вновь созданных родительских каталогов, вы можете установить umask перед вызовом makedirs(). Биты прав доступа к файлам существующих родительских каталогов не изменяются.

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

Примечание

makedirs() запутается, если элементы пути для создания включают pardir (например, «..» в системах UNIX).

Эта функция правильно обрабатывает пути UNC.

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

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

Изменено в версии 3.4.1: До Python 3.4.1, если exist_ok был True и каталог существовал, makedirs() всё равно вызывала бы ошибку, если mode не соответствовал режиму существующего каталога. Поскольку такое поведение было невозможно реализовать безопасно, оно было удалено в Python 3.4.1. См. bpo-21082.

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

Изменено в версии 3.7: Аргумент mode больше не влияет на биты прав доступа к файлам вновь созданных каталогов промежуточного уровня.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

Создать FIFO (именованный конвейер) с именем path с числовым режимом mode. Текущее значение umask сначала маскируется из режима.

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

FIFO — это конвейеры, к которым можно получить доступ как к обычным файлам. FIFO существуют до тех пор, пока они не будут удалены (например, с os.unlink()). Обычно FIFO используются как место встречи между процессами типа «клиент» и «сервер»: сервер открывает FIFO для чтения, а клиент открывает его для записи. Обратите внимание, что mkfifo() не открывает FIFO — он просто создаёт точку рандеву.

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

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

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

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

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

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

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

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

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

os.major(device)

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

os.minor(device)

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

os.makedev(major, minor)

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

os.pathconf(path, name)

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

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

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

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

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

os.pathconf_names

Имена сопоставления словаря, принятые pathconf() и fpathconf(), с целочисленными значениями, определенными для этих имён операционной системой хоста. Можно использовать для определения набора имён, известных системе.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)

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

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

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

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

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

В Windows, если существует dst, всегда вызывается FileExistsError.

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

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

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

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

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

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

os.renames(old, new)

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')

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

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

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

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

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

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

scandir.close()

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

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

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

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

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

Примечание

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

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

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

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

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

class os.DirEntry

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

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

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

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

Для непосредственного использования в качестве путеподобного объекта, os.DirEntry реализует интерфейс PathLike.

Атрибуты и методы экземпляра os.DirEntry следующие:

name

Базовое имя файла записи относительно аргумента scandir() path.

У атрибута name будет вид bytes, если у аргумента scandir() path будет тип bytes, и str в противном случае. Используйте fsdecode() для декодирования байтовых имён файлов.

path

Полный путь к записи: эквивалент os.path.join(scandir_path, entry.name), где scandir_path — это аргумент scandir() path. Путь является абсолютным, только если аргумент scandir() path был абсолютным. Если аргумент scandir() path был файловым дескриптором, атрибут path совпадает с атрибутом name.

У атрибута path будет вид bytes, если у аргумента scandir() path будет тип bytes, и str в противном случае. Используйте fsdecode() для декодирования байтовых имён файлов.

inode()

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

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

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

is_dir(*, follow_symlinks=True)

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

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

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

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

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

is_file(*, follow_symlinks=True)

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

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

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

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

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

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

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

stat(*, follow_symlinks=True)

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См.также

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

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

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

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

class os.stat_result

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

Атрибуты:

st_mode

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

st_ino

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

st_dev

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

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

st_uid

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

st_gid

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

st_size

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

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

st_atime

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

st_mtime

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

st_ctime

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

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

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

st_mtime_ns

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

st_ctime_ns

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

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

Примечание

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

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

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

st_blocks

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

st_blksize

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

st_rdev

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

st_flags

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

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

st_gen

Номер поколения файла.

st_birthtime

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

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

st_fstype

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

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

st_rsize

Реальный размер файла.

st_creator

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

st_type

Тип файла.

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

st_file_attributes

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

st_reparse_tag

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

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

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

Добавлено в версии 3.3: Добавлены члены st_atime_ns, st_mtime_ns и st_ctime_ns.

Добавлено в версии 3.5: Добавлен член st_file_attributes в Windows.

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

Добавлено в версии 3.7: В Solaris/производные добавлен член st_fstype.

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

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

os.statvfs(path)

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

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

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

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

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

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

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

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

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

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

os.supports_dir_fd

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

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

os.stat in os.supports_dir_fd

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

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

os.supports_effective_ids

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

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

os.access in os.supports_effective_ids

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

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

os.supports_fd

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

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

os.chdir in os.supports_fd

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

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

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

os.stat in os.supports_follow_symlinks

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

os.sync()

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

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

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

os.truncate(path, length)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # не посещать каталоги CVS

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

# Удалить все доступное из каталога, указанного в "top", при условии, что нет
# символических ссылок. ВНИМАНИЕ: это опасно! Например, если top == '/', он может
# удалить все файлы на вашем диске.
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')  # не посещать каталоги CVS

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

# Удалить все доступное из каталога, указанного в "top", при условии, что нет
# символических ссылок. ВНИМАНИЕ: это опасно! Например, если top == '/', он может
# удалить все файлы на вашем диске.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

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

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

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

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

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

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

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

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

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

os.MFD_CLOEXEC
os.MFD_ALLOW_SEALING
os.MFD_HUGETLB
os.MFD_HUGE_SHIFT
os.MFD_HUGE_MASK
os.MFD_HUGE_64KB
os.MFD_HUGE_512KB
os.MFD_HUGE_1MB
os.MFD_HUGE_2MB
os.MFD_HUGE_8MB
os.MFD_HUGE_16MB
os.MFD_HUGE_32MB
os.MFD_HUGE_256MB
os.MFD_HUGE_512MB
os.MFD_HUGE_1GB
os.MFD_HUGE_2GB
os.MFD_HUGE_16GB

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

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

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

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

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

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

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

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

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

Поднимает событие аудита os.getxattr с аргументами path, attribute.

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

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

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

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

Поднимает событие аудита os.listxattr с аргументом path.

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

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

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

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

Поднимает событие аудита os.removexattr с аргументами path, attribute.

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

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

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

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

Примечание

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

Поднимает событие аудита os.setxattr с аргументами path, attribute, value, flags.

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

os.XATTR_SIZE_MAX

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

os.XATTR_CREATE

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

os.XATTR_REPLACE

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

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

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

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

os.abort()

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

os.add_dll_directory(path)

Добавить путь к пути поиска DLL.

Этот путь поиска используется при разрешении зависимостей для импортированных модулей расширения (сам модуль разрешается через sys.path), а также ctypes.

Удалить каталог, вызвав close() для возвращенного объекта или используя его в операторе with.

См. документацию от Microsoft для получения дополнительной информации о том, как загружаются DLL библиотеки.

Поднимает событие аудита os.add_dll_directory с аргументом path.

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

Добавлено в версии 3.8: Предыдущие версии CPython разрешали библиотеки DLL, используя поведение по умолчанию для текущего процесса. Это приводило к несоответствиям, например, только иногда поиск PATH или текущего рабочего каталога, а функции ОС, такие как AddDllDirectory, не имели никакого эффекта.

В версии 3.8 два основных способа загрузки DLL теперь явно переопределяют поведение всего процесса для обеспечения согласованности. См. примечания по переносу для получения информации об обновлении библиотек.

os.execl(path, arg0, arg1, ...)
os.execle(path, arg0, arg1, ..., env)
os.execlp(file, arg0, arg1, ...)
os.execlpe(file, arg0, arg1, ..., env)
os.execv(path, args)
os.execve(path, args, env)
os.execvp(file, args)
os.execvpe(file, args, env)

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

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

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

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

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

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

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

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

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

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

os._exit(n)

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

Примечание

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

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

Примечание

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

os.EX_OK

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

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

os.EX_USAGE

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

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

os.EX_DATAERR

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

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

os.EX_NOINPUT

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

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

os.EX_NOUSER

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

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

os.EX_NOHOST

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

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

os.EX_UNAVAILABLE

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

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

os.EX_SOFTWARE

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

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

os.EX_OSERR

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

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

os.EX_OSFILE

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

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

os.EX_CANTCREAT

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

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

os.EX_IOERR

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

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

os.EX_TEMPFAIL

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

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

os.EX_PROTOCOL

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

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

os.EX_NOPERM

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

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

os.EX_CONFIG

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

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

os.EX_NOTFOUND

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

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

os.fork()

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

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

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

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

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

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

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

os.forkpty()

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

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

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

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

os.kill(pid, sig)

Отправить сигнал sig процессу pid. Константы для конкретных сигналов, доступных на платформе хоста, определены в модуле signal.

Windows: сигналы signal.CTRL_C_EVENT и signal.CTRL_BREAK_EVENT — это специальные сигналы, которые могут быть отправлены только консольным процессам, которые совместно используют общее окно консоли, например, некоторым подпроцессам. Любое другое значение для sig вызовет безоговорочное завершение процесса API TerminateProcess, а код выхода будет установлен на sig. Версия kill() для Windows дополнительно требует уничтожения дескрипторов процессов.

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

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

Добавлено в версии 3.2: Поддержка Windows.

os.killpg(pgid, sig)

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

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

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

os.nice(increment)

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

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

os.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.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

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

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

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

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

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

os.POSIX_SPAWN_OPEN

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

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

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

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

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Доступность: См. документацию по posix_spawn().

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

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

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

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

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

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

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

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

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

os.spawnl(mode, path, ...)
os.spawnle(mode, path, ..., env)
os.spawnlp(mode, file, ...)
os.spawnlpe(mode, file, ..., env)
os.spawnv(mode, path, args)
os.spawnve(mode, path, args, env)
os.spawnvp(mode, file, args)
os.spawnvpe(mode, file, args, env)

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

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

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

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

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

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

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

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

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

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

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

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

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

os.P_NOWAIT
os.P_NOWAITO

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

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

os.P_WAIT

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

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

os.P_DETACH
os.P_OVERLAY

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

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

os.startfile(path[, operation])

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

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

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

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

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

Поднимает событие аудита os.startfile с аргументами path, operation.

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

os.system(command)

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

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

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

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

Поднимает событие аудита os.system с аргументом command.

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

os.times()

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

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

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

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

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

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

os.wait()

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

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

os.waitid(idtype, id, options)

Дождаться завершения одного или нескольких дочерних процессов. idtype может быть P_PID, P_PGID или P_ALL. id указывает идентификатор ожидания. 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, и вернуть кортеж, содержащий его идентификатор процесса и индикацию состояния выхода (закодированную как 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(), за исключением того, что не указан аргумент идентификатора процесса и возвращается трехэлементный кортеж, содержащий идентификатор дочернего процесса, индикацию статуса выхода и информацию об использовании ресурсов. Обратитесь к resource.getrusage() для получения подробной информации об использовании ресурсов. Аргумент опции тот же, что и для waitpid() и wait4().

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

os.wait4(pid, options)

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

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

os.WNOHANG

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

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

os.WCONTINUED

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

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

os.WUNTRACED

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

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

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

os.WCOREDUMP(status)

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

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

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

os.WIFCONTINUED(status)

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

См. вариант WCONTINUED.

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

os.WIFSTOPPED(status)

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

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

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

os.WIFSIGNALED(status)

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

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

os.WIFEXITED(status)

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

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

os.WEXITSTATUS(status)

Возвращает статус выхода процесса.

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

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

os.WSTOPSIG(status)

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

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

Доступность: Unix.

os.WTERMSIG(status)

Возвращает номер сигнала, вызвавшего завершение процесса.

Эту функцию следует использовать, только если WIFSIGNALED() истинно.

Доступность: Unix.

Интерфейс к планировщику

Эти функции управляют распределением процессорного времени для процесса операционной системой. Они доступны только на некоторых платформах Unix. Для получения более подробной информации обратитесь к вашим руководствам по Unix.

Добавлено в версии 3.3.

Следующие политики планирования доступны, если они поддерживаются операционной системой.

os.SCHED_OTHER

Политика планирования по умолчанию.

os.SCHED_BATCH

Политика планирования для процессов, интенсивно использующих ЦПУ, которая пытается сохранить интерактивность на остальной части компьютера.

os.SCHED_IDLE

Политика планирования для фоновых задач с крайне низким приоритетом.

os.SCHED_SPORADIC

Политика планирования для спорадических серверных программ.

os.SCHED_FIFO

Политика планирования в порядке очереди.

os.SCHED_RR

Политика планирования с циклическим перебором.

os.SCHED_RESET_ON_FORK

Этот флаг может быть объединен оператором ИЛИ с любой другой политикой планирования. Когда процесс с этим флагом разветвляется, его дочерняя политика планирования и приоритет сбрасываются на значения по умолчанию.

class os.sched_param(sched_priority)

Этот класс представляет настраиваемые параметры планирования, используемые в sched_setparam(), sched_setscheduler() и sched_getparam(). Это непреложно.

На данный момент возможен только один параметр:

sched_priority

Приоритет планирования для политики планирования.

os.sched_get_priority_min(policy)

Получить минимальное значение приоритета для policy. policy — одна из указанных выше констант политики планирования.

os.sched_get_priority_max(policy)

Получить максимальное значение приоритета для policy. policy — одна из указанных выше констант политики планирования.

os.sched_setscheduler(pid, policy, param)

Установить политику планирования для процесса с PID pid. 0 pid означает вызывающий процесс. 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. 0 pid означает вызывающий процесс.

os.sched_rr_get_interval(pid)

Возвращает циклический такт в секундах для процесса с PID pid. 0 pid означает вызывающий процесс.

os.sched_yield()

Добровольно отказаться от процессора.

os.sched_setaffinity(pid, mask)

Ограничить процесс с PID pid (или текущим процессом, если он равен нулю) набором процессоров. mask — это итерация целых чисел, представляющая множество процессоров, которым должен быть ограничен процесс.

os.sched_getaffinity(pid)

Возвращает множество процессоров, для которых ограничен процесс с PID pid (или текущий процесс, если он равен нулю).

Разная системная информация

os.confstr(name)

Возвращает строковые значения конфигурации системы. name указывает значение конфигурации для извлечения; это может быть строка, которая является именем определенного системного значения; эти имена указаны в ряде стандартов (POSIX, Unix 95, Unix 98 и др.). Некоторые платформы также определяют дополнительные имена. Имена, известные операционной системе хоста, даны как ключи словаря confstr_names. Для переменных конфигурации, не включенных в это сопоставление, также допускается передача целого числа для name.

Если значение конфигурации, указанное в name, не определено, возвращается None.

Если name является строкой и неизвестно, возникает ValueError. Если конкретное значение для name не поддерживается хост-системой, даже если оно включено в confstr_names, OSError поднимается с errno.EINVAL в качестве номера ошибки.

Доступность: Unix.

os.confstr_names

Имена сопоставления словаря, принятые confstr(), с целочисленными значениями, определенными для этих имён операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Доступность: Unix.

os.cpu_count()

Возвращает количество процессоров в системе. Если не определено, возвращает None.

Это число не эквивалентно количеству процессоров, которые может использовать текущий процесс. Количество используемых процессоров можно узнать с помощью len(os.sched_getaffinity(0))

Добавлено в версии 3.4.

os.getloadavg()

Возвращает количество процессов в очереди запуска системы, усредненное за последние 1, 5 и 15 минут, или поднимает OSError, если средняя загрузка была недостижимой.

Доступность: Unix.

os.sysconf(name)

Возвращает целочисленные значения конфигурации системы. Если значение конфигурации, указанное в name, не определено, возвращается -1. Комментарии относительно параметра name для confstr() применимы и здесь; словарь, который предоставляет информацию об известных именах, представлен sysconf_names.

Доступность: Unix.

os.sysconf_names

Имена сопоставления словаря, принятые sysconf(), с целочисленными значениями, определенными для этих имён операционной системой хоста. Это можно использовать для определения набора имён, известных системе.

Доступность: Unix.

Следующие значения данных используются для поддержки операций манипулирования путями. Они определены для всех платформ.

Операции более высокого уровня с именами путей определены в модуле os.path.

os.curdir

Постоянная строка, используемая операционной системой для ссылки на текущий каталог. Это '.' для Windows и POSIX. Также доступно через os.path.

os.pardir

Постоянная строка, используемая операционной системой для ссылки на родительский каталог. Это '..' для Windows и POSIX. Также доступно через os.path.

os.sep

Символ, используемый операционной системой для разделения компонентов имени пути. Это '/' для POSIX и '\\' для Windows. Обратите внимание, что этого недостаточно для анализа или объединения путей используемых os.path.split() и os.path.join(), но иногда бывает полезно. Также доступно через os.path.

os.altsep

Альтернативный символ, используемый операционной системой для разделения компонентов имени пути, или None, если существует только один символ разделителя. Это установлено на '/' в системах Windows, где sep — это обратная косая черта. Также доступно через os.path.

os.extsep

Символ, отделяющий базовое имя файла от расширения; например, '.' в os.py. Также доступно через os.path.

os.pathsep
single: ; (точка с запятой)

Символ, обычно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например ':' для POSIX или ';' для Windows. Также доступно через os.path.

os.defpath

Путь поиска по умолчанию, используемый exec*p* и spawn*p*, если в среде нет ключа 'PATH'. Также доступно через os.path.

os.linesep

Строка, используемая для разделения (или, скорее, завершения) строк на текущей платформе. Это может быть один символ, например '\n' для POSIX, или несколько символов, например '\r\n' для Windows. Не используйте os.linesep в качестве символа конца строки при записи файлов, открытых в текстовом режиме (по умолчанию); вместо этого используйте один '\n' на всех платформах.

os.devnull

Путь к файлу нулевого устройства. Например: '/dev/null' для POSIX, 'nul' для Windows. Также доступно через os.path.

os.RTLD_LAZY
os.RTLD_NOW
os.RTLD_GLOBAL
os.RTLD_LOCAL
os.RTLD_NODELETE
os.RTLD_NOLOAD
os.RTLD_DEEPBIND

Флаги для использования с функциями setdlopenflags() и getdlopenflags(). См. страницу руководства Unix dlopen(3), чтобы узнать, что означают различные флаги.

Добавлено в версии 3.3.

Случайные числа

os.getrandom(size, flags=0)

Получить до 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(), он используется в режиме блокировки: блокировать до тех пор, пока не будет инициализирован пул случайной энтропии системы (ядро собирает 128 бит энтропии). См. обоснование в PEP 524. В Linux функцию getrandom() можно использовать для получения случайных байтов в неблокирующем режиме (с использованием флага GRND_NONBLOCK) или для опроса до тех пор, пока не будет инициализирован пул случайной энтропии системы.

В Unix-подобной системе случайные байты считываются с устройства /dev/urandom. Если устройство /dev/urandom недоступно или не читается, возникает исключение NotImplementedError.

В Windows он будет использовать CryptGenRandom().

См.также

Модуль secrets обеспечивает функции более высокого уровня. Чтобы получить простой в использовании интерфейс для генератора случайных чисел, предоставляемый вашей платформой, см. random.SystemRandom.

Изменено в версии 3.6.0: В Linux getrandom() теперь используется в режиме блокировки для повышения безопасности.

Изменено в версии 3.5.2: В Linux, если системный вызов getrandom() блокируется (пул случайной энтропии ещё не инициализирован), вернуться к чтению /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.