حِزم SDK
SDK بايثون
nanoflags الأعلام محليًا وبشكل متزامن على إعداد موقّع في الذاكرة، وتُبقيه خيوطٌ في الخلفية محدّثًا عبر الاتصال الحي. واستدعاء القراءة لا يُجري أي عملية إدخال/إخراج ولا يرفع استثناءً أبدًا.في هذه الصفحة
التثبيت
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-sdk0.8 أو أحدث. - المحرك نقلٌ بلغة Python الصرفة لمحرك NanoFlags. وهو مختبَر على الحالات المشتركة المولَّدة من المحرك المرجعي (21,998 حالة تقييم)، ويعطي النتائج نفسها التي تعطيها حزمتا جافاسكريبت وGo.
- برخصة Apache-2.0. والشيفرة المصدرية في مستودع nanoflags-sdk.
البدء السريع
انسخ مفتاح خادم (nf_srv_…) من الإعدادات ← مفاتيح SDK (Settings → SDK keys) في لوحة التحكم واحفظه في متغير بيئة.
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 هو الهوية الثابتة المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعد الاستهداف كل خاصية أخرى.
ctx = {"key": account.id, "plan": account.plan, "country": "SA", "beta": True, "seats": 12}
flags.string_variation("search-ranking", "relevance-v2", ctx)- لا يغادر السياق العملية لاتخاذ القرار. وانظر القياس لمعرفة ما ترسله بيانات التشخيص.
- مرّر
keyنفسه للمستخدم نفسه في كل مكان: تُحسب الشريحة منه، فيقع المفتاح نفسه في شريحة الطرح نفسها في Python وGo وجافاسكريبت ولوحة التحكم.
القراءات المُنمَّطة
كل دالة قراءة تأخذ مفتاح العلم والقيمة الافتراضية وسياقًا اختياريًا. وتُقدَّم القيمة الافتراضية حين يتعذّر تقييم العلم.
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 المضبوطة له.
التفاصيل والأسباب
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 | القيمة المقدَّمة (قيمتك الافتراضية في حالات الاحتياط). |
reason | rule_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، لا في العنوان أبدًا). وتدفع الحافة كل نسخة منشورة موقّعةً مسبقًا؛ فيتحقق منها العميل ويستبدلها ذرّيًا، فيرى التقييم دائمًا نسخة واحدة كاملة.
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 | بصمة الإعداد الجديد. |
source | network أو store (ذاكرة الملف المؤقتة) أو bootstrap |
transport | live (مدفوعة) أو stream (مجلوبة بعد إشعار أحداث من الخادم) أو poll |
latency_ms | من الالتزام في قاعدة البيانات حتى هذا الحدث، للنسخ المدفوعة التي تحمل وقت التزامها؛ وإلا None. يقارن ساعتين، فدقّته بقدر اتفاقهما. |
- تعمل المستمعات على خيط العميل في الخلفية: اجعلها قصيرة، وسلّم العمل الأطول لطابورك الخاص. والاستثناء في مستمع يُسجَّل ولا يعطّل العميل أبدًا.
on_changeوon_errorوon("update" | "error" | "status", cb)تعيد دالة لإلغاء الاشتراك. ويمكنك أيضًا تمريرon_change=وon_error=إلى المُنشئ كي لا يفوتك التحميل الأول.- الاحتياط: إن تعذّر فتح الاتصال يستخدم العميل أحداث الخادم (
/v1/stream) ويستطلع كل 30 ثانية. وأثناء سلامة الاتصال يعمل استطلاع أمان كل 5 دقائق. وتتراجع محاولات إعادة الاتصال من ثانية واحدة حتى 5 دقائق مع تذبذب. وانظر وسائل النقل للبروتوكول.
الجاهزية والحالة
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). ولا يستبدل العميل الإعداد بنسخة أقدم أبدًا.
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)، وتُرفض الحزم غير الموقّعة. وتُحسب بصمة البايتات الموقّعة كما قُدّمت تمامًا.
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
pip install "nanoflags[openfeature]"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
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_url | https://edge.nanoflags.io | عنوان الحافة. |
service | "unknown" | الاسم الذي تُبلغ به هذه العملية. |
poll_interval | 30.0 | الثواني بين الاستطلاعات حين لا يكون اتصال مفتوح. و0 يعطّل الاستطلاع. |
live_poll_interval | 300.0 | استطلاع الأمان أثناء سلامة الاتصال الحي. |
live | True | False يتخطى WebSocket ويستخدم أحداث الخادم والاستطلاع. |
streaming | True | False لا يُبقي إلا الاستطلاع. |
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 | لا شيء | مستمعات تُسجَّل قبل التحميل الأول. |
start | True | False يؤجل العمل في الخلفية حتى 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 يعطّل القياس.
الإغلاق والإيقاف
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) ليُرسل القياس.
حل المشكلات
- كل قراءة تعيد القيمة الافتراضية. افحص
flags.statusوسجّلon_errorقبل التحميل الأول (وسيط للمُنشئ). يعنيunauthorizedأن المفتاح رُفض؛ ومع مفتاح متصفح (nf_pub_…) لا تُسلَّم إلا الأعلام المكشوفة للعميل. - الخوادم التي تتفرّع مسبقًا (gunicorn وuWSGI وCelery prefork). الخيوط لا تنجو من
fork(). أنشئ العميل في كل عامل بعد بدئه (مثلًا في خطافpost_forkأو عند أول استخدام)، لا وقت الاستيراد في العملية الأم. - خلف وسيط أو مع سلطة شهادات مخصّصة. يحترم HTTP وWebSocket المتغيرين
HTTPS_PROXYوSSL_CERT_FILE. وإن حُجبت الترقية يستخدم العميل أحداث الخادم والاستطلاع، ويعرضflags.transportالقيمةstreamأوpoll. 403«error code: 1010» من طلبات HTTP الخاصة بك. ترفض الحافة الطلبات التي تحمل User-Agent الافتراضيPython-urllib. ويرسل الـ SDK nanoflags-python/<version>، فلا يتأثر بذلك إلا الشيفرة التي تستدعي الحافة مباشرة (مثل طلبات OFREP أو السكربتات): اضبط ترويسةUser-Agentالخاصة بك.- أخطاء بالرمز
signature. لم تجتز الحزمة التحقق فلم تُستخدم. وإن مرّرتbase_urlمخصّصًا فثبّت مفاتيح تلك الحافة عبرVerifyOptions. - أخطاء بالرمز
engine. يحتاج الإعداد محرك تقييم أحدث: حدّث بـpip install -U nanoflags. - أخطاء بالرمز
environment_deleted. حُذفت بيئة المفتاح. يتوقف العميل عن إعادة الاتصال ويُبقي آخر إعداد بحالةstale؛ استبدل المفتاح.