Python | SeekGist

حزمة Python اسمها seekgist. تحتاج إلى Python 3.12 أو أحدث، وفيها عميل عادي (SeekGist) وعميل غير متزامن (AsyncSeekGist)، وكلاهما مبني على httpx ومع أنواع كاملة. دوال الواجهة البرمجية مولّدة من ملف OpenAPI، أما الدوال المساعدة فمكتوبة يدويًا.

بداية سريعة

from seekgist import SeekGist
 
with SeekGist(api_key="sg_sec_...") as client:  # أو اضبط SEEKGIST_API_KEY
    res = client.find("فستان سهرة تحت 100", lang="ar", per_page=12)
    res.data["ids"]   # أرقام المنتجات بترتيب الصلة
    res.data["hits"]  # بطاقات المنتجات
    res.usage         # Usage(searches, limit, billed, period) من X-SeekGist-Usage
    res.request_id    # اذكره عند التواصل مع الدعم

from seekgist import AsyncSeekGist
 
async with AsyncSeekGist() as client:
    res = await client.find("white sneakers", lang="en")

الخيارات: base_url (الافتراضي https://api.seekgist.com، أو SEEKGIST_BASE_URL)، وtimeout (10 ثوانٍ لكل محاولة)، وmax_retries (2)، وheaders، وhttp_client.

مزامنة الكتالوج

summary = client.upsert_products(products, replace_all=True, key_prefix="nightly-2026-10-14")

دفعات حتى 1,000 منتج، وIdempotency-Key واحد لكل دفعة (<key_prefix>-<n>)، و5 محاولات إعادة. وتشغيلها مرة أخرى بقيمة key_prefix نفسها استئناف آمن. ومع replace_all=True تصبح مزامنة كاملة.

كل دوال الواجهة البرمجية

مجال أسماء لكل قسم من الواجهة، ودالة لكل نقطة نهاية، بمعاملات مسمّاة فقط: client.search وevents وcatalog وimports وconnectors وjobs وsynonyms وrules وexperiments وtranslation وassistant وanalytics وwebhooks وaccount وbilling وhealth وfiles.

client.synonyms.create(body={"kind": "equivalent", "terms": ["sneakers", "trainers", "سنيكرز"]})
client.catalog.products_get(product_id="42")
client.analytics.stats(report="top_queries", from_="2026-10-01")  # كلمة from محجوزة في Python، لذا: from_
r = client.request("search_post", body={"q": "dress"})  # أي نقطة نهاية، مع الترويسات

تقبل كل دالة options={"timeout", "max_retries", "idempotency_key", "headers", "query"}.

الدوال المساعدة

الدالة	ماذا تفعل
`client.find(q, **fields)`	`POST /v1/search` مع `.usage`
`client.upsert_products(products, ...)`	مزامنة آمنة للكتالوج على دفعات؛ وترجع `UpsertSummary`
`client.wait_for_job(job_id)`	تنتظر انتهاء مهمة
`client.pages(lambda c: client.synonyms.list(cursor=c))`	كل عناصر قائمة
`AsyncSeekGist.suggester(debounce=0.12, ...)`	اقتراحات مع انتظار توقف الكتابة للكود غير المتزامن (روبوت محادثة، أو وسيط على الخادم). والاقتراحات لا تُحسب في الفاتورة أبدًا
`verify_webhook(secret, headers, raw_body)`	تتحقق من توقيع الإشعار ومن وقته (5 دقائق)
`parse_usage(header)`	تقرأ `X-SeekGist-Usage`

في المتصفح، استخدم حزمة JavaScript أو أداة البحث للاقتراحات.

الأخطاء وإعادة المحاولة

ApiError (status، code، request_id، field_errors، retry_after_s)، وTimeoutError، وConnectionError، وWebhookVerificationError. وكلها من نوع SeekGistError.
تُعاد طلبات GET والبحث وعمليات الكتابة التي تحمل Idempotency-Key (تضيفه الحزمة وتحتفظ به في كل محاولة). أما النقرات والأحداث والمحادثة فلا تُعاد بعد خطأ شبكة أو خطأ 5xx، ويُعاد الطلب عند 429 دائمًا.
في صفحة البحث في متجر: SeekGist(timeout=0.3, max_retries=0)، واعرض بحث متجرك عند أي SeekGistError. راجع الرجوع إلى بحث المتجر.

أمثلة

في المستودع: packages/sdk-python/examples/search.py، وsync_catalog.py، وwebhook_receiver.py، وasync_suggest.py.