16.1. `os` – Различные интерфейсы операционной системы

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

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

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

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

Примечание

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

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

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

Смотрите также

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

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

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

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

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

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

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

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

os.ctermid()¶

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

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

os.environ¶

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

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

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

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

Примечание

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

Примечание

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

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

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

os.environb¶

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

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

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

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

os.fsencode(filename)¶

Encode path-like filename to the filesystem encoding with 'surrogateescape' error handler, or 'strict' on Windows; return bytes unchanged.

fsdecode() является обратной функцией.

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

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

os.fsdecode(filename)¶

Decode the path-like filename from the filesystem encoding with 'surrogateescape' error handler, or 'strict' on Windows; return str unchanged.

fsencode() является обратной функцией.

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

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

os.fspath(путь)¶

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

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

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

classos.PathLike¶

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

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

abstractmethod__fspath__()¶

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

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

os.getenv(key, default=None)¶

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

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

Доступность: большинство разновидностей 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()¶

Возвращает имя пользователя, вошедшего в систему на управляющем терминале процесса. Для большинства целей полезнее использовать getpass.getuser(), так как последняя проверяет переменные окружения LOGNAME или USERNAME, чтобы определить, кто является пользователем, и в случае неудачи обращается к pwd.getpwuid(os.getuid())[0], чтобы получить имя входа текущего реального идентификатора пользователя.

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

os.getpgid(идентификатор процесса)¶

Возвращает идентификатор группы процесса с идентификатором процесса 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(имя пользователя, gid)¶

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

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

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

os.putenv(ключ, значение)¶

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

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

Примечание

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

os.setpgrp()¶

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

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

os.setpgid(pid, pgrp)¶

Вызывает системный вызов setpgid() для установки идентификатора группы процессов процесса с id 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(идентификатор процесса)¶

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

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

os.setsid()¶

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

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

os.setuid(uid)¶

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

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

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

os.supports_bytes_environ¶: True, если собственный тип окружения ОС – байты (например, False в Windows).

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

os.umask(маска)¶: Устанавливает текущую числовую маску 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. Создание файлового объекта

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

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

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

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

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

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

os.close(fd)¶: Закрывает файловый дескриптор fd.

Примечание

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

os.closerange(fd_low, fd_high)¶

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

python

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

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

os.dup(fd)¶

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

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

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

os.dup2(fd, fd2, inheritable=True)¶: Дублирует файловый дескриптор fd в fd2, при необходимости закрывая последний. Файловый дескриптор fd2 является наследуемым по умолчанию, или ненаследуемым, если inheritable равен False.

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

os.fchmod(fd, mode)¶

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

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

os.fchown(fd, uid, gid)¶

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

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

os.fdatasync(fd)¶

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

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

Примечание

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

os.fpathconf(fd, name)¶

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

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

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

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

os.fstat(fd)¶

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

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

Смотрите также

Функция stat().

os.fstatvfs(fd)¶

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

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

os.fsync(fd)¶

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

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

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

os.ftruncate(fd, length)¶

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

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

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

os.get_blocking(fd)¶

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

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

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

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

os.isatty(fd)¶: Возвращает True, если файловый дескриптор fd открыт и подключён к (псевдо)терминальному устройству, иначе 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(). Их можно комбинировать с помощью оператора побитового ИЛИ |. Некоторые из них доступны не на всех платформах. Описание их доступности и использования см. в справочной странице 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()¶

Создаёт канал (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)¶

Объявляет намерение обращаться к данным в определённом шаблоне, что позволяет ядру выполнять оптимизации. Совет (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)¶

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

os.set_blocking(fd, blocking)¶

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

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

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

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

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

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

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

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

os.readv(fd, buffers)¶

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

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

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

os.tcgetpgrp(fd)¶

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

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

os.tcsetpgrp(fd, pg)¶

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

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

os.ttyname(fd)¶

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

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

os.write(fd, str)¶: Записывает байтовую строку из str в файловый дескриптор fd. Возвращает количество фактически записанных байтов.

Примечание

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

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

os.writev(fd, buffers)¶

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

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

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

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

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

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

os.get_terminal_size(fd=STDOUT_FILENO)¶

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

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

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

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

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

classos.terminal_size¶

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

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

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

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

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

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

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

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

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

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

os.get_handle_inheritable(handle)¶

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

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

os.set_handle_inheritable(handle, inheritable)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

python

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

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

python

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.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

os.chroot(путь)¶

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

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

Изменено в версии 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(устройство)¶: Извлекает старший номер устройства из исходного номера устройства (обычно поле st_dev или st_rdev из stat).

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

os.makedev(major, minor)¶: Составляет исходный номер устройства из старшего и младшего номеров устройства.

os.pathconf(path, name)¶

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

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

Доступность: 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(имя)¶: Удаляет каталоги рекурсивно. Работает как 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).

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

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

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

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

scandir.close()¶

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

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

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

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

python

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.

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

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

Возвращает номер 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().

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

Пример:

python

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

classos.stat_result¶

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

Атрибуты:

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

st_ino¶

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

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

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

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

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

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

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

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

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

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

st_ctime¶

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

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

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

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

st_ctime_ns¶

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

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

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

Примечание

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

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

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

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

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

st_rdev¶: Тип устройства, если индексный дескриптор является устройством.

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

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

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

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

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

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

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

st_type¶: Тип файла.

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

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

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

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

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

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

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

os.stat_float_times([newvalue])¶

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

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

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

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

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

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

os.statvfs(путь)¶

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

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

python

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, например:

python

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() открытые файловые дескрипторы при вызове на вашей локальной платформе:

python

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

python

os.stat in os.supports_follow_symlinks

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

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

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

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

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

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

