انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

حِزم SDK

SDK بايثون

تقيّم حزمة nanoflags الأعلام محليًا وبشكل متزامن على إعداد موقّع في الذاكرة، وتُبقيه خيوطٌ في الخلفية محدّثًا عبر الاتصال الحي. واستدعاء القراءة لا يُجري أي عملية إدخال/إخراج ولا يرفع استثناءً أبدًا.

التثبيت

sh
pip install nanoflags
pip install "nanoflags[openfeature]"   # with the OpenFeature provider
  • منشورة على PyPI باسم nanoflags 0.1.0. تتطلب Python 3.9 أو أحدث، ومُنمَّطة بالكامل (py.typed).
  • الاعتماديات: cryptography (‏Ed25519) وwebsockets. والإضافة openfeature تضيف openfeature-sdk 0.8 أو أحدث.
  • المحرك نقلٌ بلغة Python الصرفة لمحرك NanoFlags. وهو مختبَر على الحالات المشتركة المولَّدة من المحرك المرجعي (21,998 حالة تقييم)، ويعطي النتائج نفسها التي تعطيها حزمتا جافاسكريبت وGo.
  • برخصة Apache-2.0. والشيفرة المصدرية في مستودع nanoflags-sdk.

البدء السريع

انسخ مفتاح خادم (nf_srv_…) من الإعدادات ← مفاتيح SDK (Settings → SDK keys) في لوحة التحكم واحفظه في متغير بيئة.

app.py
import os
from nanoflags import NanoFlags

flags = NanoFlags(
    os.environ["NANOFLAGS_SDK_KEY"],   # nf_srv_… (server view) or nf_pub_… (client-exposed flags only)
    service="checkout-api",            # shown in "which revision is each service running"
)
flags.wait_until_ready(timeout=5)      # never raises; True once a configuration is in use

user = {"key": "user-42", "plan": "beta", "region": "DE"}
if flags.bool_variation("new-checkout", False, user):
    ...

flags.close()                          # on shutdown (or use `with NanoFlags(...) as flags:`)

أنشئ عميلًا واحدًا لكل عملية وشاركه بين الخيوط. والعنوان الأساسي افتراضيًا هو الحافة المستضافة https://edge.nanoflags.io.

السياقات

السياق dict من قيم شبيهة بـ JSON (نصوص وأرقام وقيم منطقية وNone وقوائم وقواميس). وkey هو الهوية الثابتة المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعد الاستهداف كل خاصية أخرى.

python
ctx = {"key": account.id, "plan": account.plan, "country": "SA", "beta": True, "seats": 12}
flags.string_variation("search-ranking", "relevance-v2", ctx)
  • لا يغادر السياق العملية لاتخاذ القرار. وانظر القياس لمعرفة ما ترسله بيانات التشخيص.
  • مرّر key نفسه للمستخدم نفسه في كل مكان: تُحسب الشريحة منه، فيقع المفتاح نفسه في شريحة الطرح نفسها في Python وGo وجافاسكريبت ولوحة التحكم.

القراءات المُنمَّطة

كل دالة قراءة تأخذ مفتاح العلم والقيمة الافتراضية وسياقًا اختياريًا. وتُقدَّم القيمة الافتراضية حين يتعذّر تقييم العلم.

python
enabled = flags.bool_variation("new-checkout", False, user)
accent  = flags.string_variation("accent", "blue", user)
limit   = flags.number_variation("rate-limit", 100, user)       # int or float
layout  = flags.json_variation("layout", {"cols": 3}, user)     # any JSON value

