stripe python

مكتبة شريط بايثون

توفر مكتبة Stripe Python وصولاً سهلاً إلى Stripe API من التطبيقات المكتوبة بلغة Python. يتضمن مجموعة محددة مسبقًا من الفئات لموارد واجهة برمجة التطبيقات (API) التي تقوم بتهيئة نفسها ديناميكيًا من استجابات واجهة برمجة التطبيقات (API) مما يجعلها متوافقة مع مجموعة واسعة من إصدارات Stripe API.

التوثيق

راجع مستندات Python API.

شاهد عروض الفيديو التي تغطي كيفية استخدام المكتبة.

تثبيت

لا تحتاج إلى كود المصدر هذا إلا إذا كنت تريد تعديل الحزمة. إذا كنت تريد فقط استخدام الحزمة، فما عليك سوى تشغيل:

pip install --upgrade stripe

التثبيت من المصدر باستخدام:

python setup.py install

متطلبات

• بايثون 3.6+ (يدعم PyPy)

إهمال بايثون 2.7

أعلن مجتمع Python Software Foundation (PSF) عن انتهاء دعم Python 2 في 01 يناير 2020. بدءًا من الإصدار 6.0.0 Stripe SDK، لن تدعم حزم Python بعد الآن Python 2.7. للاستمرار في الحصول على ميزات وتحديثات أمنية جديدة، يرجى التأكد من تحديث وقت تشغيل Python الخاص بك إلى Python 3.6+.

الإصدار الأخير من Stripe SDK الذي يدعم Python 2.7 هو 5.5.0.

الاستخدام

يجب تكوين المكتبة باستخدام المفتاح السري لحسابك والمتوفر في لوحة تحكم Stripe الخاصة بك. اضبط stripe.api_key على قيمته:

 from stripe import StripeClient

client = StripeClient ( "sk_test_..." )

# list customers
customers = client . customers . list ()

# print the first customer's email
print ( customers . data [ 0 ]. email )

# retrieve specific Customer
customer = client . customers . retrieve ( "cus_123456789" )

# print that customer's email
print ( customer . email )

التعامل مع الاستثناءات

تثير الطلبات غير الناجحة استثناءات. ستعكس فئة الاستثناء نوع الخطأ الذي حدث. يرجى مراجعة مرجع واجهة برمجة التطبيقات (API) للحصول على وصف لفئات الأخطاء التي يجب عليك التعامل معها، وللحصول على معلومات حول كيفية فحص هذه الأخطاء.

التكوين حسب الطلب

قم بتكوين الطلبات الفردية باستخدام وسيطة options . على سبيل المثال، يمكنك تقديم طلبات باستخدام إصدار Stripe محدد أو كحساب متصل:

 from stripe import StripeClient

client = StripeClient ( "sk_test_..." )

# list customers
client . customers . list (
    options = {
        "api_key" : "sk_test_..." ,
        "stripe_account" : "acct_..." ,
        "stripe_version" : "2019-02-19" ,
    }
)

# retrieve single customer
client . customers . retrieve (
    "cus_123456789" ,
    options = {
        "api_key" : "sk_test_..." ,
        "stripe_account" : "acct_..." ,
        "stripe_version" : "2019-02-19" ,
    }
)

تكوين عميل HTTP

يمكنك تكوين StripeClient الخاص بك لاستخدام urlfetch أو requests أو pycurl أو urllib2 باستخدام خيار http_client :

 client = StripeClient ( "sk_test_..." , http_client = stripe . UrlFetchClient ())
client = StripeClient ( "sk_test_..." , http_client = stripe . RequestsClient ())
client = StripeClient ( "sk_test_..." , http_client = stripe . PycurlClient ())
client = StripeClient ( "sk_test_..." , http_client = stripe . Urllib2Client ())

بدون تكوين عميل، ستحاول المكتبة افتراضيًا تحميل المكتبات بالترتيب أعلاه (أي يُفضل استخدام urlfetch مع استخدام urllib2 كحل أخير). نوصي عادةً بأن يستخدم الأشخاص requests .

تكوين الوكيل

يمكن تكوين الوكيل باستخدام خيار العميل proxy :

 client = StripeClient ( "sk_test_..." , proxy = "https://user:[email protected]:1234" )

تكوين المحاولات التلقائية

يمكنك تمكين إعادة المحاولة التلقائية للطلبات التي تفشل بسبب مشكلة عابرة عن طريق تكوين الحد الأقصى لعدد مرات إعادة المحاولة:

 client = StripeClient ( "sk_test_..." , max_network_retries = 2 )

يمكن أن تؤدي الأخطاء المختلفة إلى إعادة المحاولة، مثل خطأ في الاتصال أو انتهاء المهلة، وكذلك استجابات معينة لواجهة برمجة التطبيقات (API) مثل حالة HTTP 409 Conflict .

يتم إنشاء مفاتيح العجز تلقائيًا وإضافتها إلى الطلبات، في حالة عدم تقديمها، لضمان أن تكون عمليات إعادة المحاولة آمنة.

التسجيل

