Metadata-Version: 2.4
Name: apiservisim
Version: 0.2.0
Summary: Apiservisim Türkçe API'leri için bağımlılıksız Python istemcisi
Project-URL: Homepage, https://apiservisim.vercel.app/
Project-URL: Repository, https://github.com/fortextexe/apiservisim
Keywords: apiservisim,api,turkey,türkçe,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Apiservisim Python SDK

Apiservisim'in Türkçe API'lerine Python ile erişmek için bağımlılıksız istemci. Python 3.10+ ve yalnızca standart kütüphane gerekir.

## Kurulum

```bash
python -m pip install "apiservisim>=0.2.0"
```

Kaynak koddan geliştirme kurulumu için `python -m pip install .` komutunu `python-sdk` klasöründe çalıştırın.

## Katalogdaki API'ler

Paket, web sitesindeki **36 katalog servisini** `API_CATALOG` ile, uygulamadaki tüm kamuya açık route şablonlarını da `API_ENDPOINTS` ile dışa aktarır. Yönetim amaçlı `/api/admin/...` uçları bilerek bu genel katalogda yer almaz. Yeni bir route eklense bile `get`, `post` ve `request` ile doğrudan çağırabilirsiniz.

```python
from apiservisim import API_CATALOG, API_ENDPOINTS, ApiServisim

api = ApiServisim()

print(len(API_CATALOG))   # 36 katalog servisi
print(len(API_ENDPOINTS)) # public route şablonları ve alias'lar

# Servis adıyla çağrı
kurlar = api.call_api("Döviz API")
hava = api.call_api("Hava Durumu API", path_params={"sehir": "istanbul"})

# İki dinamik path parçası ve query parametreleri
kargo = api.call_api(
    "Kargo API",
    path_params={"carrier": "aras", "takip_no": "TAKIP-NO"},
)

# API_CATALOG veya API_ENDPOINTS'te olmayan yeni/özel bir route da çağrılabilir.
sonuc = api.get("/api/doviz")
```

`API_CATALOG` servis adlarını birincil route şablonlarına eşler. `API_ENDPOINTS` nested ve dinamik route'ları da listeler. Dinamik route'larda `{sehir}` gibi tek segmentli parametreler; `{path...}` gibi catch-all parametrelerde ise slash'lı metin veya segment listesi kullanılabilir. Path değerleri URL için otomatik kodlanır.

Örnek özel route çağrıları:

```python
from apiservisim import ApiServisim

api = ApiServisim()

# JSON yerine görsel döndüren endpoint: sonuç bytes olur.
qr_png = api.call_api("/api/qr", params={"data": "Merhaba", "size": 600})

# Catch-all route: IANA zaman dilimi iki path parçası olarak korunur.
saat = api.call_api(
    "/api/saat/{sehir...}",
    path_params={"sehir": "Europe/Paris"},
)

# Uçuşlar, domain geçmişi, posta kodu, noter alt yolları ve diğer tüm kayıtlı
# rotalar API_ENDPOINTS içinden keşfedilebilir.
```

## Genel HTTP metotları

JSON yanıtları Python nesnesine, JSON olmayan yanıtlar `bytes`'a çevrilir. İhtiyaca göre `request` ile GET, POST, PUT, PATCH veya DELETE gönderebilirsiniz:

```python
sonuc = api.get("doviz", params={"baz": "TRY"})
yanit = api.post("tckimlik", json={"tc": "...", "ad": "..."})
sonuc = api.request("DELETE", "/api/ornek", params={"id": 123})
```

## T.C. Kimlik No Kontrol API'si

```python
import os
from apiservisim import ApiServisim

sonuc = ApiServisim().call_api(
    "T.C. Kimlik No Kontrol API",
    method="POST",
    json={
        "tc": os.environ["TC_KIMLIK_NO"],
        "ad": os.environ["KISI_ADI"],
        "soyad": os.environ["KISI_SOYADI"],
        "dogum_yili": 1990,
    },
)
```

Bu endpoint yalnızca yerel biçim ve kontrol basamağı algoritmasını çalıştırır. Harici kimlik kayıtlarına bağlanmaz ve gerçek bir kişinin kimliğini doğrulamaz. Gerçek kişisel verileri GET URL'sine koymayın veya günlüklerde saklamayın; POST JSON kullanın.

## Özel sunucu adresi, zaman aşımı ve hatalar

```python
from apiservisim import ApiServisim, ApiServisimHTTPError

api = ApiServisim(base_url="https://apiservisim.vercel.app", timeout=20)

try:
    sonuc = api.get("saat", params={"sehir": "İstanbul"})
except ApiServisimHTTPError as hata:
    print(hata.status_code, hata.body)
```

`ApiServisimConnectionError`, bağlantı ve zaman aşımı sorunlarında; `ApiServisimHTTPError` API'nin 4xx/5xx yanıtlarında yükseltilir. Hata gövdesi `ApiServisimHTTPError.body` içindedir.

## Testler

```bash
python -m unittest discover -s tests -v
```
