หน้าแรก>การเขียนโปรแกรมที่เกี่ยวข้อง>หลาม
ดาวน์โหลด

ไลบรารีลาย Python

สถานะการสร้าง

ไลบรารี Stripe Python ช่วยให้เข้าถึง Stripe API ได้อย่างสะดวกจากแอปพลิเคชันที่เขียนด้วยภาษา Python ประกอบด้วยชุดคลาสที่กำหนดไว้ล่วงหน้าสำหรับทรัพยากร API ที่เริ่มต้นตัวเองแบบไดนามิกจากการตอบสนองของ API ซึ่งทำให้เข้ากันได้กับ Stripe API เวอร์ชันต่างๆ ที่หลากหลาย

เอกสารประกอบ

ดูเอกสาร Python API

ชมวิดีโอสาธิตวิธีการใช้ห้องสมุด

การติดตั้ง

คุณไม่จำเป็นต้องใช้ซอร์สโค้ดนี้ เว้นแต่ว่าคุณต้องการแก้ไขแพ็คเกจ หากคุณต้องการใช้แพ็คเกจเพียงแค่เรียกใช้: 

pip install --upgrade stripe

ติดตั้งจากแหล่งที่มาด้วย: 

python setup.py install

ความต้องการ

  • Python 3.6+ (รองรับ PyPy)

การเลิกใช้งาน Python 2.7

ชุมชน Python Software Foundation (PSF) ประกาศสิ้นสุดการสนับสนุน Python 2 ในวันที่ 1 มกราคม 2020 เริ่มต้นด้วยเวอร์ชัน 6.0.0 แพ็คเกจ Stripe SDK Python จะไม่รองรับ Python 2.7 อีกต่อไป หากต้องการรับฟีเจอร์ใหม่และการอัปเดตความปลอดภัยต่อไป โปรดอย่าลืมอัปเดตรันไทม์ Python ของคุณเป็น Python 3.6+

Stripe SDK เวอร์ชันล่าสุดที่รองรับ Python 2.7 คือ 5.5.0

การใช้งาน

จำเป็นต้องกำหนดค่าไลบรารีด้วยรหัสลับของบัญชีของคุณซึ่งมีอยู่ใน Stripe Dashboard ของคุณ ตั้งค่า 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

คีย์ Idempotency จะถูกสร้างขึ้นโดยอัตโนมัติและเพิ่มลงในคำขอ เมื่อไม่ได้ให้ไว้ เพื่อรับประกันว่าการลองใหม่จะปลอดภัย

การบันทึก

คุณสามารถกำหนดค่าไลบรารีให้ปล่อยการบันทึกที่จะช่วยให้คุณเข้าใจได้ดีขึ้นว่ากำลังทำอะไรอยู่ โดยปกติแล้วระดับการบันทึก 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 ที่เชื่อมโยงกับเวอร์ชันเก่า โปรดทราบว่าข้อมูลที่คุณเห็นขณะรันไทม์อาจไม่ตรงกับประเภทดังกล่าว

SDK เบต้า

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" )

คำขอที่กำหนดเอง

หากคุณต้องการส่งคำขอไปยัง API ที่ไม่มีเอกสาร (เช่น คุณอยู่ในรุ่นเบต้าส่วนตัว) หรือหากคุณต้องการข้ามคำจำกัดความของวิธีการในไลบรารีและระบุรายละเอียดคำขอของคุณโดยตรง คุณสามารถใช้วิธี 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 เลิกใช้แล้วตั้งแต่ stripe-python v5 โปรดย้ายไปยัง .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 สำหรับการจัดรูปแบบโค้ด รหัสต้องอยู่ในรูปแบบสีดำก่อนที่จะส่ง PR มิฉะนั้น CI จะไม่สำเร็จ รันฟอร์แมตเตอร์ด้วย: 

make fmt
ขยาย
ข้อมูลเพิ่มเติม
แอปที่เกี่ยวข้อง
แนะนำสำหรับคุณ
ข้อมูลที่เกี่ยวข้อง ทั้งหมด