16.1. os – Различные интерфейсы операционной системы¶os – Miscellaneous operating system interfaces

16.1.1. Имена файлов, аргументы командной строки и переменные окружения¶File Names, Command Line Arguments, and Environment Variables

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

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

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

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

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

Эти функции описаны в Files and Directories.

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)¶

Возвращает значение переменной окружения ключ, если она существует, или значение по умолчанию, если нет. ключ, значение по умолчанию и результат имеют тип str.

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

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

os.getenvb(key, default=None)¶

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

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

Return the name of the user logged in on the controlling terminal of the process. For most purposes, it is more useful to use getpass.getuser() since the latter checks the environment variables LOGNAME or USERNAME to find out who the user is, and falls back to pwd.getpwuid(os.getuid())[0] to get the login name of the current real user id.

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

os.getpgid(pid)¶

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

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

os.getpgrp()¶

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

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

os.getpid()¶

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

os.getppid()¶

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

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

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

os.getpriority(which, who)¶

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

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

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

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

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

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

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

os.getresuid()¶

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

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

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

os.getresgid()¶

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

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

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

os.getuid()¶

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

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

os.initgroups(username, gid)¶

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

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

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

os.putenv(key, value)¶

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

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

Примечание

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

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

os.setegid(egid)¶

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

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

os.seteuid(euid)¶

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

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

os.setgid(gid)¶

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

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

os.setgroups(groups)¶

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

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

Примечание

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

os.setpgrp()¶

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

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

os.setpgid(pid, pgrp)¶

Вызывает системный вызов setpgid(), чтобы установить идентификатор группы процессов процесса с идентификатором 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 если нативный тип ОС окружения – bytes (например, False на Windows).

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

os.umask(mask)¶

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

os.uname()¶

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

• sysname – имя операционной системы

• nodename – имя машины в сети (определяется реализацией)

• release – выпуск операционной системы

• version – версия операционной системы

• machine – идентификатор оборудования

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

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

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

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

os.unsetenv(key)¶

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

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

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

16.1.3. Создание объекта файла¶File Object Creation

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

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

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

16.1.4. Операции с файловыми дескрипторами¶File Descriptor Operations

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

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

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

os.close(fd)¶

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

Примечание

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

os.closerange(fd_low, fd_high)¶

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

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

os.device_encoding(fd)¶

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

os.dup(fd)¶

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

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

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

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

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

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

os.fchmod(fd, mode)¶

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

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

os.fchown(fd, uid, gid)¶

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

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

os.fdatasync(fd)¶

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

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

Примечание

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

os.fpathconf(fd, name)¶

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

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

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

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

os.fstat(fd)¶

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

Начиная с Python 3.3, это эквивалентно os.stat(fd).

См. также

Функция stat().

os.fstatvfs(fd)¶

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

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

os.fsync(fd)¶

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

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

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

os.ftruncate(fd, length)¶

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

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

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

os.get_blocking(fd)¶

Возвращает блокирующий режим файлового дескриптора: False, если установлен флаг O_NONBLOCK, и True, если флаг сброшен.

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

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

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

os.isatty(fd)¶

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

os.lockf(fd, cmd, len)¶

Применяет, проверяет или удаляет POSIX-блокировку на открытом файловом дескрипторе. fd – открытый файловый дескриптор. cmd задаёт команду: одну из F_LOCK, F_TLOCK, F_ULOCK или F_TEST. len задаёт участок файла для блокировки.

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

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

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

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

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

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

os.lseek(fd, pos, how)¶

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

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

os.O_RDONLY¶

os.O_WRONLY¶

os.O_RDWR¶

os.O_APPEND¶

os.O_CREAT¶

os.O_EXCL¶

os.O_TRUNC¶

Приведённые выше константы доступны в Unix и Windows.

os.O_DSYNC¶

os.O_RSYNC¶

os.O_SYNC¶

os.O_NDELAY¶

os.O_NONBLOCK¶

os.O_NOCTTY¶

os.O_CLOEXEC¶

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

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

os.O_BINARY¶

os.O_NOINHERIT¶

os.O_SHORT_LIVED¶

os.O_TEMPORARY¶

os.O_RANDOM¶

os.O_SEQUENTIAL¶

os.O_TEXT¶

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

os.O_ASYNC¶

os.O_DIRECT¶

os.O_DIRECTORY¶

os.O_NOFOLLOW¶

os.O_NOATIME¶

os.O_PATH¶

os.O_TMPFILE¶

os.O_SHLOCK¶

os.O_EXLOCK¶

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

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

os.openpty()¶

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

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

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

os.pipe()¶

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

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

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

os.pipe2(flags)¶

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

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

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

