Урок 2.4 — Типы данных и Enum'ы

Все типы данных в aiosend можно разделить на три категории:

Enum Asset — это перечисление всех криптовалют, поддерживаемых Crypto Pay. Он используется везде, где нужно указать криптовалюту: при создании инвойса, получении курса, проверке баланса.

from aiosend import Asset

# Доступ к значениям
print(Asset.USDT)        # Asset.USDT
print(Asset.USDT.value)  # "USDT"
print(Asset("TON"))      # Asset.TON (из строки)
print(Asset.BTC.name)    # "BTC" (имя атрибута)

# Итерация по всем активам
for asset in Asset:
    print(f"{asset.name}: {asset.value}")

# Проверка
if some_value in Asset._value2member_map_:
    asset = Asset(some_value)
    print(f"Это актив: {asset}")

# Сравнение
if user_asset == Asset.USDT:
    print("Пользователь выбрал USDT")

Enum Fiat содержит все фиатные валюты, поддерживаемые Crypto Pay для создания счетов в фиате. Используется в параметре fiat метода create_invoice().

from aiosend import Fiat

# Использование
invoice = await cp.create_invoice(
    amount=100,
    fiat=Fiat.USD,     # можно передать сам Enum
    # или просто строку "USD"
)

# Доступ к значению
print(Fiat.EUR.value)    # "EUR"
print(Fiat.RUB.name)     # "RUB"

# Все доступные фиатные валюты
fiats = [f.value for f in Fiat]
print(fiats)
# ['USD', 'EUR', 'RUB', 'BYN', 'UAH', 'GBP', 'CNY', 'KZT', 'UZS', 'GEL', 'TRY', 'AED']

Остальные Enum'ы покрывают статусы, типы и кнопки. Рассмотрим каждый:

CurrencyType — тип валюты счёта

InvoiceStatus — статус инвойса

CheckStatus — статус чека

UpdateType — тип обновления

PaidBtnName — кнопка после оплаты

from aiosend import (
    CurrencyType,
    InvoiceStatus,
    CheckStatus,
    UpdateType,
    PaidBtnName,
)

# CurrencyType
print(CurrencyType.CRYPTO.value)  # "crypto"

# InvoiceStatus — проверка статуса
if invoice.status == InvoiceStatus.PAID.value:
    print("Инвойс оплачен!")
elif invoice.status == InvoiceStatus.EXPIRED.value:
    print("Инвойс просрочен")

# CheckStatus
if check.status == CheckStatus.ACTIVATED.value:
    print("Чек активирован")

# UpdateType — для фильтрации обновлений
update_type = UpdateType.INVOICE_PAID

# PaidBtnName — для create_invoice
invoice = await cp.create_invoice(
    amount=25,
    asset="USDT",
    paid_btn_name=PaidBtnName.VIEWITEM.value,
    paid_btn_url="https://example.com/item",
)

CryptoPayObject — это базовый класс для всех моделей данных в aiosend. Он наследуется от Pydantic BaseModel и предоставляет стандартные методы сериализации, валидации и работы с данными.

pydantic.BaseModel
  └── aiosend.CryptoPayObject        # базовый класс для всех моделей
        ├── App                      # информация о приложении
        ├── Invoice                  # счёт (инвойс)
        ├── Check                    # крипто-чек
        ├── Transfer                 # перевод
        ├── Balance                  # баланс валюты
        ├── Currency                 # информация о валюте
        ├── ExchangeRate             # курс обмена
        ├── AppStats                 # статистика приложения
        ├── Update                   # обновление (событие)
        └── Error                    # ошибка API

Каждая модель наследует все возможности Pydantic: валидацию типов, преобразование данных, сериализацию.

from aiosend import CryptoPayObject

# Все модели наследуют от CryptoPayObject
# который наследует от pydantic.BaseModel

# У каждой модели есть:
obj.model_dump()           # сериализация в dict (Pydantic v2)
obj.model_dump_json()      # сериализация в JSON-строку
obj.model_fields           # словарь полей модели
obj.model_fields_set       # множество установленных полей

Все объекты aiosend можно сериализовать в словарь или JSON. Это полезно для логирования, сохранения в базу данных или передачи по сети.

Метод dict() (Pydantic v1 style)

Старый метод dict() всё ещё доступен для обратной совместимости, но рекомендуется использовать model_dump():

import json
from aiosend import CryptoPay

cp = CryptoPay(token="TOKEN")
app = await cp.get_me()

# Pydantic v2 способ (рекомендуется)
data = app.model_dump()
print(data)
# {
#     'app_id': 12345,
#     'name': 'My App',
#     'payment_processing_bot_username': 'CryptoTestnetBot',
#     'supported_assets': [...]
# }

# Pydantic v1 способ (устаревший)
data_old = app.dict()

# Сериализация в JSON
json_str = app.model_dump_json(indent=2)
print(json_str)

