stripe-python Method signatures not interpreted correctly

The Fix

pip install stripe==14.4.0a2

Based on closed stripe/stripe-python issue #1113 · PR/commit linked

Production note: This usually shows up under retries/timeouts. Treat it as a side-effect risk until you can verify behavior with a canary + real traffic.

Jump to Verify Open PR/Commit

@@ -3545,9 +3545,9 @@ def _cls_delete(
 
     @overload
-    @classmethod
+    @staticmethod
     def delete(

repro.py

import stripe

def f(payment_method: str, customer: str) -> None:
    stripe.PaymentMethod.attach(payment_method, customer=customer)

def g(payment_method: str) -> None:
    stripe.PaymentMethod.detach(payment_method)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install stripe==14.4.0a2\nWhen NOT to use: This fix is not applicable if the method signatures are intended to require 'self' or 'cls'.\n\n

Why This Fix Works in Production

Trigger: t.py:4: error: No overload variant of "attach" of "PaymentMethod" matches argument types "str", "str" [call-overload]
Mechanism: Mypy reports incorrect method signatures due to inconsistent use of classmethod and staticmethod decorators
Why the fix works: Adds @staticmethod overloads to address mypy type checking issues with class methods in the Stripe library. (first fixed release: 14.4.0a2).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Mypy reports incorrect method signatures due to inconsistent use of classmethod and staticmethod decorators
Production symptom (often without a traceback): t.py:4: error: No overload variant of "attach" of "PaymentMethod" matches argument types "str", "str" [call-overload]

Proof / Evidence

GitHub issue: #1113
Fix PR: https://github.com/stripe/stripe-python/pull/1116
First fixed release: 14.4.0a2
Reproduced locally: No (not executed)
Last verified: 2026-02-08
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.67

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Released in https://github.com/stripe/stripe-python/releases/tag/v7.2.0”

@richardm-stripe · 2023-10-31 · confirmation · source

“Hello @samueljsb. Thanks for the report. I am able to reproduce and am trying to figure out a fix.”

@richardm-stripe · 2023-10-31 · source

“Thank you @samueljsb for being a patient/quick adopter of the type annotations, writing a detailed report, and helping to make the library better for everyone!”

@richardm-stripe · 2023-10-31 · source

“Thank you for responding and getting an update out so quickly!”

@samueljsb · 2023-11-01 · source

Failure Signature (Search String)

t.py:4: error: No overload variant of "attach" of "PaymentMethod" matches argument types "str", "str" [call-overload]
t.py:4: note: def attach(self, self: PaymentMethod, idempotency_key: str | None = ..., **params: Any) -> PaymentMethod

Copy-friendly signature

signature.txt

Failure Signature
-----------------
t.py:4: error: No overload variant of "attach" of "PaymentMethod" matches argument types "str", "str"  [call-overload]
t.py:4: note:     def attach(self, self: PaymentMethod, idempotency_key: str | None = ..., **params: Any) -> PaymentMethod

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
t.py:4: error: No overload variant of "attach" of "PaymentMethod" matches argument types "str", "str"  [call-overload]
t.py:4: note:     def attach(self, self: PaymentMethod, idempotency_key: str | None = ..., **params: Any) -> PaymentMethod

Minimal Reproduction

repro.py

import stripe

def f(payment_method: str, customer: str) -> None:
    stripe.PaymentMethod.attach(payment_method, customer=customer)

def g(payment_method: str) -> None:
    stripe.PaymentMethod.detach(payment_method)

What Broke

Mypy errors prevent users from compiling code that uses the Stripe library correctly.

Why It Broke

Mypy reports incorrect method signatures due to inconsistent use of classmethod and staticmethod decorators

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install stripe==14.4.0a2

When NOT to use: This fix is not applicable if the method signatures are intended to require 'self' or 'cls'.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/stripe/stripe-python/pull/1116

First fixed release: 14.4.0a2

Last verified: 2026-02-08. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable if the method signatures are intended to require 'self' or 'cls'.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
14.4.0a2	Fixed

Related Issues

No related fixes found.

Cluster: stripe-python:configuration-error stripe-python hub stripe-python best practices All hubs All clusters

Related clusters: Data consistency Other Payments

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

stripe-python Method signatures not interpreted correctly by mypy (Fix)