O módulo stat da biblioteca padrão ajuda a interpretar os metadados retornados por os.stat(), os.fstat() e os.lstat(). Esses dados incluem tipo do objeto, permissões, proprietário, tamanho, número de links, dispositivo, inode e horários. O módulo é especialmente útil quando uma aplicação precisa analisar vários atributos sem repetir chamadas ao sistema.
Este guia mostra como reconhecer arquivos, diretórios, links e objetos especiais; extrair bits de permissão; exibir modos legíveis; entender diferenças entre plataformas; e evitar problemas de segurança como condições de corrida e seguimento indevido de links simbólicos.
Obter metadados com os.stat
import os
info = os.stat("dados.txt")
print(info.st_size)
print(info.st_mtime)
print(info.st_mode)O resultado é um objeto semelhante a uma tupla, mas com atributos nomeados. Prefira esses atributos em vez dos índices históricos como ST_SIZE, pois o código fica mais claro.
Identificar o tipo do arquivo
O campo st_mode combina o tipo do objeto com bits de permissão. As funções S_ISREG(), S_ISDIR(), S_ISLNK(), S_ISSOCK(), S_ISFIFO(), S_ISCHR() e S_ISBLK() testam tipos específicos.
import os
import stat
modo = os.lstat("atalho").st_mode
if stat.S_ISLNK(modo):
print("link simbólico")
elif stat.S_ISDIR(modo):
print("diretório")
elif stat.S_ISREG(modo):
print("arquivo comum")Use lstat() quando precisar examinar o próprio link. stat() normalmente segue o link e retorna informações do destino.
Evitar chamadas repetidas
Funções como os.path.isfile() e os.path.isdir() são convenientes, mas cada teste pode exigir uma nova consulta ao sistema. Quando você já chamou os.stat(), reutilize st_mode com o módulo stat.
info = os.stat(caminho)
modo = info.st_mode
regular = stat.S_ISREG(modo)
diretorio = stat.S_ISDIR(modo)
permissoes = stat.S_IMODE(modo)Essa abordagem é útil em indexadores, scanners, backups e inventários que processam milhares de entradas.
Exibir permissões de forma legível
stat.filemode() converte o modo para uma representação semelhante à exibida por ls -l, como -rw-r--r-- ou drwxr-xr-x.
import os
import stat
info = os.stat("dados.txt")
print(stat.filemode(info.st_mode))O primeiro caractere descreve o tipo; os nove seguintes representam leitura, escrita e execução para proprietário, grupo e outros. Essa string é ótima para logs e interfaces, mas decisões de acesso devem usar bits e APIs reais.
Extrair apenas os bits configuráveis
S_IMODE() remove a parte que identifica o tipo e mantém permissões, sticky bit, setuid e setgid.
modo_atual = os.stat("script.sh").st_mode
permissoes = stat.S_IMODE(modo_atual)
print(oct(permissoes))Ao modificar permissões com os.chmod(), trabalhe com máscaras explícitas. Evite copiar cegamente modos de arquivos não confiáveis, principalmente bits especiais.
Bits de proprietário, grupo e outros
O módulo define constantes como S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH e S_IXOTH.
modo = os.stat("arquivo.txt").st_mode
if modo & stat.S_IWOTH:
print("gravável por outros")
if modo & stat.S_IXUSR:
print("executável pelo proprietário")Esses bits descrevem a configuração do arquivo, não garantem que o processo atual consiga acessá-lo. ACLs, privilégios, montagem somente leitura e políticas de segurança também influenciam.
Sticky, setuid e setgid
S_ISVTX representa o sticky bit; em diretórios como /tmp, ele restringe remoção e renomeação. S_ISUID e S_ISGID têm significados especiais em Unix.
Ferramentas de auditoria podem sinalizar esses bits, mas não devem alterá-los automaticamente sem uma política explícita. Uma correção ingênua pode quebrar software ou criar vulnerabilidades.
Tamanho nem sempre significa bytes de arquivo comum
Para arquivos regulares, st_size representa bytes. Para FIFOs e sockets em alguns sistemas Unix, pode indicar bytes aguardando leitura. Em dispositivos, o significado varia.
Antes de usar st_size para alocar memória ou validar uploads, confirme que S_ISREG(st_mode) é verdadeiro e imponha limites independentes.
Entender atime, mtime e ctime
st_atime é o último acesso, st_mtime é a última modificação do conteúdo e st_ctime depende da plataforma. Em Unix, ctime costuma indicar alteração de metadados; no Windows, tradicionalmente representa criação.
Não use ctime como “data de criação” em código portátil. Sistemas de arquivos, opções de montagem e precisão dos timestamps podem variar. Para comparações precisas, prefira as versões em nanossegundos, como st_mtime_ns.
Inode, dispositivo e links físicos
st_ino e st_dev ajudam a identificar um objeto em sistemas compatíveis. st_nlink informa quantos links físicos apontam para o inode.
info = os.stat("dados.txt")
identidade = (info.st_dev, info.st_ino)
print(identidade, info.st_nlink)Esse par pode ajudar a detectar duplicatas durante uma varredura, mas não deve ser persistido como identificador global permanente. Inodes podem ser reutilizados.
Links simbólicos e segurança
Há uma janela entre verificar um caminho e usá-lo. Outro processo pode substituir o arquivo após a validação, criando uma condição TOCTOU. Em operações sensíveis, prefira APIs que trabalham com descritores, opções dir_fd, follow_symlinks=False ou abertura segura oferecida pelo sistema.
Também valide a raiz permitida e evite confiar apenas em extensão, nome ou resultado de um teste anterior.
Flags de BSD e macOS
O módulo expõe flags como UF_IMMUTABLE, UF_APPEND, UF_HIDDEN e diversas constantes SF_* em plataformas compatíveis. Python 3.13 ampliou algumas dessas definições.
Teste disponibilidade com hasattr(stat, "UF_IMMUTABLE"). Não suponha que uma constante existente tenha efeito idêntico em todos os sistemas.
Atributos de arquivos no Windows
No Windows, os.stat() pode fornecer st_file_attributes e st_reparse_tag. O módulo oferece constantes como FILE_ATTRIBUTE_HIDDEN, FILE_ATTRIBUTE_READONLY, FILE_ATTRIBUTE_REPARSE_POINT e tags conhecidas para links e pontos de montagem.
info = os.stat(caminho, follow_symlinks=False)
atributos = getattr(info, "st_file_attributes", 0)
if atributos & stat.FILE_ATTRIBUTE_HIDDEN:
print("oculto no Windows")Use getattr() para manter portabilidade.
Exemplo de inventário seguro
from pathlib import Path
import os
import stat
def descrever(caminho: Path):
info = os.lstat(caminho)
modo = info.st_mode
if stat.S_ISLNK(modo):
tipo = "link"
elif stat.S_ISDIR(modo):
tipo = "diretorio"
elif stat.S_ISREG(modo):
tipo = "arquivo"
else:
tipo = "especial"
return {
"nome": caminho.name,
"tipo": tipo,
"modo": stat.filemode(modo),
"tamanho": info.st_size,
"mtime_ns": info.st_mtime_ns,
}O exemplo usa lstat() para não seguir links e retorna dados adequados a relatórios. A aplicação ainda deve tratar erros de permissão, arquivos removidos durante a leitura e limites de diretório.
Erros frequentes
- Interpretar
st_ctimecomo criação em todas as plataformas. - Usar
stat()quando queria inspecionar o link. - Confiar em
st_sizesem verificar o tipo. - Tratar bits de modo como autorização completa.
- Repetir chamadas ao sistema desnecessariamente.
- Ignorar condições de corrida entre verificação e uso.
- Assumir que flags específicas existem em qualquer sistema.
Boas práticas
- Reutilize o resultado de uma única chamada.
- Use
S_IS*para testar tipos. - Use
S_IMODE()para extrair permissões. - Use
filemode()somente para apresentação. - Prefira timestamps em nanossegundos para comparação.
- Trate links e caminhos com uma política explícita.
- Teste comportamento em cada plataforma suportada.
Conteúdos relacionados
Veja os guias sobre filecmp, mmap, platform, sysconfig e fnmatch.
Consulte a documentação oficial do stat e a documentação de os.stat.
Conclusão
O módulo stat transforma modos e atributos de baixo nível em testes legíveis e portáveis. Ele é valioso para auditoria, backups, indexação e ferramentas de sistema, mas deve ser combinado com tratamento de erros, validação de caminhos e APIs resistentes a condições de corrida.
