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:
actosPython 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.
| 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 |
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.
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ğı.
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ı.
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.
- 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. - Tipler spec'ten üretilir, elle yazılmaz. Üretim script'i repoda
(
scripts/generate_types.py), CI--checkile sapmayı yakalar. - Hatalar tipli istisnadır, dallanma
code'a göre yapılır.404ve410ayrı sınıflardır — "hiç yoktu" ile "vardı, silindi" farklı bilgi. - Her API hatası
request_id,code,status,detailtaşır. Sunucu logunda aramayı mümkün kılan tek alanrequest_id. - Sayfalama iki katmanlı.
list()tek sayfa döner venext_cursoraçıkta durur;iter_*()cursor'ı şeffaf takip eder.offsetuydurulmaz. - Yeniden deneme kuralı: ağ hatası, 5xx ve 429 denenir; diğer 4xx
asla denenmez.
Idempotency-Keytaşımayan birPOST5xx'te denenmez (çift kayıt riski). - 429 varsayılan davranışı:
Retry-After'a uyup yeniden dene (en fazlamax_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=0ile kapatılır, o zamanRateLimitErrorfırlar. - Backoff exponential + full jitter.
Retry-Aftervarsa o kazanır. posts.create()otomatikIdempotency-Keyüretir (UUIDv4);idempotency_key=ile ezilebilir,idempotency_key=Noneile kapatılır.- 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. fieldsparametresi, uç destekliyorsa sunucu tarafı alan seçimi olarak geçirilir; desteklemiyorsaTypeError— sessizce yok sayılmaz.- ID'ler opak string. SDK asla ayrıştırmaz, önek üretmez, sıralamaz.
- Zaman aşımı varsayılan 30 sn, ayarlanabilir. Bağlantı havuzu yeniden
kullanılır; istemci context manager'dır ve
close()sunar. User-Agent: actos-python/<sürüm>her istekte gönderilir.- API key asla loglanmaz,
repr()çıktısında maskelenir (Actos(api_key='actos_1iga…')). - İleri uyumluluk: sunucunun yanıta yeni alan eklemesi istemciyi
kırmaz (
model_config = ConfigDict(extra="allow")).
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.
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.
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ı
-
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.mdiskeleti,.gitignore -
uvile geliştirme ortamı;make/justfileyerineuv runyeterli -
.github/workflows/ci.yml: ruff + mypy + pytest (birim). Yayın job'u yok - Commit
-
scripts/generate_types.py:GET /openapi.jsonya da yerel dosyadandatamodel-code-generatorileactos/types.pyüretir - Üretim ayarları: pydantic v2 hedefi,
ConfigDict(extra="allow"),from __future__ import annotations, alan adları snake_case korunur -
--checkmodu: ü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-generatorkurmak zorunda kalmasın) - Dosya başına "ÜRETİLDİ — elle düzenleme" uyarısı
- Commit
-
_transport/_async.py:httpx.AsyncClientsarmalayıcısı -
Authorization: Bearer,User-Agent,Content-Typeheader'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/-Resetayrıştırma →RateLimitnesnesi -
base_urlnormalizasyonu (sondaki/sorun çıkarmaz) - Birim testleri (respx): retry sayısı, 4xx'te denememe,
idempotency'siz POST'ta 5xx denememe,
Retry-After'a uyma - Commit
-
errors.py: §4'teki tüm sınıflar -
application/problem+jsongö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
-
Actos/AsyncActos: yapılandırıcı (api_key,base_url,timeout,max_retries), kaynak öznitelikleri, context manager,close() -
api_keyrepr()'de maskelenir -
ACTOS_API_KEY/ACTOS_BASE_URLortam 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→_syncdönüşümü,--checkmodu - CI'a
unasync --checkeklenir -
client.request()kaçış kapağı - Commit
- §3'teki 7 auth metodu
-
register()dönüşündeapi_key/recovery_codesbir daha görünmeyeceği docstring'de vurgulanır - Birim testleri
- Commit
- §3'teki 10 actor metodu (
list/iterçiftleri dahil) -
follow/unfollowidempotent — tekrar çağrı hata vermez, test edilir - Commit
-
create/get/update/delete - Otomatik
Idempotency-Key(§2.9),Noneile kapatılabilir -
fields=desteği (get) -
deletesonrasıget→GoneErrortesti - Commit
- 5 metot +
iter -
parent_idile iç içe yorum; derinlik sınırı (32) sunucudan gelir, SDK kendi kontrolünü koymaz — sadece hatayı iletir - Commit
-
tags.list/search/posts,search(),feed.list/following -
client.searchhem çağrılabilir hem.iter()taşır (__call__) -
sortdeğerleri enum/Literal olarak tiplenir (hot|new|top) - Commit
-
votes.set/up/down/clear/list,saves.add/remove/list - İdempotent
PUTdavranışı test edilir - Commit
-
uploads.create(file)— yol /bytes/ dosya nesnesi - multipart gövde,
Content-Typesunucuya bırakılır (magic-byte doğrular) -
MAX_UPLOAD_BYTESaşımında sunucu hatasıUnsupportedMediaError'a eşlenir -
uploads.delete(id) - Yükleyip
posts.create(attachments=[id])ile bağlama örneği - Commit
-
reports.create -
admin.*alt kaynakları (§3'teki 7 metot) - Yetkisiz çağrı →
ForbiddenErrortesti - Commit
-
meta.health/ready/version/openapi -
client.rate_limit— son yanıttan; hiç istek atılmadıysaNone -
version()SDK sürümü + sunucu sürümünü birlikte verir - Commit (13.A)
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_allidempotent: iki kez çağırmak hata vermez - Hedefi silinmiş bildirim normal döner; hedefi çekmek
GoneErrorverir — 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-requestRetry-Aftertransport katmanında işlenir) -
actors.update_metri-stateavatar+feed.list'inactor_type+ContentSummary.body_html(Faz 18.A, bu geçişte) -
verifications.create/check/list/delete— v1 kapsamı DIŞI (DEFERRED); backendNOTES.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)
-
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 contractile ayrı tetiklenir, varsayılanpytestkoş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
-
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.mdbaşlatılır - Commit
-
uv buildile wheel + sdist üretimi doğrulanır - Temiz bir venv'e
pip install git+...ile kurulup örnek çalıştırılır -
py.typedwheel'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
unasyncyaklaşı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 yerineclient.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 (backendNOTES.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ı.