Ядро (tbank.core)

Домен-агностичный фундамент, общий для эквайринга и открытого банка: транспорт, стратегии аутентификации, ретраи, декларативные эндпоинты, модели и ошибки. Обычно напрямую не используется, но полезен для тонкой настройки (свой транспорт, таймауты, политика ретраев).

Ошибки

exception tbank.core.errors.TBankError

Базовые классы: Exception

Базовое исключение SDK.

exception tbank.core.errors.TBankNetworkError

Базовые классы: TBankError

Сетевой сбой (соединение/таймаут) после исчерпания ретраев.

exception tbank.core.errors.TBankTimeoutError

Базовые классы: TBankNetworkError

Истёк таймаут запроса.

exception tbank.core.errors.MutualTLSRequiredError

Базовые классы: TBankError

Вызван secured-метод, но клиент создан без mTLS-сертификата.

exception tbank.core.errors.TBankAPIError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankError

Логическая ошибка API (Success=false / HTTP 4xx-5xx).

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.AuthenticationError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Ошибка аутентификации/подписи.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.InvalidRequestError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Некорректный запрос/параметры.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.InsufficientFundsError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Недостаточно средств на карте.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.ThreeDSError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Не пройдена аутентификация 3DS.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.TerminalBlockedError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Операция заблокирована для терминала.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.ForbiddenError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Доступ запрещён (неизвестный IP / нехватка скоупов / нет прав). HTTP 403.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.ValidationError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Некорректные данные запроса. HTTP 400/422.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.RateLimitError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Превышен лимит запросов. HTTP 429.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

exception tbank.core.errors.ServerError(*, code, message, details=None, http_status=None, status=None, error_id=None)

Базовые классы: TBankAPIError

Ошибка на стороне сервера. HTTP 5xx.

Параметры:

• code (str)

• message (str)

• details (Optional[str])

• http_status (Optional[int])

• status (Optional[str])

• error_id (Optional[str])

Тип результата:

None

tbank.core.errors.build_api_error(*, code, message, details=None, http_status=None, status=None)

Собрать типизированное исключение по коду ошибки.

Параметры:

• code (str)

• message (str)

• details (str | None)

• http_status (int | None)

• status (str | None)

Тип результата:

TBankAPIError

tbank.core.errors.error_from_tapi_response(response, *, fallback='request failed')

Исключение из T-API error-ответа ({errorId, errorMessage, errorCode, errorDetails}).

Параметры:

• response (Response)

• fallback (str)

Тип результата:

TBankAPIError

Ретраи

class tbank.core.retry.RetryPolicy(attempts: 'int' = 3, backoff_base: 'float' = 0.5, backoff_max: 'float' = 8.0, jitter: 'bool' = True, retry_statuses: 'FrozenSet[int]' = frozenset({500, 502, 503, 504, 429}), retry_non_idempotent: 'bool' = False)

Базовые классы: object

Параметры:

• attempts (int)

• backoff_base (float)

• backoff_max (float)

• jitter (bool)

• retry_statuses (FrozenSet[int])

• retry_non_idempotent (bool)

tbank.core.retry.should_retry(policy, *, status, attempt, method='GET', idempotent=None)

Ретраить ли попытку номер attempt (1-based).

idempotent — явный признак безопасности повтора (например, у запроса есть Idempotency-Key); если не задан, выводится из метода. 429 повторяется всегда: сервер отклонил запрос до обработки.

Параметры:

• policy (RetryPolicy)

• status (int | None)

• attempt (int)

• method (str)

• idempotent (bool | None)

Тип результата:

bool

tbank.core.retry.compute_delay(policy, *, attempt, retry_after=None)

Задержка перед попыткой attempt (1-based).

Параметры:

• policy (RetryPolicy)

• attempt (int)

• retry_after (float | None)

Тип результата:

float

Аутентификация

class tbank.core.auth.AuthStrategy(*args, **kwargs)

Базовые классы: Protocol

Готовит тело/заголовки запроса под конкретную схему auth.

Транспорт

class tbank.core.transport.AsyncTransport(*, client=None, **kwargs)

Базовые классы: _TransportBase

Параметры:

• client (Optional[httpx.AsyncClient])

• kwargs (Any)

class tbank.core.transport.SyncTransport(*, client=None, **kwargs)

Базовые классы: _TransportBase

Параметры:

• client (Optional[httpx.Client])

• kwargs (Any)

tbank.core.transport.build_sync_transports(token, *, base_url, secured_base_url=None, cert=None, verify=True, retry=None, transport=None, secured_transport=None)

Пара транспортов (обычный, secured) с Bearer-авторизацией.

Secured-транспорт создаётся, только если переданы cert и secured_base_url. Уже созданные транспорты пробрасываются как есть.

Параметры:

• token (str)

• base_url (str)

• secured_base_url (str | None)

• cert (str | Tuple[str, str] | Tuple[str, str, str] | None)

• verify (bool | str | SSLContext)

• retry (RetryPolicy | None)

• transport (SyncTransport | None)

• secured_transport (SyncTransport | None)

Тип результата:

Tuple[SyncTransport, SyncTransport | None]

tbank.core.transport.build_async_transports(token, *, base_url, secured_base_url=None, cert=None, verify=True, retry=None, transport=None, secured_transport=None)

Асинхронный аналог build_sync_transports.

Параметры:

• token (str)

• base_url (str)

• secured_base_url (str | None)

• cert (str | Tuple[str, str] | Tuple[str, str, str] | None)

• verify (bool | str | SSLContext)

• retry (RetryPolicy | None)

• transport (AsyncTransport | None)

• secured_transport (AsyncTransport | None)

Тип результата:

Tuple[AsyncTransport, AsyncTransport | None]

Адреса хостов

Общие адреса хостов открытого банка T-API.

Единственный источник: домены импортируют константы отсюда, а не объявляют свои копии.

Модели и типы

class tbank.core.models.TBankModel

Базовые классы: BaseModel

Базовая модель: snake_case в Python, PascalCase на проводе.

model_config = {'alias_generator': <function to_pascal>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tbank.core.models.to_kopecks(rubles)

Рубли → целые копейки.

Параметры:

rubles (Decimal | int | str)

Тип результата:

int

tbank.core.models.to_rubles(kopecks)

Копейки → рубли (Decimal).

Параметры:

kopecks (int)

Тип результата:

Decimal

Эндпоинты

class tbank.core.endpoint.Endpoint(method, path, response_model, request_model=None, secured=False)

Базовые классы: Generic[TResp]

Декларация вызова API: метод, путь и модели запроса/ответа.

request_model позволяет передавать в _call словарь — он будет провалидирован и приведён к модели. secured=True направляет вызов на secured-хост (mTLS).

Параметры:

• method (str)

• path (str)

• response_model (Type[TResp])

• request_model (Type[BaseModel] | None)

• secured (bool)