# TKSBrokerAPI — список релизных изменений

*[Нечёткие технологии](https://fuzzy-technologies.github.io/)*<br>
<a href="https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md" target="_blank"><img src="https://github.com/Tim55667757/TKSBrokerAPI/blob/develop/docs/media/TKSBrokerAPI-Logo.png?raw=true" alt="TKSBrokerAPI-Logo" width="780" /></a><br>
**T**echnologies · **K**nowledge · **S**cience

[![gift](https://badgen.net/badge/gift/donate/green)](https://yoomoney.ru/fundraise/4WOyAgNgb7M.230111)

* 🇺🇸 [Релиз-ноты на английском (see release notes in english here)](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/CHANGELOG_EN.md)
  * 💡 [Все запланированные релизы и вошедшие в них фичи](https://github.com/Tim55667757/TKSBrokerAPI/milestones?direction=desc&sort=title&state=open)
  * 📂 [Все открытые задачи в беклоге](https://github.com/Tim55667757/TKSBrokerAPI/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)
* 📚 [Документация и примеры](https://tim55667757.github.io/TKSBrokerAPI)
* 🎁 Поддержать проект: [410015019068268](https://yoomoney.ru/fundraise/4WOyAgNgb7M.230111)


### [release-1.6 (2025-05-20)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/release-1.6) — опубликована

##### Дайджест

Добавлен быстрый алгоритм оценки вероятности достижения целевой цены на основе волатильности и доходности. Модель учитывает дрейф, использует Байесовскую агрегацию и корректируется по фазе и хаосу, позволяя фильтровать сигналы по степени доверия.

Реализована быстрая фильтрация аномалий методом Хампеля с ускоренной функцией и примерами использования. Добавлена нечёткая шкала для интерпретации вероятностей в терминах `{Min, Low, Med, High, Max}`, что упрощает отбор сигналов.

Существенно улучшена инфраструктура: появилась многопоточная загрузка истории с докачкой, автообновление по крону `--history-auto-updater`, реализован централизованный Rate Limiter в `SendAPIRequest()` и CI/CD-сборка Docker-образов. Это ускорило работу с брокером и повысило стабильность.

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

* [#119](https://github.com/Tim55667757/TKSBrokerAPI/issues/119) Реализован новый пример использования платформы TKSBrokerAPI: [Anomaly Volumes Detector](https://github.com/Tim55667757/TKSBrokerAPI/tree/develop/docs/examples/AnomalyVolumesDetector) — это простой Телеграм бот для поиска и анализа аномалий в объёмах спроса и предложения покупателей и продавцов.
* [#111](https://github.com/Tim55667757/TKSBrokerAPI/issues/111) В модуль TradeRoutines добавлен метод `CalculateLotsForDeal()`. Он помогает определить нужное количество лотов инструмента при открытии позиции.
* [#112](https://github.com/Tim55667757/TKSBrokerAPI/issues/112) В модуль TradeRoutines добавлен метод `HampelFilter()`. Он позволяет обнаружить аномалию ("выброс", нестандартное значение, отклонение от нормы) среди значений любого числового ряда, используя функцию фильтрации Хампеля. Фильтр Хампеля обнаруживает аномалии на основе скользящего окна и подсчёта разницы между медианными значениями и входными значениями числового ряда.
* [#113](https://github.com/Tim55667757/TKSBrokerAPI/issues/113) В модуль TradeRoutines добавлен метод `HampelAnomalyDetection()`, который использует фильтр Хампеля. Эта функция возвращает минимальный индекс элемента в списке найденных аномалий или индекс первого максимального элемента во входном ряду, если этот индекс меньше индекса аномального элемента.
* [#114](https://github.com/Tim55667757/TKSBrokerAPI/issues/114) Были добавлены примеры фильтрации методом Хампеля: 1) Jupyter Notebook с теорией и практикой ([русская](https://nbviewer.org/github/Tim55667757/TKSBrokerAPI/blob/develop/docs/examples/HampelFilteringExample.ipynb) и [английская](https://nbviewer.org/github/Tim55667757/TKSBrokerAPI/blob/develop/docs/examples/HampelFilteringExample_EN.ipynb) версии); 2) [пример](https://github.com/Tim55667757/TKSBrokerAPI/blob/develop/docs/examples/TestAnomalyFilter.py) скрипта на Python; 3) статья: "Как быстро найти аномалии в числовых рядах с помощью метода Хампеля" ([русская](https://forworktests.blogspot.com/2022/12/blog-post.html) и [английская](https://forworktests.blogspot.com/2023/01/how-to-quickly-find-anomalies-in-number.html) версии).
* [#117](https://github.com/Tim55667757/TKSBrokerAPI/issues/117) Правила открытия/закрытия позиций в зависимости от нечётких уровней Риска/Достижимости были добавлены в виде матриц `OPENING_RULES` и `CLOSING_RULES` с логическими значениями. Методы `CanOpen()` и `CanClose` являются функциями-фильтрами и могут проверять правила открытия/закрытия позиций, опираясь на эти матрицы и нечёткие значения Риска/Достижимости.
* [#118](https://github.com/Tim55667757/TKSBrokerAPI/issues/118) Добавлены методы для вычисления уровней нечёткого риска и нечёткой достижимости: `RiskLong()`, `RiskShort()`, `ReachLong()` и `ReachShort()`.
* [#14](https://github.com/Tim55667757/TKSBrokerAPI/issues/14) Реализован "Установщик сетки ордеров". Этот скрипт позволяет настроить сетку ордеров (лимитных или стоп-ордеров, на покупку или на продажу) с заданными шагами и лотностью для множества инструментов по их тикерам в конвейерном параллельном режиме работы.
* [#140](https://github.com/Tim55667757/TKSBrokerAPI/issues/140) Реализовано CI/CD на GitHub Actions.
* [#145](https://github.com/Tim55667757/TKSBrokerAPI/issues/145) Реализована оценка вероятности достижимости ценой целевых уровней.
* [#152](https://github.com/Tim55667757/TKSBrokerAPI/issues/152) Добавлен централизованный троттлинг с кооперативным ожиданием в `SendAPIRequest()`.
* [#154](https://github.com/Tim55667757/TKSBrokerAPI/issues/154) Добавлены модели оценки хаоса (Hurst, SampEn, DFA) и фазовая фильтрация в метод `EstimateTargetReachability()`. Реализованы доверительные коэффициенты, агрегация вероятности, расширенные тесты и оптимизация производительности.
* [#78](https://github.com/Tim55667757/TKSBrokerAPI/issues/78) Добавлена многопоточная загрузка истории свечей с поддержкой частичной докачки (`--only-missing`).
* [#57](https://github.com/Tim55667757/TKSBrokerAPI/issues/57) Добавлен режим `--history-auto-updater`: параллельная закачка истории тикеров по крону с сохранением в отдельные CSV-файлы.
* [#141](https://github.com/Tim55667757/TKSBrokerAPI/issues/141) Добавлена сборка и публикация Docker-образа TKSBrokerAPI через GitHub Actions с поддержкой версий `dev` и `release`.

##### Улучшения

* [#92](https://github.com/Tim55667757/TKSBrokerAPI/issues/92) Блокировка мьютекса была реализована для метода `SendAPIRequest()`, чтобы избежать проблем с недоступным ресурсом при мультипроцессной работе платформы TKSBrokerAPI.
* [#89](https://github.com/Tim55667757/TKSBrokerAPI/issues/89) Если вы запускаете несколько экземпляров платформы TKSBrokerAPI в параллельном режиме, можно использовать дополнительный тег для упрощения отладки и идентификации экземпляров в логах. Тег добавляется ключом `--tag`.
* [#99](https://github.com/Tim55667757/TKSBrokerAPI/issues/99) Нарисован логотип и баннер TKSBrokerAPI и добавлен во все шаблоны HTML-отчётов.
* [#98](https://github.com/Tim55667757/TKSBrokerAPI/issues/98) Новое поле со значением непокрытой позиции было добавлено в раздел отчёта о состоянии маржинальной торговли (ключ `--user-info`).
* [#96](https://github.com/Tim55667757/TKSBrokerAPI/issues/96) Был реализован метод `UpdateClassFields()` и написаны позитивные и негативные юнит-тесты на него. Он получает настройки как словарь (например, загруженный из YAML файла) и применяет к полям и значениям указанного инстанса некоторого класса пару `key: value`.
* [#100](https://github.com/Tim55667757/TKSBrokerAPI/issues/100) Теперь в методах `CloseAllByTicker()` и `CloseAllByTicker()` ордеры закрываются до закрытия основной позиции по инструменту, чтобы минимизировать число заблокированных лотов.
* [#104](https://github.com/Tim55667757/TKSBrokerAPI/issues/104) Выполняется попытка определить `self.figi`, чтобы избежать лишних предупреждений в методе `Overview()`, если FIGI пустой.
* [#106](https://github.com/Tim55667757/TKSBrokerAPI/issues/106) Реализован метод`SeparateByEqualParts()`. Этот метод получает на вход лист элементов и пытается разделить его на список списков равных по количеству элементов.
* [#27](https://github.com/Tim55667757/TKSBrokerAPI/issues/27) Try...except блок и негативные юнит-тексты были добавлены для метода `NanoToFloat()`.
* [#28](https://github.com/Tim55667757/TKSBrokerAPI/issues/28) Try...except блок и негативные юнит-тексты были добавлены для метода `FloatToNano()`.
* [#30](https://github.com/Tim55667757/TKSBrokerAPI/issues/30) Try...except блок и негативные юнит-тексты были добавлены для метода `GetDatesAsString()`.
* [#33](https://github.com/Tim55667757/TKSBrokerAPI/issues/33) Try...except блок и негативные юнит-тексты были добавлены для метода `_ParseJSON()`.
* [#107](https://github.com/Tim55667757/TKSBrokerAPI/issues/107) `onlyFiles` параметр был добавлен к некоторым методам, где был параметр `show`: `OverviewUserInfo()`, `OverviewAccounts()`, `OverviewLimits()`, `Deals()`, `Overview()`, `ShowListOfPrices()`, `GetListOfPrices()`, `SearchInstruments()`, `ShowInstrumentsInfo()` и `ShowInstrumentInfo()`. Он позволяет генерировать только файлы отчётов, без отображения информации в консоли.
* [#116](https://github.com/Tim55667757/TKSBrokerAPI/issues/116) API-документация на модули `TKSBrokerAPI` теперь с тёмной темой.
* [#126](https://github.com/Tim55667757/TKSBrokerAPI/issues/126) Счетчик типов операций был обновлён в отчёте по сделкам.
* [#138](https://github.com/Tim55667757/TKSBrokerAPI/issues/138) Патч для np.NaN.
* [#146](https://github.com/Tim55667757/TKSBrokerAPI/issues/146) В сотни раз ускорена работа метода `HampelFilter()`, особенно это заметно для длинных рядов, содержащих более 1 млн. значений.
* [#148](https://github.com/Tim55667757/TKSBrokerAPI/issues/148) Реализована оптимизированная и ускоренная версия `FastBBands()`, вместо аналогичной медленной функции из pandas_ta.
* [#149](https://github.com/Tim55667757/TKSBrokerAPI/issues/149) Реализована оптимизированная и ускоренная версия `FastPSAR()`, вместо аналогичной медленной функции из pandas_ta.
* [#144](https://github.com/Tim55667757/TKSBrokerAPI/issues/144) Реализована функция `CalculateAdaptiveCacheReserve()` для адаптивного динамического управления объёмом ликвидности.
* [#150](https://github.com/Tim55667757/TKSBrokerAPI/issues/150) Улучшена базовая функция `SendAPIRequest()`: безопасные повторы, разбор ошибок, полные тесты; повышена стабильность клиента.
* [#151](https://github.com/Tim55667757/TKSBrokerAPI/issues/151) Оптимизирован метод `Overview()` для портфеля и добавлены юнит-тесты.
* [#153](https://github.com/Tim55667757/TKSBrokerAPI/issues/153) Добавлена мини-функция `FormatTimedelta()` для форматирования timedelta с точностью до секунд, с возвратом строки по умолчанию при ошибках.
* [#88](https://github.com/Tim55667757/TKSBrokerAPI/issues/88) Улучшен вид таблицы со стоп-ордерами в `--overview`.
* [#91](https://github.com/Tim55667757/TKSBrokerAPI/issues/91) Тикеры теперь можно указывать в любом формате (регистронезависимые).

##### Баг-фиксы

* [#93](https://github.com/Tim55667757/TKSBrokerAPI/issues/93) Исправлен баг: `KeyError: 'stopOrders' and KeyError: 'orders'` в методах `RequestPendingOrders()` и `RequestStopOrders()`.
* [#94](https://github.com/Tim55667757/TKSBrokerAPI/issues/94) Исправлен баг в методе `Overview()`: `KeyError: 'currentNkd'`, если инструмент не является облигацией.
* [#95](https://github.com/Tim55667757/TKSBrokerAPI/issues/95) Исправлен баг со "сломанной" таблицей Overview в колонке `Lots`.
* [#101](https://github.com/Tim55667757/TKSBrokerAPI/issues/101) Исправлен баг с неправильным расчётом доступных валют и аналитики в таблицах `Overview()`.
* [#102](https://github.com/Tim55667757/TKSBrokerAPI/issues/102) Исправлен баг в методе `Deals()`: `KeyError: 'OPERATION_STATE_PROGRESS'`. Для этого был добавлен новый статус `OPERATION_STATE_PROGRESS` в константу `TKS_OPERATION_STATES`.
* [#103](https://github.com/Tim55667757/TKSBrokerAPI/issues/103) Таблицы отформатированы.
* [#120](https://github.com/Tim55667757/TKSBrokerAPI/issues/120) Исправлен баг в методе `History()`: `KeyError: 'candles'`. Добавлена дополнительная проверка.
* [#121](https://github.com/Tim55667757/TKSBrokerAPI/issues/121) Исправлен баг в константе `TKS_QUALIFIED_TYPES`. Некоторые новые значения в поле ответа `qualified_for_work_with` были добавлены в Tinkoff REST API, но не задокументированы: `foreign_bonds_russian_law`, `convertible_bonds`, `russian_bonds_foreign_law`, `non_quoted_instruments` и `option`. Эти дополнительные значения были добавлены в текущем баг-фиксе.
* [#122](https://github.com/Tim55667757/TKSBrokerAPI/issues/122) Для ошибки импорта вида `No module named 'Templates'` в README.md [добавлена инструкция](https://github.com/Tim55667757/TKSBrokerAPI/blob/develop/README.md#Ошибки-импорта) по её исправлению.
* [#123](https://github.com/Tim55667757/TKSBrokerAPI/issues/123) Баг `ValueError` был исправлен для методов `History()` and `LoadHistory()`. Добавлены дополнительные проверки.
* [#124](https://github.com/Tim55667757/TKSBrokerAPI/issues/124) Ошибочные вычисления исправлены: `Incorrect values in view["stat"]["funds"] record`.
* [#125](https://github.com/Tim55667757/TKSBrokerAPI/issues/125) Был исправлен баг `KeyError: 'OPERATION_TYPE_OUT_STAMP_DUTY'`, в константе `TKS_OPERATION_TYPES` не хватало значений.
* [#127](https://github.com/Tim55667757/TKSBrokerAPI/issues/127) Был исправлен баг `KeyError: 'name'` в методе`Overview()`.
* [#128](https://github.com/Tim55667757/TKSBrokerAPI/issues/128) Был исправлен баг: `RUB000UTSTOM` FIGI отсутствует в `dump.json`. С 7 марта 2023 RUB000UTSTOM FIGI перестал возвращаться брокером в списке валют через API.
* [#142](https://github.com/Tim55667757/TKSBrokerAPI/issues/142) Был исправлен баг: ImportError после установки и запуска TKSBrokerAPI.
* [#129](https://github.com/Tim55667757/TKSBrokerAPI/issues/129) Добавлена функция `DetermineDecimalPrecision()` и интеграция в метод `History()` для автоматического округления цен перед сохранением в CSV, чтобы избежать ошибок округления.
* [#131](https://github.com/Tim55667757/TKSBrokerAPI/issues/131) Исправлена ошибка при наличии "запрещённых" валют "недружественных" стран в портфеле.
* [#133](https://github.com/Tim55667757/TKSBrokerAPI/issues/133) Исправлен TypeError при экспорте в XLSX.
* [#137](https://github.com/Tim55667757/TKSBrokerAPI/issues/137) Исправлен KeyError: 'rub', если кеш в рублях равен нулю в портфеле (обычно при открытии счёта, до первого пополнения).


### [1.5.120 (2022-11-21)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.5.120) — опубликована

##### Дайджест

В очередной версии TKSBrokerAPI в отчёте о портфеле пользователя появилась новая секция с календарём платежей по облигациям. Он строится автоматически, если имеется хотя бы одна облигация в портфеле (ключ `--overview-calendar`). Был добавлен ключ `--html` для сохранения любых пользовательских отчётов в HTML формат. Кроме того, появилась возможность закрывать позицию и все ордера по ключу `--close-all` для одного инструмента, заданного через `--ticker` или `--figi`.

Торговый сценарий [./docs/examples/scenario1.py](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/docs/examples/scenario1.py) был переписан в парадигме ООП: [./docs/examples/scenario1a.py](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/docs/examples/scenario1a.py). Теперь это полноценный торговый шаблон на базе платформы TKSBrokerAPI. Его можно использовать за основу для разработки собственных сценариев.

Пофикшен обидный баг при торговле "по рынку" (ключ `--trade`), когда TP/SL ордеры открывались даже если основная заявка не была исполнена. Теперь при любых ошибках TP/SL ордеры не выставляются. А также, для удобства отладки теперь можно указывать ключ `--more` вместе с любой другой командой. В логах появится больше информации, например, сетевые запросы, сетевые ответы и их заголовки.

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

* [#62](https://github.com/Tim55667757/TKSBrokerAPI/issues/62) В отчёт о состоянии портфеля пользователя добавлена секция с календарём платежей по облигациям, который строится автоматически, если хотя бы одна облигация присутствует в портфеле (метод `Overview(details="calendar")`, ключ `--overview-calendar`).
* [#80](https://github.com/Tim55667757/TKSBrokerAPI/issues/80) Пример торгового сценария [./docs/examples/scenario1.py](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/docs/examples/scenario1.py) дополнительно переписан в парадигме ООП: [./docs/examples/scenario1a.py](https://github.com/Tim55667757/TKSBrokerAPI/blob/master/docs/examples/scenario1a.py). Эти шаблоны можно брать за основу для разработки собственных торговых сценариев, на базе платформы TKSBrokerAPI.
* [#48](https://github.com/Tim55667757/TKSBrokerAPI/issues/48) Если ключ `--close-all` будет указан совместно с одним из ключей `--ticker` или `--figi`, тогда будут закрыты все незаблокированные объёмы открытой позиции, отложенные лимитные и стоп ордеры для выбранного инструмента. Для поддержки этой фичи были реализованы дополнительные методы: `CloseAllByTicker()` — для закрытия всех позиций и ордеров по инструменту заданному тикером, `CloseAllByFIGI()` — для закрытия всех позиций и ордеров по инструменту заданному FIGI идентификатором, `IsInLimitOrders()` — функция, которая возвращает `True` или `False`, при наличии или отсутствии открытых отложенных лимитных ордеров, `GetLimitOrderIDs()` — функция, которая возвращает список открытых отложенных лимитных ордеров, `IsInStopOrders()` — функция, которая возвращает `True` или `False`, при наличии или отсутствии открытых стоп ордеров и `GetStopOrderIDs()` — функция, которая возвращает список открытых стоп ордеров для инструмента.
* [#83](https://github.com/Tim55667757/TKSBrokerAPI/issues/83) Теперь можно указывать ключ `--html` для генерации дополнительных отчётов из Markdown-файлов в HTML формат. Рендеринг HTML и ключ `--html` были реализованы для отчётов, создаваемых командами `--list`, `--info`, `--search`, `--prices`, `--deals`, `--limits`, `--calendar`, `--account`, `--user-info`, `--overview`, `--overview-digest`, `--overview-positions`, `--overview-orders`, `--overview-analytics` и `--overview-calendar`. HTML-генератор основан на [Mako Templates library](https://www.makotemplates.org/).
* [#67](https://github.com/Tim55667757/TKSBrokerAPI/issues/67) Теперь можно указывать ключ `--more` вместе с любой командой. Он включает во всех методах TKSBrokerAPI больше отладочной информации и выводит её в логи. Например, сохраняются фактические сетевые запросы, ответы на них и заголовки.

##### Улучшения

* [#74](https://github.com/Tim55667757/TKSBrokerAPI/issues/74) Улучшен CI/CD скрипт `.travis.yml`. Теперь при запуске сборки из пулл-реквеста выполняются только шаги запуска юнит-тестов и сборки пакета. Выкладка пакета в PyPI не происходит. Публикация в PyPI теперь запускается только при сборке напрямую из ветки или после принятия пулл-реквеста.
* [#39](https://github.com/Tim55667757/TKSBrokerAPI/issues/39) Теперь все операции закрытия позиций или ордеров (наборы ключей `--close-***`) поддерживают возможность указания инструментов не только через тикеры, но и через FIGI идентификаторы.
* [#60](https://github.com/Tim55667757/TKSBrokerAPI/issues/60) Теперь ключи `--ticker` и `--figi` — регистронезависимые. Можно указывать в консоли их значения в любом регистре, а внутри платформы TKSBrokerAPI они будут автоматически приведены к верхнему регистру.
* [#75](https://github.com/Tim55667757/TKSBrokerAPI/issues/75) Если при запуске с ключом `--limits` окажется, что нет доступных для вывода лимитов денежных средств, то теперь пустая таблица отображаться не будет.
* [#68](https://github.com/Tim55667757/TKSBrokerAPI/issues/68) В отчёт по акции (метод `ShowInstrumentInfo()`, ключ `--info`) добавлена информация про тип акции: обыкновенная, привилегированная, американские депозитарные расписки, глобальные депозитарные расписки, товарищество с ограниченной ответственностью, акции из реестра Нью-Йорка, закрытый инвестиционный фонд или траст недвижимости.
* [#35](https://github.com/Tim55667757/TKSBrokerAPI/issues/35) В таблице "Summary" с отчетом по операциям (ключ `--deals`) упрощены заголовки.
* [#51](https://github.com/Tim55667757/TKSBrokerAPI/issues/51) Константа `NANO`, методы `NanoToFloat()` и `FloatToNano()` вынесены в новый модуль `TradeRoutines`. Это библиотека с набором функций для упрощения реализации торговых стратегий на базе платформы TKSBrokerAPI.
* [#52](https://github.com/Tim55667757/TKSBrokerAPI/issues/52) Метод `GetDatesAsString()` также перенесён в модуль `TradeRoutines`.

##### Баг-фиксы

* [#66](https://github.com/Tim55667757/TKSBrokerAPI/issues/66) Исправлен баг в методе `Trade()` (ключ `--trade`). Теперь, в случае если основной рыночный ордер по инструменту не был исполнен, то TP/SL ордеры также не выставляются для этого инструмента. В предыдущих версиях TP/SL ордеры открывались даже в случае ошибок при открытии рыночного ордера, к которому они привязаны, что нарушало логику торговых сценариев.
* [#84](https://github.com/Tim55667757/TKSBrokerAPI/issues/84) Исправлен баг в методе `Overview()` (ключ `--overview`), который появился после решения задачи [#17](https://github.com/Tim55667757/TKSBrokerAPI/issues/17). В секциях лимитных и стоп ордеров в отчёте о состоянии портфеля пользователя отображались только первые ордеры в списке. Сейчас снова отображаются все открытые ордеры. Кроме того, улучшена производительность: теперь для ордеров по одному и тому же инструменту цена запрашивается только один раз, что критично, в случае большого числа открытых ордеров.
* [#81](https://github.com/Tim55667757/TKSBrokerAPI/issues/81) Исправлено отображение дробных чисел при печати биржевого стакана.


### [1.4.90 (2022-11-07)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.4.90) — опубликована

##### Дайджест

Теперь можно обогащать сырые данные по облигациям большим числом полей и значений, выгружать их в 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] Российская Федерация"`, перед расчётом статистики.


### [1.3.70 (2022-09-07)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.3.70) — опубликована

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

* [#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.


### [1.2.62 (2022-08-23)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.2.62) — опубликована

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

* [#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"]`.


### [1.1.48 (2022-07-28)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.1.48) — опубликована

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

* Лицензия изменена с 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`. Ошибка возникла из-за неправильной обработки формата входной строки в одном из отладочных сообщений. Убраны лишние сообщения, а вместе с ними и ошибка форматирования.


## [1.0.1 (2020-05 - 2022-07)](https://github.com/Tim55667757/TKSBrokerAPI/releases/tag/1.0.1) — устаревшая версия, неработоспособная с новым Tinkoff Open API REST-протоколом

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

Первый прототип [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-протоколом, выложить библиотеку в опенсорс и настроить релизный цикл её выпуска.

[![gift](https://badgen.net/badge/gift/donate/green)](https://yoomoney.ru/fundraise/4WOyAgNgb7M.230111)