every   = flags.all_flags(user)                                  # {"new-checkout": True, ...}
الدالةتعيد
bool_variation(key, default, context=None)قيمة bool
string_variation(key, default, context=None)قيمة str
number_variation(key, default, context=None)قيمة int أو float (لا تُقبل القيم المنطقية ولا الأرقام غير المنتهية)
json_variation(key, default, context=None)أي قيمة JSON: قاموس أو قائمة أو نص أو رقم أو قيمة منطقية أو None
*_variation_detail(key, default, context=None)كائن Evaluation، انظر التفاصيل والأسباب
evaluate(key, default, context=None)نتيجة المحرك دون فحص للنوع
all_flags(context=None)كل أعلام الإعداد المحمَّل كـ dict (و{} من دونه؛ ولا يُؤخذ كعيّنة في القياس)

تحصل على قيمتك الافتراضية عندما لم يُحمَّل إعداد بعد، أو عندما يكون العلم مجهولًا (أو غير مكشوف للعميل مع مفتاح متصفح)، أو عندما يقدّم العلم قيمة من نوع آخر. والعلم المعطّل ليس حالة احتياط: فهو يعيد قيمة off المضبوطة له.

التفاصيل والأسباب

python
detail = flags.bool_variation_detail("new-checkout", False, user)
print(detail.value, detail.reason, detail.rule_id, detail.revision)   # True rule_match beta 57

for step in detail.trace:                                             # the same steps the dashboard shows
    print(step.kind, step.title, step.detail)
الحقلالمعنى
valueالقيمة المقدَّمة (قيمتك الافتراضية في حالات الاحتياط).
reasonrule_match، default (لم تطابق قاعدة)، off (العلم معطّل)، flag_not_found، error (نوع خاطئ أو إعداد مشوّه)
rule_index · rule_idالقاعدة المطابقة (فهرس يبدأ من الصفر)، أو None.
in_rollout · bucketللطرح بالنسب المئوية: هل المفتاح داخل التوزيع، وشريحته (من 0 إلى 99.99).
revisionنسخة الإعداد التي جاءت منها النتيجة.
traceقائمة من TraceStep تشرح القرار خطوة بخطوة.
errorلماذا كان reason هو error.

التحديثات الحيّة وon_change

يفتح العميل اتصال WebSocket واحدًا إلى wss://edge.nanoflags.io/v1/live (ينتقل المفتاح في ترويسة Authorization، لا في العنوان أبدًا). وتدفع الحافة كل نسخة منشورة موقّعةً مسبقًا؛ فيتحقق منها العميل ويستبدلها ذرّيًا، فيرى التقييم دائمًا نسخة واحدة كاملة.

python
def changed(e):
    print(f"now on r{e.revision} (was r{e.previous_revision}) via {e.transport}, {e.latency_ms} ms after commit")

unsubscribe = flags.on_change(changed)
flags.on_error(lambda err: log.warning("nanoflags %s: %s", err.code, err))
الحقلالمعنى
revision · previous_revisionالنسخة الجديدة والنسخة التي حلّت محلها (None للأولى).
checksumبصمة الإعداد الجديد.
sourcenetwork أو store (ذاكرة الملف المؤقتة) أو bootstrap
transportlive (مدفوعة) أو stream (مجلوبة بعد إشعار أحداث من الخادم) أو poll
latency_msمن الالتزام في قاعدة البيانات حتى هذا الحدث، للنسخ المدفوعة التي تحمل وقت التزامها؛ وإلا None. يقارن ساعتين، فدقّته بقدر اتفاقهما.
  • تعمل المستمعات على خيط العميل في الخلفية: اجعلها قصيرة، وسلّم العمل الأطول لطابورك الخاص. والاستثناء في مستمع يُسجَّل ولا يعطّل العميل أبدًا.
  • on_change وon_error وon("update" | "error" | "status", cb) تعيد دالة لإلغاء الاشتراك. ويمكنك أيضًا تمرير on_change= وon_error= إلى المُنشئ كي لا يفوتك التحميل الأول.
  • الاحتياط: إن تعذّر فتح الاتصال يستخدم العميل أحداث الخادم (/v1/stream) ويستطلع كل 30 ثانية. وأثناء سلامة الاتصال يعمل استطلاع أمان كل 5 دقائق. وتتراجع محاولات إعادة الاتصال من ثانية واحدة حتى 5 دقائق مع تذبذب. وانظر وسائل النقل للبروتوكول.

