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, не Emscripten, не 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().

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

os.environb¶

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

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

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

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

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

os.geteuid()¶

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

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

os.getgid()¶

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

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

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

os.getgrouplist(user, group, /)¶

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

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

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

os.getgroups()¶

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

Доступность: Unix, не Emscripten, не 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, не Emscripten, не WASI.

os.getpgid(pid)¶

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

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

os.getpgrp()¶

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

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

os.getpid()¶

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

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

os.getppid()¶

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

Доступность: Unix, Windows, не Emscripten, не 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, не Emscripten, не WASI.

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

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

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

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

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

os.getresuid()¶

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

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

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

os.getresgid()¶

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

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

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

os.getuid()¶

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

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

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

os.initgroups(username, gid, /)¶

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

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

Новое в версии 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 соответственно.

Примечание

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

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

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

os.setegid(egid, /)¶

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

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

os.seteuid(euid, /)¶

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

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

os.setgid(gid, /)¶

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

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

os.setgroups(groups, /)¶

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

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

Примечание

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

os.setpgrp()¶

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

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

os.setpgid(pid, pgrp, /)¶

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

Доступность: Unix, не Emscripten, не 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, не Emscripten, не WASI.

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

os.setregid(rgid, egid, /)¶

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

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

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

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

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

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

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

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

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

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

os.setreuid(ruid, euid, /)¶

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

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

os.getsid(pid, /)¶

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

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

os.setsid()¶

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

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

os.setuid(uid, /)¶

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

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

os.strerror(code, /)¶

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

os.supports_bytes_environ¶

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

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

os.umask(mask, /)¶

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

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

os.uname()¶

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

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

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

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

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

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

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

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

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

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

os.unsetenv(key, /)¶

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

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

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

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

Создание файловых объектов¶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. Файлы, на которые указывают src и dst, должны находиться в одной файловой системе, иначе OSError будет вызвано с errno, установленным в errno.EXDEV.

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

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

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

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

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.

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

os.fdatasync(fd)¶

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

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

Примечание

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

os.fpathconf(fd, name, /)¶

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

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

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

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

os.fstat(fd)¶

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

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

См. также

Функция stat().

os.fstatvfs(fd, /)¶

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

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

os.fsync(fd)¶

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

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

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

os.ftruncate(fd, length, /)¶

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

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

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

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

os.get_blocking(fd, /)¶

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

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

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

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

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

os.isatty(fd, /)¶

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

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

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

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

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

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

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

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

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

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

os.login_tty(fd, /)¶

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

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

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

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

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

os.pipe()¶

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

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

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

os.pipe2(flags, /)¶

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

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

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

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

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

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

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

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

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

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

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

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

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

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

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

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

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

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

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

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

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

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

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

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

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

os.SF_NOCACHE¶

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

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

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

os.set_blocking(fd, blocking, /)¶

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

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

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

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

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

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

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

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

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

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

Изменено в версии 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, не Emscripten, не 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 или соответствующее целочисленное значение). Все остальные биты игнорируются.

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

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

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

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

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

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

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

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

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

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

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

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

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

os.chroot(path)¶

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

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

Изменено в версии 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, не Emscripten, не 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, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

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

os.lchown(path, uid, gid)¶

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

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

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

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

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

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

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

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

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

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

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

name¶

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

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

path¶

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

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

inode()¶

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

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

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

is_dir(*, follow_symlinks=True)¶

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

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

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

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

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

is_file(*, follow_symlinks=True)¶

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

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

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

is_symlink()¶

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

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

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

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

stat(*, follow_symlinks=True)¶

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

В Unix этот метод всегда требует системного вызова. В Windows он требует системного вызова, только если follow_symlinks равен True, а запись является точкой повторной обработки (например, символической ссылкой или 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() и stat().

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

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

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

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

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

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

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

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

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

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

st_atime_ns¶

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

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

st_mtime_ns¶

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

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

st_ctime_ns¶

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

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

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

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

Примечание

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

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

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

st_blocks¶

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

st_blksize¶

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

st_rdev¶

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

st_flags¶

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

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

st_gen¶

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

st_birthtime¶

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

В 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 по ситуации.

os.statvfs(path)¶

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

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

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

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

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

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

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

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

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

Изменено в версии 3.7: Добавлен атрибут f_fsid.

os.supports_dir_fd¶

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

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

os.stat in os.supports_dir_fd

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

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

os.supports_effective_ids¶

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

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

os.access in os.supports_effective_ids

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

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

os.supports_fd¶

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

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

os.chdir in os.supports_fd

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

os.supports_follow_symlinks¶

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

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

os.stat in os.supports_follow_symlinks

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

os.sync()¶

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

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

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

os.truncate(path, length)¶

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

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

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

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

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

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

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

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

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

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

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

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