Skip to content

Latest commit

 

History

History
256 lines (235 loc) · 16.1 KB

YAPILACAKLAR.md

File metadata and controls

256 lines (235 loc) · 16.1 KB

Yapılacaklar — Python SDK

GÜNCELLEME (2026-09-05): publish dışı tüm 18.A eksikleri tamamlandı — inbox.*, feed actor_type, tri-state update_me (actos.UNSET sentineli), comments body_html, openapi+types regen, README/PLAN düzeltmeleri. Kapılar yeşil (pytest 114, mypy --strict, ruff, unasync, generate_types --check). Kalan yalnızca yayın (PyPI).

Durum özeti: SDK, backend Faz 18.A'dan önceki spec'e göre bilinçli ve eksiksiz kodlanmış (Faz 0–16 [x], sözleşmenin 16 maddesi test edilmiş, ruff/mypy --strict/pytest hepsi yeşil). Backend Faz 18.A 2026-09-03'te bitti; bu SDK artık spec'in gerisinde: repodaki openapi.json kopyası 42 yol, canlı spec 45 yol. Fark tamamen ekleyici (inbox uçları + birkaç yeni alan/parametre), kırıcı değil. verifications.* ayrı bir konu: backend'de süresiz ertelendi, "bekleniyor" değil — plandan düşülmeli. En kritik somut bulgu: tests/unit/test_types.py:: test_generate_types_check_cli bu ortamda (kardeş actos-backend reposu mevcut olduğu için) şu an gerçekten kırmızı — drift otomatik yakalanıyor.

Son kontrol: 2026-09-03, backend Faz 18.A sonrası. Doğrulama: .venv/bin/python scripts/generate_types.py --check, .venv/bin/python -m pytest -q -m "not contract", .venv/bin/python -m mypy actos tests --strict, ruff check ., scripts/unasync.py --check, ve backend openapi.json ile repo kopyasının Python ile programatik diff'i.

1. Backend Faz 18.A'dan doğan eksikler

