Kod kalitesi ve CI: ruff, mypy, pre-commit, pytest, GitHub Actions

Derinleş: kalite hattını üretim düzeyine taşımak

ruff, mypy, pre-commit ve temel bir GitHub Actions iş akışı kurmayı gördün. Gerçek bir ekipte bunların üstüne dört konu daha eklenir: karmaşıklık ölçümü (kodun ne kadar dallandığı), bilinçli istisnalar (noqa, dosya bazlı kural kapatma), güvenlik taraması (bandit, pip-audit) ve ileri CI (işler arası bağımlılık, önbellek, matris, eşzamanlılık). Parametrize testler ve mock ayrıntıları "İleri test" dersinde; paket yayımlama adımları "Paketleme ve dağıtım" dersinde.

1. Döngüsel karmaşıklık (cyclomatic complexity)

Bir fonksiyondaki bağımsız yol sayısıdır: 1'den başlar, her if, elif, for, while, except, üçlü ifade ve her ek and/or koşulu bir ekler. 10'u geçen fonksiyonu test etmek zorlaşır, çünkü her yol için ayrı test gerekir. ruff'ta C901 kuralı ve max-complexity ayarı bunu denetler; radon cc -s src/ ise harf notu (A–F) verir. Hesap ast ile birkaç satırdır:

import ast

KOD = """
def kredi_karari(skor, gelir, kara_liste):
    if kara_liste:
        return "red"
    elif skor >= 700 and gelir > 30000:
        return "onay"
    elif skor >= 600 or gelir > 80000:
        return "inceleme"
    return "red"

def kdv(tutar):
    return round(tutar * 1.2, 2)
"""

DALLAR = (ast.If, ast.For, ast.While, ast.IfExp, ast.ExceptHandler)

for f in ast.parse(KOD).body:
    k = 1
    for d in ast.walk(f):
        if isinstance(d, DALLAR):
            k += 1
        elif isinstance(d, ast.BoolOp):
            k += len(d.values) - 1
    print(f"{f.name}: {k}")

elif ast'te ayrı bir düğüm değildir; önceki if'in orelse listesinde iç içe bir ast.If olarak durur. Bu yüzden saymak doğru sonucu verir: kredi_karari için 1 + 3 if + 2 BoolOp = 6.

2. Bilinçli istisnalar: noqa ve per-file-ignores

Her kural her yerde doğru değildir. __init__.py içindeki yeniden dışa aktarımlar (re-export) "kullanılmayan import" (F401) gibi görünür; testlerde assert kullanımı bandit'in S101 kuralına takılır. Kuralı bütün projede kapatmak yerine dar kapsamda kapat:

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "C90", "S"]

[tool.ruff.lint.mccabe]
max-complexity = 10

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]        # yeniden dışa aktarım
"tests/**" = ["S101"]           # testte assert serbest

Tek satırlık istisna için satır sonuna # noqa: F401 yazılır. Kural kodu olmadan çıplak # noqa o satırdaki her uyarıyı susturur; bu yüzden ruff'ın PGH004 kuralı çıplak noqa'yı yasaklar. ruff check --statistics hangi kuralın kaç kez tetiklendiğini özetler; yeni bir kuralı açmadan önce bu sayıya bakarsın.

import re

KAYNAK = """import os  # noqa: F401
import sys  # noqa
eval(girdi)  # noqa: S307, E501
x=1"""

RX = re.compile(r"#s*noqa(?::s*([A-Z]+[0-9]+(?:s*,s*[A-Z]+[0-9]+)*))?", re.I)
for no, satir in enumerate(KAYNAK.splitlines(), 1):
    m = RX.search(satir)
    if not m:
        print(no, "istisna yok")
    elif m[1] is None:
        print(no, "TÜM kurallar susturuldu (tehlikeli)")
    else:
        print(no, "susturulan:", [k.strip().upper() for k in m[1].split(",")])

3. Güvenlik taraması

Sık bulgular: B602 subprocess.run(komut, shell=True) (kabuk enjeksiyonu; liste argüman kullan), B105 parola = "1234" (gizli bilgiyi ortam değişkeninden oku), B608 f-string ile kurulmuş SQL (parametreli sorgu kullan), B307 eval. Bir bulgu yanlış alarmsa # nosec B602 ile gerekçesini yazarak kapatırsın.

