Typing Stubs for Stripe

Warnings

• breaking For `stripe` library versions 7.1.0 and higher, the `stripe` package now includes inline type annotations. Installing `types-stripe` alongside `stripe>=7.1.0` is redundant and can lead to type checker conflicts or incorrect type resolution. Users should uninstall `types-stripe` if using `stripe>=7.1.0`.
  Fix: Uninstall `types-stripe` using `pip uninstall types-stripe`. Ensure `stripe` is `7.1.0` or newer.
• gotcha The version `X.Y.Z.YYYYMMDD` of `types-stripe` (e.g., `3.5.2.20240106`) is designed to provide accurate annotations for `stripe==X.Y.*` (e.g., `stripe==3.5.*`). Using `types-stripe` with `stripe` versions outside this specified range may result in inaccurate or missing type hints.
  Fix: Ensure your installed `stripe` library version aligns with the `X.Y.*` part of the `types-stripe` version. For `stripe>=7.1.0`, see the breaking change warning.
• gotcha `types-stripe` is marked as a partial stub package, meaning some annotations might be missing. If type errors occur due to missing annotations, contributions to `typeshed` are encouraged, or `# type: ignore` comments can be used as a temporary workaround.
  Fix: Contribute missing annotations to the `typeshed` project on GitHub or use `# type: ignore` comments to suppress specific errors.
• gotcha Upgrading the `stripe` runtime library to a new *minor* version may introduce new type errors, as `stripe-python`'s type annotations are not strictly tied to its semantic versioning.
  Fix: It's recommended to constrain `stripe` to a minor version range (e.g., `stripe~=X.Y`) in your `requirements.txt` to mitigate unexpected type checking failures when new minor `stripe` versions are released.

Install

• pip install types-stripe Install types-stripe

Imports

• stripe

  import stripe

  Type checkers automatically use installed stubs for the `stripe` library; direct imports from `types-stripe` are not needed for type checking.
• Customer

  from stripe import Customer

Quickstart

This quickstart demonstrates how to use the `stripe` library. When `types-stripe` is installed (and `stripe` is an older version without inline types), type checkers will automatically pick up the provided type hints, allowing for static analysis of `stripe` API calls and response objects.

import os
import stripe
from typing import Optional

# Set your Stripe API key (usually from environment variables)
# For demonstration, use a placeholder. In real applications, ensure this is securely managed.
stripe.api_key = os.environ.get("STRIPE_SECRET_KEY", "sk_test_YOUR_SECRET_KEY")

def get_customer_email(customer_id: str) -> Optional[str]:
    """
    Retrieves a Stripe customer's email.
    Type checkers will use types-stripe (or inline stubs if stripe>=7.1.0) to
    validate API calls and response types.
    """
    try:
        # The 'stripe' library methods are typed by types-stripe (if installed and applicable)
        customer = stripe.Customer.retrieve(customer_id)
        # Type checker knows 'customer' is a stripe.Customer object and 'email' is Optional[str]
        print(f"Customer email: {customer.email}")
        return customer.email
    except stripe.error.StripeError as e:
        print(f"Error retrieving customer: {e}")
        return None

if __name__ == "__main__":
    # This example assumes you have a test customer ID.
    # Replace 'cus_example_id' with a real test customer ID if you want to run it.
    # Note: Without a valid key and customer, this will raise a StripeError.
    customer_id_example = "cus_example_id" # Replace with actual test customer ID
    get_customer_email(customer_id_example)

    # Example of creating a Customer (showing parameters are typed)
    try:
        new_customer = stripe.Customer.create(
            description="Test customer for types-stripe example",
            email="test@example.com"
            # metadata={"order_id": "123"} # Other optional typed parameters
        )
        print(f"Created new customer with ID: {new_customer.id}")
    except stripe.error.StripeError as e:
        print(f"Error creating customer: {e}")