يمكن تكوين المكتبة لإصدار التسجيل الذي سيمنحك رؤية أفضل لما تفعله. عادةً ما يكون مستوى تسجيل info هو الأكثر ملاءمة للاستخدام في الإنتاج، ولكن debug متاح أيضًا لمزيد من التفصيل.

هناك بعض الخيارات لتمكينه:

1. قم بتعيين متغير البيئة STRIPE_LOG على القيمة debug أو info

   $ export STRIPE_LOG=debug

2. تعيين stripe.log :

    import stripe
   stripe . log = 'debug'

3. قم بتمكينه من خلال وحدة التسجيل في Python:

    import logging
   logging . basicConfig ()
   logging . getLogger ( 'stripe' ). setLevel ( logging . DEBUG )

الوصول إلى رمز الاستجابة والعناوين

يمكنك الوصول إلى رمز استجابة HTTP ورؤوسها باستخدام خاصية last_response للمورد الذي تم إرجاعه.

 customer = client . customers . retrieve (
    "cus_123456789"
)

print ( customer . last_response . code )
print ( customer . last_response . headers )

كتابة البرنامج المساعد

إذا كنت تكتب مكونًا إضافيًا يستخدم المكتبة، فنحن نقدر ذلك إذا حددته باستخدام stripe.set_app_info() :

 stripe . set_app_info ( "MyAwesomePlugin" , version = "1.2.34" , url = "https://myawesomeplugin.info" )

يتم تمرير هذه المعلومات عندما تقوم المكتبة باستدعاء Stripe API.

القياس عن بعد

افتراضيًا، ترسل المكتبة بيانات القياس عن بعد إلى Stripe فيما يتعلق بوقت استجابة الطلب واستخدام الميزة. تساعد هذه الأرقام Stripe على تحسين زمن الاستجابة الإجمالي لواجهة برمجة التطبيقات (API) الخاصة به لجميع المستخدمين، وتحسين الميزات الشائعة.

يمكنك تعطيل هذا السلوك إذا كنت تفضل:

 stripe . enable_telemetry = False 

أنواع

في الإصدار 7.1.0 والإصدارات الأحدث، تتضمن المكتبة تعليقات توضيحية للنوع. راجع الويكي للحصول على دليل مفصل.

يرجى ملاحظة أن بعض التعليقات التوضيحية تستخدم ميزات تم قبولها مؤخرًا إلى حد ما، مثل Unpack[TypedDict] التي تم قبولها في يناير 2023. لقد اختبرنا أن هذه الأنواع تم التعرف عليها بشكل صحيح بواسطة Pyright. لا يزال دعم Unpack في MyPy تجريبيًا، ولكن يبدو أنه يتراجع بشكل جيد. يرجى الإبلاغ عن مشكلة إذا كان هناك أي شيء يمكننا القيام به لتحسين الأنواع لمدقق النوع الذي تختاره.

الأنواع وسياسة الإصدار

نصدر تغييرات في النوع في الإصدارات الثانوية. بينما يتبع stripe-python الإصدارات الدلالية، فإن إصداراتنا الدلالية تصف سلوك وقت التشغيل للمكتبة وحدها. لا تنعكس التعليقات التوضيحية الخاصة بنا في النسخة الدلالية . أي أن الترقية إلى إصدار ثانوي جديد من stripe-python قد يؤدي إلى قيام مدقق النوع بإنتاج خطأ في النوع لم يحدث من قبل. يمكنك استخدام محدد الإصدار ~=xx أو xx* في ملف requirements.txt الخاص بك لتقييد pip في نطاق صغير معين من stripe-python .

أنواع وإصدارات API

تصف الأنواع إصدار Stripe API الذي كان الأحدث في وقت الإصدار. هذا هو الإصدار الذي ترسله مكتبتك بشكل افتراضي. إذا كنت تقوم بتجاوز stripe.api_version / stripe_version على StripeClient ، أو تستخدم نقطة نهاية webhook مرتبطة بإصدار أقدم، فاعلم أن البيانات التي تراها في وقت التشغيل قد لا تتطابق مع الأنواع.

حزم تطوير البرمجيات بيتا

يحتوي Stripe على ميزات في المرحلة التجريبية يمكن الوصول إليها عبر الإصدار التجريبي من هذه الحزمة. نود أن تجرب هذه الميزات وتشاركنا تعليقاتك قبل أن تصل هذه الميزات إلى مرحلة الاستقرار. لتثبيت إصدار تجريبي، استخدم pip install مع الإصدار المحدد الذي ترغب في استخدامه:

 pip install --pre stripe

ملاحظة: قد تكون هناك تغييرات جذرية بين إصدارات بيتا. ولذلك نوصي بتثبيت إصدار الحزمة على إصدار تجريبي محدد في ملف المتطلبات الخاص بك أو setup.py . وبهذه الطريقة يمكنك تثبيت نفس الإصدار في كل مرة دون كسر التغييرات إلا إذا كنت تبحث عمدًا عن أحدث إصدار تجريبي.