4. İleri GitHub Actions

name: CI
on:
  push: { branches: [main] }
  pull_request:
  workflow_dispatch:                 # elle tetikleme düğmesi

concurrency:                         # aynı PR'a yeni push gelince eskisini iptal et
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12", cache: pip }
      - run: pip install ruff mypy && ruff check . && mypy src/
  test:
    needs: lint                      # lint geçmeden test başlamaz
    timeout-minutes: 15
    strategy:
      fail-fast: false               # bir kombinasyon düşse de diğerleri sürsün
      matrix:
        os: [ubuntu-latest, windows-latest]
        python: ["3.11", "3.12"]
        exclude:
          - { os: windows-latest, python: "3.11" }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "${{ matrix.python }}", cache: pip }
      - run: pip install -e ".[dev]" && pytest --cov --cov-report=xml
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: "kapsam-${{ matrix.os }}-${{ matrix.python }}", path: coverage.xml }

Matrisi kafanda genişletebilmelisin: os × python 4 kombinasyon, exclude birini çıkarır, 3 iş koşar. Aynı mantık Python'da:

from itertools import product

matris = {"os": ["ubuntu-latest", "windows-latest"], "python": ["3.11", "3.12"]}
haric = [{"os": "windows-latest", "python": "3.11"}]

anahtarlar = list(matris)
isler = []
for degerler in product(*matris.values()):
    kombin = dict(zip(anahtarlar, degerler))
    if any(all(kombin[k] == v for k, v in h.items()) for h in haric):
        continue
    isler.append(kombin)
for i in isler:
    print(i["os"], i["python"])
print("toplam iş:", len(isler))

Yerelde birden fazla Python sürümünde aynı kontrolü koşmak için nox (ya da tox) kullanılır: pip install nox, kökte noxfile.py ve nox -s testler. CI dosyası da yalnızca nox çağırır; böylece "CI'da ne çalışıyorsa yerelde de o çalışır".

import nox

@nox.session(python=["3.11", "3.12"])
def testler(session):
    session.install("-e", ".[dev]")
    session.run("pytest", "--cov")

@nox.session
def lint(session):
    session.install("ruff")
    session.run("ruff", "check", ".")

CI "kod sağlam mı?" sorusunu yanıtlar. Sürekli dağıtım (continuous delivery/deployment, CD) ise bir sonraki soruyu: "Sağlam kod kullanıcıya nasıl, güvenle ve geri alınabilir biçimde ulaşır?" Bu bölüm imaj üretmeyi, ortamları, sürüm etiketlerini, geri almayı ve ML projelerinde model kalite kapısını anlatıyor.

Teslim mi, dağıtım mı?

Çoğu ekip ortadakini kullanır: main'e her birleşme staging'e otomatik gider; prod'a çıkış bir sürüm etiketi (v1.4.2) ve onayla olur.

İmajı bir kez inşa et, her yere aynısını taşı

CD'nin altın kuralı: staging'de test ettiğin aynı imaj prod'a gider; prod için yeniden inşa edilmez. Ortamlar arasında yalnız yapılandırma (ortam değişkenleri, sırlar) değişir. İmaj, kayıt defterine (registry: GitHub Container Registry, Docker Hub, ECR) değiştirilemez bir etiketle gönderilir: commit SHA'sı ya da sürüm numarası. latest yalnız kolaylık etiketidir, dağıtımda kullanılmaz.

# .github/workflows/cd.yml
name: cd
on:
  push:
    branches: [main]
    tags: ["v*.*.*"]