os.posix_fallocate(fd, offset, len)¶

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

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

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

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

os.pread(fd, buffersize, offset)¶

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

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

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

os.pwrite(fd, str, offset)¶

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

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

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

os.read(fd, n)¶

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

Примечание

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

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

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

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

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

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

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

os.tcgetpgrp(fd)¶

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

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

os.tcsetpgrp(fd, pg)¶

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

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

os.ttyname(fd)¶

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

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

os.write(fd, str)¶

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

Примечание

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

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

os.writev(fd, buffers)¶

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

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

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

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

16.1.5. Файлы и каталоги¶Files and Directories

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

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

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

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

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

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

• Не следовать символьным ссылкам: Если follow_symlinks равен False, и последний элемент пути для операции является символьной ссылкой, функция будет работать с самой символьной ссылкой, а не с файлом, на который она указывает. (В системах POSIX Python вызовет версию функции l....)

  Вы можете проверить, поддерживается ли follow_symlinks на вашей платформе, с помощью os.supports_follow_symlinks. Если эта возможность недоступна, её использование вызовет NotImplementedError.

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

os.F_OK¶

os.R_OK¶

os.W_OK¶

os.X_OK¶

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

os.chdir(path)¶

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

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

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

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

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

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

• stat.UF_NODUMP

• stat.UF_IMMUTABLE

• stat.UF_APPEND

• stat.UF_OPAQUE

• stat.UF_NOUNLINK

• stat.UF_COMPRESSED

• stat.UF_HIDDEN

• stat.SF_ARCHIVED

• stat.SF_IMMUTABLE

• stat.SF_APPEND

• stat.SF_NOUNLINK

• stat.SF_SNAPSHOT

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

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

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

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

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

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

• stat.S_ISUID

• stat.S_ISGID

• stat.S_ENFMT

• stat.S_ISVTX

• stat.S_IREAD

• stat.S_IWRITE

• stat.S_IEXEC

• stat.S_IRWXU

• stat.S_IRUSR

• stat.S_IWUSR

• stat.S_IXUSR

• stat.S_IRWXG

• stat.S_IRGRP

• stat.S_IWGRP

• stat.S_IXGRP

• stat.S_IRWXO

• stat.S_IROTH

• stat.S_IWOTH

• stat.S_IXOTH

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

Примечание

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

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

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

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

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

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

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

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

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

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

os.chroot(path)¶

Изменяет корневую директорию текущего процесса на path.

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

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

os.fchdir(fd)¶

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

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

os.getcwd()¶

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

os.getcwdb()¶

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

os.lchflags(path, flags)¶

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

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

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

os.lchmod(path, mode)¶

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

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

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

os.lchown(path, uid, gid)¶

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')¶

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

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

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

Примечание

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

См. также

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

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

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

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

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

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

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

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

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

См. также

Функция stat().

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметр mode передается в mkdir(); подробнее об интерпретации см. в описании mkdir() .

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

Примечание

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

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

Новое в версии 3.2: Параметр exist_ok.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.major(device)¶

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

os.minor(device)¶

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

os.makedev(major, minor)¶

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

os.pathconf(path, name)¶

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

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

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

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

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

os.pathconf_names¶

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

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

os.readlink(path, *, dir_fd=None)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)¶

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

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

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

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

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

Если требуется кроссплатформенная перезапись целевого объекта, используйте replace().

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

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

os.renames(old, new)¶

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')¶

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

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

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

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

scandir.close()¶

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

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

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

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

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

Примечание

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

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

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

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

class os.DirEntry¶

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

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

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

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

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

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

name¶

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

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

path¶

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

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

inode()¶

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

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

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

is_dir(*, follow_symlinks=True)¶

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

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

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

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

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

is_file(*, follow_symlinks=True)¶

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

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

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

is_symlink()¶

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

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

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

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

stat(*, follow_symlinks=True)¶

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См. также

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

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

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

class os.stat_result¶

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

Атрибуты:

st_mode¶

Режим файла: тип файла и биты режима (права доступа).

st_ino¶

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

• номер inode в Unix,

• индекс файла на Windows

st_dev¶

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

st_nlink¶

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

st_uid¶

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

st_gid¶

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

st_size¶

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

Временные метки:

st_atime¶

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

st_mtime¶

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

st_ctime¶

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

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

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

st_atime_ns¶

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

st_mtime_ns¶

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

st_ctime_ns¶

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

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

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

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

Примечание

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

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

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

st_blocks¶

Количество 512-байтовых блоков, выделенных файлу. Может быть меньше st_size/512, если в файле есть дырки (holes).

st_blksize¶

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

st_rdev¶

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

st_flags¶

Определённые пользователем флаги для файла.

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

