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 的支持。从 6.0.0 版本开始，Stripe SDK Python 包将不再支持 Python 2.7。要继续获取新功能和安全更新，请确保将您的 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]我们已经测试过 Pyright 可以正确识别这些类型。 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