الجاهزية والحالة

python
if not flags.wait_until_ready(timeout=5):
    log.warning("flags not loaded yet; variations return their defaults")

flags.status      # "not-ready" | "ready" | "stale"
flags.revision    # revision in use, or None
flags.transport   # "live" | "stream" | "poll"
  • wait_until_ready(timeout) (والاسم البديل ready) ينتظر حتى يصبح إعداد قيد الاستخدام، أو حتى تنتهي محاولة التحميل الأولى دونه. ولا يرفع استثناءً أبدًا؛ ويعيد True عندما يكون إعداد قيد الاستخدام.
  • ready: أكّدت الحافة الإعداد في آخر محاولة. stale: إعداد قيد الاستخدام لكن لا يُعرف أنه الحالي (استُعيد من الذاكرة المؤقتة ولم يُؤكَّد بعد، أو تعذّر الوصول إلى الحافة). not-ready: لا شيء محمَّل، وكل دالة قراءة تعيد قيمتها الافتراضية.
  • لا تُوقف طلبًا بانتظار الجاهزية. انتظر مرة واحدة عند البدء بمهلة قصيرة، ودع قيمك الافتراضية تغطي الباقي.

آخر إعداد سليم والتهيئة المسبقة

بعد التحميل، يبقى آخر إعداد سليم قيد الاستخدام عبر أعطال الشبكة والحزم المرفوضة وأخطاء الحافة (فتصبح status ‏stale). ولا يستبدل العميل الإعداد بنسخة أقدم أبدًا.

python
flags = NanoFlags(
    sdk_key,
    cache_path="/var/cache/app/flags.json",   # keep the last good bundle across restarts
)

# Or start from a bundle you ship (dict or JSON text), served until the edge answers:
flags = NanoFlags(sdk_key, bootstrap=open("flags-bootstrap.json").read())
  • cache_path يكتب الحزمة ذرّيًا بالصلاحيات 0600. وعند البدء تُستعاد بحالة stale حتى تؤكّدها الحافة. ويُتحقق من النسخة المستعادة مجددًا، وتُتجاهل إن لم تجتز التحقق أو كُتبت لمفتاح أو حافة أخرى.
  • store= يقبل أي كائن له get() وset(text) (مثل nanoflags.FileStore(path)) ويتقدّم على cache_path.
  • تحتوي الذاكرة المؤقتة على قواعد الأعلام، لا على مفتاح الـ SDK أبدًا. والتهيئة المسبقة مفيدة لأنظمة الملفات للقراءة فقط وللاختبارات.

التحقق من التوقيع

تُفحص كل حزمة (‏Ed25519، حسب معرّف المفتاح) قبل أن تحلّ محل المستخدمة: عبر الاتصال الحي وعبر HTTP ومن الذاكرة المؤقتة. ومع الحافة المستضافة يكون ذلك مفعّلًا افتراضيًا بمفاتيح الإنتاج المضمّنة في الحزمة (OFFICIAL_SIGNING_KEYS)، وتُرفض الحزم غير الموقّعة. وتُحسب بصمة البايتات الموقّعة كما قُدّمت تمامًا.

python
from nanoflags import NanoFlags, VerifyOptions