jobs:
  imaj:
    runs-on: ubuntu-latest
    permissions: {contents: read, packages: write}
    outputs: {etiket: ${{ steps.meta.outputs.version }}}
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with: {registry: ghcr.io, username: ${{ github.actor }}, password: ${{ secrets.GITHUB_TOKEN }}}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/anadolu/market-api
          tags: |
            type=sha
            type=semver,pattern={{version}}
      - uses: docker/build-push-action@v6
        with: {push: true, tags: ${{ steps.meta.outputs.tags }}}
  staging:
    needs: imaj
    environment: staging
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh staging ${{ needs.imaj.outputs.etiket }}
      - run: ./smoke_test.sh https://staging.market.example.com
  prod:
    needs: staging
    if: startsWith(github.ref, 'refs/tags/v')
    environment: production          # GitHub'da "required reviewers" ile onay ister
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh prod ${{ needs.imaj.outputs.etiket }}

environment: anahtarı GitHub'da ortam başına ayrı sırlar ve koruma kuralları (onaylayıcı, bekleme süresi, yalnız etiketlerden dağıtım) tanımlamanı sağlar. Duman testi (smoke test), dağıtımdan hemen sonra birkaç kritik uç noktayı (/health, giriş, sepet) çağıran kısa bir denetimdir; başarısızsa hat durur.

Sürüm numarası: anlamsal sürümleme

Anlamsal sürümleme (semantic versioning) MAJOR.MINOR.PATCH biçimindedir: geriye uyumsuz değişiklik major'ı, yeni özellik minor'ı, hata düzeltmesi patch'i artırır. Commit mesajlarını Conventional Commits kuralıyla (feat:, fix:, feat!:) yazarsan bir sonraki sürümü araçlar (release-please, semantic-release) otomatik hesaplar ve değişiklik günlüğünü (CHANGELOG) üretir.

Geri alma (rollback)

Her dağıtım bir gün geri alınacakmış gibi yapılır. Değiştirilemez etiketler sayesinde geri almak, bir önceki başarılı imaj etiketini yeniden dağıtmaktır (kubectl rollout undo, Render/Fly panelinde "redeploy previous"). Geri almayı zorlaştıran tek şey veritabanıdır: yeni sürümün migration'ı eski kodu bozuyorsa geri dönüş de bozulur. Bu yüzden sqlalchemy-orm dersindeki genişlet-daralt kalıbı CD'nin ön koşuludur. Riskli özellikleri özellik bayrağı (feature flag) arkasında yayınlamak, kodu geri almadan özelliği kapatmayı sağlar. Kanarya (canary) dağıtımda yeni sürüm önce trafiğin küçük bir yüzdesine açılır, hata oranı izlenir, sorun yoksa genişletilir.

ML projelerinde model kalite kapısı

Model de bir yapıt (artifact) gibi sürümlenir ve dağıtılır; ama "testler geçti" yetmez, yeni model eskisinden kötü olabilir. Kalite kapısı, aday modeli üretimdeki (temel) modelle aynı sabit doğrulama kümesinde karşılaştırır ve kurallardan biri bozulursa dağıtımı durdurur: ana metrik en az temel kadar olmalı, gecikme ve model boyutu sınırı aşmamalı, hiçbir müşteri segmentinde performans belirgin düşmemeli.

from sklearn.datasets import make_classification
from sklearn.linear_model import LogisticRegression
from sklearn.tree import DecisionTreeClassifier
from sklearn.metrics import roc_auc_score
from sklearn.model_selection import train_test_split

X, y = make_classification(n_samples=1500, n_features=8, random_state=7)
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.3, random_state=7)

temel = LogisticRegression(max_iter=1000).fit(X_tr, y_tr)
aday = DecisionTreeClassifier(max_depth=3, random_state=7).fit(X_tr, y_tr)
auc_t = roc_auc_score(y_te, temel.predict_proba(X_te)[:, 1])
auc_a = roc_auc_score(y_te, aday.predict_proba(X_te)[:, 1])

TOLERANS = 0.005          # gürültü payı
gecti = auc_a >= auc_t - TOLERANS
print(f"temel AUC={auc_t:.3f}  aday AUC={auc_a:.3f}  kapı: {'GEÇTİ' if gecti else 'REDDEDİLDİ'}")

Bu betik CI'da çalışır ve reddedince sys.exit(1) ile hattı durdurur. Doğrulama kümesi sabit tutulur (sürümlenir); her eğitimde değişirse karşılaştırma anlamsızlaşır. MLflow model kayıt defterinde "Staging → Production" geçişi de bu kapının arkasına konur.