Bu içeriği projenin CLAUDE.md / AGENTS.md / .cursorrules dosyasına yapıştır.

---

Python Projesi Kuralları

Version & tooling

• Python 3.12+ (3.10 altı yasak — match/case, modern typing, performance).
• Paket yöneticisi: uv (tercih) veya poetry. pip install doğrudan yasak.
• Lockfile commit edilir (uv.lock / poetry.lock).
• Virtual env .venv (klasör isim sabitliği).
• .python-version dosyası proje kökünde.

Code style & lint

• Formatter: ruff format (Black uyumlu). PR öncesi format zorunlu.
• Linter: ruff check — şu rule set'ler aktif:

  [tool.ruff.lint]
  select = [
    "E", "F", "W",       # pycodestyle + pyflakes
    "I",                  # isort
    "B",                  # flake8-bugbear
    "C4",                 # flake8-comprehensions
    "UP",                 # pyupgrade
    "N",                  # pep8-naming
    "ANN",                # flake8-annotations (type hints)
    "ASYNC",              # async/await best practices
    "S",                  # bandit (security)
    "PL",                 # pylint subset
    "RUF"                 # ruff-specific
  ]
  ignore = ["ANN101", "ANN102"]  # self/cls annotation gereksiz
  

• Line length: 100 (projeye göre — 88-120 arası seçilir, tutarlı kullanılır).
• Import sıralama: stdlib / third-party / local (ruff halleder).

Type hints zorunlu

• Tüm fonksiyon signature'larında tip var. Public API'de -> None bile explicit.
• mypy --strict yeşil olmalı. Scope gereği gevşetme inline # type: ignore[code] + yorum.
• Any yasak. Unknown (TypeAlias) ya da object veya concrete type.
• typing.Any iç kodda görürsen refactor et. Dış boundary'de (untyped lib) cast + yorum.
• Modern typing: list[int], dict[str, Any], X | None (3.10+). List, Dict, Optional deprecated.
• Generic'ler: Sequence, Mapping, Iterable (abstract), concrete list/dict sadece gerçekten list/dict lazımsa.
• Pydantic v2 runtime validation için; type hint ayrı katman.

Naming

• Modules: snake_case.py
• Classes: PascalCase
• Functions / variables: snake_case
• Constants: SCREAMING_SNAKE
• Private: _leading_underscore (gerçekten private'sa)
• __dunder__ sadece Python protokol için

Yapı

• Paket layout: src/ layout. Root'ta __init__.py yok.

  project/
    src/
      myapp/
        __init__.py
        api/
        models/
        services/
    tests/
    pyproject.toml
  

• Dosya boyutu: 500 satırı geçerse parçala.
• __init__.py barrel sadece public API için. Wildcard import yasak (from module import *).

Async disiplini

• asyncio + async def FastAPI, async DB driver kullananlar için.
• async def fonksiyonda senkron I/O çağırma (blocks event loop):
  • requests ❌ → httpx ✅
  • psycopg2 ❌ → asyncpg / psycopg[async] ✅
  • time.sleep() ❌ → asyncio.sleep() ✅
• CPU-bound iş async fonksiyonda ❌. asyncio.to_thread() ile thread'e at.
• asyncio.gather() paralel I/O için — return_exceptions=True dikkatli.
• Context manager async with connection/file için.

FastAPI (kullanılıyorsa)

• Route handler ince: input parse → service call → response format. İş mantığı handler'da değil.
• Pydantic model'leri:
  • Request: XxxRequest
  • Response: XxxResponse
  • DB model'i (SQLAlchemy) ≠ API model'i. Çevirme katmanı olur.
• Dependency injection (Depends) DB session, current user, feature flag için.
• Exception handler global: domain exception → HTTP mapping.
• Response model explicit — response_model=XxxResponse (extra field sızıntısını önler).
• Path / query / body ayrımı net. Query param: Query(...); path: Path(...).

DB (SQLAlchemy 2.x)

• Async engine: create_async_engine.
• Session factory: async_sessionmaker.
• Typed mapped classes: SQLAlchemy 2.x Mapped[] syntax.
• Transactions: async with session.begin(): context'i. Otomatik rollback on exception.
• N+1 = sorun: selectinload, joinedload ile eager load.
• Migration: Alembic. Auto-generate kabul ama manual review edilir (rename column gibi şeyler auto-detect edilmez).
• Repository pattern: karmaşık projelerde. Küçükte direct SQLAlchemy query kabul.

Error handling

• Exception yakalama sadece en dış katmanda (FastAPI handler, task runner). İçeride spesifik exception.
• Custom exception class'ları: NotFoundError, ValidationError, AuthError gibi domain-specific.
• try/except/pass yasak — ya handle et ya yukarı fırlat.
• raise ... from e context zinciri için.
• Assert production kodunda mantık için yasak — Python -O flag ile assert'leri atlar. if not x: raise kullan.

Logging

• logging module ya da structlog. print() yasak.
• Logger instance modül seviyesinde: logger = logging.getLogger(__name__)
• Seviyeler bilinçli:
  • DEBUG — troubleshoot için
  • INFO — başarılı operasyon
  • WARNING — beklenmeyen ama toparlanıyor
  • ERROR — işlem başarısız
  • CRITICAL — servis etkileniyor
• Structured log: logger.info("order.created", extra={"order_id": id})

Test (pytest)

• Test dosyası: tests/ ayrı klasör. test_*.py naming.
• Fixture'lar conftest.py'de. Scope bilinçli (function, module, session).
• pytest-asyncio async test için. asyncio_mode = "auto" config.
• pytest-cov coverage raporu. Hedef kaplama % değil kritik yolun testi.
• Parametrize (@pytest.mark.parametrize) benzer case'ler için.
• Mock: unittest.mock veya pytest-mock. Mock ≠ her yer — boundary'de kullan.
• Factories: factory-boy veya plain fixture functions.
• DB test'leri transaction rollback ile izole (sqlalchemy session.rollback sonunda).

Performans notları

• sum(x for x in lst) ✅ generator — büyük veri için. List comprehension sadece gerekirse.
• dict.get(key, default) vs key in dict: ... — tercih .get.
• f-string >> .format() >> %s (performance + okunur).
• Early return nested if'ten iyidir.
• functools.lru_cache saf fonksiyonlar için. Instance method'a dikkat (memory leak).

Secret & config

• .env dosyası git-ignored. .env.example commit'lenir.
• pydantic-settings type-safe config.
• Hardcoded secret yasak — env, secret manager, vault.
• getpass.getpass() scripts için.

Packaging

• pyproject.toml her şey tek yerde (setup.py yok).
• [tool.ruff], [tool.mypy], [tool.pytest.ini_options] hepsi burada.
• Dependencies: [project.dependencies] (runtime), [project.optional-dependencies] (dev).
• Version __version__ = ... single source of truth.

Yasak listesi (özet)

• from X import * (wildcard)
• print() prod kodunda
• typing.Any iç kodda
• typing.Optional (use X | None)
• typing.List/Dict/Tuple (use list/dict/tuple)
• except: veya except Exception: pass
• assert business logic için
• pip install doğrudan (paket yöneticisi kullan)
• requests async context'te
• time.sleep() async context'te
• global statement (statefulness gerekliyse class veya dependency)
• sys.path manipülasyonu
• Hardcoded secret / API key

Commit

Conventional Commits + "neden". Kapsam prefix'leri: api, db, worker, infra.