# Self-hosted or proxied edge: pin your keys and require signatures
flags = NanoFlags(
    sdk_key,
    base_url="https://flags.internal.example",
    verify=VerifyOptions(public_keys=[{"kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "k1"}], require=True),
)
  • الحزمة التي تفشل في التحقق لا تُستخدم: تبقى السابقة، ويستلم on_error الرمز signature.
  • الحزمة التي تذكر معرّف مفتاح مجهولًا (تدوير مفاتيح) تجعل العميل يحمّل GET /v1/keys مرة واحدة، ومرة في الدقيقة على الأكثر.
  • public_keys="fetch" يحمّل المفاتيح من الحافة بدل تثبيتها. والمفاتيح المثبّتة أقوى: فالمفاتيح المجلوبة موثوقة بقدر الحافة التي قدّمتها فقط.
  • verify=False يعطّل التحقق. والنص القانوني والترويسات موصوفة في التواقيع.
  • الحزمة المكتوبة لمحرك تقييم أحدث مما تدعمه الحزمة تُرفض (الرمز engine) ويبقى الإعداد الحالي: حدّث الحزمة.

مزوّد OpenFeature

sh
pip install "nanoflags[openfeature]"
python
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from nanoflags import NanoFlags
from nanoflags.openfeature import NanoFlagsProvider

provider = NanoFlagsProvider(NanoFlags(sdk_key, service="checkout-api"), close_client=True)
api.set_provider_and_wait(provider)   # openfeature-sdk >= 0.9; on 0.8 use api.set_provider(provider)

client = api.get_client()
client.get_boolean_value("new-checkout", False, EvaluationContext(targeting_key="user-42", attributes={"plan": "beta"}))
  • يبقى التقييم محليًا: المزوّد يغلّف العميل أعلاه، فتعمل التحديثات الحيّة والتواقيع وآخر إعداد سليم بالطريقة نفسها.
  • يصبح targeting_key هو key. والأسباب: علم معطّل ← DISABLED، ولم تطابق قاعدة ← DEFAULT، وقاعدة ثابتة ← TARGETING_MATCH، وطرح تدريجي ← SPLIT (والمتغيّر هو معرّف القاعدة). والأخطاء: FLAG_NOT_FOUND وTYPE_MISMATCH.
  • دالة القراءة العشرية تقبل الأعداد الصحيحة. والنسخ الجديدة تطلق PROVIDER_CONFIGURATION_CHANGED؛ وتغيّرات الحالة تطلق PROVIDER_READY وPROVIDER_STALE.
  • close_client=True يغلق عميل NanoFlags عندما يوقف OpenFeature المزوّد. والخيارات: ready_timeout (افتراضيًا 10 ث).

asyncio

python
from nanoflags.aio import AsyncNanoFlags

async with AsyncNanoFlags(sdk_key, service="api") as flags:
    await flags.wait_until_ready(5)
    enabled = flags.bool_variation("new-checkout", False, {"key": user_id})   # local, no await needed

يأخذ AsyncNanoFlags وسائط الكلمات المفتاحية نفسها. وتبقى دوال القراءة متزامنة؛ أمّا wait_until_ready وrefresh وflush وclose فقابلة للانتظار. ويقبل on_change دوال coroutine تعمل على حلقة الأحداث التي أنشأت العميل.

الخيارات

الخيارالافتراضيالوصف
base_urlhttps://edge.nanoflags.ioعنوان الحافة.
service"unknown"الاسم الذي تُبلغ به هذه العملية.
poll_interval30.0الثواني بين الاستطلاعات حين لا يكون اتصال مفتوح. و0 يعطّل الاستطلاع.
live_poll_interval300.0استطلاع الأمان أثناء سلامة الاتصال الحي.
liveTrueFalse يتخطى WebSocket ويستخدم أحداث الخادم والاستطلاع.
streamingTrueFalse لا يُبقي إلا الاستطلاع.
cache_path · storeلا شيءانظر آخر إعداد سليم.
bootstrapلا شيءحزمة (قاموس أو نص JSON) تُقدَّم حتى تجيب الحافة.
verifyمفعّل للحافة المستضافةVerifyOptions(public_keys, require) أو False.
eventsعيّنة 10 %EventsOptions(enabled, sample_rate, flush_interval, report_interval, redact) أو False.
on_change · on_errorلا شيءمستمعات تُسجَّل قبل التحميل الأول.
startTrueFalse يؤجل العمل في الخلفية حتى start().

رموز الأخطاء

تصل أعطال الخلفية إلى on_error كـ NanoFlagsError له code (وhttp_status عند الحاجة): network وunauthorized وhttp وinvalid_bundle وstore وconfig وsignature وsession وengine وenvironment_deleted. ولا يُرفع أي شيء من استدعاء قراءة أبدًا. والمعاني مطابقة لـ SDK جافاسكريبت.

القياس

تُرسل عيّنة 10 % من التقييمات كل 10 ثوانٍ، مع بلاغ خدمة كل 60 ثانية. وافتراضيًا لا تغادر قيم السياق العملية أبدًا: لا يُرسل إلا أسماء الخصائص التي تستخدمها قواعد العلم (وأنواع قيمها). ويحلّ events=EventsOptions(redact=...) محل ذلك؛ وevents=False يعطّل القياس.

الإغلاق والإيقاف

python
import atexit
atexit.register(flags.close)

# or scope it
with NanoFlags(sdk_key, service="nightly-job") as flags:
    run(flags)
  • close() يوقف خيوط الخلفية ويرسل القياس المنتظر (بأفضل جهد، مع مهلة قصيرة). واستدعاؤه أكثر من مرة آمن.
  • بعد close() تواصل دوال القراءة العمل على آخر إعداد؛ لكنه يتوقف عن التحديث فقط.
  • خيوط الخلفية خيوط daemon، فلا تُبقي السكربت حيًّا. ومع ذلك يجب أن تستدعي السكربتات القصيرة close() (أو تستخدم with) ليُرسل القياس.

حل المشكلات

  1. كل قراءة تعيد القيمة الافتراضية. افحص flags.status وسجّل on_error قبل التحميل الأول (وسيط للمُنشئ). يعني unauthorized أن المفتاح رُفض؛ ومع مفتاح متصفح (nf_pub_…) لا تُسلَّم إلا الأعلام المكشوفة للعميل.
  2. الخوادم التي تتفرّع مسبقًا (gunicorn وuWSGI وCelery prefork). الخيوط لا تنجو من fork(). أنشئ العميل في كل عامل بعد بدئه (مثلًا في خطاف post_fork أو عند أول استخدام)، لا وقت الاستيراد في العملية الأم.
  3. خلف وسيط أو مع سلطة شهادات مخصّصة. يحترم HTTP وWebSocket المتغيرين HTTPS_PROXY وSSL_CERT_FILE. وإن حُجبت الترقية يستخدم العميل أحداث الخادم والاستطلاع، ويعرض flags.transport القيمة stream أو poll.
  4. 403 ‏«error code: 1010» من طلبات HTTP الخاصة بك. ترفض الحافة الطلبات التي تحمل User-Agent الافتراضي Python-urllib. ويرسل الـ SDK ‏nanoflags-python/<version>، فلا يتأثر بذلك إلا الشيفرة التي تستدعي الحافة مباشرة (مثل طلبات OFREP أو السكربتات): اضبط ترويسة User-Agent الخاصة بك.
  5. أخطاء بالرمز signature. لم تجتز الحزمة التحقق فلم تُستخدم. وإن مرّرت base_url مخصّصًا فثبّت مفاتيح تلك الحافة عبر VerifyOptions.
  6. أخطاء بالرمز engine. يحتاج الإعداد محرك تقييم أحدث: حدّث بـ pip install -U nanoflags.
  7. أخطاء بالرمز environment_deleted. حُذفت بيئة المفتاح. يتوقف العميل عن إعادة الاتصال ويُبقي آخر إعداد بحالة stale؛ استبدل المفتاح.
لغات أخرى
لـ Go حزمة SDK أصلية أيضًا: انظر SDK لغة Go. ولتطبيقات الجوال حزم أصلية لـ React Native وFlutter وiOS وAndroid. وتتوفر حزم SDK أصلية للخوادم أيضًا لـ Java و.NET وPHP وRuby. ويمكن للغات الأخرى قراءة أعلام NanoFlags عبر مزوّد OpenFeature OFREP.