stat en Python: tipos y permisos

El módulo stat de la biblioteca estándar interpreta los metadatos devueltos por os.stat(), os.fstat() y os.lstat(). Estos datos incluyen tipo de objeto, permisos, propietario, tamaño, número de enlaces, dispositivo, inode y marcas de tiempo. Es especialmente útil cuando una aplicación necesita analizar varios atributos sin repetir llamadas al sistema.

Esta guía explica cómo reconocer archivos normales, directorios, enlaces y objetos especiales; extraer bits de permiso; mostrar modos legibles; comprender diferencias entre plataformas; y evitar problemas de seguridad como enlaces simbólicos y condiciones de carrera.

Obtener metadatos con os.stat

import os

info = os.stat("datos.txt")
print(info.st_size)
print(info.st_mtime)
print(info.st_mode)

El resultado se comporta como una tupla, pero ofrece atributos con nombre. Prefiere estos atributos a los índices históricos como ST_SIZE, porque el código queda más claro.

Identificar el tipo de objeto

El campo st_mode combina el tipo con los bits de permiso. Funciones como S_ISREG(), S_ISDIR(), S_ISLNK(), S_ISSOCK(), S_ISFIFO(), S_ISCHR() y S_ISBLK() comprueban tipos específicos.

import os
import stat

modo = os.lstat("acceso").st_mode

if stat.S_ISLNK(modo):
    print("enlace simbólico")
elif stat.S_ISDIR(modo):
    print("directorio")
elif stat.S_ISREG(modo):
    print("archivo normal")

Usa lstat() cuando necesites analizar el propio enlace. stat() normalmente lo sigue y devuelve información del destino.

Evitar llamadas repetidas

Funciones como os.path.isfile() y os.path.isdir() son cómodas, pero cada prueba puede requerir una consulta adicional. Cuando ya tienes un resultado de stat, reutiliza st_mode.

info = os.stat(ruta)
modo = info.st_mode

regular = stat.S_ISREG(modo)
directorio = stat.S_ISDIR(modo)
permisos = stat.S_IMODE(modo)

Este diseño resulta útil en indexadores, backups, escáneres, navegadores e inventarios con miles de entradas.

Mostrar permisos legibles

stat.filemode() convierte el modo a una representación similar a ls -l, como -rw-r--r-- o drwxr-xr-x.

import os
import stat

info = os.stat("datos.txt")
print(stat.filemode(info.st_mode))

El primer carácter indica el tipo. Los nueve siguientes representan lectura, escritura y ejecución para propietario, grupo y otros. La cadena es adecuada para logs e interfaces, pero no sustituye una comprobación real de acceso.

Extraer los bits configurables

S_IMODE() elimina la parte del tipo y conserva permisos, sticky bit, set-user-ID y set-group-ID cuando existen.

actual = os.stat("script.sh").st_mode
permisos = stat.S_IMODE(actual)
print(oct(permisos))

Al usar os.chmod(), trabaja con máscaras deliberadas. No copies modos de archivos no confiables sin revisar los bits especiales.

Permisos de propietario, grupo y otros

El módulo define constantes como S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH y S_IXOTH.

modo = os.stat("archivo.txt").st_mode

if modo & stat.S_IWOTH:
    print("otros pueden escribir")
if modo & stat.S_IXUSR:
    print("el propietario puede ejecutar")

Estos bits describen la configuración, pero no garantizan acceso al proceso actual. ACLs, privilegios, montajes de solo lectura y políticas de seguridad también influyen.

Sticky, setuid y setgid

S_ISVTX representa el sticky bit. En directorios como /tmp, restringe borrado y renombrado. S_ISUID y S_ISGID tienen significados especiales en Unix.

Las herramientas de auditoría pueden informar estos bits, pero no deberían cambiarlos automáticamente sin una política documentada. Una corrección ingenua puede romper software o crear una vulnerabilidad.

El tamaño depende del tipo

En archivos normales, st_size representa bytes. En FIFOs y sockets de algunos sistemas Unix puede indicar bytes pendientes de lectura. En dispositivos el significado varía aún más.

Antes de usar el valor para reservar memoria o validar una carga, confirma que S_ISREG(st_mode) sea verdadero e impone un límite independiente.

atime, mtime y ctime

