0Pricing
AI Agents · Aula

Operações seguras com arquivos e tratamento de erros

Verificação da existência e das permissões de arquivos, com tratamento adequado de erros de IO.

Operações seguras com arquivos e tratamento de erros é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Por que operações seguras com arquivos são importantes

As operações de arquivo em agentes podem falhar de muitas maneiras: o arquivo pode não existir, o agente pode não ter permissão, o caminho pode ser um diretório ou o espaço em disco pode acabar durante a gravação. Um agente que falha por causa de um erro de arquivo deixa uma saída parcial e um estado corrompido. A programação defensiva, com verificações e tratamento de erros adequados, torna os agentes resilientes.

from pathlib import Path

# Unsafe: crashes with FileNotFoundError
# content = Path('missing.txt').read_text()

# Safe: check first
path = Path('config.json')
if path.exists():
    content = path.read_text(encoding='utf-8')
    print('Loaded config')
else:
    print(f'Config not found at {path.resolve()}')
    content = '{}'  # use default

Path.exists() e Path.is_file()

Antes de ler um arquivo, verifique se ele existe e se é realmente um arquivo regular (não um diretório, um link simbólico para um diretório nem um arquivo especial). Path.exists() retorna True para qualquer objeto do sistema de arquivos; Path.is_file() retorna True somente para arquivos regulares.

from pathlib import Path

path = Path('data/report.csv')

# Chain of checks
if not path.exists():
    print(f'Not found: {path}')
elif not path.is_file():
    print(f'Not a regular file: {path} (is_dir={path.is_dir()})')
elif path.stat().st_size == 0:
    print(f'File is empty: {path}')
else:
    # Safe to read
    import csv
    with open(path, 'r', encoding='utf-8', newline='') as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    print(f'Read {len(rows)} rows')

os.access() — Verificando permissões

os.access(path, mode) verifica se o processo atual tem a permissão especificada em um arquivo. Use os.R_OK para leitura, os.W_OK para gravação e os.X_OK para execução. Isso é útil antes de tentar operações que exigem permissões específicas.

import os
from pathlib import Path

def check_file_access(path):
    p = Path(path)

    checks = {
        'exists': p.exists(),
        'is_file': p.is_file(),
        'readable': os.access(p, os.R_OK),
        'writable': os.access(p, os.W_OK),
    }

    for check, result in checks.items():
        status = 'OK' if result else 'FAIL'
        print(f'  {check}: {status}')

    return all(checks.values())

if check_file_access('data/input.json'):
    print('File is accessible')
else:
    print('Access problem — check path and permissions')

Capturando FileNotFoundError

FileNotFoundError (uma subclasse de OSError) é gerado quando você tenta abrir um arquivo que não existe. Capture-o explicitamente e forneça uma mensagem de erro útil que inclua o caminho esperado, para que o usuário ou operador saiba exatamente o que está faltando.

import json
from pathlib import Path

