AI Agents · Ders

Hata İşleme ile Güvenli Dosya İşlemleri

Dosyanın varlığını ve izinlerini denetleme, IO hatalarını uygun biçimde ele alma.

Hata İşleme ile Güvenli Dosya İşlemleri, CoddyKit'te ücretsiz bir AI Agents dersidir. Bu, 4 dersinin 4. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Agents öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Agents kursu toplamda 4 dersten oluşur.

Güvenli Dosya İşlemleri Neden Önemlidir

Ajanlardaki dosya işlemleri birçok şekilde başarısız olabilir: dosya mevcut olmayabilir, ajanın izni olmayabilir, yol bir dizin olabilir veya yazma sırasında disk alanı tükenebilir. Dosya hatası nedeniyle çöken bir ajan, kısmi çıktı ve bozulmuş durum bırakır. Uygun denetimler ve hata yönetimiyle yapılan savunmacı programlama, ajanları dayanıklı hâle getirir.

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

Bir dosyayı okumadan önce dosyanın var olduğunu ve gerçekten normal bir dosya olduğunu (dizin, bir dizine işaret eden sembolik bağlantı veya özel dosya olmadığını) denetleyin. Path.exists(), tüm dosya sistemi nesneleri için True döndürür; Path.is_file() ise yalnızca normal dosyalar için True döndürür.

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() — İzinleri Denetleme

os.access(path, mode), geçerli işlemin bir dosya üzerinde belirtilen izne sahip olup olmadığını denetler. Okuma için os.R_OK, yazma için os.W_OK, çalıştırma için os.X_OK kullanın. Bu yöntem, belirli izinler gerektiren işlemleri denemeden önce kullanışlıdır.

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 Yakalama

FileNotFoundError (OSError sınıfının bir alt sınıfı), var olmayan bir dosyayı açmaya çalıştığınızda oluşturulur. Bu hatayı açıkça yakalayın ve kullanıcı ya da işleci tam olarak neyin eksik olduğunu anlayabilsin diye beklenen yolu içeren yararlı bir hata iletisi sağlayın.

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 Yakalama

PermissionError, işlem bir dosyayı okumak veya yazmak için gerekli izne sahip olmadığında oluşturulur. Bu durum sistem dosyalarında, başka bir kullanıcıya ait dosyalarda veya kısıtlayıcı izinlere sahip dosyalarda ortaya çıkabilir. Her zaman FileNotFoundError hatasından ayrı olarak yakalayın; bu hatalar farklı karşılıklar gerektirir.

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 Yakalama

IsADirectoryError, bir dizini dosyaymış gibi açmaya çalıştığınızda oluşturulur. Bu durum, bir ajan yolu yanlış oluşturduğunda, örneğin zaten dizin olarak bulunan bir yola dosya adı eklediğinde ortaya çıkabilir. Anlamlı hata çıktısı sağlamak için bu hatayı her zaman yakalayın.

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

Geçici Dosyayla Atomik Yazma

Doğrudan bir dosyaya yazmak tehlikelidir; ajan yazma işleminin ortasında çökerse dosya kısmen yazılmış ve bozulmuş durumda kalır. Çözüm, atomik yazma yapmaktır: Önce geçici bir dosyaya yazın, ardından bu dosyayı son yola yeniden adlandırın. POSIX sistemlerinde yeniden adlandırma atomiktir; son dosya ya eski sürüm ya da yeni sürüm olur, hiçbir zaman kısmi olmaz.

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

Eşzamanlı Ajanlar için Dosya Kilitleme

Birden çok ajan örneği paralel olarak çalışıp aynı dosyaya yazdığında yarış koşulları verileri bozabilir. Eşzamanlı yazmaları önlemek için fcntl modülüyle (Linux/macOS) veya platformlar arası dosya kilitleme kitaplığıyla kilitleme kullanın.

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

Varlık Denetimleriyle Güvenli Silme

Var olmayan bir dosyayı silmek FileNotFoundError oluşturur. Path.unlink() ile bir dizini silmek ise IsADirectoryError oluşturur. Güvenli silme için Path.unlink(missing_ok=True) (Python 3.8 ve sonrası) kullanın veya önce varlığı denetleyin.

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

Yazmadan Önce Disk Alanını Denetleme

Büyük dosyalar (yapay zekâ çıktıları, veri kümeleri, günlükler) yazan ajanlar önce kullanılabilir disk alanını denetlemelidir. shutil.disk_usage(path), toplam, kullanılan ve boş bayt miktarını döndürür. Uzun bir yazma işlemine başlamadan önce boş alanın beklenen çıktı boyutunu aştığını denetleyin.

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)

Üzerine Yazmadan Önce Yedekleme

Bir ajan mevcut bir dosyayı güncellediğinde önceki sürümün yedeğini saklamak akıllıca olur. Böylece yeni içerik hatalıysa geri dönüş yapabilirsiniz. Zaman damgalı bir yedek dosya adı kullanın ve disk alanının dolmasını önlemek için yedek sayısını sınırlayın.

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

Hızlı Sınama: Atomik Yazma

Güvenli dosya yazma düzeneklerini ne kadar anladığınızı sınayın.

Güvenli Dosya İşlemlerinin Özeti

Ajanlarınız artık dosyaları güvenli bir yaklaşımla işleyebilir:

Erişmeden önce denetleyin: Path.exists() + Path.is_file() + os.access(path, os.R_OK)
FileNotFoundError, PermissionError ve IsADirectoryError hatalarını açık iletilerle yakalayın
Çökme durumunda kısmi veya bozuk dosyaları önlemek için atomik yazma kullanın (geçici dosya + os.replace)
Birden çok ajan aynı dosyaya yazdığında dosya kilitleme kullanın (dosya kilitleme kitaplığı)
FileNotFoundError oluşmadan güvenli silme yapmak için missing_ok=True kullanın
Büyük yazma işlemlerinden önce disk alanını denetleyin; önemli dosyaların üzerine yazmadan önce yedeklerini saklayın

Sıkça Sorulan Sorular

“Hata İşleme ile Güvenli Dosya İşlemleri” dersi ücretsiz mi?

Evet — “Hata İşleme ile Güvenli Dosya İşlemleri” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Agents kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Agents kursu toplamda 4 dersten oluşur.

“Hata İşleme ile Güvenli Dosya İşlemleri” dersinde ne öğreneceğim?

Dosyanın varlığını ve izinlerini denetleme, IO hatalarını uygun biçimde ele alma. AI Agents ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

AI Agents öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te AI Agents, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 4. dersidir.

“Hata İşleme ile Güvenli Dosya İşlemleri” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu AI Agents dersinde kod yazıp çalıştırabilir miyim?

Evet. Her AI Agents dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

← AI Agents Sayfasına Dön