stripe python

Stripe Python 庫

Stripe Python 程式庫提供了從用 Python 語言編寫的應用程式對 Stripe API 的便捷存取。它包括一組預先定義的 API 資源類，這些類別根據 API 回應動態初始化自身，這使其與 Stripe API 的各種版本相容。

文件

請參閱 Python API 文件。

請觀看有關如何使用該庫的視訊演示。

安裝

除非您想修改包，否則不需要此原始程式碼。如果您只想使用該包，只需運行：

pip install --upgrade stripe

從源安裝：

python setup.py install

要求

• Python 3.6+（支援 PyPy）

Python 2.7 棄用

Python 軟體基金會 (PSF) 社群宣佈於 2020 年 1 月 1 日終止對 Python 2 的支援。若要繼續取得新功能和安全性更新，請確保將您的 Python 執行時間更新至 Python 3.6+。

支援Python 2.7的Stripe SDK的最後一個版本是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 )

訪問響應代碼和標頭

您可以使用傳回資源的last_response屬性存取HTTP 回應代碼和標頭。

 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 

類型

在 v7.1.0 及更高版本中，該程式庫包含類型註解。請參閱 wiki 以取得詳細指南。

請注意，某些註解使用最近才被接受的功能，例如 2023 年 1 月接受的Unpack[TypedDict] MyPy 中對Unpack的支援仍處於實驗階段，但似乎會正常降級。如果我們可以採取任何措施來改進您選擇的類型檢查器的類型，請回報問題。

類型和版本控制策略

我們在次要版本中發布類型變更。雖然 stripe-python 遵循語義版本控制，但我們的語義版本僅描述庫的運行時行為。我們的類型註釋沒有反映在語義版本中。也就是說，升級到 stripe-python 的新次要版本可能會導致類型檢查器產生先前沒有的類型錯誤。您可以在requirements.txt中使用~=xx或xx*版本說明符將pip限制在stripe-python的某個較小範圍內。

類型和 API 版本

這些類型描述了發佈時最新的 Stripe API 版本。這是您的庫預設發送的版本。如果您要覆蓋StripeClient上的stripe.api_version / stripe_version ，或使用與舊版本綁定的 Webhook 端點，請注意您在執行時看到的資料可能與類型不符。

測試版 SDK

Stripe 具有處於測試階段的功能，可透過該套件的測試版本存取這些功能。我們希望您在這些功能達到穩定階段之前嘗試這些功能並與我們分享回饋。要安裝測試版，請使用pip install以及您想要使用的確切版本：

 pip install --pre stripe

注意Beta 版本之間可能存在重大變更。因此，我們建議將套件版本固定到需求檔案或setup.py中的特定 beta 版本。這樣，您每次都可以安裝相同的版本，而不會破壞更改，除非您有意尋找最新的測試版。

我們強烈建議您專注於您感興趣的測試版功能何時從測試版變為穩定版，以便您可以從使用 SDK 的測試版轉向穩定版。

如果您的 Beta 功能需要傳送Stripe-Version標頭，請使用stripe.api_version stripe.add_beta_version ：

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

客製化請求

如果您想要向未記錄的 API 發送請求（例如您處於私人測試版），或者如果您希望繞過庫中的方法定義並直接指定請求詳細信息，則可以使用StripeClient上的raw_request方法。

 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 ，因為自 stripe-python v5 起.save已被棄用。請遷移到.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，因此請確保從後台終端取得並運行它（stripe-mock 的 README 也包含透過 Homebrew 和其他方法安裝的說明）：

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

執行以下命令來設定開發 virtualenv：

make

在所有支援的 Python 版本上執行所有測試：

make test

執行特定 Python 版本的所有測試（根據您的 Python 目標修改-e ）：

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 之前必須將程式碼格式化為 Black，否則 CI 將失敗。使用以下命令運行格式化程式：

make fmt