Kaynak spec: /home/efe/Documents/actos/actos-backend/docs/openapi.json (45 yol). Repo kopyası: /home/efe/Documents/actos/python/openapi.json (42 yol, eski). Programatik diff ile doğrulandı — fark şu üç yol ve üç şema: /me/inbox, /me/inbox/read, /me/inbox/{id}/read; InboxResponse, NotificationSummary, MarkAllReadResponse. Ayrıca 4 mevcut şema/parametreye alan eklendi (aşağıda ayrı ayrı).

  1. openapi.json kopyasını tazele. python/openapi.json → backend'deki güncel kopyayla değiştirilecek (cp ../actos-backend/docs/openapi.json openapi.json ya da scripts/generate_types.py'nin BACKEND_SPEC_PATH fallback'i zaten kardeş repo varken bunu otomatik kullanıyor — asıl mesele committed kopyanın kardeş repo olmadan kurulumlarda kullanılacak olması). Dosya: python/openapi.json. Neden: scripts/generate_types.py:22-36 resolve_default_source() önce ../actos-backend/docs/openapi.json'a bakıyor, o yoksa yerel kopyaya düşüyor — CI'da (tek repo checkout) sadece yerel kopya var, o yüzden CI bugün bu drift'i yakalamıyor (bkz. §4, tuzak notu).

  2. actos/types.py'yi yeniden üret ve commit'le. uv run python scripts/generate_types.py (kardeş repo mevcutken otomatik güncel spec'i kullanır). Doğrulandı: bu komut şu an ActorSummary'ye avatar_url + trust_level, ContentSummary'ye body_html, ve üç yeni şemayı (InboxResponse, NotificationSummary, MarkAllReadResponse) ekliyor — çıktı gerçek diff olarak alındı, tahmini değil. Dosya: actos/types.py. Bu tek başına yapılınca tests/unit/test_types.py::test_generate_types_check_cli (satır 126-137) tekrar yeşile döner.

  3. inbox.* kaynağını uygula (PLAN.md Faz 13.B, - [ ] satır 436-445). Backend uçları artık var, doğrulandı (actos-backend/docs/openapi.json → /me/inbox GET, /me/inbox/read POST, /me/inbox/{id}/read PATCH).

    • client.inbox.list(unread=False, limit=, cursor=) → GET /me/inbox, InboxResponse.notifications + .next_cursor + .unread_count.
    • client.inbox.iter(...) → auto-paging.
    • client.inbox.read(notification_id) → PATCH /me/inbox/{id}/read. Doğrulandı: spec'e göre 204 döner, başka actor'ün bildirimi 404 verir (id sızdırmaz), zaten okunmuşu tekrar işaretlemek de 204 — idempotent.
    • client.inbox.read_all(up_to_cursor=None) → POST /me/inbox/read, cursor verilmezse tümü işaretlenir; MarkAllReadResponse.marked döner. Spec açıkça "Idempotent" diyor.
    • client.inbox.unread_count() → PLAN.md'de ayrı bir uç yok, muhtemelen list(limit=1) çağırıp InboxResponse.unread_count'u döndürmek (spec: "unread_count is always the TOTAL unread count, not the number of items on this page"). Doğrulanamadı: spec'te bunun için ayrı bir hafif uç yok, PLAN.md da HTTP karşılığını belirtmiyor (§3 satır 218'de "↑ yanıttaki sayacı döner" yazıyor) — uygulayan ajan list() üzerinden türetmeli, ekstra bir uç uydurmamalı.
    • client.inbox.watch(interval=...) yoklama yardımcısı (PLAN.md satır 440-442): sonsuz üreteç, Retry-After/rate-limit header'larına uyar.
    • Dosyalar: yeni actos/resources/_async/inbox.py + actos/resources/_sync/inbox.py (unasync ile üretilecek, elle yazılmayacak — bkz. scripts/unasync.py), actos/client.py:125-137 ve :203-215'e self.inbox = ... satırı, actos/__init__.py'ye export.
    • Testler: tests/unit/test_inbox.py (yok, oluşturulmalı) + tests/contract/test_contract.py'ye dokunmaya gerek yok (16 madde zaten API yüzeyinden bağımsız sözleşme kuralları, ama yeni bir contract_17 gerekmiyor — inbox sözleşmenin bir parçası değil, §3 "API yüzeyi" haritasının bir parçası).
  4. feed.list/feed.following'e actor_type parametresi ekle. Doğrulandı: actos/resources/_async/feed.py:18-59 (list) ve :90-131 (following) — ikisinde de params sözlüğünde actor_type yok, docstring'de açıkça "Strictly does not support actor_type filtering (§0.2)" yazıyor (satır 29). Spec diff'i doğruladı: /feed ve /feed/following GET parametrelerine actor_type eklenmiş (query parametre listesi programatik olarak karşılaştırıldı). actors.py'deki list() zaten aynı deseni kullanıyor (actor_type: ActorType | str | None, satır 32-52) — oradaki desen kopyalanabilir. Sync taraf unasync ile otomatik gelir, elle dokunulmaz.

  5. actors.update_me'ye avatar parametresi ekle. Doğrulandı: actos/resources/_async/actors.py:105-130 — imzada avatar yok, docstring'de "NOTE: Avatar updates are deferred and not supported (§0.2)" yazıyor (satır 113). Spec: UpdateProfileRequest.avatar eklendi (string | null, upload'ın dış id'si f_...). Tuzak: alan Option<Option<T>> deseni taşıyor (spec açıklaması) — display_name/ bio ile aynı "gönderilmezse dokunma, null gönderilirse temizle, değer gönderilirse güncelle" davranışı. Mevcut kod zaten display_name/bio için bu ayrımı yapmıyor (satır 122-126: if display_name is not None: payload[...] — yani kullanıcı bio="" ile temizleyebilir ama bio=None ile "dokunma" ile "temizle" arasındaki farkı ifade edemez, None her zaman "dokunma" anlamına geliyor). avatar eklenirken bu sınırlama miras alınacaksa bilerek alınmalı; None → "dokunma", avatar'ı temizlemek isteyen kullanıcı için ayrı bir yol (avatar=UNSET gibi bir sentinel) düşünülmeli — bugünkü display_name/ bio davranışıyla tutarlı olsun istenmiyorsa bu üçü birlikte ele alınmalı, sadece avatar farklı davranmamalı.

  6. comments.list/comments.iter'a body_html: bool parametresi ekle. Doğrulandı: actos/resources/_async/comments.py:61-104 (list) ve :106-136 (iter) — body_html parametresi yok. Spec: GET /posts/{id}/comments üzerinde yeni body_html query parametresi (boolean, varsayılan false), fields değil — spec'in kendi açıklaması: bu uçta ?fields= desteklenmiyor çünkü ağaç yapısını (replies) bozar, o yüzden ayrı bayrak var. PLAN.md'nin §0.2 tablosunda bu madde hiç yok (plan yazıldığında bu parametre spec'te yoktu, tahmin edilmemiş) — yani PLAN.md'ye de eklenmesi gereken yeni bir satır. Not: posts.get() ve comments.get() zaten genel fields= desteğine sahip, oralarda body_html zaten fields=["body_html"] ile çekilebilir (spec: "Tekil uçlar ?fields='ten bağımsız her zaman doldurur" — yani fields filtrelemesi tekil uçlarda body_html'i etkilemiyor bile, otomatik dolu geliyor). Sadece tree/list uçları için ayrı parametre gerekiyor.

  7. ActorSummary.avatar_url ve .trust_level — tip üretiminden sonra SDK tarafında elle yapılacak bir şey yok, ama doğrulanmalı. Bu iki alan actos/types.py yeniden üretildiğinde otomatik gelir (madde 2). Kod tarafında ActorSummary'yi elle inşa eden tek yer actos/resources/_async/feed.py:56 ve :128 (Post.model_construct(**item) — fields= verildiğinde şema doğrulamasını atlıyor) etkilenmez çünkü orası ContentSummary (Post alias'ı) kullanıyor, ActorSummary değil. Yeni alanlar extra="allow" sayesinde bugün de model_extra üzerinden erişilebilir durumda ama tip güvenli değil — actor.trust_level mypy --strict altında attr-defined hatası verir (tip üretilmeden). Regenerasyondan sonra ek bir kod değişikliği gerekmiyor, sadece testlerde bu alanların varlığının doğrulandığından emin olunmalı (madde 9, test_types.py).