def load_agent_config(config_path='agent_config.json'):
    path = Path(config_path)
    try:
        with open(path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except FileNotFoundError:
        print(f'Config file not found: {path.resolve()}')
        print('Create agent_config.json with your settings')
        print('Example: {"model": "gpt-4o", "max_retries": 3}')
        return {}  # return empty config as default
    except json.JSONDecodeError as e:
        print(f'Invalid JSON in {path}: {e}')
        return {}

# --- demo ---
config = load_agent_config('does_not_exist_config.json')
print(f'Config used: {config}')

Capturando PermissionError

PermissionError é gerado quando o processo não tem permissão para ler ou gravar um arquivo. Isso pode acontecer com arquivos do sistema, arquivos pertencentes a outro usuário ou arquivos com permissões restritivas. Sempre o capture separadamente de FileNotFoundError — eles exigem respostas diferentes.

from pathlib import Path

def read_file_safely(path):
    try:
        return Path(path).read_text(encoding='utf-8')
    except FileNotFoundError:
        print(f'File not found: {path}')
        return None
    except PermissionError:
        import os
        print(f'Permission denied: {path}')
        print(f'File permissions: {oct(Path(path).stat().st_mode)}')
        print(f'Current user: {os.getlogin()}')
        print('Try: chmod +r ' + str(path))
        return None
    except IsADirectoryError:
        print(f'Path is a directory, not a file: {path}')
        return None

# --- demo ---
import os
print(read_file_safely('does_not_exist.txt'))

os.makedirs('a_directory', exist_ok=True)
print(read_file_safely('a_directory'))

Capturando IsADirectoryError

IsADirectoryError é gerado quando você tenta abrir um diretório como se ele fosse um arquivo. Isso pode acontecer quando um agente constrói um caminho incorretamente — por exemplo, anexando um nome de arquivo que já existe como diretório. Sempre o capture para fornecer uma mensagem de erro significativa.

from pathlib import Path

def safe_write(output_path, content):
    path = Path(output_path)

    # Check the path is not an existing directory
    if path.is_dir():
        raise IsADirectoryError(
            f'Cannot write file: {path} is a directory. '
            f'Use a filename like {path}/output.txt instead.'
        )

    # Ensure parent directory exists
    path.parent.mkdir(parents=True, exist_ok=True)

    try:
        path.write_text(content, encoding='utf-8')
        print(f'Written: {path} ({len(content)} chars)')
    except IsADirectoryError as e:
        print(f'Path error: {e}')
    except PermissionError:
        print(f'Cannot write to {path} — permission denied')

# --- demo ---
import os
safe_write('demo_output/report.txt', 'Agent finished the task.')

os.makedirs('already_a_dir', exist_ok=True)
try:
    safe_write('already_a_dir', 'this will fail')
except IsADirectoryError as e:
    print(f'Rejected: {e}')

Gravações atômicas com tempfile

Gravar diretamente em um arquivo é perigoso — se o agente falhar no meio da gravação, o arquivo ficará parcialmente gravado e corrompido. A solução é uma gravação atômica: grave primeiro em um arquivo temporário e depois renomeie-o para o caminho final. A renomeação é atômica em sistemas POSIX — o arquivo final será sempre a versão antiga ou a nova, nunca uma versão parcial.

import tempfile
import os
import json
from pathlib import Path

def atomic_write_json(file_path, data):
    path = Path(file_path)
    path.parent.mkdir(parents=True, exist_ok=True)

    # Write to temp file in same directory
    tmp_fd, tmp_path = tempfile.mkstemp(
        dir=path.parent,
        prefix='.tmp_',
        suffix='.json'
    )
    try:
        with os.fdopen(tmp_fd, 'w', encoding='utf-8') as f:
            json.dump(data, f, indent=2, ensure_ascii=False)
        # Atomic rename: replaces final file in one operation
        os.replace(tmp_path, path)
        print(f'Atomically wrote: {path}')
    except Exception as e:
        os.unlink(tmp_path)  # clean up temp file on error
        raise

# --- demo ---
atomic_write_json('demo_state/state.json', {'step': 3, 'status': 'running'})
print('File contents:', Path('demo_state/state.json').read_text(encoding='utf-8'))

Bloqueio de arquivos para agentes concorrentes

Quando várias instâncias de agentes são executadas em paralelo e gravam no mesmo arquivo, condições de corrida corrompem os dados. Use o bloqueio de arquivos com o módulo fcntl (Linux/macOS) ou a biblioteca multiplataforma filelock para impedir gravações simultâneas.

from filelock import FileLock, Timeout
import json
from pathlib import Path

COUNTER_FILE = Path('shared_counter.json')
LOCK_FILE = Path('shared_counter.json.lock')

def increment_counter():
    lock = FileLock(str(LOCK_FILE), timeout=10)
    try:
        with lock:
            # Only one process can be here at a time
            if COUNTER_FILE.exists():
                data = json.loads(COUNTER_FILE.read_text())
            else:
                data = {'count': 0}

            data['count'] += 1
            COUNTER_FILE.write_text(
                json.dumps(data, indent=2)
            )
            return data['count']
    except Timeout:
        print('Could not acquire lock within 10 seconds')
        return None

Exclusão segura com verificações de existência

Excluir um arquivo inexistente gera FileNotFoundError. Excluir um diretório com Path.unlink() gera IsADirectoryError. Use Path.unlink(missing_ok=True) (Python 3.8 ou posterior) ou verifique a existência primeiro para excluir com segurança.

from pathlib import Path
import shutil

# Safe file deletion (Python 3.8+)
Path('temp_output.json').unlink(missing_ok=True)

# Safe directory deletion
def safe_remove(path):
    p = Path(path)
    if not p.exists():
        print(f'Already gone: {p}')
        return
    if p.is_file():
        p.unlink()
        print(f'Deleted file: {p}')
    elif p.is_dir():
        shutil.rmtree(p)
        print(f'Deleted directory: {p}')
    else:
        print(f'Unknown file type: {p}')

# Clean up temporary workspace
safe_remove('/tmp/agent_workspace/run_001')

Verificações de espaço em disco antes da gravação

Agentes que gravam arquivos grandes (saídas de IA, conjuntos de dados, registros) devem verificar primeiro o espaço disponível em disco. shutil.disk_usage(path) retorna o total de bytes, os bytes usados e os bytes livres. Verifique se o espaço livre excede o tamanho esperado da saída antes de iniciar uma operação de gravação longa.

import shutil
from pathlib import Path

def check_disk_space(output_dir, required_bytes):
    path = Path(output_dir)
    path.mkdir(parents=True, exist_ok=True)

    usage = shutil.disk_usage(path)
    free_gb = usage.free / (1024 ** 3)
    required_gb = required_bytes / (1024 ** 3)

    print(f'Disk free: {free_gb:.2f} GB')
    print(f'Required:  {required_gb:.2f} GB')

    if usage.free < required_bytes * 1.1:  # 10% safety margin
        raise IOError(
            f'Insufficient disk space: '
            f'{free_gb:.2f} GB free, '
            f'{required_gb:.2f} GB required'
        )
    return True

# Before writing a 500 MB dataset
check_disk_space('/tmp/output', 500 * 1024 * 1024)

Cópia de segurança antes de substituir

Quando um agente atualiza um arquivo existente, é recomendável manter uma cópia de segurança da versão anterior. Isso permite reverter a alteração se o novo conteúdo estiver incorreto. Use um nome de arquivo de cópia de segurança com marcação de data e hora e limite o número de cópias para evitar ocupar todo o espaço em disco.

import shutil
import datetime
from pathlib import Path

def write_with_backup(file_path, content, max_backups=5):
    path = Path(file_path)
    backup_dir = path.parent / '.backups'
    backup_dir.mkdir(exist_ok=True)

    # Backup existing file
    if path.exists():
        timestamp = datetime.datetime.now().strftime('%Y%m%d_%H%M%S')
        backup = backup_dir / f'{path.name}.{timestamp}'
        shutil.copy2(path, backup)
        print(f'Backed up to: {backup}')

    # Write new content
    path.write_text(content, encoding='utf-8')

    # Prune old backups
    backups = sorted(backup_dir.glob(f'{path.name}.*'))
    for old in backups[:-max_backups]:
        old.unlink()
        print(f'Pruned old backup: {old.name}')

# --- demo ---
write_with_backup('demo_notes.txt', 'version 1')
write_with_backup('demo_notes.txt', 'version 2')
print('Backups:', [p.name for p in sorted(Path('.backups').glob('demo_notes.txt.*'))])

Verificação rápida: gravações atômicas

Verifique se você compreendeu os padrões seguros de gravação de arquivos.

Recapitulação das operações seguras com arquivos

Agora seus agentes conseguem lidar com arquivos de forma defensiva:

  • Verifique antes de acessar: Path.exists() + Path.is_file() + os.access(path, os.R_OK)
  • Capture FileNotFoundError, PermissionError e IsADirectoryError com mensagens claras
  • Use gravações atômicas (tempfile + os.replace) para impedir arquivos parciais ou corrompidos em caso de falha
  • Use o bloqueio de arquivos (biblioteca filelock) quando vários agentes gravarem no mesmo arquivo
  • Use missing_ok=True para excluir com segurança sem gerar FileNotFoundError
  • Verifique o espaço em disco antes de gravações grandes; mantenha cópias de segurança antes de substituir arquivos importantes

Perguntas Frequentes

A aula “Operações seguras com arquivos e tratamento de erros” é grátis?

Sim — o texto completo de “Operações seguras com arquivos e tratamento de erros” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Operações seguras com arquivos e tratamento de erros”?

Verificação da existência e das permissões de arquivos, com tratamento adequado de erros de IO. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Operações seguras com arquivos e tratamento de erros”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Lendo e escrevendo arquivos no contexto de agentes
  2. Percurso de diretórios e descoberta de arquivos
  3. Tratamento de formatos de arquivo: CSV, JSON e TXT
  4. Operações seguras com arquivos e tratamento de erros
← Voltar para AI Agents