Урок 1.2 — Установка и настройка

aiosend требует Python 3.10 или выше (на момент написания курса — версия 3.0.x поддерживает Python 3.10+). Это связано с использованием современных возможностей языка: литеральные типы (Literal), синтаксис Union с | (PEP 604), match/case (PEP 634) и другие фичи, доступные только с Python 3.10+.

Проверь свою версию Python:

python --version
# или
python3 --version
# или
python3.12 --version

Если версия меньше 3.10, нужно обновить Python. Вот способы:

Самый простой и распространённый способ установки — через pip (стандартный менеджер пакетов Python). Рекомендуется устанавливать в виртуальное окружение:

# 1. Создаём директорию проекта
mkdir aiosend-course && cd aiosend-course

# 2. Создаём виртуальное окружение
python3 -m venv venv

# 3. Активируем виртуальное окружение
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 4. Устанавливаем aiosend
pip install -U aiosend

Флаг -U (--upgrade) означает «обновить до последней версии, если уже установлено». Это хорошая практика — всегда устанавливать с -U, чтобы получить последнюю версию.

aiosend потянет за собой зависимости:

aiosend>=3.0.0
python-dotenv>=1.0.0

Помимо классического pip, aiosend можно установить через современные менеджеры пакетов. Выбери тот, который используешь в повседневной работе:

После установки нужно убедиться, что всё прошло успешно. Есть несколько способов:

pip list | grep aiosend
# Ожидаемый вывод:
# aiosend        3.0.6

python -c "import aiosend; print(aiosend.__version__)"
# Ожидаемый вывод: 3.0.6

Успешный импорт aiosend без ошибок означает, что библиотека установлена корректно и все зависимости разрешены.

Для работы с Crypto Pay API нужен токен — уникальный ключ, который идентифицирует твоё приложение. Токен получается в два шага: сначала создаётся приложение в @CryptoBot, затем из него берётся токен.

Токен выглядит так: 1234:ABCDefghijklmnopQRSTuvwxyz1234567890. Он состоит из двух частей, разделённых двоеточием: числовой ID приложения и секретная строка.

Пошаговая инструкция для TESTNET (рекомендуется):

Для MAINNET (когда будешь готов к реальным платежам):

Процедура точно такая же, но в боте @CryptoBot (или @send). Внимание: в MAINNET используются реальные средства, поэтому не торопись туда переносить код — сначала всё протестируй в TESTNET.

Crypto Pay API существует в двух независимых сетях. Понимание разницы между ними — ключ к безопасной разработке:

После создания приложения в @CryptoTestnetBot (или @CryptoBot) важно настроить разрешения для методов. По умолчанию некоторые методы отключены по соображениям безопасности.

В настройках приложения (My Apps → выбери приложение → Security) ты увидишь следующие опции:

Для учебных целей рекомендую включить все три опции (Checks, Transfers, Webhooks) — это позволит тебе экспериментировать со всеми методами библиотеки без ограничений.

Хранить токен прямо в коде — плохая практика. Если ты закоммитишь токен в Git или опубликуешь код на GitHub, любой сможет им воспользоваться. Правильный подход — использовать переменные окружения или .env-файл.

Библиотека python-dotenv загружает переменные из .env-файла в os.environ. Это стандартный способ хранения секретов в Python-проектах.

# Crypto Pay API токен для TESTNET
CRYPTO_PAY_TOKEN=1234:ABCDefghijklmnopQRSTuvwxyz1234567890

# Опционально: сеть (aiosend определяет автоматически, но можно принудительно)
# CRYPTO_PAY_NETWORK=TESTNET

# Опционально: другие настройки
# DEBUG=True

Важно: никогда не коммить .env-файл в Git! Добавь его в .gitignore:

# .gitignore
.env
.env.local
venv/
__pycache__/
*.pyc

Установка python-dotenv:

pip install python-dotenv

Пример использования python-dotenv с aiosend:

import os
from dotenv import load_dotenv
from aiosend import CryptoPay

# Загружаем переменные из .env файла
load_dotenv()

# Получаем токен из переменной окружения
token = os.getenv("CRYPTO_PAY_TOKEN")

if not token:
    raise ValueError("Токен не найден! Проверь .env файл.")

# Создаём клиента
cp = CryptoPay(token=token)

# Всё готово к работе!
print(f"Токен загружен: {token[:8]}...")

Финальный шаг — проверить, что всё настроено правильно. Есть два способа: быстрая проверка через терминал (одна строка) и полноценный скрипт.

Способ 1: Быстрая проверка (однострочник):

# Просто импортируем библиотеку
python -c "import aiosend; print('aiosend', aiosend.__version__, '- OK')"

# Проверяем с токеном (замени на свой)
python -c "from aiosend import CryptoPay; cp = CryptoPay(token='ТВОЙ_ТОКЕН'); app = cp.sync.get_me(); print('App:', app.name, '| ID:', app.app_id)"

Способ 2: Полноценный скрипт:

import os
from dotenv import load_dotenv
from aiosend import CryptoPay
from aiosend.errors import APIError, CryptoPayError

# Загружаем .env
load_dotenv()

# Получаем токен
token = os.getenv("CRYPTO_PAY_TOKEN")

if not token:
    print("❌ Ошибка: CRYPTO_PAY_TOKEN не найден в .env файле!")
    print("Создай файл .env и добавь строку: CRYPTO_PAY_TOKEN=твой_токен")
    exit(1)

print(f"🔑 Токен: {token[:10]}...{token[-5:]}")
print()

try:
    # Пробуем подключиться (синхронно)
    cp = CryptoPay(token=token)
    app = cp.sync.get_me()

    print("✅ Подключение успешно!")
    print(f"   Имя приложения: {app.name}")
    print(f"   ID приложения: {app.app_id}")
    print(f"   Платёжный бот: @{app.payment_processing_bot_username}")

except APIError as e:
    print(f"❌ Ошибка API (код {e.code}): {e.name}")
except CryptoPayError as e:
    print(f"❌ Ошибка aiosend: {e}")
except Exception as e:
    print(f"❌ Неожиданная ошибка: {e}")

Рекомендую организовать проекты по урокам в единой структуре. Это поможет не запутаться в файлах:

aiosend-course/
├── module-01/                    # Модуль 1: Введение
│   ├── lesson-1.1/               # Урок 1.1
│   ├── lesson-1.2/               # Урок 1.2
│   │   ├── .env                  # Токен (НЕ КОММИТИТЬ!)
│   │   ├── .gitignore            # gitignore
│   │   ├── check_connection.py   # Скрипт проверки
│   │   ├── main.py               # Основной скрипт
│   │   └── requirements.txt      # Зависимости
│   └── lesson-1.3/               # Урок 1.3
├── module-02/                    # Модуль 2: Инвойсы
├── module-03/                    # Модуль 3: Чеки
├── ...
├── venv/                         # Виртуальное окружение (не коммитить)
├── .gitignore                    # Общий .gitignore
└── README.md                     # Описание проекта (опционально)

Для каждого урока можно создавать отдельную папку со своими файлами. Это позволит изолировать эксперименты и не сломать предыдущие работающие примеры.

Пройди по этому чек-листу, чтобы убедиться, что всё настроено правильно: