{"id":4306,"library":"types-stripe","title":"Typing Stubs for Stripe","description":"types-stripe is a PEP 561 type stub package for the `stripe` library, providing static type annotations for use with type-checking tools like MyPy, Pyright, or PyCharm. The current version aims to provide accurate annotations for `stripe==3.5.*`. Maintained by the Typeshed project, it is automatically released up to once a day via PyPI.","status":"active","version":"3.5.2.20240106","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/stripe","tags":["typing","stubs","type hints","stripe","typeshed"],"install":[{"cmd":"pip install types-stripe","lang":"bash","label":"Install types-stripe"}],"dependencies":[{"reason":"Provides runtime functionality; `types-stripe` only supplies type hints for this library.","package":"stripe","optional":false}],"imports":[{"note":"Type checkers automatically use installed stubs for the `stripe` library; direct imports from `types-stripe` are not needed for type checking.","symbol":"stripe","correct":"import stripe"},{"symbol":"Customer","correct":"from stripe import Customer"}],"quickstart":{"code":"import os\nimport stripe\nfrom typing import Optional\n\n# Set your Stripe API key (usually from environment variables)\n# For demonstration, use a placeholder. In real applications, ensure this is securely managed.\nstripe.api_key = os.environ.get(\"STRIPE_SECRET_KEY\", \"sk_test_YOUR_SECRET_KEY\")\n\ndef get_customer_email(customer_id: str) -> Optional[str]:\n    \"\"\"\n    Retrieves a Stripe customer's email.\n    Type checkers will use types-stripe (or inline stubs if stripe>=7.1.0) to\n    validate API calls and response types.\n    \"\"\"\n    try:\n        # The 'stripe' library methods are typed by types-stripe (if installed and applicable)\n        customer = stripe.Customer.retrieve(customer_id)\n        # Type checker knows 'customer' is a stripe.Customer object and 'email' is Optional[str]\n        print(f\"Customer email: {customer.email}\")\n        return customer.email\n    except stripe.error.StripeError as e:\n        print(f\"Error retrieving customer: {e}\")\n        return None\n\nif __name__ == \"__main__\":\n    # This example assumes you have a test customer ID.\n    # Replace 'cus_example_id' with a real test customer ID if you want to run it.\n    # Note: Without a valid key and customer, this will raise a StripeError.\n    customer_id_example = \"cus_example_id\" # Replace with actual test customer ID\n    get_customer_email(customer_id_example)\n\n    # Example of creating a Customer (showing parameters are typed)\n    try:\n        new_customer = stripe.Customer.create(\n            description=\"Test customer for types-stripe example\",\n            email=\"test@example.com\"\n            # metadata={\"order_id\": \"123\"} # Other optional typed parameters\n        )\n        print(f\"Created new customer with ID: {new_customer.id}\")\n    except stripe.error.StripeError as e:\n        print(f\"Error creating customer: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Uninstall `types-stripe` using `pip uninstall types-stripe`. Ensure `stripe` is `7.1.0` or newer.","message":"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`.","severity":"breaking","affected_versions":"stripe>=7.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.5.0, >3.5.*"},{"fix":"Contribute missing annotations to the `typeshed` project on GitHub or use `# type: ignore` comments to suppress specific errors.","message":"`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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"stripe>=7.1.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}