Документация Python неофициальный перевод

stat – Интерпретация результатов stat()stat – Interpreting stat() results

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

Модуль stat определяет константы и функции для интерпретации результатов os.stat(), os.fstat() и os.lstat() (если они существуют). За полными сведениями о вызовах stat(), fstat() и lstat() обращайтесь к документации вашей системы.

Изменено в версии 3.4: Модуль stat реализован на C.

Модуль stat определяет следующие функции для проверки определённых типов файлов:

stat.S_ISDIR(mode)

Возвращает ненулевое значение, если режим соответствует каталогу.

stat.S_ISCHR(mode)

Возвращает ненулевое значение, если режим соответствует файлу символьного устройства.

stat.S_ISBLK(mode)

Возвращает ненулевое значение, если режим соответствует файлу блочного устройства.

stat.S_ISREG(mode)

Возвращает ненулевое значение, если режим соответствует обычному файлу.

stat.S_ISFIFO(mode)

Возвращает ненулевое значение, если режим соответствует FIFO (именованному каналу).

stat.S_ISLNK(mode)

Возвращает ненулевое значение, если режим соответствует символической ссылке.

stat.S_ISSOCK(mode)

Возвращает ненулевое значение, если режим соответствует сокету.

stat.S_ISDOOR(mode)

Возвращает ненулевое значение, если режим соответствует двери.

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

stat.S_ISPORT(mode)

Возвращает ненулевое значение, если режим соответствует порту событий.

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

stat.S_ISWHT(mode)

Возвращает ненулевое значение, если режим соответствует whiteout.

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

Определены ещё две функции для более общей работы с режимом файла:

stat.S_IMODE(mode)

Возвращает часть режима файла, которую можно установить с помощью os.chmod() – то есть биты прав доступа к файлу, а также sticky-бит, биты set-group-id и set-user-id (в системах, где они поддерживаются).

stat.S_IFMT(mode)

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

Обычно для проверки типа файла используются функции os.path.is*(); приведённые здесь функции полезны, когда выполняется несколько проверок одного и того же файла и хочется избежать накладных расходов на системный вызов stat() для каждой проверки. Они также полезны при получении информации о файле, которая не обрабатывается os.path, например, при проверке блочных и символьных устройств.

Пример:

import os, sys
from stat import *

