https://github.com/empenoso/backtrader-quickstart-template
A modular and flexible backtesting framework for trading strategies in Python using Backtrader.
https://github.com/empenoso/backtrader-quickstart-template
backtrader backtrader-plotting
Last synced: 8 months ago
JSON representation
A modular and flexible backtesting framework for trading strategies in Python using Backtrader.
- Host: GitHub
- URL: https://github.com/empenoso/backtrader-quickstart-template
- Owner: empenoso
- License: mit
- Created: 2025-08-13T06:19:52.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-25T15:10:01.000Z (9 months ago)
- Last Synced: 2025-08-25T16:12:46.952Z (9 months ago)
- Topics: backtrader, backtrader-plotting
- Language: Python
- Homepage:
- Size: 4.43 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Backtrader Quickstart Template: народный фреймворк для алготрейдинга
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
Готовый шаблон для быстрого старта в алгоритмической торговле на Python с использованием библиотеки Backtrader. Проект создан, чтобы частные инвесторы и разработчики могли сосредоточиться на главном — на разработке и тестировании стратегий, а не на борьбе с инфраструктурой.
---
## 🎯 Философия проекта
В мире алгоритмической торговли доминируют крупные фонды с их колоссальными ресурсами. Этот проект — попытка создать мощный и доступный инструмент для частных инвесторов. Идея проста: больше не нужно зависеть от проприетарных платформ или писать с нуля сложную инфраструктуру для тестирования каждой новой идеи.
Цель — построить открытый стандарт для алготрейдинга на базе **Backtrader**, заточенный под реалии российского рынка. Мы создаём систему, которая была бы так же удобна, как TradingView, но с гибкостью и мощью Python. Чтобы каждый, кто заинтересован в алгоритмической торговле, мог без усилий внедрить свою стратегию, протестировать её и получить наглядные результаты.
Этот репозиторий — не просто набор скриптов, а призыв к действию. Давайте объединим усилия и создадим по-настоящему «народный» Backtrader!
## ✨ Ключевые особенности
* **Максимальная модульность**: одна стратегия — один файл. Никаких сложных зависимостей. Просто добавьте свой `.py` файл в папку `strategies`, и система автоматически его подхватит.
* **Простое управление**: главный файл `main.py` — это единая панель управления. Выбирайте режим, стратегию и период тестирования в одном месте.
* **Два режима работы**:
* `BACKTEST`: быстрая проверка гипотезы на исторических данных.
* `OPTIMIZATION`: автоматический подбор лучших параметров для вашей стратегии.
* **Информативные отчеты**: по итогам каждого теста генерируется подробный текстовый отчет с ключевыми метриками (прибыль, просадка, профит-фактор, коэффициент Сортино) и наглядные графики.
* **Визуализация оптимизации**: для режима оптимизации по двум параметрам строится тепловая карта, которая помогает визуально определить самые прибыльные и устойчивые зоны.
* **Адаптация под портфель**: шаблон изначально спроектирован для тестирования стратегий на нескольких акциях одновременно и корректно обрабатывает асинхронные исторические данные разной длины.
* **Готовность к реальной торговле**: архитектура закладывает основу для легкого перехода от бэктестинга к реальной торговле через API российских брокеров (Тинькофф, Финам, Алор и др.).
## 📂 Структура проекта
```
.
├── data-connector/Data/Tinkoff/ # Папка для ваших исторических данных (CSV/TXT)
│ └── TQBR.SBER_D1.txt
├── reports/ # Сюда сохраняются все отчеты и графики
│ └── SmaCrossStrategy_test_... .txt
├── strategies/ # Здесь живут ваши торговые стратегии
│ ├── __init__.py # 🚀 Автоматически загружает все стратегии из этой папки
│ ├── base_strategy.py # 🧱 Базовый класс-шаблон для всех стратегий
│ └── sma_cross_strategy.py # 📈 Пример готовой стратегии
├── utils/ # Вспомогательные модули
│ ├── custom_csv.py # 📈 Загрузчик для CSV-файлов нестандартного формата
│ ├── report_generator.py # 📊 Генератор текстовых отчетов и тепловых карт
│ └── sortino_analyzer.py # 📉 Анализатор для расчета коэффициента Сортино
├── main.py # 🚀 Главный файл для запуска тестов и оптимизации
├── requirements.txt # Список необходимых библиотек
└── install_requirements.bat # Скрипт для быстрой установки зависимостей (для Windows)
```
## 🚀 Быстрый старт
### 1. Клонирование репозитория
```bash
git clone https://github.com/empenoso/backtrader-quickstart-template.git
cd backtrader-quickstart-template
```
### 2. Установка зависимостей
Запустите `install_requirements.bat` (для Windows) или выполните команду в терминале:
```bash
pip install -r requirements.txt
```
### 3. Добавление исторических данных
Поместите ваши файлы с историческими данными в формате `.txt` или `.csv` в папку `data-connector/Data/`.
Вы можете использовать данные, полученные из любых источников, включая коннекторы **FinamPy**, **AlorPy** или **TinkoffPy**. Папка `Tinkoff` в пути `data-connector/Data/Tinkoff/` используется для примера, вы можете создавать любую удобную для вас структуру.
Главное — убедиться, что:
1. В `main.py` переменная `DATA_DIR` указывает на верную папку.
2. Формат ваших данных соответствует загрузчику `utils/custom_csv.py`. По умолчанию он настроен на текстовые файлы с разделителем-табуляцией и форматом даты `ДД.ММ.ГГГГ ЧЧ:ММ`. При необходимости вы легко можете его адаптировать.
### 4. Настройка и запуск
Откройте файл `main.py` и настройте "Главную панель управления":
```python
# 1. ВЫБЕРИТЕ РЕЖИМ: 'BACKTEST' или 'OPTIMIZATION'
MODE = 'BACKTEST'
# 2. ВЫБЕРИТЕ СТРАТЕГИЮ из загруженных
STRATEGY_TO_RUN = 'SmaCrossStrategy'
# 3. НАСТРОЙКИ ПЕРИОДА ТЕСТИРОВАНИЯ
FROM_DATE = datetime.datetime(2018, 1, 1)
TO_DATE = datetime.datetime(2025, 8, 12)
```
После настройки просто запустите скрипт:
```bash
python main.py
```
## 🛠️ Как использовать
### Создание новой стратегии
1. Создайте новый Python-файл в папке `strategies` (например, `my_super_strategy.py`).
2. Внутри файла создайте класс, унаследованный от `BaseStrategy`.
3. Определите обязательные атрибуты: `tickers`, `start_cash`, `commission` и параметры для оптимизации `opt_params`.
4. Реализуйте основную торговую логику в методе `next()`.
Система автоматически обнаружит и загрузит вашу новую стратегию при следующем запуске.
### Анализ результатов
Все результаты сохраняются в папку `reports`.
* **Для бэктеста** создается текстовый отчет с полной статистикой и отдельные `.png` файлы с графиками для каждого тикера.
Пример отчета:
```
--- ОТЧЕТ ПО БЭКТЕСТУ СТРАТЕГИИ: SmaCrossStrategy ---
Бумаги в тесте: ['SBER', 'VTBR', 'GAZP', 'LKOH', 'NVTK', 'YDEX', 'T']
Параметры: {'fast_ma': 20, 'slow_ma': 50, ...}
Период тестирования: с 01.01.2018 по 12.08.2025
--- РЕЗУЛЬТАТЫ ---
Итоговая прибыль/убыток: 252 713.12 [50.54%]
Доходность (годовых): 5.44%
Результат 'Купил и держал': 205 648.56 [41.13%]
Максимальная просадка: 67 124.98 [13.42%]
Всего сделок: 128
Процент прибыльных сделок: 41.41% (53 из 128)
Фактор прибыли: 2.13
Коэффициент Сортино: 1.08
--------------------------------------------------
```
* **Для оптимизации** создается текстовый отчет со всеми комбинациями параметров и **тепловая карта** (`.png`), на которой цветом показана эффективность (профит-фактор) каждой комбинации.
## 🤝 Как помочь проекту?
Этот шаблон — лишь основа. Чтобы он стал по-настоящему удобным и «народным», ему нужна помощь сообщества.
Что можно сделать:
* **Улучшить визуализацию**: стандартный `cerebro.plot()` плохо справляется с портфелем из десятка акций. В `main.py` уже есть наработки по сохранению графиков в отдельные файлы, но это решение можно усовершенствовать.
* **Добавить новые метрики**: предложите новые анализаторы или улучшите существующие отчеты.
* **Предложить свои идеи**: возможно, вы видите архитектуру иначе? Знаете, как сделать управление стратегиями еще удобнее? Создайте `Issue` и давайте обсудим!
* **Добавить примеры стратегий**: поделитесь своими наработками с сообществом.
* **Интеграция с брокерами**: помогите с реализацией готовых модулей для подключения к API российских брокеров.
Если вы разделяете идею создания «народного Backtrader» — подключайтесь! Любые улучшения, замечания и Pull Request'ы приветствуются.
Автор: Михаил Шардин
[🔗 Моя онлайн-визитка](https://shardin.name/?utm_source=github)
[📢 Telegram «Умный Дом Инвестора»](https://t.me/+asaEcPax8o41MjQy)