Skip to content

Latest commit

 

History

History
496 lines (402 loc) · 24.6 KB

PLAN.md

File metadata and controls

496 lines (402 loc) · 24.6 KB

Actos Python SDK — Uygulama Planı

Bu dosya canlı bir kontrol listesidir. Bir adım bitince [ ] → [x] yapılır. Kural: bir seferde bir adım. Her adım kendi başına kurulur/çalışır ve kendi commit'ini alır. "Sonra toparlarız" yok.

Kapsam: actos Python paketi (sync + async). Backend ayrı repo (actos-dev/backend), bu plan onu değiştirmez.

Bu planı okuyan ajana: §2'deki "SDK Sözleşmesi" bu paketin varlık sebebidir. Bir uygulama kararı sözleşmeyle çelişiyorsa sözleşme kazanır. §2 üç SDK'da (python/node/rust) birebir aynıdır — bir maddeyi burada değiştiriyorsan diğer iki repoda da değiştirmen gerekir.


0. Sabitlenmiş Kararlar (değiştirmeden önce iki kere düşün)

Konu Karar
Paket adı actos (import actos) — PyPI'da rezerve edilmedi, v1'de yayın yok
Python sürümü 3.10+ (`X
HTTP istemcisi httpx — tek kütüphane hem sync hem async veriyor
Sync/async İkisi de. Kaynak _async/ altında yazılır, _sync/ üretilir (unasync deseni). Elle iki kopya tutulmaz
Tipler GET /openapi.json'dan üretilir → actos/types.py, pydantic v2. Üretilen dosya elle düzenlenmez
Tip üretici datamodel-code-generator
Lisans Apache-2.0 — backend AGPL kalır. Gerekçe §0.1
Yayın v1'de yok. Kurulum pip install git+https://github.com/actos-dev/python
Paketleme pyproject.toml + hatchling, geliştirme uv
Lint / tip ruff (lint+format) + mypy --strict
Test pytest + pytest-asyncio + respx (birim), canlı backend'e karşı ayrı sözleşme paketi
Hata dallanması code alanına göre (status'e değil) — §4
429 varsayılanı Retry-After'a uyup yeniden dene (en fazla 2). CLI'ın tersi, gerekçe §2.7
Sayfalama list() tek sayfa (next_cursor açıkta), iter_*() şeffaf takip eder
Idempotency posts.create() otomatik anahtar üretir, kullanıcı ezebilir
MSRV benzeri taban httpx>=0.27, pydantic>=2.7

0.1. Neden SDK Apache-2.0, backend AGPL

AGPL bir kütüphaneye konduğunda onu import eden herkesin kendi kodunu açmasını dayatır. Actos'un hedefi "herkes için özgür platform" — kapalı kaynaklı bir ajan yazan kişiyi SDK'yı kullanmaktan alıkoymak bu hedefin tam tersi olurdu; o kişi düz HTTP'ye düşer ve SDK'nın kodladığı sözleşmeleri (sayfalama, idempotency, 429) yeniden, muhtemelen yanlış yazar. Sunucunun kendisi AGPL kalarak platform korunmaya devam eder.

0.2. Faz 18.A sonrası çözülmüş ertelemeler

Backend Faz 18.A artık canlı spec'te; tipler bu geçişte yeniden üretildi ve eski "bekliyor" parçaları koda eklendi. Canlı GET /openapi.json otoritedir: bu planın §3'ünde listelenip spec'te bulunmayan hiçbir uç ya da alan için kod yazılmaz, uydurulmaz.

Faz 18.A bu geçişte landed:

Ne Nerede
inbox.* (list/iter/read/read_all/unread_count/watch) Faz 13.B
actors.update_me'in avatar parametresi (tri-state) Faz 6
feed.list'in actor_type parametresi Faz 9
body_html alanı (ContentSummary) Faz 12

Ertelenen (DEFERRED — v1 kapsamı dışı): verifications.*. Backend NOTES.md §9.2'ye göre v1 ürününde yer almayacak; bu yüzden §3 tablosundan ve Faz 13.B'den çıkarıldı ve planda [ ]-bekleyen madde olarak bırakılmıyor.

Spec nerede: actos-backend/docs/openapi.json — repoda commit'li, sunucu ayağa kaldırmana gerek yok. Canlı doğrulama yapacaksan backend'de docker compose up -d + cargo run -p actos-api ile 127.0.0.1:3100.

Açık bırakılan (v1'de karar verilecek): httpx yerine aiohttp/requests ikilisine düşme ihtimali (düşük), actos.testing altında sahte istemci sunulup sunulmayacağı.


1. Bu SDK neden var

Bir Python geliştiricisi Actos'a zaten httpx ile erişebilir: API açık, GET /openapi.json belgeli, public okuma uçları kimlik istemiyor. Öyleyse SDK ne katıyor?

SDK'nın işi HTTP'yi sarmalamak değil, platformun sözleşmelerini kullanıcının yerine kodlamak:

Sözleşme Kullanıcı tek başına ne yapardı SDK ne yapıyor
Cursor'lu sayfalama while next_cursor: döngüsü yazardı for post in client.feed.iter():
Idempotency-Key Zaman aşımında tekrar deneyip çift post atardı Anahtarı üretir ve yönetir
X-RateLimit-* Header'ları elle okurdu client.rate_limit, otomatik bekleme
RFC 9457 code JSON gövdesini ayrıştırırdı Tipli istisna hiyerarşisi
410 Gone vs 404 İkisini karıştırırdı GoneError vs NotFoundError
?fields= Bilmezdi fields=[...] ile ağ yükünü kısar
5xx / ağ hatası Ya hiç denemezdi ya körü körüne denerdi Jitter'lı backoff, güvenli olmayan yazmada denemez
Tip güvenliği dict["title"] ile KeyError avlardı post.title, IDE tamamlaması

Ölçüt: bir metot bu listeden hiçbir şey yapmıyorsa, o metot düz httpx'e göre değer üretmiyor demektir — ya değer eklenmeli ya client.request() kaçış kapağına bırakılmalı.


2. SDK Sözleşmesi

Bu bölüm dışa dönük bir taahhüttür. Buradaki her madde test edilir (Faz 14) ve kırılması breaking change sayılır. Üç SDK'da (python/node/rust) aynıdır.

  1. Tek giriş noktası. Actos(api_key=...) / AsyncActos(api_key=...). Kaynaklar öznitelik: client.posts, client.comments, client.actors, client.tags, client.feed, client.search, client.votes, client.saves, client.uploads, client.reports, client.admin, client.auth, client.meta.
  2. Tipler spec'ten üretilir, elle yazılmaz. Üretim script'i repoda (scripts/generate_types.py), CI --check ile sapmayı yakalar.
  3. Hatalar tipli istisnadır, dallanma code'a göre yapılır. 404 ve 410 ayrı sınıflardır — "hiç yoktu" ile "vardı, silindi" farklı bilgi.
  4. Her API hatası request_id, code, status, detail taşır. Sunucu logunda aramayı mümkün kılan tek alan request_id.
  5. Sayfalama iki katmanlı. list() tek sayfa döner ve next_cursor açıkta durur; iter_*() cursor'ı şeffaf takip eder. offset uydurulmaz.
  6. Yeniden deneme kuralı: ağ hatası, 5xx ve 429 denenir; diğer 4xx asla denenmez. Idempotency-Key taşımayan bir POST 5xx'te denenmez (çift kayıt riski).
  7. 429 varsayılan davranışı: Retry-After'a uyup yeniden dene (en fazla max_retries, varsayılan 2). CLI'da varsayılan hızlı başarısızlıktır; SDK'da tersi, çünkü SDK bir program içinde çalışır, kullanıcı orada değildir. max_retries=0 ile kapatılır, o zaman RateLimitError fırlar.
  8. Backoff exponential + full jitter. Retry-After varsa o kazanır.
  9. posts.create() otomatik Idempotency-Key üretir (UUIDv4); idempotency_key= ile ezilebilir, idempotency_key=None ile kapatılır.
  10. Rate-limit header'ları her yanıttan ayrıştırılır, son değer client.rate_limit üzerinden okunur; RateLimitError üzerinde de taşınır.
  11. fields parametresi, uç destekliyorsa sunucu tarafı alan seçimi olarak geçirilir; desteklemiyorsa TypeError — sessizce yok sayılmaz.
  12. ID'ler opak string. SDK asla ayrıştırmaz, önek üretmez, sıralamaz.
  13. Zaman aşımı varsayılan 30 sn, ayarlanabilir. Bağlantı havuzu yeniden kullanılır; istemci context manager'dır ve close() sunar.
  14. User-Agent: actos-python/<sürüm> her istekte gönderilir.
  15. API key asla loglanmaz, repr() çıktısında maskelenir (Actos(api_key='actos_1iga…')).
  16. İleri uyumluluk: sunucunun yanıta yeni alan eklemesi istemciyi kırmaz (model_config = ConfigDict(extra="allow")).

3. API yüzeyi

Tam harita. Sol sütun SDK metodu, sağ sütun karşılık gelen uç. [A] = kimlik gerektirir, [M] = moderatör, [X] = admin.

client.auth.register(username, actor_type, display_name=None)  POST   /auth/register
client.auth.whoami()                                      [A]  GET    /auth/whoami
client.auth.create_key(label=None)                        [A]  POST   /auth/keys
client.auth.list_keys()                                   [A]  GET    /auth/keys
client.auth.revoke_key(key_id)                            [A]  DELETE /auth/keys/{key_id}
client.auth.recover(username, recovery_code)                   POST   /auth/recover
client.auth.regenerate_recovery_codes()                   [A]  POST   /auth/recovery-codes/regenerate

client.actors.list(actor_type=None, limit=, cursor=)           GET    /actors
client.actors.iter(...)                                        ↑ auto-paging
client.actors.get(username)                                    GET    /actors/{username}
client.actors.update_me(display_name=, bio=, avatar=)     [A]  PATCH  /actors/me
client.actors.delete_me()                                 [A]  DELETE /actors/me
client.actors.followers(username) / .iter_followers()          GET    /actors/{username}/followers
client.actors.following(username) / .iter_following()          GET    /actors/{username}/following
client.actors.posts(username) / .iter_posts()                  GET    /actors/{username}/posts
client.actors.comments(username) / .iter_comments()            GET    /actors/{username}/comments
client.actors.follow(username)                            [A]  PUT    /actors/{username}/follow
client.actors.unfollow(username)                          [A]  DELETE /actors/{username}/follow

client.posts.create(title, body, tags=, attachments=,
                    metadata=, idempotency_key=)          [A]  POST   /posts
client.posts.get(id, fields=)                                  GET    /posts/{id}
client.posts.update(id, title=, body=)                    [A]  PATCH  /posts/{id}
client.posts.delete(id)                                   [A]  DELETE /posts/{id}

client.comments.create(post_id, body, parent_id=)         [A]  POST   /posts/{id}/comments
client.comments.list(post_id, sort=, depth=, parent=, body_html=False)  GET    /posts/{id}/comments
client.comments.iter(post_id, ...)                             ↑ auto-paging
client.comments.get(id)                                        GET    /comments/{id}
client.comments.update(id, body)                          [A]  PATCH  /comments/{id}
client.comments.delete(id)                                [A]  DELETE /comments/{id}

client.tags.list() / .iter()                                   GET    /tags
client.tags.search(prefix)                                     GET    /tags/search
client.tags.posts(name, sort=) / .iter_posts(...)              GET    /tags/{name}/posts

client.search(q, type=, limit=, cursor=, fields=)              GET    /search
client.search.iter(q, ...)                                     ↑ auto-paging

client.feed.list(sort=, window=, actor_type=, fields=)         GET    /feed
client.feed.iter(...)                                          ↑ auto-paging
client.feed.following(...) / .iter_following(...)         [A]  GET    /feed/following

client.votes.set(content_id, value)                       [A]  PUT    /contents/{id}/vote
client.votes.up(id) / .down(id) / .clear(id)              [A]  ↑ kolaylık sarmalayıcıları
client.votes.list() / .iter()                             [A]  GET    /me/votes
client.saves.add(content_id)                              [A]  PUT    /contents/{id}/save
client.saves.remove(content_id)                           [A]  DELETE /contents/{id}/save
client.saves.list() / .iter()                             [A]  GET    /me/saves

client.uploads.create(file)                               [A]  POST   /uploads
client.uploads.delete(id)                                 [A]  DELETE /uploads/{id}

client.reports.create(target_type, target_id, reason)     [A]  POST   /reports

client.admin.reports.list(status=) / .iter(...)           [M]  GET    /admin/reports
client.admin.reports.update(id, status, notes=)           [M]  PATCH  /admin/reports/{id}
client.admin.contents.delete(id, reason)                  [M]  DELETE /admin/contents/{id}
client.admin.bans.create(username, reason, expires_at=)   [M]  POST   /admin/bans
client.admin.bans.remove(username)                        [M]  DELETE /admin/bans/{username}
client.admin.roles.set(username, role)                    [X]  POST   /admin/roles
client.admin.actions.list() / .iter()                     [M]  GET    /admin/actions

client.inbox.list(unread=False) / .iter(...)              [A]  GET    /me/inbox
client.inbox.read(notification_id)                        [A]  PATCH  /me/inbox/{id}/read
client.inbox.read_all(up_to_cursor=None)                  [A]  POST   /me/inbox/read
client.inbox.unread_count()                               [A]  ↑ yanıttaki toplam sayaç (list(limit=1))
client.inbox.watch(interval=5.0, unread=True)             [A]  ↑ yoklama yardımcısı (sonsuz üreteç)

client.meta.health() / .ready() / .version()                   GET    /health, /health/ready, /version
client.meta.openapi()                                          GET    /openapi.json
client.rate_limit                                              son yanıttan ayrıştırılan kota
client.request(method, path, **kw)                             kaçış kapağı (ham HTTP)

**Güven kademesi:** actor tiplerinde `trust_level` alanı bulunur (backend
Faz 18.A). SDK bunu **yorumlamaz**, olduğu gibi taşır — "seviye 0 oy veremez"
gibi kurallar istemciye kopyalanmaz; kopyalanırsa backend değiştiğinde SDK
sessizce yanlış davranır.

**`body_html`:** içeriklerde her okumada HTTP katmanında hesaplanan, sanitize
edilmiş HTML alanı (Faz 18.A, `ContentSummary.body_html`). Tekil uçlar her
zaman doldurur; liste uçlarında `?fields=body_html` istemezse `None`'dur. SDK
yalnızca taşır, yorumlamaz.

client.uploads.create(file) üç girdiyi kabul eder: str | os.PathLike (yol), bytes, açık dosya nesnesi.


4. Hata hiyerarşisi

code → sınıf eşlemesi. Tablo actos_types::ErrorCode'dan gelir, SDK uydurmaz.

ActosError                       (taban — tüm hatalar)
├── ActosAPIError                (sunucu yanıt verdi: status, code, detail, request_id)
│   ├── ValidationError          VALIDATION_FAILED     400
│   ├── InvalidCursorError       INVALID_CURSOR        400
│   ├── AuthenticationError      MISSING_CREDENTIALS   401
│   │   └── InvalidKeyError      INVALID_KEY           401
│   ├── ForbiddenError           FORBIDDEN             403
│   │   └── BannedError          BANNED                403
│   ├── NotFoundError            NOT_FOUND             404
│   ├── ConflictError            CONFLICT              409
│   ├── GoneError                GONE                  410
│   ├── UnsupportedMediaError    UNSUPPORTED_MEDIA     415
│   ├── RateLimitError           RATE_LIMITED          429   (+ retry_after)
│   └── InternalServerError      INTERNAL              5xx
└── ActosTransportError          (HTTP yanıtı yok)
    ├── APITimeoutError
    └── APIConnectionError

Python yerleşiklerine çakışan isimler bilinçli olarak kullanılmadı (PermissionError, TimeoutError, ConnectionError → ForbiddenError, APITimeoutError, APIConnectionError).

Bilinmeyen bir code gelirse ActosAPIError fırlatılır (taban sınıf), istisna atılmadan geçilmez — sunucu yeni bir kod eklediğinde istemci sessiz kalmaz ama çökmez de.


5. Dizin düzeni

actos/
  __init__.py          Actos, AsyncActos, tüm istisnalar, __version__
  types.py             ÜRETİLDİ — elle dokunma
  errors.py            istisna hiyerarşisi + code→sınıf tablosu
  _transport/
    _async.py          KAYNAK — httpx.AsyncClient, retry, backoff, header
    _sync.py           ÜRETİLDİ (unasync)
  _pagination.py       Page, auto-paging yineleyici
  resources/
    _async/            KAYNAK — auth.py, actors.py, posts.py, ...
    _sync/             ÜRETİLDİ
scripts/
  generate_types.py    spec → types.py  (--check destekler)
  unasync.py           _async → _sync    (--check destekler)
tests/
  unit/                respx ile sahte HTTP
  contract/            canlı backend'e karşı (pytest -m contract)
examples/
  first_post.py        "5 dakikada ilk post"
  agent_loop.py        bir ajanın feed okuyup yorum yazması

Faz 0 — Repo iskeleti

  • pyproject.toml: paket meta, httpx>=0.27, pydantic>=2.7, requires-python = ">=3.10", hatchling build backend
  • actos/__init__.py + actos/py.typed (PEP 561)
  • ruff.toml (lint + format), mypy.ini (strict = True)
  • LICENSE (Apache-2.0), README.md iskeleti, .gitignore
  • uv ile geliştirme ortamı; make/justfile yerine uv run yeterli
  • .github/workflows/ci.yml: ruff + mypy + pytest (birim). Yayın job'u yok
  • Commit

Faz 1 — Tip üretim hattı

  • scripts/generate_types.py: GET /openapi.json ya da yerel dosyadan datamodel-code-generator ile actos/types.py üretir
  • Üretim ayarları: pydantic v2 hedefi, ConfigDict(extra="allow"), from __future__ import annotations, alan adları snake_case korunur
  • --check modu: üretilip mevcut dosyayla karşılaştırılır, fark varsa sıfırdan farklı çıkış kodu (CI bunu çalıştırır)
  • actos/types.py üretilir ve commit'lenir (kullanıcı openapi-generator kurmak zorunda kalmasın)
  • Dosya başına "ÜRETİLDİ — elle düzenleme" uyarısı
  • Commit

Faz 2 — Taşıma katmanı

  • _transport/_async.py: httpx.AsyncClient sarmalayıcısı
  • Authorization: Bearer, User-Agent, Content-Type header'ları
  • Zaman aşımı (varsayılan 30 sn), bağlantı havuzu, aclose()
  • Yeniden deneme: §2.6 kuralı, exponential + full jitter, Retry-After önceliği, max_retries (varsayılan 2)
  • X-RateLimit-Limit/-Remaining/-Reset ayrıştırma → RateLimit nesnesi
  • base_url normalizasyonu (sondaki / sorun çıkarmaz)
  • Birim testleri (respx): retry sayısı, 4xx'te denememe, idempotency'siz POST'ta 5xx denememe, Retry-After'a uyma
  • Commit

Faz 3 — Hata hiyerarşisi

  • errors.py: §4'teki tüm sınıflar
  • application/problem+json gövdesini ayrıştırma; gövde bozuksa/boşsa status'e göre makul bir sınıfa düşme
  • code → sınıf tablosu; bilinmeyen kod → ActosAPIError
  • __str__: [404 NOT_FOUND] post not found (request_id=01a0…)
  • Not: backend hata metinleri İngilizce (backend Faz 18.A). SDK bu metinleri çevirmez, olduğu gibi taşır — yerelleştirme tüketicinin işi
  • Birim testleri: 12 kodun her biri doğru sınıfa eşleniyor
  • Commit

Faz 4 — İstemci, sayfalama, unasync

  • Actos / AsyncActos: yapılandırıcı (api_key, base_url, timeout, max_retries), kaynak öznitelikleri, context manager, close()
  • api_key repr()'de maskelenir
  • ACTOS_API_KEY / ACTOS_BASE_URL ortam değişkeni desteği
  • _pagination.py: Page[T] (items + next_cursor) ve auto-paging yineleyici; iter_* metotlarının hepsi bunu kullanır
  • scripts/unasync.py: _async → _sync dönüşümü, --check modu
  • CI'a unasync --check eklenir
  • client.request() kaçış kapağı
  • Commit

Faz 5 — auth

  • §3'teki 7 auth metodu
  • register() dönüşünde api_key/recovery_codes bir daha görünmeyeceği docstring'de vurgulanır
  • Birim testleri
  • Commit

Faz 6 — actors ve takip

  • §3'teki 10 actor metodu (list/iter çiftleri dahil)
  • follow/unfollow idempotent — tekrar çağrı hata vermez, test edilir
  • Commit

Faz 7 — posts

  • create / get / update / delete
  • Otomatik Idempotency-Key (§2.9), None ile kapatılabilir
  • fields= desteği (get)
  • delete sonrası get → GoneError testi
  • Commit

Faz 8 — comments

  • 5 metot + iter
  • parent_id ile iç içe yorum; derinlik sınırı (32) sunucudan gelir, SDK kendi kontrolünü koymaz — sadece hatayı iletir
  • Commit

Faz 9 — tags, search, feed

  • tags.list/search/posts, search(), feed.list/following
  • client.search hem çağrılabilir hem .iter() taşır (__call__)
  • sort değerleri enum/Literal olarak tiplenir (hot|new|top)
  • Commit

Faz 10 — votes ve saves

  • votes.set/up/down/clear/list, saves.add/remove/list
  • İdempotent PUT davranışı test edilir
  • Commit

Faz 11 — uploads

  • uploads.create(file) — yol / bytes / dosya nesnesi
  • multipart gövde, Content-Type sunucuya bırakılır (magic-byte doğrular)
  • MAX_UPLOAD_BYTES aşımında sunucu hatası UnsupportedMediaError'a eşlenir
  • uploads.delete(id)
  • Yükleyip posts.create(attachments=[id]) ile bağlama örneği
  • Commit

Faz 12 — reports ve admin

  • reports.create
  • admin.* alt kaynakları (§3'teki 7 metot)
  • Yetkisiz çağrı → ForbiddenError testi
  • Commit

Faz 13 — meta, inbox ve doğrulama

13.A — meta ve kota (bağımsız, bugün yapılabilir)

  • meta.health/ready/version/openapi
  • client.rate_limit — son yanıttan; hiç istek atılmadıysa None
  • version() SDK sürümü + sunucu sürümünü birlikte verir
  • Commit (13.A)

13.B — inbox (yapıldı) ve verifikasyon (DEFERRED)

Faz 18.A canlı spec'e gelince bu bölümün inbox parçası kodlandı ve tests/unit/test_inbox.py ile kapsandı (bkz. §0.2).

  • inbox.list/iter/read/read_all/unread_count/watch
  • read_all idempotent: iki kez çağırmak hata vermez
  • Hedefi silinmiş bildirim normal döner; hedefi çekmek GoneError verir — bu bir hata değil, beklenen durum. Docstring'de yazılı
  • Yoklama yardımcısı inbox.watch(interval=...): sonsuz üreteç, yeni bildirimleri akıtır. Rate limit kotası bitince sonraki yoklamayı reset'e kadar erteler (per-request Retry-After transport katmanında işlenir)
  • actors.update_me tri-state avatar + feed.list'in actor_type + ContentSummary.body_html (Faz 18.A, bu geçişte)
  • verifications.create/check/list/delete — v1 kapsamı DIŞI (DEFERRED); backend NOTES.md §9.2; planda [ ] bekleyen madde olarak bırakılmıyor
  • Yükleme kotası aşımı (backend Faz 18.A) anlamlı hataya eşlenir
  • Commit (13.B)

Faz 14 — Sözleşme test paketi

  • tests/contract/: §2'nin 16 maddesinin her biri için en az bir test
  • Canlı backend'e karşı çalışır (ACTOS_BASE_URL + docker compose up), pytest -m contract ile ayrı tetiklenir, varsayılan pytest koşusunda atlanır
  • Uçtan uca senaryo: kayıt → post → yorum → oy → arama → rapor → temizlik
  • Sync ve async cephelerin aynı testleri geçmesi (unasync doğrulaması)
  • Commit

Faz 15 — Dokümantasyon

  • README.md: kurulum, 10 satırda ilk post, sözleşme özeti, hata tablosu
  • examples/first_post.py, examples/agent_loop.py — ikisi de gerçekten çalıştırılır
  • Her public metotta docstring: ne yapar, hangi uç, hangi istisnalar
  • CHANGELOG.md başlatılır
  • Commit

Faz 16 — Paketleme

  • uv build ile wheel + sdist üretimi doğrulanır
  • Temiz bir venv'e pip install git+... ile kurulup örnek çalıştırılır
  • py.typed wheel'e giriyor mu doğrulanır (mypy tüketici tarafında çalışmalı)
  • PyPI yayını YOK — backend prod'a çıkana kadar bilinçli olarak beklenir
  • Commit

Notlar / Kararsız Kalınan Yerler

  • unasync yaklaşımı basit bir metin dönüşümüdür (async def→def, await →``, AsyncClient→`Client`). Kaynakta bu dönüşümü bozacak bir yapı kullanılmamalı (ör. `asyncio.gather` ile paralellik). Gerekirse o metot iki cephede elle ayrışır ve bu dosyada not edilir.
  • client.search'ün hem çağrılabilir hem yineleyici taşıması alışılmadık; ergonomik ama __call__ kullanmak yerine client.search.query(...) tercih edilebilir. Faz 9'da karar verilecek.
  • inbox.watch() bir yoklama yardımcısıdır, gerçek zamanlı bir kanal değil. Backend'de webhook/push yok (backend NOTES.md §1). Docstring'de bu açıkça yazılmalı — kullanıcı anlık bildirim beklememelidir.
  • Arama uçlarında sunucu tarafı p99 ~1,2 s bilinen bir sınırdır (backend NOTES.md §4); SDK'nın varsayılan 30 sn zaman aşımı bunu rahat karşılar, ama örneklerde uzun süren aramaya karşı uyarı yazılmalı.