0Pricing
AI Agents · Урок

Безопасные операции с файлами и обработка ошибок

Проверка существования файлов и разрешений, а также корректная обработка ошибок IO.

«Безопасные операции с файлами и обработка ошибок» — бесплатный урок AI Agents на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Почему безопасные операции с файлами важны

Операции с файлами в агентах могут завершаться ошибкой по многим причинам: файл не существует, у агента нет необходимых разрешений, указанный путь ведёт к каталогу или во время записи заканчивается место на диске. Агент, который завершается при ошибке работы с файлом, оставляет частичный вывод и повреждённое состояние. Защитное программирование с надлежащими проверками и обработкой ошибок делает агентов устойчивыми.

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() и Path.is_file()

Перед чтением файла проверьте, что он существует и действительно является обычным файлом (а не каталогом, символической ссылкой на каталог или специальным файлом). Path.exists() возвращает значение True для любого объекта файловой системы; Path.is_file() возвращает значение True только для обычных файлов.

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() — Проверка разрешений

os.access(path, mode) проверяет, есть ли у текущего процесса указанное разрешение для файла. Используйте os.R_OK для чтения, os.W_OK для записи и os.X_OK для выполнения. Это полезно перед попыткой выполнить операции, требующие определённых разрешений.

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')

Перехват FileNotFoundError

FileNotFoundError (подкласс OSError) возникает при попытке открыть несуществующий файл. Перехватывайте это исключение явно и выводите понятное сообщение об ошибке с ожидаемым путём, чтобы пользователь или оператор точно понимал, чего не хватает.

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}')

Перехват PermissionError

PermissionError возникает, когда процесс не имеет разрешения на чтение или запись файла. Это может произойти с системными файлами, файлами, принадлежащими другому пользователю, или файлами с ограниченными разрешениями. Всегда перехватывайте это исключение отдельно от FileNotFoundError — для них требуются разные действия.

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'))

Перехват IsADirectoryError

IsADirectoryError возникает при попытке открыть каталог как файл. Это может произойти, если агент неправильно сформировал путь — например, добавил имя файла, которое уже существует как каталог. Всегда перехватывайте это исключение, чтобы выводить понятное сообщение об ошибке.

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}')

Атомарная запись с временным файлом

Прямая запись в файл опасна: если агент аварийно завершится в середине записи, файл останется записанным лишь частично и будет повреждён. Решение — атомарная запись: сначала записать данные во временный файл, а затем переименовать его в конечный путь. Переименование атомарно в системах POSIX — конечный файл либо содержит старую версию, либо новую, но никогда не бывает частичным.

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'))

Блокировка файлов для параллельных агентов

Когда несколько экземпляров агента работают параллельно и записывают данные в один файл, состояния гонки приводят к повреждению данных. Используйте блокировку файлов с модулем fcntl (Linux/macOS) или кроссплатформенной библиотекой блокировки файлов, чтобы предотвратить одновременную запись.

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

Безопасное удаление с проверкой существования

Удаление несуществующего файла вызывает FileNotFoundError. Удаление каталога с помощью Path.unlink() вызывает IsADirectoryError. Используйте Path.unlink(missing_ok=True) (Python 3.8+) или сначала проверяйте существование объекта для безопасного удаления.

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')

Проверка места на диске перед записью

Агентам, записывающим большие файлы (результаты работы ИИ, наборы данных, журналы), сначала следует проверить доступное место на диске. shutil.disk_usage(path) возвращает общий объём, занятое и свободное пространство в байтах. Перед началом длительной операции записи убедитесь, что свободного места больше ожидаемого размера результата.

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)

Резервное копирование перед перезаписью

Когда агент обновляет существующий файл, рекомендуется сохранять резервную копию предыдущей версии. Это позволяет выполнить откат, если новое содержимое окажется неправильным. Используйте имя резервной копии с отметкой времени и ограничивайте их количество, чтобы не заполнить всё дисковое пространство.

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.*'))])

Быстрая проверка: атомарная запись

Проверьте, насколько хорошо Вы поняли безопасные способы записи файлов.

Итоги безопасных операций с файлами

Теперь Ваши агенты умеют безопасно работать с файлами:

  • Проверяйте перед обращением: Path.exists() + Path.is_file() + os.access(path, os.R_OK)
  • Перехватывайте FileNotFoundError, PermissionError и IsADirectoryError, выводя понятные сообщения
  • Используйте атомарную запись (временный файл + os.replace), чтобы при сбое не оставались частично записанные или повреждённые файлы
  • Используйте блокировку файлов (библиотеку блокировки файлов), когда несколько агентов записывают данные в один файл
  • Используйте missing_ok=True для безопасного удаления без FileNotFoundError
  • Проверяйте свободное место на диске перед большой записью и сохраняйте резервные копии перед перезаписью важных файлов

Часто задаваемые вопросы

Урок «Безопасные операции с файлами и обработка ошибок» бесплатный?

Да — полный текст урока «Безопасные операции с файлами и обработка ошибок» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Безопасные операции с файлами и обработка ошибок»?

Проверка существования файлов и разрешений, а также корректная обработка ошибок IO. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Безопасные операции с файлами и обработка ошибок»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Чтение и запись файлов в контексте агента
  2. Обход каталогов и поиск файлов
  3. Работа с форматами файлов: CSV, JSON и TXT
  4. Безопасные операции с файлами и обработка ошибок
← Назад к AI Agents