2. Planda [x] ama kodda eksik/eskimiş

Bu kategoride hiçbir madde bulunamadı — [x] işaretli Faz 0-16 maddeleri tek tek kodla karşılaştırıldı (dosya varlığı, testlerin geçmesi, README/ CHANGELOG tutarlılığı) ve hepsi doğrulandı:

  • .venv/bin/python -m pytest -q -m "not contract" → 107 geçti, 18 deselect edildi (contract testleri), sadece 1 test kırmızı (test_generate_types_check_cli — bu §1'in sonucu, "planda [x] ama eskimiş" değil, "backend ilerledi, SDK henüz onu takip etmedi").
  • .venv/bin/python -m mypy actos tests --strict → temiz, 57 dosya.
  • .venv/bin/python -m ruff check . → temiz.
  • .venv/bin/python scripts/unasync.py --check → temiz, sync/async senkron.
  • tests/contract/test_contract.py → §2'nin 16 maddesinin hepsi için test var (test_contract_1_... → test_contract_16_..., satır 71-420).
  • grep -rn "skip\|xfail" tests/ → boş, hiçbir test atlanmış değil.
  • scratch/ boş ve git'e hiç girmemiş (bkz. §4).

Not: --check şu an bu ortamda kırmızı olsa da, bu "planda [x] ama kod eskimiş" kategorisine girmiyor çünkü kod bittiğinde (Faz 1, 2026 başlarında) spec gerçekten 42 yol'du ve types.py o spec'le doğruydu — sonradan backend ilerledi. Bu §1'in konusu.

3. Plandan düşülmesi gerekenler (yapılmayacak)

  • verifications.create/check/list/delete — PLAN.md:220-222 (§3 API yüzeyi) ve PLAN.md:443 (Faz 13.B, - [ ] madde), ayrıca NOTES.md:25 (deferred tablosu) bunu "backend Faz 18.A'yı bekliyor" gibi sunuyor. Bu artık yanlış. Doğrulandı: /home/efe/Documents/actos/actos-backend/NOTES.md §9.2 başlığı "Alan adı doğrulaması — ERTELENDİ (2026-09-03), tasarım burada saklı" ve açıkça yazıyor: "Karar: v1'e girmiyor." Gerekçe §9.2.4-9.2.5: HTTPS yöntemi seçilirse SSRF yüzeyi (saldırgan sunucuya 127.0.0.1:3101 gibi iç adresler denetletebilir) ve DNS rebinding TOCTOU riski (kontrol ile bağlantı arasında alan adı 127.0.0.1'e çözümlenebilir) — bu yüzden "henüz olmayan bir problemi çözüyor, bedeli bugün somut, faydası bugün sıfır" denip süresiz ertelenmiş. /me/ verifications* uçları canlı spec'te hiç yok (45 yolun hiçbiri bu değil, programatik olarak doğrulandı) ve backend'in kendi notuna göre hiç olmayacak. Eylem: PLAN.md Faz 13.B'deki verifications.* maddesi (satır 443) "[ ] = bekliyor" değil, tamamen silinmeli ya da açıkça "YAPILMAYACAK — bkz. backend NOTES.md §9.2" notuyla işaretlenmeli. §3'teki API yüzeyi haritasından (satır 220-222) da çıkarılmalı — orada hâlâ SDK'nın bir parçasıymış gibi duruyor. NOTES.md:19-29'daki "Deferred Items" tablosundaki verifications.* satırı da aynı şekilde yanlış ve düzeltilmeli (bu dosyayı ben değiştirmedim, yöneticiye bırakıyorum). Bu repo dışına da not düşülmeli mi (node/rust SDK'larının PLAN.md'sinde aynı satır olabilir) — doğrulanamadı, kapsam dışı, sadece bu repo incelendi.

4. Diğer teknik borç

  1. scripts/generate_types.py'nin kaynak önceliği CI'ı kör bırakıyor. resolve_default_source() (satır 29-36) önce kardeş actos-backend reposuna bakıyor; CI (.github/workflows/ci.yml:33, tek repo checkout) o dizini hiç görmüyor, otomatik olarak yerel openapi.json kopyasına düşüyor. Doğrulandı: --source openapi.json ile --check çalıştırıldığında [OK] dönüyor (yerel kopya kendi içinde tutarlı), ama kardeş repo mevcutken (bu geliştirme ortamında olduğu gibi) --check kırmızı. Yani bugünkü CI, yerel openapi.json kopyası güncellenmeden types.py'nin gerçek backend spec'inden saptığını asla yakalamaz — tek güvence, birinin elle openapi.json'ı tazeleyip PR açmasıdır. Bu otomatik değil, insan hafızasına bağlı bir süreç. Madde 1'deki güncellemeyle birlikte bu döngü kapanır ama mekanizma kırılgan kalır — ileride backend spec'i her değiştiğinde bu SDK'nın bunu nasıl öğreneceği (polling? backend CI'da bir "spec değişti" bildirimi?) planlanmamış. Doğrulanamadı: böyle bir mekanizma olması gerekip gerekmediği bu görevin kapsamı dışında, sadece mevcut durumun kırılganlığını not ediyorum.
  2. scratch/ dizini tamamen boş ve git'e hiç girmemiş (git ls-files scratch/ boş döner, git log --all -- scratch/ boş döner). Kalması için görünür bir sebep yok. Ya silinsin ya da ne için ayrıldığı bir .gitkeep + tek satır açıklamayla belirtilsin. Düşük öncelik.
  3. README.md:194 kaynak tablosu küçük ölçüde güncel değil (18.A ile ilgisiz, önceden var olan bir tutarsızlık): client.auth satırı delete_key metodundan bahsediyor ama gerçek metot adı revoke_key (actos/resources/_async/auth.py:105); recover ve regenerate_recovery_codes tabloda hiç yok. client.comments satırı tree diye bir metottan bahsediyor, böyle bir metot yok — gerçek metotlar create/list/iter/get/update/delete (actos/resources/_async/comments.py:24,61,106,138,158,178). İşlevsel bir hata değil, sadece dokümantasyon küçük drift'i; inbox eklenirken bu tablo da güncellenirse iyi olur (aynı PR).
  4. PLAN.md §0.2 tablosu (satır 55-59) ve §3 API yüzeyi (satır 220-222, 229-232) madde 1 ve 3'teki değişikliklerle güncellenmeli: body_html parametresi tabloya hiç girmemiş (spec büyüdüğünde fark edilmemiş bir madde), verifications.* çıkarılmalı. Bu değişiklikleri ben yapmadım (görev tanımı gereği), yöneticiye bırakıyorum.

5. Sıra önerisi

  1. openapi.json kopyasını tazele + actos/types.py'yi yeniden üret ve commit'le (§1.1-2). Tek başına bu, kırmızı testi yeşile çevirir ve sonraki tüm işin temelini atar.
  2. feed.list/feed.following'e actor_type ekle (§1.4) — en küçük, bağımsız, actors.list'teki mevcut desenin kopyası.
  3. comments.list/iter'a body_html ekle (§1.6) — küçük, bağımsız.
  4. actors.update_me'ye avatar ekle (§1.5) — Option<Option<T>> tuzağı için önce display_name/bio'nun bugünkü davranışına karar vermek gerekiyor (tutarlı mı bırakılacak, üçü birden mi düzeltilecek); bu yüzden 2 ve 3'ten sonra, tek başına ele alınmalı.
  5. inbox.* kaynağını uygula (§1.3) — en büyük parça, yeni dosyalar, yeni testler; 1-4 bittikten sonra çünkü types.py üzerinden InboxResponse/NotificationSummary/MarkAllReadResponse'a bağımlı.
  6. PLAN.md'yi güncelle: Faz 13.B'yi tamamla, verifications.* maddesini plandan düşür (§3), §0.2 ve §3 tablolarını düzelt (yönetici işi).
  7. §4'teki küçük teknik borç maddeleri (README tablosu, scratch/) — 5'le aynı PR'a eklenebilir, ayrı bir tur gerektirmez.