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

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

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

Кодировка файловой системы и обработчик ошибок настраиваются при запуске Python функцией PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors объекта PyConfig.

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

См. также кодировку локали.

Режим UTF-8 в Python¶Python UTF-8 Mode

Режим UTF-8 в Python игнорирует кодировку локали и принудительно использует кодировку UTF-8:

• Использовать UTF-8 в качестве кодировки файловой системы.

• sys.getfilesystemencoding() возвращает 'utf-8'.

• locale.getpreferredencoding() возвращает 'utf-8' (аргумент do_setlocale не имеет эффекта).

• sys.stdin, sys.stdout и sys.stderr все используют UTF-8 в качестве текстовой кодировки, при этом surrogateescape обработчик ошибок включён для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace, как и в режиме по умолчанию с учётом локали)

• В Unix os.device_encoding() возвращает 'utf-8' вместо кодировки устройства.

Обратите внимание: настройки стандартных потоков в режиме UTF-8 могут быть переопределены с помощью PYTHONIOENCODING (как и в режиме по умолчанию с учётом локали).

Вследствие изменений в этих низкоуровневых API другие высокоуровневые API также демонстрируют другое поведение по умолчанию:

• Аргументы командной строки, переменные окружения и имена файлов декодируются в текст с использованием кодировки UTF-8.

• os.fsdecode() и os.fsencode() используют кодировку UTF-8.

• open(), io.open() и codecs.open() по умолчанию используют кодировку UTF-8. Однако по умолчанию они также используют строгий обработчик ошибок, так что попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не вернёт бессмысленные данные.

Режим UTF-8 Python включается, если при запуске Python локаль LC_CTYPE равна C или POSIX (см. функцию PyConfig_Read()).

Его можно включить или отключить с помощью параметра командной строки -X utf8 и переменной окружения PYTHONUTF8.

Если переменная окружения PYTHONUTF8 вообще не задана, интерпретатор по умолчанию использует текущие настройки локали, если только текущая локаль не определена как устаревшая локаль на основе ASCII (как описано для PYTHONCOERCECLOCALE), а приведение локали либо отключено, либо не срабатывает. В таких устаревших локалях интерпретатор по умолчанию будет включать режим UTF-8, если только явно не указано иное.

Режим UTF-8 Python можно включить только при запуске Python. Его значение можно прочитать из sys.flags.utf8_mode.

См. также режим UTF-8 в Windows и кодировку файловой системы и обработчик ошибок.

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

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

os.ctermid()¶

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

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

os.environ¶

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

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

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

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

В Windows ключи преобразуются в верхний регистр. Это также относится к получению, установке или удалению элемента. Например, environ['monty'] = 'python' сопоставляет ключ 'MONTY' со значением 'python'.

Примечание

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

Примечание

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

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

См. также

Функция os.reload_environ().

Изменено в версии 3.9: Обновлено для поддержки операторов объединения (|) и обновления (|=) из PEP 584.

os.environb¶

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

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

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

Изменено в версии 3.9: Обновлено для поддержки операторов объединения (|) и обновления (|=) из PEP 584.

os.reload_environ()¶

Отображения os.environ и os.environb являются кешем переменных окружения на момент запуска Python. Поэтому изменения окружения текущего процесса не отражаются, если они были сделаны вне Python или с помощью os.putenv() или os.unsetenv(). Используйте os.reload_environ() для обновления os.environ и os.environb такими изменениями в окружении текущего процесса.

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

Эта функция не является потокобезопасной. Вызов её во время изменения окружения в другом потоке приводит к неопределённому поведению. Чтение os.environ или os.environb, или вызов os.getenv() во время перезагрузки может вернуть пустой результат.

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

os.chdir(path)

os.fchdir(fd)

os.getcwd()

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

os.fsencode(filename)¶

Кодирует path-like имя файла в кодировку файловой системы и обработчик ошибок; возвращает bytes без изменений.

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

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

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

os.fsdecode(filename)¶

Декодирует path-like имя файла из кодировки файловой системы и обработчика ошибок; возвращает str без изменений.

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

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

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

os.fspath(path)¶

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

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

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

class os.PathLike¶

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

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

abstractmethod __fspath__()¶

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

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

os.getenv(key, default=None)¶

