Adyen / Adyen/adyen-python-api-library
[Feature]: Thread-safe Multi-Instance API Client with Configuration Isolation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 68
- Forks
- 49
- Avg merge
- 2h 3m
- Merged PRs (30d)
- 2
Description
Feature summary
Multi‑instance, thread‑safe API client with better typing
Problem statement
Background
The current Python client uses a singleton pattern for each API handler and the HTTP client. In multithreaded environments (e.g., UWSGI) this leads to thread‑safety issues and makes it impossible to use different credentials/settings for separate services (e.g., ECOM vs. POS).
A workaround is already in place: importing individual API parts from submodules and instantiating a separate HTTP client for each use‑case. However, the library’s interface still encourages the global singleton, which is not safe.
Proposed improvements
| Area | Desired change |
|---|---|
| Instance isolation | Remove the singleton pattern and allow callers to create multiple independent client instances. Each instance should accept its own configuration (API endpoint, authentication keys, HTTP client, etc.). |
| Documentation | Clearly document that the top‑level exported objects are global singletons and discourage their use in multi‑tenant or concurrent workflows. Provide examples of per‑instance creation. |
| Thread safety | Ensure no shared mutable state lives inside the client or its handler objects, so concurrent requests with different configs are safe. |
| Type hints | Improve static typing: • Functions that currently return AdyenResult | None | Unknown actually raise inside helper functions. Either raise the exception directly or return a clear Union with explicit error types. • Provide type stubs / .pyi files or refined type annotations so tools like basedpyright and mypy can understand the API signatures. • Example: Replace the ad‑hoc ListTerminalsProtocol workaround with a real protocol exposed in the library. |
My comments (for reference)
- The library is generated via an API generator, so a complete rewrite is not realistic.
- Instantiating small objects in Python has negligible memory overhead—no performance penalty.
- I am available for hire, on a consulting basis.
Proposed solution
Goal: Get a library that supports multiple concurrent clients with distinct configurations while providing robust typing for static analysis tools. This solves the thread‑safety problem and makes the ECOM/POS multi‑tenant use‑case straightforward.
Alternatives considered
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by mapping the top-level exported objects, individual API handler submodules, and HTTP client entry points to understand where singleton state and configuration are held. Review the ListTerminalsProtocol workaround and existing annotations; done means independent configurations work concurrently and static analyzers can understand the client API.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100