def walktree(top, callback):
    '''рекурсивно обойти дерево каталогов, начиная с top,
       вызов функции обратного вызова для каждого обычного файла'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # Это каталог, рекурсивно зайти в него
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # Это файл, вызвать функцию обратного вызова
            callback(pathname)
        else:
            # Неизвестный тип файла, вывести сообщение
            print('Skipping %s' % pathname)

def visitfile(file):
    print('visiting', file)

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)

Предоставляется дополнительная утилита для преобразования режима файла в читаемую строку:

stat.filemode(mode)

Преобразует режим файла в строку вида ‘-rwxrwxrwx’.

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

Изменено в версии 3.4: Функция поддерживает S_IFDOOR, S_IFPORT и S_IFWHT.

Все приведенные ниже переменные – это просто символические индексы кортежа из 10 элементов, возвращаемого функциями os.stat(), os.fstat() или os.lstat().

stat.ST_MODE

Режим защиты inode.

stat.ST_INO

Номер inode.

stat.ST_DEV

Устройство, на котором находится inode.

Количество ссылок на inode.

stat.ST_UID

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

stat.ST_GID

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

stat.ST_SIZE

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

stat.ST_ATIME

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

stat.ST_MTIME

Время последнего изменения.

stat.ST_CTIME

«ctime» в том виде, в котором он сообщается операционной системой. В некоторых системах (например, Unix) это время последнего изменения метаданных, а в других (например, Windows) – время создания (подробнее см. документацию платформы).

Интерпретация «размера файла» зависит от типа файла. Для обычных файлов это размер файла в байтах. Для FIFO и сокетов в большинстве разновидностей Unix (включая Linux) «размер» – это количество байтов, ожидающих чтения на момент вызова os.stat(), os.fstat() или os.lstat(); это иногда может быть полезно, особенно для опроса одного из таких специальных файлов после неблокирующего открытия. Смысл поля размера для других символьных и блочных устройств варьируется сильнее в зависимости от реализации нижележащего системного вызова.

Приведенные ниже переменные определяют флаги, используемые в поле ST_MODE.

Использование приведенных выше функций более переносимо, чем использование первого набора флагов:

stat.S_IFSOCK

Сокет.

stat.S_IFLNK

Символическая ссылка.

stat.S_IFREG

Обычный файл.

stat.S_IFBLK

Блочное устройство.

stat.S_IFDIR

Каталог.

stat.S_IFCHR

Символьное устройство.

stat.S_IFIFO

FIFO.

stat.S_IFDOOR

Дверь.

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

stat.S_IFPORT

Порт событий.

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

stat.S_IFWHT

Белая маска.

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

Примечание

S_IFDOOR, S_IFPORT или S_IFWHT определяются как\n0, если платформа не поддерживает эти типы файлов.

Следующие флаги также можно использовать в аргументе mode функции os.chmod():

stat.S_ISUID

Бит setuid.

stat.S_ISGID

Бит set-group-ID. Этот бит имеет несколько особых применений. Для каталога\nон указывает, что для этого каталога используется семантика BSD:\nсоздаваемые в нём файлы наследуют свой идентификатор группы от каталога, а не\nот эффективного идентификатора группы создающего процесса, а создаваемые там\nкаталоги также будут иметь установленный бит S_ISGID. Для\nфайла, у которого не установлен бит выполнения для группы (S_IXGRP),\nбит set-group-ID указывает на обязательную блокировку файлов/записей\n(см. также S_ENFMT).

stat.S_ISVTX

Sticky bit. Когда этот бит установлен для каталога, это означает, что файл\nв этом каталоге может быть переименован или удалён только владельцем\nфайла, владельцем каталога или привилегированным процессом.

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

Остальные имеют право на выполнение.

stat.S_ENFMT

Принудительная блокировка файлов System V. Этот флаг разделяется с S_ISGID: блокировка файлов/записей применяется к файлам, у которых не установлен бит выполнения группы (S_IXGRP).

stat.S_IREAD

Синоним Unix V7 для S_IRUSR.

stat.S_IWRITE

Синоним Unix V7 для S_IWUSR.

stat.S_IEXEC

Синоним Unix V7 для S_IXUSR.

Следующие флаги можно использовать в аргументе flags функции os.chflags():

stat.UF_NODUMP

Не сбрасывать файл в дамп.

stat.UF_IMMUTABLE

Файл нельзя изменить.

stat.UF_APPEND

Файл можно только дополнять.

stat.UF_OPAQUE

Каталог непрозрачен при просмотре через стек объединения.

Файл нельзя переименовать или удалить.

stat.UF_COMPRESSED

Файл хранится в сжатом виде (macOS 10.6+).

stat.UF_HIDDEN

Файл не должен отображаться в графическом интерфейсе (macOS 10.5+).

stat.SF_ARCHIVED

Файл может быть архивирован.

stat.SF_IMMUTABLE

Файл нельзя изменить.

stat.SF_APPEND

Файл можно только дополнять.

Файл нельзя переименовать или удалить.

stat.SF_SNAPSHOT

Файл является снимком.

Для получения дополнительной информации смотрите страницу руководства chflags(2) в системах *BSD или macOS.

В Windows для проверки битов в члене st_file_attributes, возвращаемом функцией os.stat(), доступны следующие константы атрибутов файла. Для получения более подробной информации о значении этих констант смотрите документацию Windows API.

stat.FILE_ATTRIBUTE_ARCHIVE
stat.FILE_ATTRIBUTE_COMPRESSED
stat.FILE_ATTRIBUTE_DEVICE
stat.FILE_ATTRIBUTE_DIRECTORY
stat.FILE_ATTRIBUTE_ENCRYPTED
stat.FILE_ATTRIBUTE_HIDDEN
stat.FILE_ATTRIBUTE_INTEGRITY_STREAM
stat.FILE_ATTRIBUTE_NORMAL
stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
stat.FILE_ATTRIBUTE_NO_SCRUB_DATA
stat.FILE_ATTRIBUTE_OFFLINE
stat.FILE_ATTRIBUTE_READONLY
stat.FILE_ATTRIBUTE_REPARSE_POINT
stat.FILE_ATTRIBUTE_SPARSE_FILE
stat.FILE_ATTRIBUTE_SYSTEM
stat.FILE_ATTRIBUTE_TEMPORARY
stat.FILE_ATTRIBUTE_VIRTUAL

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

В Windows для сравнения с членом st_reparse_tag, возвращаемым функцией os.lstat(), доступны следующие константы. Это общеизвестные константы, но список не является исчерпывающим.

stat.IO_REPARSE_TAG_MOUNT_POINT

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