Возвращает значение переменной окружения key в виде строки, если она существует, или default в противном случае. key – строка. Обратите внимание, что поскольку getenv() использует os.environ, отображение getenv() также фиксируется при импорте, и функция может не отражать будущие изменения окружения.

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

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

os.getenvb(key, default=None)¶

Возвращает значение переменной окружения key в виде байтов, если она существует, или default в противном случае. key должен быть байтами. Обратите внимание, что поскольку getenvb() использует os.environb, отображение getenvb() также фиксируется при импорте, и функция может не отражать будущие изменения окружения.

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, не WASI.

os.geteuid()¶

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

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

os.getgid()¶

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

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

Функция является заглушкой на WASI; подробнее см. платформы WebAssembly.

os.getgrouplist(user, group, /)¶

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

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

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

os.getgroups()¶

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

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

Примечание

На macOS поведение getgroups() несколько отличается от других Unix-платформ. Если интерпретатор Python был собран с целевой версией развёртывания 10.5 или более ранней, getgroups() возвращает список эффективных идентификаторов групп, связанных с текущим пользовательским процессом; этот список ограничен системно определённым количеством записей, обычно 16, и может быть изменён вызовами setgroups() при наличии соответствующих привилегий. Если сборка выполнена с целевой версией развёртывания выше 10.5, getgroups() возвращает текущий список доступа к группам для пользователя, связанного с эффективным идентификатором пользователя процесса; список доступа к группам может меняться в течение времени жизни процесса, на него не влияют вызовы setgroups(), и его длина не ограничена 16. Значение целевой версии развёртывания, MACOSX_DEPLOYMENT_TARGET, можно получить с помощью sysconfig.get_config_var().

os.getlogin()¶

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

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

os.getpgid(pid)¶

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

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

os.getpgrp()¶

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

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

os.getpid()¶

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

Функция является заглушкой на WASI; подробнее см. платформы WebAssembly.

os.getppid()¶

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

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

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

os.getpriority(which, who)¶

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

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

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

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

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

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

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

os.PRIO_DARWIN_THREAD¶

os.PRIO_DARWIN_PROCESS¶

os.PRIO_DARWIN_BG¶

os.PRIO_DARWIN_NONUI¶

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

Доступность: macOS

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

os.getresuid()¶

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

Доступность: Unix, не WASI, не macOS, не iOS.

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

os.getresgid()¶

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

Доступность: Unix, не WASI, не macOS, не iOS.

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

os.getuid()¶

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

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

На WASI эта функция является заглушкой; дополнительную информацию см. в платформах WebAssembly.

os.initgroups(username, gid, /)¶

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

Доступность: Unix, не WASI, не Android.

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

os.putenv(key, value, /)¶

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

Присваивания элементам os.environ автоматически преобразуются в соответствующие вызовы putenv(); однако вызовы putenv() не обновляют os.environ, поэтому на практике предпочтительнее присваивать значения элементам os.environ. Это также относится к getenv() и getenvb(), которые в своей реализации используют os.environ и os.environb соответственно.

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

Примечание

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

Возбуждает событие аудита os.putenv с аргументами key, value.

Изменено в версии 3.9: Теперь функция всегда доступна.

