Tksbrokerapi

Дайджест

Теперь можно обогащать сырые данные по облигациям большим числом полей и значений, выгружать их в XLSX-формате и pandas dataframe! Это пригодится датасайнтистам и биржевым аналитикам (смотрите описание ключа `--bonds-xlsx`). С помощью этих данных можно построить полный календарь выплат по облигациям (ключ `--calendar`).

Для скачиваемых с сервера или загружаемых из файла исторических свечей теперь можно построить интерактивные или простые графики (ключ `--render-chart`). Если вам нужны сырые данные с сервера по всем инструментам, их можно сохранить в формате XLSX с ключом `--list-xlsx`.

А также, теперь можно узнать: все данные по своему аккаунту, включая `accounId` (команда `--user-info` или `--account`) и лимиты на вывод доступных средств (команда `--limits`).

Новая функциональность

* [15](https://github.com/Tim55667757/TKSBrokerAPI/issues/15) Реализованы методы: `RequestLimits()` для запроса сырых данных по лимитам для пользователя на вывод средств, `OverviewLimits()` для отображения табличных данных и ключ `--limits` (`--withdrawal-limits`, `-w`) для запроса и отображения лимитов в консоли.
* [6](https://github.com/Tim55667757/TKSBrokerAPI/issues/6) При запуске с ключом `--history` добавлена возможность указать дополнительный ключ `--render-chart` и сгенерировать интерактивный или не интерактивный свечные графики, при помощи библиотеки [`PriceGenerator`](https://tim55667757.github.io/PriceGenerator). Аналогично можно построить графики для ранее сохранённых csv-файлов с историей свечей. Для этого нужно указать ключ `--render-chart` вместе с новым ключом для загрузки данных из файла: `--load-history`.
* [46](https://github.com/Tim55667757/TKSBrokerAPI/issues/46) Реализован ключ `--list-xlsx` (или `-x`), который возвращает необработанные данные по всем доступным для данного аккаунта инструментам, аналогичные данным из `dump.json`, но сохраненные в формате XLSX, для дальнейшего использования дата-сайнтистами или биржевыми аналитиками, по умолчанию используется `dump.xlsx`. Также был разработан новый метод `DumpInstrumentsAsXLSX()` который конвертирует сырые данные по инструментам в формат XLSX.
* [11](https://github.com/Tim55667757/TKSBrokerAPI/issues/11) Добавлен ключ `--user-info` (`-u`), который выводит данные, связанные с аккаунтом, привязанным к текущему токену: доступную информацию о пользователе и его аккаунтах, права на операции, лимиты для маржинальной торговли. Также добавлен ключ `--account` (`--accounts`, `-a`), который выводит простую табличку, содержащую только аккаунты пользователя.
* [10](https://github.com/Tim55667757/TKSBrokerAPI/issues/10) При запросе информации об облигациях (с ключом `--info` или `-i`), теперь рассчитывается и отображается больше данных: график выплат по облигациям, общее количество выплат и уже погашенные купоны, купонный доход в процентах годовых (средняя купонная ежедневная доходность * 365), текущая доходность в процентах годовых (зависит от цены и количества оставшихся невыплаченных купонов, считается как средняя текущая ежедневная доходность * 365), НКД и размер купона. Для запроса нужной информации реализованы методы `RequestBondCoupons()` (возвращает словарь обработанных данных, полученных с сервера) и `ExtendBondsData()` (возвращает обогащённый pandas dataframe, содержащий больше информации об облигациях). Метод `ShowInstrumentInfo()` был доработан, для отображения большего количества информации по облигациям и календаря выплат. Для выгрузки обогащённых данных по облигациям в формат XLSX-файла (по умолчанию `ext-bonds.xlsx`), теперь можно использовать ключ `--bonds-xlsx` (`-b`).
* [63](https://github.com/Tim55667757/TKSBrokerAPI/issues/63) Реализован метод `CreateBondsCalendar()`, генерирующий pandas dataframe с общим календарём выплат по указанным или всем облигациям. Метод `ShowBondsCalendar()` отображает календарь в консоли и сохраняет в файл, `calendar.md` по умолчанию в формате markdown. Для запроса календаря выплат нужно использовать ключ `--calendar` (`-c`), при этом также сохраняется таблица в формате XLSX, в файл по умолчанию `calendar.xlsx`. В случае, если календарь строится более чем для одной облигации, то платежи в один и тот же месяц группируются.

Улучшения

* [59](https://github.com/Tim55667757/TKSBrokerAPI/issues/59) TKSBrokerAPI билд-номер теперь печатается в логах, а также его можно узнать набрав команду `--version` (или `--ver`).
* [47](https://github.com/Tim55667757/TKSBrokerAPI/issues/47) `iList` поле более неактуально из-за использования локального дампа `dump.json`, в котором автоматически обновляется список доступных для торговли инструментов, поэтому поле удалено из класса `TinkoffBrokerServer()`.
* [9](https://github.com/Tim55667757/TKSBrokerAPI/issues/9) В метод `ShowInstrumentInfo()` добавлена информация о текущем статусе торгов по запрашиваемому инструменту. Реализован дополнительный метод `RequestTradingStatus()` для запроса статуса торгов по инструменту. Добавлены флаги: `buyAvailableFlag`, `sellAvailableFlag`, `shortEnabledFlag`, `limitOrderAvailableFlag`, `marketOrderAvailableFlag` и `apiTradeAvailableFlag`. В рамках этой же задачи реализована задача [#37](https://github.com/Tim55667757/TKSBrokerAPI/issues/37): добавлена возможность сохранения информации по инструменту в файл, заданный ключом `--output`, по умолчанию `info.md`.
* [64](https://github.com/Tim55667757/TKSBrokerAPI/issues/64) ВНИМАНИЕ! Выполнен рефакторинг во многих методах. Все параметры, которые отвечают за отображение дополнительной информации в консоли: `showPrice`, `showPrices`, `printInfo`, `showInfo`, `showInstruments`, `showResults`, `showStatistics`, `printDeals`, `printCandles`, `showLimits`, `showAccounts` — были заменены переменной с простым именем`show`.
* [65](https://github.com/Tim55667757/TKSBrokerAPI/issues/65) ВНИМАНИЕ! Выполнен рефакторинг во многих методах. Все `overview` параметры заменены переменной `portfolio`.
* Отключены повторы для 4xx сетевых ошибок, повторы оставлены только для 5xx ошибок. Это связано с тем, что нет смысла ожидать появления отсутствующих данных на сервере, например, в случае неверного указания ресурса.
* Теперь при запуске метода `SendAPIRequest(debug=True)` в логи выводится больше отладочной информации, например, параметры запроса и ответа сервера, а также их хедеры.
* Добавлено ожидание между сетевыми запросами, в случае достижения лимита по количеству запросов. Лимит определяется по значению заголовка ответа `"x-ratelimit-remaining": "0"`, а количество секунд ожидания определяется значением заголовка `x-ratelimit-reset`, например, `"x-ratelimit-reset": "15"`, что означает ожидание 15 секунд до следующего запроса. Это позволило значительно уменьшить количество сетевых ошибок, связанных с ожиданием для большого числа запросов к API сервера.
* Хедер `"x-app-name": "Tim55667757.TKSBrokerAPI"` был добавлен к каждому API-запросу, для идентификации фреймворка TKSBrokerAPI.

Баг-фиксы

* Исправлена ошибка `NoneType object has no attribute ...` в случае, если ключ `--history` использовался без указания каких-либо параметров.
* [71](https://github.com/Tim55667757/TKSBrokerAPI/issues/71) Пришлось сделать быстрый хак, чтобы избежать проблем в секциях статистики `Portfolio distribution by currencies` и `Portfolio distribution by countries`: принудительно добавлена валюта `rub` и страна `"[RU] Российская Федерация"`, перед расчётом статистики.

Новая функциональность

* [5](https://github.com/Tim55667757/TKSBrokerAPI/issues/5) Добавлена возможность скачивания истории цен по инструменту с поддержкой докачки по ключу `--history`. Также ключ `--interval` позволяет указать временной интервал для скачиваемых ценовых свечей в формате OHLCV. Ключ `--only-missing` позволяет докачать только последние свечи, сохранённые в файле, заданном через `--output`. Ключ `--csv-sep` задаёт разделитель между данными в csv-файлах. History returned between two given dates: `start` and `end`. `1970-01-01` минимальная дата в прошлом, начиная с которой брокер даёт скачать историю. Внимание! Брокер использует ISO UTC формат времени.

Улучшения

* [17](https://github.com/Tim55667757/TKSBrokerAPI/issues/17) Оптимизирован запрос цен для инструментов и убраны повторные запросы цены для одного и того же инструмента при запуске с ключом `--prices` или вызове метода `Overview()`. За счёт удаления дублирующих запросов немного повысилась скорость работы.
* [43](https://github.com/Tim55667757/TKSBrokerAPI/issues/43) Добавлены новые ключи для уменьшения информации в методе `Overview()`: ключ `--overview-positions` показывает только открытые позиции, без всего остального, ключ `--overview-digest` показывает короткий дайджест состояния портфеля, ключ `--overview-analytics` показывает только раздел аналитики и распределения портфеля по различным категориям, ключ `--overview-orders` показывает только секцию открытых лимитных и стоп ордеров.
* [44](https://github.com/Tim55667757/TKSBrokerAPI/issues/44) Все markdown-таблицы приведены к стандартному виду, включая отрисовку правой части таблиц.

Баг-фиксы

* [18](https://github.com/Tim55667757/TKSBrokerAPI/issues/18) Добавлена обработка ошибки `raise JSONDecodeError("Expecting value", s, err.value) from None`. Теперь отображается сообщение: `Check you Internet connection! Failed to establish a new connection to broker server!` и выводится путь до файла с дебажными логами.
* [16](https://github.com/Tim55667757/TKSBrokerAPI/issues/16) Исправлено отображение дробных чисел с первым нулём после десятичной точки, в случаях, когда вместо `1.0` выводилось `1.`.
* [38](https://github.com/Tim55667757/TKSBrokerAPI/issues/38) Исправлено отображение дробной части цен при запросе ETF.

Новая функциональность

* [13](https://github.com/Tim55667757/TKSBrokerAPI/issues/13) Для уменьшения количества запросов к серверу, добавлена возможность кэширования данных по биржевым инструментам. Кэш используется по умолчанию при первичной инициализации класса `TinkoffBrokerServer`, но это действие можно отменить через переменную класса `useCache=False` или используя ключ `--no-cache` в консоли. Добавлен метод `DumpInstruments()`, с помощью которого можно создать дамп данных с сервера. В класс `TinkoffBrokerServer` также добавлена переменная `iListDumpFile` (путь до кэша, по умолчанию `dump.json`). Кэш автоматически обновляется, если идёт другой день, чем день последнего изменения файла `dump.json`. Примечание: все даты используются в UTC-формате.
* [7](https://github.com/Tim55667757/TKSBrokerAPI/issues/7) Добавлена возможность поиска инструмента по части названия, тикера или FIGI с помощью ключа `--search` (или `-s`). Реализован метод для поиска `SearchInstruments()`, которому на вход можно передать поисковый паттерн: часть слова или строку с регулярным выражением. В качестве результата метод возвращает словарь словарей, похожий на переменную `iList`, но содержащий только найденные инструменты ([примеры](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md#Найти-инструмент)).
* Был добавлен новый метод `IsInPortfolio()`. Он проверяет на наличие инструмента в портфеле пользователя. Инструмент должен быть задан через `self.ticker` (приоритетно) или через `self.figi`. Метод возвращает `True`, если портфель содержит открытую позицию по инструменту, в противном случае возвращает `False`.
* Был добавлен новый метод `GetInstrumentFromPortfolio()`. Он возвращает данные по инструменту, если он есть в портфеле пользователя. Инструмент должен быть задан через `self.ticker` (приоритетно) или через `self.figi`.

Улучшения

* [12](https://github.com/Tim55667757/TKSBrokerAPI/issues/12) В общую информацию о состоянии портфеля (ключ `--overview` или `-o`), добавлен раздел "Распределение портфеля по странам" ([пример](https://github.com/Tim55667757/TKSBrokerAPI#получить-текущий-портфель-пользователя-и-статистику-распределения-активов)).
* [8](https://github.com/Tim55667757/TKSBrokerAPI/issues/8) Добавлен ключ `--no-cancelled` и переменная `showCancelled` в методе `Deals()`, чтобы регулировать отображение информации об отменённых операциях при использовании ключа `--deals` (или `-d`). Изменено имя файла с отчётом по умолчанию: вместо `report.md` теперь используется `deals.md`.
* [42](https://github.com/Tim55667757/TKSBrokerAPI/issues/42) Добавлен [пример](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md#Пример-реализации-абстрактного-сценария) реализации абстрактного торгового сценария.
* В секцию `stat` результатов, выдаваемых методом `Overview()`, было добавлено поле `funds`. Теперь в нём хранится словарь доступных для торговли средств по каждой валюте (всего средств - заблокированные средства), например, `{"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}`.

Баг-фиксы

* Исправлен тип данных для облигаций (неправильно: `iJSON["type"] == "Bond"`, правильно: `iJSON["type"] == "Bonds"`).
* Исправлена ошибка с JSON-декодером: `TypeError: JSONDecoder.__init__() got an unexpected keyword argument 'encoding'`. Ошибка была из-за изменений в Python 3.9: аргумент `encoding` был удалён. Смотрите: https://docs.python.org/3/library/json.html#json.loads
* Исправлена ошибка с неверным расчётом оставшихся свободных средств в рублях: `Overview()["stat"]["funds"]["rub"]`.

Новая функциональность

* Лицензия изменена с MIT на [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
* **Важно!** Восстановлена функциональность большей части методов, входящих в `TKSBrokerAPI` v1.0, кроме открытия сетки ордеров и скачивания исторических данных (будут добавлены в следующих релизах). Теперь все методы работают с новым Open API: https://tinkoff.github.io/investAPI/swagger-ui/
* **Важно!** модуль `TKSBrokerAPI` вынесен в опенсорс, дальнейшая разработка продолжается только там: https://github.com/Tim55667757/TKSBrokerAPI (анонсы и релиз-ноты — там же).
* **Важно!** Версия Tinkoff Invest API, поддерживаемая библиотекой `TKSBrokerAPI`, теперь v2 и без обратной совместимости.
* **Важно!** Все внутренние переменные времени переведены в ISO UTC формат с `Z` (Zulu time) на конце строки. Пример: `1961-04-12T06:07:00.123456Z`. Локальное время больше не используется. Это нужно для избежания путаницы со временем Tinkoff Invest API, которое использует UTС Z-нотацию.
* [1](https://github.com/Tim55667757/TKSBrokerAPI/issues/1) Добавлены основные разделы документации в [`README.md`](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_RU.md) и примеры работы в консоли, а также API-документация на модуль [`TKSBrokerAPI`](https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html).
* [2](https://github.com/Tim55667757/TKSBrokerAPI/issues/2) Добавлен шаг `PDocBuilder` для автоматической сборки документации на базе `pdoc` для методов модуля `TKSBrokerAPI`.
* [3](https://github.com/Tim55667757/TKSBrokerAPI/issues/3) Настроен базовый CI для релизного цикла: шаг запуска юнит-тестов и запуск сборки пакета. Реализован CD для релизного цикла: для фича-веток собираются dev-сборки, из релизных веток и master — собираются релизные пакеты, которые затем публикуются в PyPI. Пример успешной сборки: [tksbrokerapi-1.2.dev39](https://app.travis-ci.com/github/Tim55667757/TKSBrokerAPI/builds/253552987) и [PyPI-пакет](https://pypi.org/project/tksbrokerapi/1.2.dev39/).
* [4](https://github.com/Tim55667757/TKSBrokerAPI/issues/4) Добавлены простейшие юнит-тесты на некоторые методы, либо заглушки.
* Добавлен раздел аналитики в `Overview()` метод. Показывается распределение инструментов по классам, компаниям, секторам и валютам активов.
* Показывается расширенная информация по инструменту для ключа `--info` в зависимости от типа инструмента (валюта, акция, облигация, фонд или фьючерс).
* Добавлены ключи `--close-order`, `--close-orders`, `--close-trade` и `--close-trades`. При их помощи можно отменить один или несколько ордеров по ID или закрыть сделки по инструментам, зная их тикеры.
* Реализованы методы закрытия ордеров и позиций: `ClosePositions()`, `CloseAllPositions()`, `CloseOrders()`, `CloseAllOrders()` и `CloseAll()`.
* Реализованы методы открытия лимитных и стоп-ордеров: `Order()`, `BuyLimit()`, `BuyStop()`, `SellLimit()` и `SellStop()`.
* Реализованы методы открытия и закрытия позиций по инструментам: `Trade()`, `CloseTrades()`, `CloseAllTrades()`, `Buy()`, `Sell()` и исправлен метод `CloseAll()` при закрытии инструментов.

Улучшения

* **Важно!** За счет оптимизации алгоритмов, рефакторинга кода и использования модуля `multiprocessing` удалось ускорить скачивание инструментов при их первичном листинге на 40-60%.
* **Важно!** Включено логирование с ротацией от 5Мб в файл по-умолчанию `TKSBrokerAPI.log`. Оптимизирован модуль логирования. Уменьшено количество ненужных оповещений. По умолчанию debug-логи печатаются только в лог-файл, а в консоль выводятся info-логи. Изменить уровень логирования можно ключами: `--debug-level`, `--verbosity` или `-v`.
* Все перечислимые типы данных и константы вынесены в файл `TKSEnums.py`.
* Добавлены алиасы для USD, EUR, GBP, CHF, CNY, HKD, TRY — теперь их можно использовать вместо тикеров.
* Портфолио клиента, информация по отдельному инструменту, список доступных инструментов для торговли и история клиентских операций теперь отображаются в markdown-формате.
* Для класса `TinkoffBrokerServer()` теперь можно задавать параметр `token` как через переменную при инициализации класса, так и при установке переменной окружения `TKS_API_TOKEN`. Если параметр `token` задан при инициализации класса, то он считается приоритетным.
* Для класса `TinkoffBrokerServer()` теперь можно задавать параметр `accountId` как через переменную при инициализации класса, так и при установке переменной окружения `TKS_ACCOUNT_ID`. Если параметр `accountId` задан при инициализации класса, то он считается приоритетным. Узнать номер своего аккаунта можно в любом брокерском отчёте, там будет указан номер договора, он же является вашим `accountId`.
* Обновлены все методы, связанные с отображением в консоли данных с биржи, после перехода у брокера Tinkoff Invest API на версию v2.
* Метод `Overview()` теперь показывает больше информации по отложенным и стоп-ордерам.
* Метод `SendAPIRequest()` теперь показывает в логах информацию от сервера при всех 4xx и 5xx ошибках.
* Из метода `Overview()` вынесены в отдельные методы `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders` и `RequestStopOrders()` — операции по запросу портфеля, открытых позиций и ордеров пользователя.
* При помощи метода `CloseOrders()` теперь можно закрывать и биржевые отложенные (pending) ордера, и стоп-ордера. Достаточно указать ID или список ID.
* Добавлено отображение разницы в % между предыдущей и текущей ценой закрытия инструмента во все таблицы, где это востребовано.
* [22](https://github.com/Tim55667757/TKSBrokerAPI/issues/22) Ключи `--open-trade` и `--open-order` заменены ключами `--trade` и `--order`, потому что у них были слишком длинные имена. Методы `OpenOrder()` и `OpenTrade()` заменены методами `Order()` и `Trade()`.
* Статический метод `GetDatesAsString()` вынесен за пределы класса `TinkoffBrokerServer()`.
* Переменная `instrumentsList` для простоты переименована в `iList`.
* Метод `MDInfo()` переименован в `ShowInstrumentInfo()` (по аналогии с уже имеющимся `ShowInstrumentsInfo()`).

Баг-фиксы

* **Важно!** Проведён рефакторинг и исправлено множество ошибок в методах, связанные с переходом Tinkoff Invest API на версию v2 и сменой типов данных.
* Исправлен счётчик в логе в строке "Pairs (tickers, timeframes) count: [XXX]"
* Исправлена ошибка в методе `Deals()`: в случае, когда конечная дата не указана теперь берётся текущая дата.
* Исправлен баг с отображением истории операций, если за указанный период были дивидендные выплаты.
* Исправлен баг, когда сервер возвращал пустую комиссию.
* [26](https://github.com/Tim55667757/TKSBrokerAPI/issues/26) Исправлена ошибка с неправильным результатом для дробных чисел: `FloatToNano(number=0.05)`.
* [34](https://github.com/Tim55667757/TKSBrokerAPI/issues/34) Исправлена ошибка с `KeyError: 'asks'`, когда от сервера не приходит ответ с данными по текущим ценам.
* [32](https://github.com/Tim55667757/TKSBrokerAPI/issues/32) Исправлены ошибки при попытке закрытия всех ордеров с ключом `--close-all orders`. Ошибка возникла из-за неправильной обработки формата входной строки в одном из отладочных сообщений. Убраны лишние сообщения, а вместе с ними и ошибка форматирования.

Ретроспектива

Первый прототип [TKSBrokerAPI](https://github.com/Tim55667757/TKSBrokerAPI) — python API над REST-протоколом для [Tinkoff Invest API](https://tinkoff.github.io/investAPI/swagger-ui/) — включал в себя основные возможности для работы с биржей:
* получать цены в стакане (DOM — Depth of Market) для выбранного инструмента;
* получать список всех инструментов, их названий, тикеров и FIGI;
* просматривать текущее состояние портфеля и его стоимость;
* получать полную брокерскую информацию по инструменту, зная его тикер или FIGI;
* получать таблицу текущих цен для списка инструментов;
* получать информацию по историческим ценам инструментов, доступных через Tinkoff Broker, и сохранять их в csv-файлы;
* загружать исторические ценовые данные из csv-файлов и отображать их на интерактивном графике или в консоли;
* открывать и закрывать лимитные ордера (биржевые заявки или однодневные ордера, отображающиеся в стакане DOM);
* создавать биржевые заявки (рыночные ордера исполняющиеся по текущим ценам в стакане DOM);
* открывать сетку лимитных ордеров с некоторым шагом;
* закрывать все ордера и активные заявки сразу или только определённого типа: акции, облигации, фонды;
* создавать отчёт по операциям за указанный период.

Затем, примерно с середины и до конца 2021 года, разработчики Tinkoff активно изменяли свой REST-протокол. Модуль `TKSBrokerAPI` стал неработоспособным. Но в течение весны-лета 2022 года удалось восстановить и даже расширить большинство его функций, переписать код на работу с новым Tinkoff Open API REST-протоколом, выложить библиотеку в опенсорс и настроить релизный цикл её выпуска.

[](https://yoomoney.ru/quickpay/shop-widget?writer=seller&targets=%D0%94%D0%BE%D0%BD%D0%B0%D1%82%20(%D0%BF%D0%BE%D0%B4%D0%B0%D1%80%D0%BE%D0%BA)%20%D0%B4%D0%BB%D1%8F%20%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%BE%D0%B2%20%D0%BF%D1%80%D0%BE%D0%B5%D0%BA%D1%82%D0%B0%20TKSBrokerAPI&default-sum=999&button-text=13&payment-type-choice=on&successURL=https%3A%2F%2Ftim55667757.github.io%2FTKSBrokerAPI%2F&quickpay=shop&account=410015019068268)