st_gen¶

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

st_birthtime¶

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

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

st_rsize¶

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

st_creator¶

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

st_type¶

Тип файла.

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

st_file_attributes¶

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

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

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

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

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

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

os.stat_float_times([newvalue])¶

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

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

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

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

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

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

os.statvfs(path)¶

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

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

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

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

Доступно: Unix.

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

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

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

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

os.supports_dir_fd¶

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

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

os.stat in os.supports_dir_fd

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

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

os.supports_effective_ids¶

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

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

os.access in os.supports_effective_ids

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

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

os.supports_fd¶

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

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

os.chdir in os.supports_fd

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

os.supports_follow_symlinks¶

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

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

os.stat in os.supports_follow_symlinks

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

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

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

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

Поддержка символических ссылок была введена в Windows 6.0 (Vista). symlink() вызовет NotImplementedError в версиях Windows старше 6.0.

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

Примечание

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

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

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

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

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

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

os.sync()¶

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

Доступно: Unix.

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

os.truncate(path, length)¶

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

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

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

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

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

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

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

Удаляет файл path. Эта функция семантически идентична remove(); имя unlink – это её традиционное имя в Unix. Подробнее см. документацию remove().

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

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

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

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

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

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

• Если times не равен None, то это должен быть кортеж из двух элементов вида (atime, mtime), где каждый элемент – int или float, выражающий секунды.

• Если times равен None, а ns не указан, то это эквивалентно указанию ns=(atime_ns, mtime_ns), где оба времени равны текущему времени.

Указывать кортежи одновременно для times и ns – ошибка.

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # не заходить в 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.

This function always supports paths relative to directory descriptors and not following symlinks. Note however that, unlike other functions, the fwalk() default value for follow_symlinks is 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: Принимает объект, подобный пути.

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

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

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

os.abort()¶

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

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

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

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

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

os.execv(path, args)¶

os.execve(path, args, env)¶

os.execvp(file, args)¶

os.execvpe(file, args, env)¶

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

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

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

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

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

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

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

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

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

os._exit(n)¶

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

Примечание

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

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

os.EX_OK¶

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

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

os.EX_USAGE¶

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

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

os.EX_DATAERR¶

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

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

os.EX_NOINPUT¶

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

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

os.EX_NOUSER¶

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

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

os.EX_NOHOST¶

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

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

os.EX_UNAVAILABLE¶

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

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

os.EX_SOFTWARE¶

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

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

os.EX_OSERR¶

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

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

os.EX_OSFILE¶

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

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

os.EX_CANTCREAT¶

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

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

os.EX_IOERR¶

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

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

os.EX_TEMPFAIL¶

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

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

os.EX_PROTOCOL¶

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

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

os.EX_NOPERM¶

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

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

os.EX_CONFIG¶

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

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

os.EX_NOTFOUND¶

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

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

os.fork()¶

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

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

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

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

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

os.forkpty()¶

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

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

os.kill(pid, sig)¶

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

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

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

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

os.killpg(pgid, sig)¶

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

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

os.nice(increment)¶

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

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

os.plock(op)¶

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

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

os.popen(cmd, mode='r', buffering=-1)¶

Открывает канал для связи с командой cmd. Возвращаемое значение – открытый файловый объект, подключённый к каналу, который можно читать или записывать в зависимости от того, является ли mode равным 'r' (по умолчанию) или 'w'. Аргумент buffering имеет тот же смысл, что соответствующий аргумент встроенной функции open(). Возвращаемый файловый объект читает или записывает текстовые строки, а не байты.

Метод close возвращает None, если подпроцесс завершился успешно, или код возврата подпроцесса в случае ошибки. В системах POSIX, если код возврата положительный, он представляет собой возвращаемое значение процесса, сдвинутое влево на один байт. Если код возврата отрицательный, процесс был завершён сигналом, соответствующим отрицательному значению кода возврата. (Например, возвращаемое значение может быть - signal.SIGKILL, если подпроцесс был убит.) В системах Windows возвращаемое значение содержит знаковый целочисленный код возврата дочернего процесса.

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

os.spawnl(mode, path, ...)¶

os.spawnle(mode, path, ..., env)¶

os.spawnlp(mode, file, ...)¶

os.spawnlpe(mode, file, ..., env)¶

os.spawnv(mode, path, args)¶

os.spawnve(mode, path, args, env)¶

os.spawnvp(mode, file, args)¶

os.spawnvpe(mode, file, args, env)¶

Выполняет программу path в новом процессе.

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

Если mode равен P_NOWAIT, эта функция возвращает идентификатор нового процесса; если mode равен P_WAIT, возвращает код выхода процесса, если он завершился нормально, или -signal, где signal – сигнал, который завершил процесс. В Windows идентификатор процесса на самом деле является дескриптором процесса, поэтому его можно использовать с функцией waitpid().