st_atime registra el último acceso, st_mtime la última modificación del contenido y st_ctime depende de la plataforma. En Unix suele ser la última modificación de metadatos; en Windows tradicionalmente representa creación.

No interpretes ctime como fecha de creación portable. Los sistemas de archivos, opciones de montaje y precisión cambian. Para comparaciones exactas, usa campos en nanosegundos como st_mtime_ns.

Inodes, dispositivos y enlaces físicos

st_ino y st_dev ayudan a identificar un objeto en sistemas compatibles. st_nlink muestra el número de enlaces físicos.

info = os.stat("datos.txt")
identidad = (info.st_dev, info.st_ino)
print(identidad, info.st_nlink)

El par puede evitar procesar el mismo inode dos veces durante un escaneo, pero no debe guardarse como identificador global permanente porque los inodes pueden reutilizarse.

Enlaces simbólicos y carreras

Una ruta puede cambiar entre la validación y el uso. Otro proceso puede sustituir el archivo comprobado, generando una carrera TOCTOU. En operaciones sensibles, prefiere APIs basadas en descriptores, dir_fd, follow_symlinks=False y opciones de apertura segura del sistema.

También valida la raíz autorizada y no confíes solo en una extensión o tipo comprobado anteriormente.

Flags de BSD y macOS

En plataformas compatibles, el módulo expone flags como UF_IMMUTABLE, UF_APPEND, UF_HIDDEN y varios valores SF_*. Python 3.13 amplió algunas definiciones.

Comprueba disponibilidad con hasattr(stat, "UF_IMMUTABLE"). La presencia de una constante no garantiza un comportamiento idéntico en todos los sistemas de archivos.

Atributos de archivos en Windows

En Windows, el resultado puede incluir st_file_attributes y st_reparse_tag. Hay constantes como FILE_ATTRIBUTE_HIDDEN, FILE_ATTRIBUTE_READONLY, FILE_ATTRIBUTE_REPARSE_POINT y etiquetas conocidas para enlaces y puntos de montaje.

info = os.stat(ruta, follow_symlinks=False)
atributos = getattr(info, "st_file_attributes", 0)

if atributos & stat.FILE_ATTRIBUTE_HIDDEN:
    print("oculto en Windows")

Usar getattr() mantiene el código importable en otras plataformas.

Ejemplo de inventario

from pathlib import Path
import os
import stat


def describir(ruta: Path):
    info = os.lstat(ruta)
    modo = info.st_mode
    if stat.S_ISLNK(modo):
        tipo = "enlace"
    elif stat.S_ISDIR(modo):
        tipo = "directorio"
    elif stat.S_ISREG(modo):
        tipo = "archivo"
    else:
        tipo = "especial"
    return {
        "nombre": ruta.name,
        "tipo": tipo,
        "modo": stat.filemode(modo),
        "tamano": info.st_size,
        "mtime_ns": info.st_mtime_ns,
    }

La función usa lstat() para no seguir enlaces. Una aplicación completa debe tratar errores de permiso, archivos eliminados durante la lectura y límites de recorrido.

Errores frecuentes

• Interpretar st_ctime como creación en todas las plataformas.
• Usar stat() cuando debía analizarse el enlace.
• Confiar en st_size sin comprobar el tipo.
• Tratar los bits de modo como autorización completa.
• Repetir consultas al sistema sin necesidad.
• Ignorar carreras entre comprobación y uso.
• Suponer que flags específicos existen en todas partes.

Buenas prácticas

• Reutiliza un único resultado de stat.
• Usa funciones S_IS* para tipos.
• Usa S_IMODE() para extraer permisos.
• Usa filemode() solo para presentación.
• Prefiere timestamps en nanosegundos para comparar.
• Define una política explícita para enlaces.
• Prueba en todas las plataformas soportadas.

Guías relacionadas

Continúa con filecmp en Python, mmap en Python, platform en Python, sysconfig en Python y fnmatch en Python.

Consulta la documentación oficial de stat y la documentación de os.stat.

Conclusión

El módulo stat convierte modos y atributos de bajo nivel en pruebas legibles y portables. Es valioso para auditorías, backups, indexación y herramientas de sistema, pero debe combinarse con manejo de errores, políticas seguras de rutas y APIs resistentes a condiciones de carrera.