نوصي بشدة بمراقبة متى تنتقل الميزة التجريبية التي تهتم بها من الإصدار التجريبي إلى الإصدار الثابت حتى تتمكن من الانتقال من استخدام إصدار تجريبي من SDK إلى الإصدار الثابت.

إذا كانت الميزة التجريبية الخاصة بك تتطلب إرسال رأس Stripe-Version ، فقم بتعيين الحقل stripe.api_version باستخدام وظيفة stripe.add_beta_version :

 stripe . add_beta_version ( "feature_beta" , "v3" )

طلبات مخصصة

إذا كنت ترغب في إرسال طلب إلى واجهة برمجة تطبيقات غير موثقة (على سبيل المثال، أنت في إصدار تجريبي خاص)، أو إذا كنت تفضل تجاوز تعريفات الطريقة في المكتبة وتحديد تفاصيل طلبك مباشرة، فيمكنك استخدام طريقة raw_request على StripeClient .

 client = StripeClient ( "sk_test_..." )
response = client . raw_request (
    "post" , "/v1/beta_endpoint" , param = 123 , stripe_version = "2022-11-15; feature_beta=v3"
)

# (Optional) response is a StripeResponse. You can use `client.deserialize` to get a StripeObject.
deserialized_resp = client . deserialize ( response , api_mode = 'V1' )

غير متزامن

تتوفر الإصدارات غير المتزامنة من أساليب تقديم الطلب عن طريق إضافة اسم الطريقة بـ _async .

 # With StripeClient
client = StripeClient ( "sk_test_..." )
customer = await client . customers . retrieve_async ( "cus_xyz" )

# With global client
stripe . api_key = "sk_test_..."
customer = await stripe . Customer . retrieve_async ( "cus_xyz" )

# .auto_paging_iter() implements both AsyncIterable and Iterable
async for c in await stripe . Customer . list_async (). auto_paging_iter ():
  ...

لا يوجد .save_async حيث تم إهمال .save منذ الإصدار 5 من stripe-python. يرجى الترحيل إلى .modify_async .

يستخدم عميل HTTP الافتراضي requests لتقديم طلبات متزامنة ولكن httpx لتقديم طلبات غير متزامنة. إذا كنت تقوم بالترحيل إلى الوضع غير المتزامن، فنوصيك بتهيئة عميل http الخاص بك بشكل صريح وتمريره إلى StripeClient أو تعيينه كافتراضي عام.

 # By default, an explicitly initialized HTTPXClient will raise an exception if you
# attempt to call a sync method. If you intend to only use async, this is useful to
# make sure you don't unintentionally make a synchronous request.
my_http_client = stripe . HTTPXClient ()

# If you want to use httpx to make sync requests, you can disable this
# behavior.
my_http_client = stripe . HTTPXClient ( allow_sync_methods = True )

# aiohttp is also available (does not support sync requests)
my_http_client = stripe . AIOHTTPClient ()

# With StripeClient
client = StripeClient ( "sk_test_..." , http_client = my_http_client )

# With the global client
stripe . default_http_client = my_http_client

يمكنك أيضًا فئة فرعية stripe.HTTPClient وتوفير المثيل الخاص بك.

يدعم

تم إصدار ميزات جديدة وإصلاحات للأخطاء في أحدث إصدار رئيسي من مكتبة Stripe Python. إذا كنت تستخدم إصدارًا رئيسيًا أقدم، فنوصيك بالترقية إلى الإصدار الأحدث حتى تتمكن من استخدام الميزات الجديدة وإصلاحات الأخطاء بما في ذلك تلك الخاصة بالثغرات الأمنية. ستظل الإصدارات الرئيسية الأقدم من الحزمة متاحة للاستخدام، ولكنها لن تتلقى أي تحديثات.

تطوير

تعتمد مجموعة الاختبار على Stripe-mock، لذا تأكد من جلبها وتشغيلها من محطة خلفية (يحتوي ملف README الخاص بـ stripe-mock أيضًا على تعليمات التثبيت عبر Homebrew وطرق أخرى):

go install github.com/stripe/stripe-mock@latest
stripe-mock

قم بتشغيل الأمر التالي لإعداد التطوير virtualenv:

make

قم بإجراء جميع الاختبارات على جميع إصدارات Python المدعومة:

make test

قم بإجراء جميع الاختبارات لإصدار محدد من Python (قم بتعديل -e وفقًا لهدف Python الخاص بك):

TOX_ARGS= " -e py37 " make test

قم بإجراء جميع الاختبارات في ملف واحد:

TOX_ARGS= " -e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py " make test

تشغيل مجموعة اختبار واحدة:

TOX_ARGS= " -e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource " make test

قم بإجراء اختبار واحد:

TOX_ARGS= " -e py37 -- tests/api_resources/abstract/test_updateable_api_resource.py::TestUpdateableAPIResource::test_save " make test

قم بتشغيل linter مع:

make lint

تستخدم المكتبة Ruff لتنسيق التعليمات البرمجية. يجب تنسيق الرمز باللون الأسود قبل إرسال طلبات المشاركة، وإلا فسوف يفشل CI. قم بتشغيل المنسق باستخدام:

make fmt