Варианты «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)

Доступность: Unix, Windows. spawnlp(), spawnlpe(), spawnvp()\nи spawnvpe() недоступны в Windows. spawnle() и\nspawnve() не являются потокобезопасными в Windows; рекомендуется использовать\nмодуль 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, она должна быть «глаголом команды» (command verb), определяющим, что делать с файлом. Распространённые глаголы, задокументированные Microsoft: 'print' и 'edit' (используются для файлов), а также 'explore' и 'find' (используются для каталогов).

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

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

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

os.system(command)¶

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

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

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

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

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

os.times()¶

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

• user – пользовательское время

• system – системное время

• children_user – пользовательское время всех дочерних процессов

• children_system – системное время всех дочерних процессов

• elapsed – прошедшее реальное время с фиксированной точки в прошлом

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

См. страницу руководства Unix\ntimes(2) или соответствующую документацию Windows Platform API.\nВ Windows известны только user и system; остальные\nатрибуты равны нулю.

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

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

os.wait()¶

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

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

os.waitid(idtype, id, options)¶

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

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

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

os.P_PID¶

os.P_PGID¶

os.P_ALL¶

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

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

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

os.WEXITED¶

os.WSTOPPED¶

os.WNOWAIT¶

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

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

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

os.CLD_EXITED¶

os.CLD_DUMPED¶

os.CLD_TRAPPED¶

os.CLD_CONTINUED¶

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

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

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

os.waitpid(pid, options)¶

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

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

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

Возбуждается OSError со значением errno, когда системный вызов возвращает -1.

В Windows: ожидает завершения процесса, заданного дескриптором процесса pid, и возвращает кортеж, содержащий pid и его статус завершения, сдвинутый влево на 8 бит (сдвиг упрощает кроссплатформенное использование функции). pid, меньший или равный 0, не имеет особого смысла в Windows и вызывает исключение. Значение целочисленного параметра options не влияет на результат. pid может относиться к любому процессу, чей идентификатор известен, не обязательно дочернему. Функции 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¶

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

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

os.WUNTRACED¶

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

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

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

os.WCOREDUMP(status)¶

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

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

os.WIFCONTINUED(status)¶

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

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

os.WIFSTOPPED(status)¶

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

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

os.WIFSIGNALED(status)¶

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

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

os.WIFEXITED(status)¶

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

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

os.WEXITSTATUS(status)¶

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

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

os.WSTOPSIG(status)¶

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

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

os.WTERMSIG(status)¶

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

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

16.1.7. Интерфейс к планировщику¶Interface to the scheduler

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

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

os.SCHED_OTHER¶

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

os.SCHED_BATCH¶

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

os.SCHED_IDLE¶

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

os.SCHED_SPORADIC¶

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

os.SCHED_FIFO¶

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

os.SCHED_RR¶

Циклическая политика планирования.

os.SCHED_RESET_ON_FORK¶

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

class os.sched_param(sched_priority)¶

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

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

sched_priority¶

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

os.sched_get_priority_min(policy)¶

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

os.sched_get_priority_max(policy)¶

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

os.sched_setscheduler(pid, policy, param)¶

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

os.sched_getscheduler(pid)¶

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

os.sched_setparam(pid, param)¶

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

os.sched_getparam(pid)¶

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

os.sched_rr_get_interval(pid)¶

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

os.sched_yield()¶

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

os.sched_setaffinity(pid, mask)¶

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

os.sched_getaffinity(pid)¶

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

16.1.8. Разные сведения о системе¶Miscellaneous System Information

os.confstr(name)¶

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

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

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

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

os.confstr_names¶

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

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

os.cpu_count()¶

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

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

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

os.getloadavg()¶

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

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

os.sysconf(name)¶

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

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

os.sysconf_names¶

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

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

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

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

os.curdir¶

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

os.pardir¶

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

os.sep¶

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

os.altsep¶

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

os.extsep¶

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

os.pathsep¶

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

os.defpath¶

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

os.linesep¶

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

os.devnull¶

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

os.RTLD_LAZY¶

os.RTLD_NOW¶

os.RTLD_GLOBAL¶

os.RTLD_LOCAL¶

os.RTLD_NODELETE¶

os.RTLD_NOLOAD¶

os.RTLD_DEEPBIND¶

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

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

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

os.getrandom(size, flags=0)¶

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

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

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

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

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

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

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

os.urandom(size)¶

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

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

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

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

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

См. также

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

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

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

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

os.GRND_NONBLOCK¶

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

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

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

os.GRND_RANDOM¶

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

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