# Сохранение в файл
with open("app_info.json", "w") as f:
    f.write(app.model_dump_json(indent=2))

# Загрузка из JSON
json_data = '{"app_id": 12345, "name": "App", ...}'
app_loaded = App.model_validate_json(json_data)

Параметры model_dump()

from aiosend import CryptoPay

cp = CryptoPay(token="TOKEN")
invoice = await cp.create_invoice(amount=100, asset="USDT")

# Только заданные поля (исключая None)
data1 = invoice.model_dump(exclude_none=True)

# Только определённые поля
data2 = invoice.model_dump(
    include={"invoice_id", "amount", "asset", "status"}
)

# Исключить определённые поля
data3 = invoice.model_dump(
    exclude={"bot_invoice_url", "mini_app_invoice_url"}
)

# Вложенная сериализация (по умолчанию True)
data4 = invoice.model_dump(mode="json")  # для JSON-сериализации

Десериализация — создание объектов из данных

Ты можешь создавать модели aiosend из словарей или JSON. Это полезно, когда ты сохраняешь данные в БД и потом загружаешь их:

from aiosend import App, Invoice, Balance

# Из словаря
app_data = {
    "app_id": 12345,
    "name": "My App",
    "payment_processing_bot_username": "CryptoBot",
    "supported_assets": [],
}
app = App.model_validate(app_data)
print(app.name)  # "My App"

# Из JSON
json_str = '{"invoice_id": 1, "amount": "100", "asset": "USDT", ...}'
invoice = Invoice.model_validate_json(json_str)

# Частичное создание (с дефолтными значениями)
balance = Balance(
    currency_code="USDT",
    available="100.50",
    onhold="0.00",
)

В таблице ниже собраны все публичные типы данных aiosend с их описанием и методами, которые их возвращают:

# Основные типы (доступны напрямую из aiosend)
from aiosend import (
    CryptoPayObject,     # базовый класс
    App,                 # информация о приложении
    Invoice,             # счёт
    Check,               # чек
    Transfer,            # перевод
    Balance,             # баланс
    Currency,            # валюта
    ExchangeRate,        # курс обмена
    AppStats,            # статистика
    Update,              # обновление
    Response,            # ответ API
    Error,               # ошибка API
)

# Enum'ы
from aiosend import (
    Asset,
    Fiat,
    CurrencyType,
    InvoiceStatus,
    CheckStatus,
    UpdateType,
    PaidBtnName,
)

Ниже приведена сравнительная таблица всех Pydantic-моделей aiosend с указанием количества полей и ключевых особенностей каждой:

Практический пример: обход всех моделей

import asyncio
from aiosend import CryptoPay
from aiosend.types import (
    App, Invoice, Check, Transfer,
    Balance, Currency, ExchangeRate, AppStats,
)

async def explore_all_types():
    cp = CryptoPay(token="TOKEN")

    # 1. App
    app: App = await cp.get_me()
    print(f"App: {app.name}")

    # 2. Invoice
    invoice: Invoice = await cp.create_invoice(
        amount=10, asset="USDT",
    )
    print(f"Invoice: #{invoice.invoice_id}")

    # 3. Balance
    balances: list[Balance] = await cp.get_balance()
    for b in balances:
        print(f"Balance: {b.currency_code}")

    # 4. Currency
    currencies: list[Currency] = await cp.get_currencies()
    for c in currencies:
        print(f"Currency: {c.currency_code}")

    # 5. ExchangeRate
    rates: list[ExchangeRate] = await cp.get_exchange_rates()
    for r in rates:
        print(f"Rate: {r.source}→{r.target} = {r.rate}")

    # 6. AppStats
    stats: AppStats = await cp.get_stats()
    print(f"Stats: volume={stats.volume}")

asyncio.run(explore_all_types())

В aiosend есть два разных понятия с похожими названиями: Enum Asset (перечисление криптовалют) и Pydantic-модель Asset (объект с данными о валюте). Не путай их! Pydantic-модель Asset возвращается в поле supported_assets объекта App и содержит подробную информацию о криптовалюте.

from aiosend import CryptoPay, Asset as AssetEnum
from aiosend.types import Asset as AssetModel

cp = CryptoPay(token="TOKEN")
app = await cp.get_me()

# Pydantic-модель Asset (из supported_assets)
for asset_model in app.supported_assets:
    print(f"{asset_model.asset_code}: {asset_model.asset_name}")
    print(f"  Decimals: {asset_model.decimals}")
    print(f"  Is blockchain: {asset_model.is_blockchain}")

# Enum Asset (для указания валюты в методах)
print(AssetEnum.USDT)       # Asset.USDT (Enum)
print(AssetEnum.USDT.value) # "USDT" (строка)

# Сравнение с Enum по коду
for asset_model in app.supported_assets:
    if asset_model.asset_code == AssetEnum.TON.value:
        print(f"Найден TON: {asset_model.asset_name}")