[Feature]: Thread-safe Multi-Instance API Client with Configuration Isolation

[karolyi]

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