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_ctimecomo creación en todas las plataformas. - Usar
stat()cuando debía analizarse el enlace. - Confiar en
st_sizesin 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.