Примечание

В Windows для успешного создания символических ссылок требуется привилегия SeCreateSymbolicLinkPrivilege. Обычно эта привилегия не предоставляется обычным пользователям, но доступна учётным записям, которые могут повысить привилегии до уровня администратора. Чтобы успешно создавать символические ссылки, необходимо либо получить эту привилегию, либо запускать приложение от имени администратора.

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

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

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

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

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

os.sync()¶

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

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

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

os.truncate(path, length)¶

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

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

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

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

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

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

os.unlink(path, *, dir_fd=None)¶: Удаляет файл path. Эта функция семантически идентична remove(); имя unlink является её традиционным именем в Unix. Дополнительную информацию см. в документации remove().

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

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

python

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() не позволяет удалять каталог до того, как каталог будет пуст:

python

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

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

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

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

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

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

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

Примечание

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

python

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() не позволяет удалять каталог до того, как каталог будет пуст:

python

# Удалить всё доступное из каталога, указанного в "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.5.1. Расширенные атрибуты Linux

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

os.execv(path, args)¶

os.execve(path, args, env)¶

os.execvp(file, args)¶

os.execvpe(file, args, env)¶

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Примечание

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

os.EX_OK¶

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

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

os.EX_USAGE¶

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

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

os.EX_DATAERR¶

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

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

os.EX_NOINPUT¶

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

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

os.EX_NOUSER¶

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

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

os.EX_NOHOST¶

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

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

os.EX_UNAVAILABLE¶

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

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

os.EX_SOFTWARE¶

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

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

os.EX_OSERR¶

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

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

os.EX_OSFILE¶

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

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

os.EX_CANTCREAT¶

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

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

os.EX_IOERR¶

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

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

os.EX_TEMPFAIL¶

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

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

os.EX_PROTOCOL¶

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

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

os.EX_NOPERM¶

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

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

os.EX_CONFIG¶

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

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

os.EX_NOTFOUND¶

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

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

os.fork()¶

Создаёт дочерний процесс с помощью 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 к значению «niceness» процесса. Возвращает новое значение niceness.

Доступность: 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(режим, файл, ...)¶

os.spawnlpe(режим, файл, ..., окружение)¶

os.spawnv(режим, путь, аргументы)¶

os.spawnve(режим, путь, аргументы, окружение)¶

os.spawnvp(режим, файл, аргументы)¶

os.spawnvpe(режим, файл, аргументы, окружение)¶

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

(Обратите внимание, что модуль 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() эквивалентны:

python

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

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

Доступность: Unix, Windows. spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не потокобезопасны в Windows; рекомендуем вместо этого использовать модуль subprocess.

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

os.P_NOWAIT¶

os.P_NOWAITO¶

Возможные значения для параметра mode семейства функций spawn*. Если указано одно из этих значений, функции spawn*() вернутся сразу после создания нового процесса, возвращая идентификатор процесса.

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

os.P_WAIT¶

Возможное значение для параметра mode семейства функций spawn*. Если в качестве mode указано это значение, функции spawn*() не вернутся, пока новый процесс не завершит выполнение, и вернут код возврата процесса в случае успешного выполнения, или -signal, если сигнал завершит процесс.

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

os.P_DETACH¶

os.P_OVERLAY¶

Возможные значения для параметра mode семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH аналогичен P_NOWAIT, но новый процесс отсоединяется от консоли вызывающего процесса. Если используется P_OVERLAY, текущий процесс будет заменен; функция spawn* не вернется.

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

os.startfile(путь[, операция])¶

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

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

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

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

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

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

os.system(команда)¶

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

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

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

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

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

os.times()¶

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

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

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

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

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

os.wait()¶

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

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

os.waitid(тип идентификатора, идентификатор, опции)¶

Ожидает завершения одного или нескольких дочерних процессов. 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(идентификатор процесса, опции)¶

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

os.wait3(опции)¶

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

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

os.wait4(идентификатор процесса, опции)¶

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

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

os.WNOHANG¶

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

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

os.WCONTINUED¶

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

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

os.WUNTRACED¶

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

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

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

os.WCOREDUMP(статус)¶

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

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

os.WIFCONTINUED(статус)¶

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

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

os.WIFSTOPPED(статус)¶

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

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

os.WIFSIGNALED(статус)¶

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

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

os.WIFEXITED(статус)¶

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

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

os.WEXITSTATUS(статус)¶

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

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

os.WSTOPSIG(статус)¶

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

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

os.WTERMSIG(статус)¶

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

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

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

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

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

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

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

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

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

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

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

os.SCHED_RR¶: Политика планирования с циклическим перебором (round-robin).

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

classos.sched_param(приоритет планирования)¶

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

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

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

os.sched_get_priority_min(политика)¶: Возвращает минимальное значение приоритета для policy. policy – одна из констант политик планирования, приведённых выше.

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

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

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

os.sched_setparam(идентификатор процесса, параметр)¶: Устанавливает параметры планирования для процесса с PID pid. pid, равный 0, означает вызывающий процесс. param – это экземпляр sched_param.

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

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

os.sched_yield()¶: Добровольно уступает процессор.

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

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

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

os.confstr(имя)¶

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

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

os.sysconf_names¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.getrandom(size, flags=0)¶

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

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

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

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

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

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

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

os.urandom(size)¶

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

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

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

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

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

Смотрите также

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

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

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

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

os.GRND_NONBLOCK¶

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

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

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

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

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

16.1. os – Различные интерфейсы операционной системы​

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

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

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

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

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

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

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

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

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

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

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

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

16.1. `os` – Различные интерфейсы операционной системы

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

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

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

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

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

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

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

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

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

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

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

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