os.setegid(egid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.seteuid(euid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.setgid(gid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.setgroups(groups, /)¶

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

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

Примечание

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

os.setns(fd, nstype=0)¶

Перепривязывает текущий поток к пространству имён Linux. См. страницы руководства setns(2) и namespaces(7) для получения дополнительных сведений.

Если fd ссылается на символическую ссылку /proc/pid/ns/, setns() перепривязывает вызывающий поток к пространству имён, связанному с этой ссылкой, а nstype может быть установлен в одну из констант CLONE_NEW*, чтобы наложить ограничения на операцию (0 означает отсутствие ограничений).

Начиная с Linux 5.8, fd может ссылаться на файловый дескриптор PID, полученный из pidfd_open(). В этом случае setns() перепривязывает вызывающий поток к одному или нескольким тем же пространствам имён, что и поток, на который ссылается fd. Это подчиняется любым ограничениям, накладываемым nstype, который представляет собой битовую маску, объединяющую одну или несколько констант CLONE_NEW*, например setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID). Членство вызывающей стороны в неуказанных пространствах имён остаётся без изменений.

fd может быть любым объектом с методом fileno() или необработанным файловым дескриптором.

В этом примере поток перепривязывается к сетевому пространству имён процесса init:

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

Доступность: Linux >= 3.0 с glibc >= 2.14.

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

См. также

Функция unshare().

os.setpgrp()¶

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

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

os.setpgid(pid, pgrp, /)¶

Вызывает системный вызов setpgid(), чтобы установить идентификатор группы процессов процесса с идентификатором pid равным группе процессов с идентификатором pgrp. За семантикой обращайтесь к руководству Unix.

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

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, не WASI.

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

os.setregid(rgid, egid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.setresgid(rgid, egid, sgid, /)¶

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

Доступность: Unix, не WASI, не Android, не macOS, не iOS.

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

os.setresuid(ruid, euid, suid, /)¶

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

Доступность: Unix, не WASI, не Android, не macOS, не iOS.

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

os.setreuid(ruid, euid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.getsid(pid, /)¶

Вызывает системный вызов getsid(). За семантикой обращайтесь к руководству Unix.

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

os.setsid()¶

Вызывает системный вызов setsid(). За семантикой обращайтесь к руководству Unix.

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

os.setuid(uid, /)¶

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

Доступность: Unix, не WASI, не Android.

os.strerror(code, /)¶

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

os.supports_bytes_environ¶

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

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

os.umask(mask, /)¶

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

Функция является заглушкой на WASI; см. платформы WebAssembly для получения дополнительной информации.

os.uname()¶

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

На macOS, iOS и Android эта функция возвращает имя и версию ядра (т.е. 'Darwin' на macOS и iOS; 'Linux' на Android). platform.uname() можно использовать для получения отображаемого пользователю имени и версии операционной системы на iOS и Android.

См. также

sys.platform, который имеет более высокую детализацию.

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

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

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

class os.uname_result¶

Имя и сведения о системе, возвращаемые os.uname(). Эти атрибуты соответствуют полям, описанным в uname(2).

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

sysname¶

Имя операционной системы.

nodename¶

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

release¶

Релиз операционной системы.

version¶

Версия операционной системы.

machine¶

Идентификатор оборудования.

os.unsetenv(key, /)¶

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

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

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

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

Изменено в версии 3.9: Функция теперь всегда доступна, а также доступна на Windows.

os.unshare(flags)¶

Отделяет части контекста выполнения процесса и перемещает их в новое пространство имён. См. страницу руководства unshare(2) для получения более подробной информации. Аргумент flags представляет собой битовую маску, объединяющую ноль или более констант CLONE_*, которая определяет, какие части контекста выполнения должны быть отделены от существующих связей и перемещены в новое пространство имён. Если аргумент flags равен 0, никаких изменений в контекст выполнения вызывающего процесса не вносится.

Доступность: Linux >= 2.6.16.

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

См. также

Функция setns().

Флаги для функции unshare(), если реализация их поддерживает. См. unshare(2) в руководстве Linux для получения информации об их точном эффекте и доступности.

os.CLONE_FILES¶

os.CLONE_FS¶

os.CLONE_NEWCGROUP¶

os.CLONE_NEWIPC¶

os.CLONE_NEWNET¶

os.CLONE_NEWNS¶

os.CLONE_NEWPID¶

os.CLONE_NEWTIME¶

os.CLONE_NEWUSER¶

os.CLONE_NEWUTS¶

os.CLONE_SIGHAND¶

os.CLONE_SYSVSEM¶

os.CLONE_THREAD¶

os.CLONE_VM¶

Создание файловых объектов¶File Object Creation

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

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

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

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

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

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

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

os.close(fd)¶

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

Примечание

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

os.closerange(fd_low, fd_high, /)¶

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

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

os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)¶

Копирует count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst. Если offset_src равно None, то src читается с текущей позиции; аналогично для offset_dst.

В ядре Linux старше 5.3 файлы, на которые указывают src и dst, должны находиться в одной файловой системе, иначе возникает исключение OSError с errno, установленным в errno.EXDEV.

Это копирование выполняется без дополнительных затрат на передачу данных из ядра в пользовательское пространство и обратно в ядро. Кроме того, некоторые файловые системы могут реализовывать дополнительные оптимизации, такие как использование reflinks (т.е. два или более индексных дескриптора, которые разделяют указатели на одни и те же дисковые блоки с копированием при записи; поддерживаемые файловые системы включают btrfs и XFS) и копирование на стороне сервера (в случае NFS).

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

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

Примечание

На Linux os.copy_file_range() не следует использовать для копирования диапазона из псевдофайла в специальной файловой системе, такой как procfs и sysfs. Он всегда будет копировать ноль байт и возвращать 0, как если бы файл был пуст, из-за известной проблемы ядра Linux.

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

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

os.device_encoding(fd)¶

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

На Unix, если включён режим Python UTF-8, возвращает 'UTF-8' вместо кодировки устройства.

Изменено в версии 3.10: На Unix функция теперь реализует режим Python UTF-8.

os.dup(fd, /)¶

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

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

Доступность: не WASI.

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

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

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

Доступность: не WASI.

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

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

os.fchmod(fd, mode)¶

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

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

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

Функция ограничена на WASI; см. платформы WebAssembly для получения дополнительной информации.

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

os.fchown(fd, uid, gid)¶

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

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

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

Функция ограничена на WASI; см. платформы WebAssembly для получения дополнительной информации.

os.fdatasync(fd)¶

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

Доступность: Unix, не macOS, не iOS.

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_result, как statvfs(). Начиная с Python 3.3, это эквивалентно os.statvfs(fd).

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

os.fsync(fd)¶

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

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

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

os.ftruncate(fd, length, /)¶

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

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

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

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

os.get_blocking(fd, /)¶

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

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

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

Функция ограничена на WASI; см. платформы WebAssembly для получения дополнительной информации.

В Windows эта функция ограничена только каналами.

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

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

os.grantpt(fd, /)¶

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

Вызывает функцию стандартной библиотеки C grantpt().

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

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

os.isatty(fd, /)¶

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

os.lockf(fd, cmd, len, /)¶

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

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

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

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

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

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

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

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

os.login_tty(fd, /)¶

Подготавливает tty, чей файловый дескриптор равен fd, для нового сеанса входа в систему. Делает вызывающий процесс лидером сеанса; делает tty управляющим tty, stdin, stdout и stderr вызывающего процесса; закрывает fd.

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

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

os.lseek(fd, pos, whence, /)¶

Устанавливает текущую позицию файлового дескриптора fd в позицию pos, изменённую согласно whence, и возвращает новую позицию в байтах относительно начала файла. Допустимые значения для whence:

• SEEK_SET или 0 – устанавливает pos относительно начала файла

• SEEK_CUR или 1 – устанавливает pos относительно текущей позиции файла

• SEEK_END или 2 – устанавливает pos относительно конца файла

• SEEK_HOLE – устанавливает pos на следующую позицию данных относительно pos

• SEEK_DATA – устанавливает pos на следующую дыру данных относительно pos

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

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

Параметры для функции lseek() и метода seek() на объектах, подобных файлам, для whence при настройке указателя позиции файла.

SEEK_SET

Настраивает позицию файла относительно начала файла.

SEEK_CUR

Настраивает позицию файла относительно текущей позиции файла.

SEEK_END

Настраивает позицию файла относительно конца файла.

Их значения: 0, 1 и 2 соответственно.

os.SEEK_HOLE¶

os.SEEK_DATA¶

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

SEEK_DATA

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

SEEK_HOLE

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

Примечание

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

Доступность: Linux >= 3.1, macOS, Unix

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

os.O_RDONLY¶

os.O_WRONLY¶

os.O_RDWR¶

os.O_APPEND¶

os.O_CREAT¶

os.O_EXCL¶

os.O_TRUNC¶

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

os.O_DSYNC¶

os.O_RSYNC¶

os.O_SYNC¶

os.O_NDELAY¶

os.O_NONBLOCK¶

os.O_NOCTTY¶

os.O_CLOEXEC¶

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

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

os.O_BINARY¶

os.O_NOINHERIT¶

os.O_SHORT_LIVED¶

os.O_TEMPORARY¶

os.O_RANDOM¶

os.O_SEQUENTIAL¶

os.O_TEXT¶

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

os.O_EVTONLY¶

os.O_FSYNC¶

os.O_SYMLINK¶

os.O_NOFOLLOW_ANY¶

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

Изменено в версии 3.10: добавлены константы O_EVTONLY, O_FSYNC, O_SYMLINK и O_NOFOLLOW_ANY.

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, не WASI.

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

os.pipe()¶

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

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

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

os.pipe2(flags, /)¶

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

Доступность: Unix, не WASI, не macOS, не iOS.

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

os.posix_fallocate(fd, offset, len, /)¶

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

Доступность: Unix, не macOS, не iOS.

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

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

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

Доступность: Unix, не macOS, не iOS.

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

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

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

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

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

os.pread(fd, n, offset, /)¶

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

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

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

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

os.posix_openpt(oflag, /)¶

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

Вызывает функцию стандартной библиотеки C posix_openpt(). Аргумент oflag используется для установки флагов состояния файла и режимов доступа к файлам, как указано в справочной странице posix_openpt() вашей системы.

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

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

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

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

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

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

• RWF_HIPRI

• RWF_NOWAIT

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

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

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

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Использование флагов требует Linux >= 4.6.

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

os.RWF_NOWAIT¶

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

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

Доступность: Linux >= 4.14.

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

os.RWF_HIPRI¶

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

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

Доступность: Linux >= 4.6.

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

os.ptsname(fd, /)¶

Возвращает имя подчинённого (slave) псевдотерминального устройства, связанного с главным (master) псевдотерминальным устройством, на которое ссылается файловый дескриптор fd. Файловый дескриптор fd не закрывается при ошибке.

Вызывает реентерабельную функцию стандартной библиотеки C ptsname_r(), если она доступна; в противном случае вызывается функция стандартной библиотеки C ptsname(), которая не гарантирует потокобезопасность.

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

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

os.pwrite(fd, str, offset, /)¶

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

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

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

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

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

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

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

• RWF_DSYNC

• RWF_SYNC

• RWF_APPEND

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

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

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

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Использование флагов требует Linux >= 4.6.

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

os.RWF_DSYNC¶

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

Доступность: Linux >= 4.7.

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

os.RWF_SYNC¶

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

Доступность: Linux >= 4.7.

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

os.RWF_APPEND¶

Предоставляет эквивалент флага O_APPEND os.open() для отдельной операции записи. Этот флаг имеет смысл только для os.pwritev(), и его действие распространяется только на диапазон данных, записываемых системным вызовом. Аргумент смещение не влияет на операцию записи; данные всегда добавляются в конец файла. Однако если аргумент смещение равен -1, текущее смещение в файле обновляется.

Доступность: Linux >= 4.16.

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

os.read(fd, n, /)¶

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

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

Примечание

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

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

os.readinto(fd, buffer, /)¶

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

Аргумент buffer должен быть изменяемым и байтоподобным. В случае успеха возвращает количество прочитанных байт. Может быть прочитано меньше байт, чем размер буфера. Базовый системный вызов будет повторен при прерывании сигналом, если только обработчик сигнала не возбуждает исключение. Другие ошибки не повторяются, и будет возбуждено исключение.

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

Примечание

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

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

os.sendfile(out_fd, in_fd, offset, count)¶

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

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

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

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

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

В macOS и FreeBSD значение 0 для count означает отправку до тех пор, пока не будет достигнут конец in_fd.

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

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

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

Примечание

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

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

Изменено в версии 3.9: Параметры out и in переименованы в out_fd и in_fd.

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

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

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

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

os.SF_NOCACHE¶

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

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

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

os.set_blocking(fd, blocking, /)¶

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

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

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

Функция ограничена на WASI; см. платформы WebAssembly для получения дополнительной информации.

В Windows эта функция ограничена каналами (pipes).

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

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

os.splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)¶

Передаёт count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst.

Поведение сращивания можно изменить, указав значение flags. Можно использовать любые из следующих переменных, комбинируя их побитовым ИЛИ (оператор |):

• Если указан SPLICE_F_MOVE, ядро пытается переместить страницы вместо копирования, но страницы всё равно могут быть скопированы, если ядро не может переместить их из канала.

• Если указан SPLICE_F_NONBLOCK, ядро просят не блокироваться при вводе-выводе. Это делает операции splice над каналами неблокирующими, но splice всё равно может блокироваться, так как соединяемые файловые дескрипторы могут быть блокирующими.

• Если указан SPLICE_F_MORE, это подсказывает ядру, что в последующем вызове splice поступит ещё больше данных.

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

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

При успешном завершении возвращается количество байт, переданных в канал или из канала. Возврат 0 означает конец ввода. Если src ссылается на канал, это означает, что данных для передачи нет, и блокироваться не имеет смысла, так как к концу записи канала не подключено ни одного записывающего процесса.

См. также

Справочная страница splice(2).

Доступность: Linux >= 2.6.17 с glibc >= 2.5

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

os.SPLICE_F_MOVE¶

os.SPLICE_F_NONBLOCK¶

os.SPLICE_F_MORE¶

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

os.readv(fd, buffers, /)¶

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

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

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

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

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

os.tcgetpgrp(fd, /)¶

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

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

os.tcsetpgrp(fd, pg, /)¶

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

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

os.ttyname(fd, /)¶

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

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

os.unlockpt(fd, /)¶

Разблокирует подчинённое псевдотерминальное устройство, связанное с главным псевдотерминальным устройством, на которое ссылается файловый дескриптор fd. Файловый дескриптор fd не закрывается при ошибке.

Вызывает функцию из стандартной библиотеки C unlockpt().

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

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

os.write(fd, str, /)¶

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

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

Примечание

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

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

os.writev(fd, buffers, /)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

os.F_OK¶

os.R_OK¶

os.W_OK¶

os.X_OK¶

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

os.chdir(path)¶

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

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

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

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

См. также

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

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

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

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

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

• stat.UF_NODUMP

• stat.UF_IMMUTABLE

• stat.UF_APPEND

• stat.UF_OPAQUE

• stat.UF_NOUNLINK

• stat.UF_COMPRESSED

• stat.UF_HIDDEN

• stat.SF_ARCHIVED

• stat.SF_IMMUTABLE

• stat.SF_APPEND

• stat.SF_NOUNLINK

• stat.SF_SNAPSHOT

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

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

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

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

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

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

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

• stat.S_ISUID

• stat.S_ISGID

• stat.S_ENFMT

• stat.S_ISVTX

• stat.S_IREAD

• stat.S_IWRITE

• stat.S_IEXEC

• stat.S_IRWXU

• stat.S_IRUSR

• stat.S_IWUSR

• stat.S_IXUSR

• stat.S_IRWXG

• stat.S_IRGRP

• stat.S_IWGRP

• stat.S_IXGRP

• stat.S_IRWXO

• stat.S_IROTH

• stat.S_IWOTH

• stat.S_IXOTH

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

Примечание

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

Функция ограничена на WASI; подробнее см. платформы WebAssembly.

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

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

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

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

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

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

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

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

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

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

Функция ограничена на WASI; подробнее см. платформы WebAssembly.

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

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

os.chroot(path)¶

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

Доступность: Unix, не WASI, не Android.

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

os.fchdir(fd)¶

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

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

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

os.getcwd()¶

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

os.getcwdb()¶

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

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

os.lchflags(path, flags)¶

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

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

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

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

os.lchmod(path, mode)¶

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

lchmod() не является частью POSIX, но реализации Unix могут предоставлять её, если поддерживается изменение режима символических ссылок.

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

Доступность: Unix, Windows, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

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

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

os.lchown(path, uid, gid)¶

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

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

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

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

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

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

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

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

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

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

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

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

os.listdir(path='.')¶

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

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

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

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

Примечание

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

См. также

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

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

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

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

os.listdrives()¶

Возвращает список, содержащий имена дисков в системе Windows.

Имя диска обычно выглядит как 'C:\\'. Не каждое имя диска будет связано с томом, а некоторые могут быть недоступны по разным причинам, включая права доступа, сетевое подключение или отсутствие носителя. Эта функция не проверяет доступность.

Может вызвать OSError, если при сборе имён дисков произошла ошибка.

Возбуждает событие аудита os.listdrives без аргументов.

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

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

os.listmounts(volume)¶

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

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

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

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

Вызывает событие аудита os.listmounts с аргументом volume.

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

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

os.listvolumes()¶

Возвращает список, содержащий тома в системе.

Тома обычно представлены GUID-путем, который выглядит как \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\. Файлы обычно можно получить через GUID-путь, если разрешения позволяют. Однако пользователи, как правило, с ними не знакомы, поэтому рекомендуется использовать эту функцию для получения точек монтирования с помощью os.listmounts().

Может вызывать OSError, если при сборе томов произошла ошибка.

Возбуждает событие аудита os.listvolumes без аргументов.

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

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

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

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

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

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

Если каталог уже существует, возникает FileExistsError. Если родительский каталог в пути не существует, возникает FileNotFoundError.

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

В Windows значение mode, равное 0o700, обрабатывается особым образом: применяется управление доступом к новому каталогу так, что доступ имеют только текущий пользователь и администраторы. Другие значения mode игнорируются.

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

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

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

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

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

Изменено в версии 3.13: В Windows теперь обрабатывается mode, равный 0o700.

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.major(device, /)¶

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

os.minor(device, /)¶

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

os.makedev(major, minor, /)¶

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

os.pathconf(path, name)¶

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

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

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

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

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

os.pathconf_names¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.removedirs(name)¶

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

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

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

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

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

В Windows, если dst существует, всегда возбуждается FileExistsError. Операция может завершиться неудачей, если src и dst находятся в разных файловых системах. Используйте shutil.move() для поддержки перемещения в другую файловую систему.

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

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

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

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

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

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

os.renames(old, new)¶

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

os.scandir(path='.')¶

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

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

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

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

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

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

scandir.close()¶

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

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

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

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

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

Примечание

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

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

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

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

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

class os.DirEntry¶

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

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

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

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

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

Объекты DirEntry являются дженериками по типу пути (str или bytes).

Атрибуты и методы экземпляра 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(). Если аргумент scandir() path был относительным, атрибут path также является относительным. Изменение текущего рабочего каталога после создания итератора scandir() может привести к тому, что последующие обращения к path будут разрешаться иначе. На некоторых платформах сформированный путь может быть недопустимым, если исходный аргумент scandir() был пригоден для перечисления, но не для объединения с именем записи. Если аргумент scandir() path был файловым дескриптором, атрибут path совпадает с атрибутом name.

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

inode()¶

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

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

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

is_dir(*, follow_symlinks=True)¶

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

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

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

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

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

is_file(*, follow_symlinks=True)¶

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

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

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

is_symlink()¶

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

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

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

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

is_junction()¶

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

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

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

stat(*, follow_symlinks=True)¶

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

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

В 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(), is_junction() и stat().

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

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

Изменено в версии 3.12: Атрибут st_ctime результата stat признан устаревшим в Windows. Время создания файла правильно доступно как st_birthtime, и в будущем st_ctime может быть изменено для возврата нуля или времени изменения метаданных, если доступно.

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

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

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

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

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

Пример:

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

См. также

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

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

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

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

class os.stat_result¶

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

Атрибуты:

st_mode¶

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

st_ino¶

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

• номер inode в Unix,

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

st_dev¶

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

st_nlink¶

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

st_uid¶

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

st_gid¶

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

st_size¶

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

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

st_atime¶

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

st_mtime¶

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

st_ctime¶

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

Изменено в версии 3.12: st_ctime устарело на Windows. Используйте st_birthtime для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как на других платформах.

st_atime_ns¶

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

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

st_mtime_ns¶

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

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

st_ctime_ns¶

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

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

Изменено в версии 3.12: st_ctime_ns устарело на Windows. Используйте st_birthtime_ns для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как на других платформах.

st_birthtime¶

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

Изменено в версии 3.12: st_birthtime теперь доступен на Windows.

st_birthtime_ns¶

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

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

Примечание

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

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

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

st_blocks¶

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

st_blksize¶

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

st_rdev¶

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

st_flags¶

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

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

st_gen¶

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

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

st_fstype¶

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

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

st_rsize¶

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

st_creator¶

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

st_type¶

Тип файла.

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

st_file_attributes¶

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

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

st_reparse_tag¶

Когда у st_file_attributes установлен FILE_ATTRIBUTE_REPARSE_POINT, это поле содержит тег, идентифицирующий тип точки повторного анализа (reparse point). Обратитесь к константам IO_REPARSE_TAG_* из модуля stat.

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

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

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

Изменено в версии 3.7: Добавлен элемент st_fstype для Solaris и его производных.

Изменено в версии 3.8: Добавлен элемент st_reparse_tag в Windows.

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

Изменено в версии 3.12: В Windows st_ctime устарел. В конечном итоге он будет содержать время последнего изменения метаданных для согласованности с другими платформами, но пока ещё содержит время создания. Используйте st_birthtime для времени создания.

В Windows st_ino теперь может быть до 128 бит, в зависимости от файловой системы. Ранее он не превышал 64 бит, а более длинные идентификаторы файлов упаковывались произвольным образом.

В Windows st_rdev больше не возвращает значение. Ранее он содержал то же, что и st_dev, что было некорректно.

Добавлен элемент st_birthtime в Windows.