tksbrokerapi.TKSBrokerAPI

   1# -*- coding: utf-8 -*-
   2# Author: Timur Gilmullin
   3
   4"""
   5**TKSBrokerAPI** is the trading platform for automation and simplifying the implementation of trading scenarios,
   6as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways:
   7from the console, it has a rich keys and commands, or you can use it as Python module with `python import`.
   8
   9TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive
  10the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.
  11
  12- **Open account for trading:** http://tinkoff.ru/sl/AaX1Et1omnH
  13- **TKSBrokerAPI module documentation:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
  14- **See CLI examples:** https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
  15- **Used constants are in the TKSEnums module:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
  16- **About Tinkoff Invest API:** https://tinkoff.github.io/investAPI/
  17- **Tinkoff Invest API documentation:** https://tinkoff.github.io/investAPI/swagger-ui/
  18"""
  19
  20# Copyright (c) 2022 Gilmillin Timur Mansurovich
  21#
  22# Licensed under the Apache License, Version 2.0 (the "License");
  23# you may not use this file except in compliance with the License.
  24# You may obtain a copy of the License at
  25#
  26#     http://www.apache.org/licenses/LICENSE-2.0
  27#
  28# Unless required by applicable law or agreed to in writing, software
  29# distributed under the License is distributed on an "AS IS" BASIS,
  30# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31# See the License for the specific language governing permissions and
  32# limitations under the License.
  33
  34
  35import sys
  36import os
  37from argparse import ArgumentParser
  38from importlib.metadata import version
  39
  40from dateutil.tz import tzlocal
  41from time import sleep
  42
  43import re
  44import json
  45import requests
  46import traceback as tb
  47from typing import Union
  48
  49from multiprocessing import cpu_count
  50from multiprocessing.pool import ThreadPool
  51import pandas as pd
  52
  53from mako.template import Template  # Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
  54from Templates import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  55from TKSEnums import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  56from TradeRoutines import *  # This library contains some methods used by trade scenarios implemented with TKSBrokerAPI module
  57
  58from pricegenerator.PriceGenerator import PriceGenerator, uLogger  # This module has a lot of instruments to work with candles data (https://github.com/Tim55667757/PriceGenerator)
  59from pricegenerator.UniLogger import DisableLogger as PGDisLog  # Method for disable log from PriceGenerator
  60
  61import UniLogger as uLog  # Logger for TKSBrokerAPI
  62
  63
  64# --- Common technical parameters:
  65
  66PGDisLog(uLogger.handlers[0])  # Disable 3-rd party logging from PriceGenerator
  67uLogger = uLog.UniLogger  # init logger for TKSBrokerAPI
  68uLogger.level = 10  # debug level by default for TKSBrokerAPI module
  69uLogger.handlers[0].level = 20  # info level by default for STDOUT of TKSBrokerAPI module
  70
  71__version__ = "1.5"  # The "major.minor" version setup here, but build number define at the build-server only
  72
  73CPU_COUNT = cpu_count()  # host's real CPU count
  74CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
  75
  76
  77class TinkoffBrokerServer:
  78    """
  79    This class implements methods to work with Tinkoff broker server.
  80
  81    Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/
  82
  83    About `token`: https://tinkoff.github.io/investAPI/token/
  84    """
  85    def __init__(self, token: str, accountId: str = None, useCache: bool = True, defaultCache: str = "dump.json") -> None:
  86        """
  87        Main class init.
  88
  89        :param token: Bearer token for Tinkoff Invest API. It can be set from environment variable `TKS_API_TOKEN`.
  90        :param accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports.
  91                          Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.
  92        :param useCache: use default cache file with raw data to use instead of `iList`.
  93                         True by default. Cache is auto-update if new day has come.
  94                         If you don't want to use cache and always updates raw data then set `useCache=False`.
  95        :param defaultCache: path to default cache file. `dump.json` by default.
  96        """
  97        if token is None or not token:
  98            try:
  99                self.token = r"{}".format(os.environ["TKS_API_TOKEN"])
 100                uLogger.debug("Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/")
 101
 102            except KeyError:
 103                uLogger.error("`--token` key or environment variable `TKS_API_TOKEN` is required! See https://tinkoff.github.io/investAPI/token/")
 104                raise Exception("Token required")
 105
 106        else:
 107            self.token = token  # highly priority than environment variable 'TKS_API_TOKEN'
 108            uLogger.debug("Bearer token for Tinkoff OpenAPI set up from class variable `token`")
 109
 110        if accountId is None or not accountId:
 111            try:
 112                self.accountId = r"{}".format(os.environ["TKS_ACCOUNT_ID"])
 113                uLogger.debug("Main account ID [{}] set up from environment variable `TKS_ACCOUNT_ID`".format(self.accountId))
 114
 115            except KeyError:
 116                uLogger.warning("`--account-id` key or environment variable `TKS_ACCOUNT_ID` undefined! Some of operations may be unavailable (overview, trading etc).")
 117
 118        else:
 119            self.accountId = accountId  # highly priority than environment variable 'TKS_ACCOUNT_ID'
 120            uLogger.debug("Main account ID [{}] set up from class variable `accountId`".format(self.accountId))
 121
 122        self.version = __version__  # duplicate here used TKSBrokerAPI main version
 123        """Current TKSBrokerAPI version: major.minor, but the build number define at the build-server only.
 124
 125        Latest version: https://pypi.org/project/tksbrokerapi/
 126        """
 127
 128        self.aliases = TKS_TICKER_ALIASES
 129        """Some aliases instead official tickers.
 130
 131        See also: `TKSEnums.TKS_TICKER_ALIASES`
 132        """
 133
 134        self.aliasesKeys = self.aliases.keys()  # re-calc only first time at class init
 135
 136        self.exclude = TKS_TICKERS_OR_FIGI_EXCLUDED  # some tickers or FIGIs raised exception earlier when it sends to server, that is why we exclude there
 137
 138        self._ticker = ""
 139        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 140
 141        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 142        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 143
 144        See also: `SearchByTicker()`, `SearchInstruments()`.
 145        """
 146
 147        self._figi = ""
 148        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 149
 150        See also: `SearchByFIGI()`, `SearchInstruments()`.
 151        """
 152
 153        self.depth = 1
 154        """Depth of Market (DOM) can be >= 1. Default: 1. It used with `--price` key to showing DOM with current prices for givens ticker or FIGI.
 155
 156        See also: `GetCurrentPrices()`.
 157        """
 158
 159        self.server = r"https://invest-public-api.tinkoff.ru/rest"
 160        """Tinkoff REST API server for real trade operations. Default: https://invest-public-api.tinkoff.ru/rest
 161
 162        See also: API method https://tinkoff.github.io/investAPI/#tinkoff-invest-api_1 and `SendAPIRequest()`.
 163        """
 164
 165        uLogger.debug("Broker API server: {}".format(self.server))
 166
 167        self.timeout = 15
 168        """Server operations timeout in seconds. Default: `15`.
 169
 170        See also: `SendAPIRequest()`.
 171        """
 172
 173        self.headers = {
 174            "Content-Type": "application/json",
 175            "accept": "application/json",
 176            "Authorization": "Bearer {}".format(self.token),
 177            "x-app-name": "Tim55667757.TKSBrokerAPI",
 178        }
 179        """Headers which send in every request to broker server. Please, do not change it! Default: `{"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}"}`.
 180
 181        See also: `SendAPIRequest()`.
 182        """
 183
 184        self.body = None
 185        """Request body which send to broker server. Default: `None`.
 186
 187        See also: `SendAPIRequest()`.
 188        """
 189
 190        self.moreDebug = False
 191        """Enables more debug information in this class, such as net request and response headers in all methods. `False` by default."""
 192
 193        self.useHTMLReports = False
 194        """
 195        If `True` then TKSBrokerAPI generate also HTML reports from Markdown. `False` by default.
 196        
 197        See also: Mako Templates for Python (https://www.makotemplates.org/). Mako is a template library provides simple syntax and maximum performance.
 198        """
 199
 200        self.historyFile = None
 201        """Full path to the output file where history candles will be saved or updated. Default: `None`, it mean that returns only Pandas DataFrame.
 202
 203        See also: `History()`.
 204        """
 205
 206        self.htmlHistoryFile = "index.html"
 207        """Full path to the html file where rendered candles chart stored. Default: `index.html`.
 208
 209        See also: `ShowHistoryChart()`.
 210        """
 211
 212        self.instrumentsFile = "instruments.md"
 213        """Filename where full available to user instruments list will be saved. Default: `instruments.md`.
 214
 215        See also: `ShowInstrumentsInfo()`.
 216        """
 217
 218        self.searchResultsFile = "search-results.md"
 219        """Filename with all found instruments searched by part of its ticker, FIGI or name. Default: `search-results.md`.
 220
 221        See also: `SearchInstruments()`.
 222        """
 223
 224        self.pricesFile = "prices.md"
 225        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 226
 227        See also: `GetListOfPrices()`.
 228        """
 229
 230        self.infoFile = "info.md"
 231        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 232
 233        See also: `ShowInstrumentsInfo()`, `RequestBondCoupons()` and `RequestTradingStatus()`.
 234        """
 235
 236        self.bondsXLSXFile = "ext-bonds.xlsx"
 237        """Filename where wider Pandas DataFrame with more information about bonds: main info, current prices, 
 238        bonds payment calendar, some statistics will be stored. Default: `ext-bonds.xlsx`.
 239
 240        See also: `ExtendBondsData()`.
 241        """
 242
 243        self.calendarFile = "calendar.md"
 244        """Filename where bonds payment calendar will be saved. Default: `calendar.md`.
 245        
 246        Pandas dataframe with only bonds payment calendar also will be stored to default file `calendar.xlsx`.
 247
 248        See also: `CreateBondsCalendar()`, `ShowBondsCalendar()`, `ShowInstrumentInfo()`, `RequestBondCoupons()` and `ExtendBondsData()`.
 249        """
 250
 251        self.overviewFile = "overview.md"
 252        """Filename where current portfolio, open trades and orders will be saved. Default: `overview.md`.
 253
 254        See also: `Overview()`, `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders()` and `RequestStopOrders()`.
 255        """
 256
 257        self.overviewDigestFile = "overview-digest.md"
 258        """Filename where short digest of the portfolio status will be saved. Default: `overview-digest.md`.
 259
 260        See also: `Overview()` with parameter `details="digest"`.
 261        """
 262
 263        self.overviewPositionsFile = "overview-positions.md"
 264        """Filename where only open positions, without everything else will be saved. Default: `overview-positions.md`.
 265
 266        See also: `Overview()` with parameter `details="positions"`.
 267        """
 268
 269        self.overviewOrdersFile = "overview-orders.md"
 270        """Filename where open limits and stop orders will be saved. Default: `overview-orders.md`.
 271
 272        See also: `Overview()` with parameter `details="orders"`.
 273        """
 274
 275        self.overviewAnalyticsFile = "overview-analytics.md"
 276        """Filename where only the analytics section and the distribution of the portfolio by various categories will be saved. Default: `overview-analytics.md`.
 277
 278        See also: `Overview()` with parameter `details="analytics"`.
 279        """
 280
 281        self.overviewBondsCalendarFile = "overview-calendar.md"
 282        """Filename where only the bonds calendar section will be saved. Default: `overview-calendar.md`.
 283
 284        See also: `Overview()` with parameter `details="calendar"`.
 285        """
 286
 287        self.reportFile = "deals.md"
 288        """Filename where history of deals and trade statistics will be saved. Default: `deals.md`.
 289
 290        See also: `Deals()`.
 291        """
 292
 293        self.withdrawalLimitsFile = "limits.md"
 294        """Filename where table of funds available for withdrawal will be saved. Default: `limits.md`.
 295
 296        See also: `OverviewLimits()` and `RequestLimits()`.
 297        """
 298
 299        self.userInfoFile = "user-info.md"
 300        """Filename where all available user's data (`accountId`s, common user information, margin status and tariff connections limit) will be saved. Default: `user-info.md`.
 301
 302        See also: `OverviewUserInfo()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()`.
 303        """
 304
 305        self.userAccountsFile = "accounts.md"
 306        """Filename where simple table with all available user accounts (`accountId`s) will be saved. Default: `accounts.md`.
 307
 308        See also: `OverviewAccounts()`, `RequestAccounts()`.
 309        """
 310
 311        self.iListDumpFile = "dump.json" if defaultCache is None or not isinstance(defaultCache, str) or not defaultCache else defaultCache
 312        """Filename where raw data about shares, currencies, bonds, etfs and futures will be stored. Default: `dump.json`.
 313
 314        Pandas dataframe with raw instruments data also will be stored to default file `dump.xlsx`.
 315
 316        See also: `DumpInstruments()` and `DumpInstrumentsAsXLSX()`.
 317        """
 318
 319        self.iList = None  # init iList for raw instruments data
 320        """Dictionary with raw data about shares, currencies, bonds, etfs and futures from broker server. Auto-updating and saving dump to the `iListDumpFile`.
 321        
 322        See also: `Listing()`, `DumpInstruments()`.
 323        """
 324
 325        # trying to re-load raw instruments data from file `iListDumpFile` or try to update it from server:
 326        if useCache:
 327            if os.path.exists(self.iListDumpFile):
 328                dumpTime = datetime.fromtimestamp(os.path.getmtime(self.iListDumpFile)).astimezone(tzutc())  # dump modification date and time
 329                curTime = datetime.now(tzutc())
 330
 331                if (curTime.day > dumpTime.day) or (curTime.month > dumpTime.month) or (curTime.year > dumpTime.year):
 332                    uLogger.warning("Local cache may be outdated! It has last modified [{}] UTC. Updating from broker server, wait, please...".format(dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
 333
 334                    self.DumpInstruments(forceUpdate=True)  # updating self.iList and dump file
 335
 336                else:
 337                    self.iList = json.load(open(self.iListDumpFile, mode="r", encoding="UTF-8"))  # load iList from dump
 338
 339                    uLogger.debug("Local cache with raw instruments data is used: [{}]. Last modified: [{}] UTC".format(
 340                        os.path.abspath(self.iListDumpFile),
 341                        dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT),
 342                    ))
 343
 344            else:
 345                uLogger.warning("Local cache with raw instruments data not exists! Creating new dump, wait, please...")
 346                self.DumpInstruments(forceUpdate=True)  # updating self.iList and creating default dump file
 347
 348        else:
 349            self.iList = self.Listing()  # request new raw instruments data from broker server
 350            self.DumpInstruments(forceUpdate=False)  # save raw instrument's data to default dump file `iListDumpFile`
 351
 352        self.priceModel = PriceGenerator()  # init PriceGenerator object to work with candles data
 353        """PriceGenerator object to work with candles data: load, render interact and non-interact charts and so on.
 354
 355        See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
 356        """
 357
 358    @property
 359    def ticker(self) -> str:
 360        """String with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 361
 362        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 363        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 364
 365        See also: `SearchByTicker()`, `SearchInstruments()`.
 366        """
 367        return self._ticker
 368
 369    @ticker.setter
 370    def ticker(self, value):
 371        """Setter for string with ticker, e.g. `GOOGL`. Tickers may be upper case only.
 372
 373        Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc.
 374        More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 375
 376        See also: `SearchByTicker()`, `SearchInstruments()`.
 377        """
 378        self._ticker = str(value).upper()  # Tickers may be upper case only
 379
 380    @property
 381    def figi(self) -> str:
 382        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 383
 384        See also: `SearchByFIGI()`, `SearchInstruments()`.
 385        """
 386        return self._figi
 387
 388    @figi.setter
 389    def figi(self, value):
 390        """Setter for string with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`. FIGIs may be upper case only.
 391
 392        See also: `SearchByFIGI()`, `SearchInstruments()`.
 393        """
 394        self._figi = str(value).upper()  # FIGI may be upper case only
 395
 396    def _ParseJSON(self, rawData="{}") -> dict:
 397        """
 398        Parse JSON from response string.
 399
 400        :param rawData: this is a string with JSON-formatted text.
 401        :return: JSON (dictionary), parsed from server response string.
 402        """
 403        responseJSON = json.loads(rawData) if rawData else {}
 404
 405        if self.moreDebug:
 406            uLogger.debug("JSON formatted raw body data of response:\n{}".format(json.dumps(responseJSON, indent=4)))
 407
 408        return responseJSON
 409
 410    def SendAPIRequest(self, url: str, reqType: str = "GET", retry: int = 3, pause: int = 5) -> dict:
 411        """
 412        Send GET or POST request to broker server and receive JSON object.
 413
 414        self.header: must be defining with dictionary of headers.
 415        self.body: if define then used as request body. None by default.
 416        self.timeout: global request timeout, 15 seconds by default.
 417        :param url: url with REST request.
 418        :param reqType: send "GET" or "POST" request. "GET" by default.
 419        :param retry: how many times retry after first request if an 5xx server errors occurred.
 420        :param pause: sleep time in seconds between retries.
 421        :return: response JSON (dictionary) from broker.
 422        """
 423        if reqType.upper() not in ("GET", "POST"):
 424            uLogger.error("You can define request type: `GET` or `POST`!")
 425            raise Exception("Incorrect value")
 426
 427        if self.moreDebug:
 428            uLogger.debug("Request parameters:")
 429            uLogger.debug("    - REST API URL: {}".format(url))
 430            uLogger.debug("    - request type: {}".format(reqType))
 431            uLogger.debug("    - headers:\n{}".format(str(self.headers).replace(self.token, "*** request token ***")))
 432            uLogger.debug("    - body:\n{}".format(self.body))
 433
 434        # fast hack to avoid all operations with some tickers/FIGI
 435        responseJSON = {}
 436        oK = True
 437        for item in self.exclude:
 438            if item in url:
 439                if self.moreDebug:
 440                    uLogger.warning("Do not execute operations with list of this tickers/FIGI: {}".format(str(self.exclude)))
 441
 442                oK = False
 443                break
 444
 445        if oK:
 446            counter = 0
 447            response = None
 448            errMsg = ""
 449
 450            while not response and counter <= retry:
 451                if reqType == "GET":
 452                    response = requests.get(url, headers=self.headers, data=self.body, timeout=self.timeout)
 453
 454                if reqType == "POST":
 455                    response = requests.post(url, headers=self.headers, data=self.body, timeout=self.timeout)
 456
 457                if self.moreDebug:
 458                    uLogger.debug("Response:")
 459                    uLogger.debug("    - status code: {}".format(response.status_code))
 460                    uLogger.debug("    - reason: {}".format(response.reason))
 461                    uLogger.debug("    - body length: {}".format(len(response.text)))
 462                    uLogger.debug("    - headers:\n{}".format(response.headers))
 463
 464                # Server returns some headers:
 465                # - `x-ratelimit-limit` — shows the settings of the current user limit for this method.
 466                # - `x-ratelimit-remaining` — the number of remaining requests of this type per minute.
 467                # - `x-ratelimit-reset` — time in seconds before resetting the request counter.
 468                # See: https://tinkoff.github.io/investAPI/grpc/#kreya
 469                if "x-ratelimit-remaining" in response.headers.keys() and response.headers["x-ratelimit-remaining"] == "0":
 470                    rateLimitWait = int(response.headers["x-ratelimit-reset"])
 471                    uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
 472                    sleep(rateLimitWait)
 473
 474                # Error status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 475                if 400 <= response.status_code < 500:
 476                    msg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 477                    uLogger.debug("    - not oK, but do not retry for 4xx errors, {}".format(msg))
 478
 479                    if "code" in response.text and "message" in response.text:
 480                        msgDict = self._ParseJSON(rawData=response.text)
 481                        uLogger.warning("HTTP-status code [{}], server message: {}".format(response.status_code, msgDict["message"]))
 482
 483                    counter = retry + 1  # do not retry for 4xx errors
 484
 485                if 500 <= response.status_code < 600:
 486                    errMsg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 487                    uLogger.debug("    - not oK, {}".format(errMsg))
 488
 489                    if "code" in response.text and "message" in response.text:
 490                        errMsgDict = self._ParseJSON(rawData=response.text)
 491                        uLogger.warning("HTTP-status code [{}], error message: {}".format(response.status_code, errMsgDict["message"]))
 492
 493                    counter += 1
 494
 495                    if counter <= retry:
 496                        uLogger.debug("Retry: [{}]. Wait {} sec. and try again...".format(counter, pause))
 497                        sleep(pause)
 498
 499            responseJSON = self._ParseJSON(rawData=response.text)
 500
 501            if errMsg:
 502                uLogger.error("Server returns not `oK` status! See: https://tinkoff.github.io/investAPI/errors/")
 503                uLogger.error("    - not oK, {}".format(errMsg))
 504
 505        return responseJSON
 506
 507    def _IUpdater(self, iType: str) -> tuple:
 508        """
 509        Request instrument by type from server. See available API methods for instruments:
 510        Currencies: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Currencies
 511        Shares: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Shares
 512        Bonds: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Bonds
 513        Etfs: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Etfs
 514        Futures: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Futures
 515
 516        :param iType: type of the instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 517        :return: tuple with iType name and list of available instruments of current type for defined user token.
 518        """
 519        result = []
 520
 521        if iType in TKS_INSTRUMENTS:
 522            uLogger.debug("Requesting available [{}] list. Wait, please...".format(iType))
 523
 524            # all instruments have the same body in API v2 requests:
 525            self.body = str({"instrumentStatus": "INSTRUMENT_STATUS_UNSPECIFIED"})  # Enum: [INSTRUMENT_STATUS_UNSPECIFIED, INSTRUMENT_STATUS_BASE, INSTRUMENT_STATUS_ALL]
 526            instrumentURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/{}".format(iType)
 527            result = self.SendAPIRequest(instrumentURL, reqType="POST")["instruments"]
 528
 529        return iType, result
 530
 531    def _IWrapper(self, kwargs):
 532        """
 533        Wrapper runs instrument's update method `_IUpdater()`.
 534        It's a workaround for using multiprocessing with kwargs. See: https://stackoverflow.com/a/36799206
 535        """
 536        return self._IUpdater(**kwargs)
 537
 538    def Listing(self) -> dict:
 539        """
 540        Gets JSON with raw data about shares, currencies, bonds, etfs and futures from broker server.
 541
 542        :return: Dictionary with all available broker instruments: currencies, shares, bonds, etfs and futures.
 543        """
 544        uLogger.debug("Requesting all available instruments for current account. Wait, please...")
 545        uLogger.debug("CPU usages for parallel requests: [{}]".format(CPU_USAGES))
 546
 547        # this parameters insert to requests: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService
 548        # iType is type of instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 549        iParams = [{"iType": iType} for iType in TKS_INSTRUMENTS]
 550
 551        poolUpdater = ThreadPool(processes=CPU_USAGES)  # create pool for update instruments in parallel mode
 552        listing = poolUpdater.map(self._IWrapper, iParams)  # execute update operations
 553        poolUpdater.close()
 554
 555        # Dictionary with all broker instruments: shares, currencies, bonds, etfs and futures.
 556        # Next in this code: item[0] is "iType" and item[1] is list of available instruments from the result of _IUpdater() method
 557        iList = {item[0]: {instrument["ticker"]: instrument for instrument in item[1]} for item in listing}
 558
 559        # calculate minimum price increment (step) for all instruments and set up instrument's type:
 560        for iType in iList.keys():
 561            for ticker in iList[iType]:
 562                iList[iType][ticker]["type"] = iType
 563
 564                if "minPriceIncrement" in iList[iType][ticker].keys():
 565                    iList[iType][ticker]["step"] = NanoToFloat(
 566                        iList[iType][ticker]["minPriceIncrement"]["units"],
 567                        iList[iType][ticker]["minPriceIncrement"]["nano"],
 568                    )
 569
 570                else:
 571                    iList[iType][ticker]["step"] = 0  # hack to avoid empty value in some instruments, e.g. futures
 572
 573        return iList
 574
 575    def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:
 576        """
 577        Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.
 578
 579        See also: `DumpInstruments()`, `Listing()`.
 580
 581        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 582                            otherwise just saves exist `iList` as XLSX-file (default: `dump.xlsx`) .
 583        """
 584        if self.iListDumpFile is None or not self.iListDumpFile:
 585            uLogger.error("Output name of dump file must be defined!")
 586            raise Exception("Filename required")
 587
 588        if not self.iList or forceUpdate:
 589            self.iList = self.Listing()
 590
 591        xlsxDumpFile = self.iListDumpFile.replace(".json", ".xlsx") if self.iListDumpFile.endswith(".json") else self.iListDumpFile + ".xlsx"
 592
 593        # Save as XLSX with separated sheets for every type of instruments:
 594        with pd.ExcelWriter(
 595                path=xlsxDumpFile,
 596                date_format=TKS_DATE_FORMAT,
 597                datetime_format=TKS_DATE_TIME_FORMAT,
 598                mode="w",
 599        ) as writer:
 600            for iType in TKS_INSTRUMENTS:
 601                df = pd.DataFrame.from_dict(data=self.iList[iType], orient="index")  # generate pandas object from self.iList dictionary
 602                df = df[sorted(df)]  # sorted by column names
 603                df = df.applymap(
 604                    lambda item: NanoToFloat(item["units"], item["nano"]) if isinstance(item, dict) and "units" in item.keys() and "nano" in item.keys() else item,
 605                    na_action="ignore",
 606                )  # converting numbers from nano-type to float in every cell
 607                df.to_excel(
 608                    writer,
 609                    sheet_name=iType,
 610                    encoding="UTF-8",
 611                    freeze_panes=(1, 1),
 612                )  # saving as XLSX-file with freeze first row and column as headers
 613
 614        uLogger.info("XLSX-file for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxDumpFile)))
 615
 616    def DumpInstruments(self, forceUpdate: bool = True) -> str:
 617        """
 618        Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server
 619        using `Listing()` method. If `iListDumpFile` string is not empty then also save information to this file.
 620
 621        See also: `DumpInstrumentsAsXLSX()`, `Listing()`.
 622
 623        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 624                            otherwise just saves exist `iList` as JSON-file (default: `dump.json`).
 625        :return: serialized JSON formatted `str` with full data of instruments, also saved to the `--output` JSON-file.
 626        """
 627        if self.iListDumpFile is None or not self.iListDumpFile:
 628            uLogger.error("Output name of dump file must be defined!")
 629            raise Exception("Filename required")
 630
 631        if not self.iList or forceUpdate:
 632            self.iList = self.Listing()
 633
 634        jsonDump = json.dumps(self.iList, indent=4, sort_keys=False)  # create JSON object as string
 635        with open(self.iListDumpFile, mode="w", encoding="UTF-8") as fH:
 636            fH.write(jsonDump)
 637
 638        uLogger.info("New cache of instruments data was created: [{}]".format(os.path.abspath(self.iListDumpFile)))
 639
 640        return jsonDump
 641
 642    def ShowInstrumentInfo(self, iJSON: dict, show: bool = True) -> str:
 643        """
 644        Show information about one instrument defined by json data and prints it in Markdown format.
 645
 646        See also: `SearchByTicker()`, `SearchByFIGI()`, `RequestBondCoupons()`, `ExtendBondsData()`, `ShowBondsCalendar()` and `RequestTradingStatus()`.
 647
 648        :param iJSON: json data of instrument, example: `iJSON = self.iList["Shares"][self._ticker]`
 649        :param show: if `True` then also printing information about instrument and its current price.
 650        :return: multilines text in Markdown format with information about one instrument.
 651        """
 652        splitLine = "|                                                             |                                                        |\n"
 653        infoText = ""
 654
 655        if iJSON is not None and iJSON and isinstance(iJSON, dict):
 656            info = [
 657                "# Main information\n\n",
 658                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
 659                "| Parameters                                                  | Values                                                 |\n",
 660                "|-------------------------------------------------------------|--------------------------------------------------------|\n",
 661                "| Ticker:                                                     | {:<54} |\n".format(iJSON["ticker"]),
 662                "| Full name:                                                  | {:<54} |\n".format(iJSON["name"]),
 663            ]
 664
 665            if "sector" in iJSON.keys() and iJSON["sector"]:
 666                info.append("| Sector:                                                     | {:<54} |\n".format(iJSON["sector"]))
 667
 668            if "countryOfRisk" in iJSON.keys() and iJSON["countryOfRisk"] and "countryOfRiskName" in iJSON.keys() and iJSON["countryOfRiskName"]:
 669                info.append("| Country of instrument:                                      | {:<54} |\n".format("({}) {}".format(iJSON["countryOfRisk"], iJSON["countryOfRiskName"])))
 670
 671            info.extend([
 672                splitLine,
 673                "| FIGI (Financial Instrument Global Identifier):              | {:<54} |\n".format(iJSON["figi"]),
 674                "| Real exchange [Exchange section]:                           | {:<54} |\n".format("{} [{}]".format(TKS_REAL_EXCHANGES[iJSON["realExchange"]], iJSON["exchange"])),
 675            ])
 676
 677            if "isin" in iJSON.keys() and iJSON["isin"]:
 678                info.append("| ISIN (International Securities Identification Number):      | {:<54} |\n".format(iJSON["isin"]))
 679
 680            if "classCode" in iJSON.keys():
 681                info.append("| Class Code (exchange section where instrument is traded):   | {:<54} |\n".format(iJSON["classCode"]))
 682
 683            info.extend([
 684                splitLine,
 685                "| Current broker security trading status:                     | {:<54} |\n".format(TKS_TRADING_STATUSES[iJSON["tradingStatus"]]),
 686                splitLine,
 687                "| Buy operations allowed:                                     | {:<54} |\n".format("Yes" if iJSON["buyAvailableFlag"] else "No"),
 688                "| Sale operations allowed:                                    | {:<54} |\n".format("Yes" if iJSON["sellAvailableFlag"] else "No"),
 689                "| Short positions allowed:                                    | {:<54} |\n".format("Yes" if iJSON["shortEnabledFlag"] else "No"),
 690            ])
 691
 692            if iJSON["figi"]:
 693                self._figi = iJSON["figi"]
 694                iJSON = iJSON | self.RequestTradingStatus()
 695
 696                info.extend([
 697                    splitLine,
 698                    "| Limit orders allowed:                                       | {:<54} |\n".format("Yes" if iJSON["limitOrderAvailableFlag"] else "No"),
 699                    "| Market orders allowed:                                      | {:<54} |\n".format("Yes" if iJSON["marketOrderAvailableFlag"] else "No"),
 700                    "| API trade allowed:                                          | {:<54} |\n".format("Yes" if iJSON["apiTradeAvailableFlag"] else "No"),
 701                ])
 702
 703            info.append(splitLine)
 704
 705            if "type" in iJSON.keys() and iJSON["type"]:
 706                info.append("| Type of the instrument:                                     | {:<54} |\n".format(iJSON["type"]))
 707
 708                if "shareType" in iJSON.keys() and iJSON["shareType"]:
 709                    info.append("| Share type:                                                 | {:<54} |\n".format(TKS_SHARE_TYPES[iJSON["shareType"]]))
 710
 711            if "futuresType" in iJSON.keys() and iJSON["futuresType"]:
 712                info.append("| Futures type:                                               | {:<54} |\n".format(iJSON["futuresType"]))
 713
 714            if "ipoDate" in iJSON.keys() and iJSON["ipoDate"]:
 715                info.append("| IPO date:                                                   | {:<54} |\n".format(iJSON["ipoDate"].replace("T", " ").replace("Z", "")))
 716
 717            if "releasedDate" in iJSON.keys() and iJSON["releasedDate"]:
 718                info.append("| Released date:                                              | {:<54} |\n".format(iJSON["releasedDate"].replace("T", " ").replace("Z", "")))
 719
 720            if "rebalancingFreq" in iJSON.keys() and iJSON["rebalancingFreq"]:
 721                info.append("| Rebalancing frequency:                                      | {:<54} |\n".format(iJSON["rebalancingFreq"]))
 722
 723            if "focusType" in iJSON.keys() and iJSON["focusType"]:
 724                info.append("| Focusing type:                                              | {:<54} |\n".format(iJSON["focusType"]))
 725
 726            if "assetType" in iJSON.keys() and iJSON["assetType"]:
 727                info.append("| Asset type:                                                 | {:<54} |\n".format(iJSON["assetType"]))
 728
 729            if "basicAsset" in iJSON.keys() and iJSON["basicAsset"]:
 730                info.append("| Basic asset:                                                | {:<54} |\n".format(iJSON["basicAsset"]))
 731
 732            if "basicAssetSize" in iJSON.keys() and iJSON["basicAssetSize"]:
 733                info.append("| Basic asset size:                                           | {:<54} |\n".format("{:.2f}".format(NanoToFloat(str(iJSON["basicAssetSize"]["units"]), iJSON["basicAssetSize"]["nano"]))))
 734
 735            if "isoCurrencyName" in iJSON.keys() and iJSON["isoCurrencyName"]:
 736                info.append("| ISO currency name:                                          | {:<54} |\n".format(iJSON["isoCurrencyName"]))
 737
 738            if "currency" in iJSON.keys():
 739                info.append("| Payment currency:                                           | {:<54} |\n".format(iJSON["currency"]))
 740
 741            if iJSON["type"] == "Bonds" and "nominal" in iJSON.keys() and "currency" in iJSON["nominal"].keys():
 742                info.append("| Nominal currency:                                           | {:<54} |\n".format(iJSON["nominal"]["currency"]))
 743
 744            if "firstTradeDate" in iJSON.keys() and iJSON["firstTradeDate"]:
 745                info.append("| First trade date:                                           | {:<54} |\n".format(iJSON["firstTradeDate"].replace("T", " ").replace("Z", "")))
 746
 747            if "lastTradeDate" in iJSON.keys() and iJSON["lastTradeDate"]:
 748                info.append("| Last trade date:                                            | {:<54} |\n".format(iJSON["lastTradeDate"].replace("T", " ").replace("Z", "")))
 749
 750            if "expirationDate" in iJSON.keys() and iJSON["expirationDate"]:
 751                info.append("| Date of expiration:                                         | {:<54} |\n".format(iJSON["expirationDate"].replace("T", " ").replace("Z", "")))
 752
 753            if "stateRegDate" in iJSON.keys() and iJSON["stateRegDate"]:
 754                info.append("| State registration date:                                    | {:<54} |\n".format(iJSON["stateRegDate"].replace("T", " ").replace("Z", "")))
 755
 756            if "placementDate" in iJSON.keys() and iJSON["placementDate"]:
 757                info.append("| Placement date:                                             | {:<54} |\n".format(iJSON["placementDate"].replace("T", " ").replace("Z", "")))
 758
 759            if "maturityDate" in iJSON.keys() and iJSON["maturityDate"]:
 760                info.append("| Maturity date:                                              | {:<54} |\n".format(iJSON["maturityDate"].replace("T", " ").replace("Z", "")))
 761
 762            if "perpetualFlag" in iJSON.keys() and iJSON["perpetualFlag"]:
 763                info.append("| Perpetual bond:                                             | Yes                                                    |\n")
 764
 765            if "otcFlag" in iJSON.keys() and iJSON["otcFlag"]:
 766                info.append("| Over-the-counter (OTC) securities:                          | Yes                                                    |\n")
 767
 768            iExt = None
 769            if iJSON["type"] == "Bonds":
 770                info.extend([
 771                    splitLine,
 772                    "| Bond issue (size / plan):                                   | {:<54} |\n".format("{} / {}".format(iJSON["issueSize"], iJSON["issueSizePlan"])),
 773                    "| Nominal price (100%):                                       | {:<54} |\n".format("{} {}".format(
 774                        "{:.2f}".format(NanoToFloat(str(iJSON["nominal"]["units"]), iJSON["nominal"]["nano"])).rstrip("0").rstrip("."),
 775                        iJSON["nominal"]["currency"],
 776                    )),
 777                ])
 778
 779                if "floatingCouponFlag" in iJSON.keys():
 780                    info.append("| Floating coupon:                                            | {:<54} |\n".format("Yes" if iJSON["floatingCouponFlag"] else "No"))
 781
 782                if "amortizationFlag" in iJSON.keys():
 783                    info.append("| Amortization:                                               | {:<54} |\n".format("Yes" if iJSON["amortizationFlag"] else "No"))
 784
 785                info.append(splitLine)
 786
 787                if "couponQuantityPerYear" in iJSON.keys() and iJSON["couponQuantityPerYear"]:
 788                    info.append("| Number of coupon payments per year:                         | {:<54} |\n".format(iJSON["couponQuantityPerYear"]))
 789
 790                if iJSON["figi"]:
 791                    iExt = self.ExtendBondsData(instruments=iJSON["figi"], xlsx=False)  # extended bonds data
 792
 793                    info.extend([
 794                        "| Days last to maturity date:                                 | {:<54} |\n".format(iExt["daysToMaturity"][0]),
 795                        "| Coupons yield (average coupon daily yield * 365):           | {:<54} |\n".format("{:.2f}%".format(iExt["couponsYield"][0])),
 796                        "| Current price yield (average daily yield * 365):            | {:<54} |\n".format("{:.2f}%".format(iExt["currentYield"][0])),
 797                    ])
 798
 799                if "aciValue" in iJSON.keys() and iJSON["aciValue"]:
 800                    info.append("| Current accumulated coupon income (ACI):                    | {:<54} |\n".format("{:.2f} {}".format(
 801                        NanoToFloat(str(iJSON["aciValue"]["units"]), iJSON["aciValue"]["nano"]),
 802                        iJSON["aciValue"]["currency"]
 803                    )))
 804
 805            if "currentPrice" in iJSON.keys():
 806                info.append(splitLine)
 807
 808                currency = iJSON["currency"] if "currency" in iJSON.keys() else ""  # nominal currency for bonds, otherwise currency of instrument
 809                aciCurrency = iExt["aciCurrency"][0] if iJSON["type"] == "Bonds" and iExt is not None and "aciCurrency" in iExt.keys() else ""  # payment currency
 810
 811                bondPrevClose = iExt["closePrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "closePrice" in iExt.keys() else 0  # previous close price of bond
 812                bondLastPrice = iExt["lastPrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "lastPrice" in iExt.keys() else 0  # last price of bond
 813                bondLimitUp = iExt["limitUp"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitUp" in iExt.keys() else 0  # max price of bond
 814                bondLimitDown = iExt["limitDown"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitDown" in iExt.keys() else 0  # min price of bond
 815                bondChangesDelta = iExt["changesDelta"][0] if iJSON["type"] == "Bonds" and iExt is not None and "changesDelta" in iExt.keys() else 0  # delta between last deal price and last close
 816
 817                curPriceSell = iJSON["currentPrice"]["sell"][0]["price"] if iJSON["currentPrice"]["sell"] else 0
 818                curPriceBuy = iJSON["currentPrice"]["buy"][0]["price"] if iJSON["currentPrice"]["buy"] else 0
 819
 820                info.extend([
 821                    "| Previous close price of the instrument:                     | {:<54} |\n".format("{}{}".format(
 822                        "{}".format(iJSON["currentPrice"]["closePrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["closePrice"] is not None else "N/A",
 823                        "% of nominal price ({:.2f} {})".format(bondPrevClose, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 824                    )),
 825                    "| Last deal price of the instrument:                          | {:<54} |\n".format("{}{}".format(
 826                        "{}".format(iJSON["currentPrice"]["lastPrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["lastPrice"] is not None else "N/A",
 827                        "% of nominal price ({:.2f} {})".format(bondLastPrice, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 828                    )),
 829                    "| Changes between last deal price and last close              | {:<54} |\n".format(
 830                        "{:.2f}%{}".format(
 831                            iJSON["currentPrice"]["changes"],
 832                            " ({}{:.2f} {})".format(
 833                                "+" if bondChangesDelta > 0 else "",
 834                                bondChangesDelta,
 835                                aciCurrency
 836                            ) if iJSON["type"] == "Bonds" else " ({}{:.2f} {})".format(
 837                                "+" if iJSON["currentPrice"]["lastPrice"] > iJSON["currentPrice"]["closePrice"] else "",
 838                                iJSON["currentPrice"]["lastPrice"] - iJSON["currentPrice"]["closePrice"],
 839                                currency
 840                            ),
 841                        )
 842                    ),
 843                    "| Current limit price, min / max:                             | {:<54} |\n".format("{}{} / {}{}{}".format(
 844                        "{}".format(iJSON["currentPrice"]["limitDown"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitDown"] is not None else "N/A",
 845                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 846                        "{}".format(iJSON["currentPrice"]["limitUp"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitUp"] is not None else "N/A",
 847                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 848                        " ({:.2f} {} / {:.2f} {})".format(bondLimitDown, aciCurrency, bondLimitUp, aciCurrency) if iJSON["type"] == "Bonds" else ""
 849                    )),
 850                    "| Actual price, sell / buy:                                   | {:<54} |\n".format("{}{} / {}{}{}".format(
 851                        "{}".format(curPriceSell).rstrip("0").rstrip(".") if curPriceSell != 0 else "N/A",
 852                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 853                        "{}".format(curPriceBuy).rstrip("0").rstrip(".") if curPriceBuy != 0 else "N/A",
 854                        "%" if iJSON["type"] == "Bonds" else" {}".format(currency),
 855                        " ({:.2f} {} / {:.2f} {})".format(curPriceSell, aciCurrency, curPriceBuy, aciCurrency) if iJSON["type"] == "Bonds" else ""
 856                    )),
 857                ])
 858
 859            if "lot" in iJSON.keys():
 860                info.append("| Minimum lot to buy:                                         | {:<54} |\n".format(iJSON["lot"]))
 861
 862            if "step" in iJSON.keys() and iJSON["step"] != 0:
 863                info.append("| Minimum price increment (step):                             | {:<54} |\n".format("{} {}".format(iJSON["step"], iJSON["currency"] if "currency" in iJSON.keys() else "")))
 864
 865            # Add bond payment calendar:
 866            if iJSON["type"] == "Bonds":
 867                strCalendar = self.ShowBondsCalendar(extBonds=iExt, show=False)   # bond payment calendar
 868                info.extend(["\n#", strCalendar])
 869
 870            infoText += "".join(info)
 871
 872            if show:
 873                uLogger.info("{}".format(infoText))
 874
 875            else:
 876                uLogger.debug("{}".format(infoText))
 877
 878            if self.infoFile is not None:
 879                with open(self.infoFile, "w", encoding="UTF-8") as fH:
 880                    fH.write(infoText)
 881
 882                uLogger.info("Info about instrument with ticker [{}] and FIGI [{}] was saved to file: [{}]".format(iJSON["ticker"], iJSON["figi"], os.path.abspath(self.infoFile)))
 883
 884                if self.useHTMLReports:
 885                    htmlFilePath = self.infoFile.replace(".md", ".html") if self.infoFile.endswith(".md") else self.infoFile + ".html"
 886                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
 887                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Main information", commonCSS=COMMON_CSS, markdown=infoText))
 888
 889                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
 890
 891        return infoText
 892
 893    def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:
 894        """
 895        Search and return raw broker's information about instrument by its ticker. Variable `ticker` must be defined!
 896
 897        :param requestPrice: if `False` then do not request current price of instrument (because this is long operation).
 898        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 899        :return: JSON formatted data with information about instrument.
 900        """
 901        tickerJSON = {}
 902        if self.moreDebug:
 903            uLogger.debug("Searching information about instrument by it's ticker [{}] ...".format(self._ticker))
 904
 905        if not self._ticker:
 906            uLogger.warning("self._ticker variable is not be empty!")
 907
 908        else:
 909            if self._ticker in TKS_TICKERS_OR_FIGI_EXCLUDED:
 910                uLogger.warning("Instrument with ticker [{}] not allowed for trading!".format(self._ticker))
 911                raise Exception("Instrument not allowed")
 912
 913            if not self.iList:
 914                self.iList = self.Listing()
 915
 916            if self._ticker in self.iList["Shares"].keys():
 917                tickerJSON = self.iList["Shares"][self._ticker]
 918                if self.moreDebug:
 919                    uLogger.debug("Ticker [{}] found in shares list".format(self._ticker))
 920
 921            elif self._ticker in self.iList["Currencies"].keys():
 922                tickerJSON = self.iList["Currencies"][self._ticker]
 923                if self.moreDebug:
 924                    uLogger.debug("Ticker [{}] found in currencies list".format(self._ticker))
 925
 926            elif self._ticker in self.iList["Bonds"].keys():
 927                tickerJSON = self.iList["Bonds"][self._ticker]
 928                if self.moreDebug:
 929                    uLogger.debug("Ticker [{}] found in bonds list".format(self._ticker))
 930
 931            elif self._ticker in self.iList["Etfs"].keys():
 932                tickerJSON = self.iList["Etfs"][self._ticker]
 933                if self.moreDebug:
 934                    uLogger.debug("Ticker [{}] found in etfs list".format(self._ticker))
 935
 936            elif self._ticker in self.iList["Futures"].keys():
 937                tickerJSON = self.iList["Futures"][self._ticker]
 938                if self.moreDebug:
 939                    uLogger.debug("Ticker [{}] found in futures list".format(self._ticker))
 940
 941        if tickerJSON:
 942            self._figi = tickerJSON["figi"]
 943
 944            if requestPrice:
 945                tickerJSON["currentPrice"] = self.GetCurrentPrices(show=False)
 946
 947                if tickerJSON["currentPrice"]["closePrice"] is not None and tickerJSON["currentPrice"]["closePrice"] != 0 and tickerJSON["currentPrice"]["lastPrice"] is not None:
 948                    tickerJSON["currentPrice"]["changes"] = 100 * (tickerJSON["currentPrice"]["lastPrice"] - tickerJSON["currentPrice"]["closePrice"]) / tickerJSON["currentPrice"]["closePrice"]
 949
 950                else:
 951                    tickerJSON["currentPrice"]["changes"] = 0
 952
 953            if show:
 954                self.ShowInstrumentInfo(iJSON=tickerJSON, show=True)  # print info as Markdown text
 955
 956        else:
 957            if show:
 958                uLogger.warning("Ticker [{}] not found in available broker instrument's list!".format(self._ticker))
 959
 960        return tickerJSON
 961
 962    def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:
 963        """
 964        Search and return raw broker's information about instrument by its FIGI. Variable `figi` must be defined!
 965
 966        :param requestPrice: if `False` then do not request current price of instrument (it's long operation).
 967        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 968        :return: JSON formatted data with information about instrument.
 969        """
 970        figiJSON = {}
 971        if self.moreDebug:
 972            uLogger.debug("Searching information about instrument by it's FIGI [{}] ...".format(self._figi))
 973
 974        if not self._figi:
 975            uLogger.warning("self._figi variable is not be empty!")
 976
 977        else:
 978            if self._figi in TKS_TICKERS_OR_FIGI_EXCLUDED:
 979                uLogger.warning("Instrument with figi [{}] not allowed for trading!".format(self._figi))
 980                raise Exception("Instrument not allowed")
 981
 982            if not self.iList:
 983                self.iList = self.Listing()
 984
 985            for item in self.iList["Shares"].keys():
 986                if self._figi == self.iList["Shares"][item]["figi"]:
 987                    figiJSON = self.iList["Shares"][item]
 988
 989                    if self.moreDebug:
 990                        uLogger.debug("FIGI [{}] found in shares list".format(self._figi))
 991
 992                    break
 993
 994            if not figiJSON:
 995                for item in self.iList["Currencies"].keys():
 996                    if self._figi == self.iList["Currencies"][item]["figi"]:
 997                        figiJSON = self.iList["Currencies"][item]
 998
 999                        if self.moreDebug:
1000                            uLogger.debug("FIGI [{}] found in currencies list".format(self._figi))
1001
1002                        break
1003
1004            if not figiJSON:
1005                for item in self.iList["Bonds"].keys():
1006                    if self._figi == self.iList["Bonds"][item]["figi"]:
1007                        figiJSON = self.iList["Bonds"][item]
1008
1009                        if self.moreDebug:
1010                            uLogger.debug("FIGI [{}] found in bonds list".format(self._figi))
1011
1012                        break
1013
1014            if not figiJSON:
1015                for item in self.iList["Etfs"].keys():
1016                    if self._figi == self.iList["Etfs"][item]["figi"]:
1017                        figiJSON = self.iList["Etfs"][item]
1018
1019                        if self.moreDebug:
1020                            uLogger.debug("FIGI [{}] found in etfs list".format(self._figi))
1021
1022                        break
1023
1024            if not figiJSON:
1025                for item in self.iList["Futures"].keys():
1026                    if self._figi == self.iList["Futures"][item]["figi"]:
1027                        figiJSON = self.iList["Futures"][item]
1028
1029                        if self.moreDebug:
1030                            uLogger.debug("FIGI [{}] found in futures list".format(self._figi))
1031
1032                        break
1033
1034        if figiJSON:
1035            self._figi = figiJSON["figi"]
1036            self._ticker = figiJSON["ticker"]
1037
1038            if requestPrice:
1039                figiJSON["currentPrice"] = self.GetCurrentPrices(show=False)
1040
1041                if figiJSON["currentPrice"]["closePrice"] is not None and figiJSON["currentPrice"]["closePrice"] != 0 and figiJSON["currentPrice"]["lastPrice"] is not None:
1042                    figiJSON["currentPrice"]["changes"] = 100 * (figiJSON["currentPrice"]["lastPrice"] - figiJSON["currentPrice"]["closePrice"]) / figiJSON["currentPrice"]["closePrice"]
1043
1044                else:
1045                    figiJSON["currentPrice"]["changes"] = 0
1046
1047            if show:
1048                self.ShowInstrumentInfo(iJSON=figiJSON, show=True)  # print info as Markdown text
1049
1050        else:
1051            if show:
1052                uLogger.warning("FIGI [{}] not found in available broker instrument's list!".format(self._figi))
1053
1054        return figiJSON
1055
1056    def GetCurrentPrices(self, show: bool = True) -> dict:
1057        """
1058        Get and show Depth of Market with current prices of the instrument as dictionary. Result example with `depth` 5:
1059        `{"buy": [{"price": 1243.8, "quantity": 193},
1060                  {"price": 1244.0, "quantity": 168},
1061                  {"price": 1244.8, "quantity": 5},
1062                  {"price": 1245.0, "quantity": 61},
1063                  {"price": 1245.4, "quantity": 60}],
1064          "sell": [{"price": 1243.6, "quantity": 8},
1065                   {"price": 1242.6, "quantity": 10},
1066                   {"price": 1242.4, "quantity": 18},
1067                   {"price": 1242.2, "quantity": 50},
1068                   {"price": 1242.0, "quantity": 113}],
1069          "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}`, where parameters mean:
1070        - buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
1071        - sell: list of dicts with Buyers prices,
1072            - price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
1073            - quantity: volume value by current price in lots,
1074        - limitUp: current trade session limit price, maximum,
1075        - limitDown: current trade session limit price, minimum,
1076        - lastPrice: last deal price of the instrument,
1077        - closePrice: previous trade session close price of the instrument.
1078
1079        See also: `SearchByTicker()` and `SearchByFIGI()`.
1080        REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1081        Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1082
1083        :param show: if `True` then print DOM to log and console.
1084        :return: orders book dict with lists of current buy and sell prices: `{"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}`.
1085                 If an error occurred then returns an empty record:
1086                 `{"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}`.
1087        """
1088        prices = {"buy": [], "sell": [], "limitUp": 0, "limitDown": 0, "lastPrice": 0, "closePrice": 0}
1089
1090        if self.depth < 1:
1091            uLogger.error("Depth of Market (DOM) must be >=1!")
1092            raise Exception("Incorrect value")
1093
1094        if not (self._ticker or self._figi):
1095            uLogger.error("self._ticker or self._figi variables must be defined!")
1096            raise Exception("Ticker or FIGI required")
1097
1098        if self._ticker and not self._figi:
1099            instrumentByTicker = self.SearchByTicker(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1100            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
1101
1102        if not self._ticker and self._figi:
1103            instrumentByFigi = self.SearchByFIGI(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1104            self._ticker = instrumentByFigi["ticker"] if instrumentByFigi else ""
1105
1106        if not self._figi:
1107            uLogger.error("FIGI is not defined!")
1108            raise Exception("Ticker or FIGI required")
1109
1110        else:
1111            uLogger.debug("Requesting current prices: ticker [{}], FIGI [{}]. Wait, please...".format(self._ticker, self._figi))
1112
1113            # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1114            priceURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetOrderBook"
1115            self.body = str({"figi": self._figi, "depth": self.depth})
1116            pricesResponse = self.SendAPIRequest(priceURL, reqType="POST")  # Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1117
1118            if pricesResponse and not ("code" in pricesResponse.keys() or "message" in pricesResponse.keys() or "description" in pricesResponse.keys()):
1119                # list of dicts with sellers orders:
1120                prices["buy"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["asks"]]
1121
1122                # list of dicts with buyers orders:
1123                prices["sell"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["bids"]]
1124
1125                # max price of instrument at this time:
1126                prices["limitUp"] = round(NanoToFloat(pricesResponse["limitUp"]["units"], pricesResponse["limitUp"]["nano"]), 6) if "limitUp" in pricesResponse.keys() else None
1127
1128                # min price of instrument at this time:
1129                prices["limitDown"] = round(NanoToFloat(pricesResponse["limitDown"]["units"], pricesResponse["limitDown"]["nano"]), 6) if "limitDown" in pricesResponse.keys() else None
1130
1131                # last price of deal with instrument:
1132                prices["lastPrice"] = round(NanoToFloat(pricesResponse["lastPrice"]["units"], pricesResponse["lastPrice"]["nano"]), 6) if "lastPrice" in pricesResponse.keys() else 0
1133
1134                # last close price of instrument:
1135                prices["closePrice"] = round(NanoToFloat(pricesResponse["closePrice"]["units"], pricesResponse["closePrice"]["nano"]), 6) if "closePrice" in pricesResponse.keys() else 0
1136
1137            else:
1138                uLogger.warning("Server return an empty or error response! See full log. Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1139                uLogger.debug("Server response: {}".format(pricesResponse))
1140
1141            if show:
1142                if prices["buy"] or prices["sell"]:
1143                    info = [
1144                        "Orders book actual at [{}] (UTC)\nTicker: [{}], FIGI: [{}], Depth of Market: [{}]\n".format(
1145                            datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
1146                            self._ticker,
1147                            self._figi,
1148                            self.depth,
1149                        ),
1150                        "-" * 60, "\n",
1151                        "             Orders of Buyers | Orders of Sellers\n",
1152                        "-" * 60, "\n",
1153                        "        Sell prices (volumes) | Buy prices (volumes)\n",
1154                        "-" * 60, "\n",
1155                    ]
1156
1157                    if not prices["buy"]:
1158                        info.append("                              | No orders!\n")
1159                        sumBuy = 0
1160
1161                    else:
1162                        sumBuy = sum([x["quantity"] for x in prices["buy"]])
1163                        maxMinSorted = sorted(prices["buy"], key=lambda k: k["price"], reverse=True)
1164                        for item in maxMinSorted:
1165                            info.append("                              | {} ({})\n".format(item["price"], item["quantity"]))
1166
1167                    if not prices["sell"]:
1168                        info.append("No orders!                    |\n")
1169                        sumSell = 0
1170
1171                    else:
1172                        sumSell = sum([x["quantity"] for x in prices["sell"]])
1173                        for item in prices["sell"]:
1174                            info.append("{:>29} |\n".format("{} ({})".format(item["price"], item["quantity"])))
1175
1176                    info.extend([
1177                        "-" * 60, "\n",
1178                        "{:>29} | {}\n".format("Total sell: {}".format(sumSell), "Total buy: {}".format(sumBuy)),
1179                        "-" * 60, "\n",
1180                    ])
1181
1182                    infoText = "".join(info)
1183
1184                    uLogger.info("Current prices in order book:\n\n{}".format(infoText))
1185
1186                else:
1187                    uLogger.warning("Orders book is empty at this time! Instrument: ticker [{}], FIGI [{}]".format(self._ticker, self._figi))
1188
1189        return prices
1190
1191    def ShowInstrumentsInfo(self, show: bool = True) -> str:
1192        """
1193        This method get and show information about all available broker instruments for current user account.
1194        If `instrumentsFile` string is not empty then also save information to this file.
1195
1196        :param show: if `True` then print results to console, if `False` — print only to file.
1197        :return: multi-lines string with all available broker instruments
1198        """
1199        if not self.iList:
1200            self.iList = self.Listing()
1201
1202        info = [
1203            "# All available instruments from Tinkoff Broker server for current user token\n\n",
1204            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1205        ]
1206
1207        # add instruments count by type:
1208        for iType in self.iList.keys():
1209            info.append("* **{}:** [{}]\n".format(iType, len(self.iList[iType])))
1210
1211        headerLine = "| Ticker       | Full name                                                 | FIGI         | Cur | Lot     | Step       |\n"
1212        splitLine = "|--------------|-----------------------------------------------------------|--------------|-----|---------|------------|\n"
1213
1214        # generating info tables with all instruments by type:
1215        for iType in self.iList.keys():
1216            info.extend(["\n\n## {} available. Total: [{}]\n\n".format(iType, len(self.iList[iType])), headerLine, splitLine])
1217
1218            for instrument in self.iList[iType].keys():
1219                iName = self.iList[iType][instrument]["name"]  # instrument's name
1220                if len(iName) > 57:
1221                    iName = "{}...".format(iName[:54])  # right trim for a long string
1222
1223                info.append("| {:<12} | {:<57} | {:<12} | {:<3} | {:<7} | {:<10} |\n".format(
1224                    self.iList[iType][instrument]["ticker"],
1225                    iName,
1226                    self.iList[iType][instrument]["figi"],
1227                    self.iList[iType][instrument]["currency"],
1228                    self.iList[iType][instrument]["lot"],
1229                    "{:.10f}".format(self.iList[iType][instrument]["step"]).rstrip("0").rstrip(".") if self.iList[iType][instrument]["step"] > 0 else 0,
1230                ))
1231
1232        infoText = "".join(info)
1233
1234        if show:
1235            uLogger.info(infoText)
1236
1237        if self.instrumentsFile:
1238            with open(self.instrumentsFile, "w", encoding="UTF-8") as fH:
1239                fH.write(infoText)
1240
1241            uLogger.info("All available instruments are saved to file: [{}]".format(os.path.abspath(self.instrumentsFile)))
1242
1243            if self.useHTMLReports:
1244                htmlFilePath = self.instrumentsFile.replace(".md", ".html") if self.instrumentsFile.endswith(".md") else self.instrumentsFile + ".html"
1245                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1246                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="List of instruments", commonCSS=COMMON_CSS, markdown=infoText))
1247
1248                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1249
1250        return infoText
1251
1252    def SearchInstruments(self, pattern: str, show: bool = True) -> dict:
1253        """
1254        This method search and show information about instruments by part of its ticker, FIGI or name.
1255        If `searchResultsFile` string is not empty then also save information to this file.
1256
1257        :param pattern: string with part of ticker, FIGI or instrument's name.
1258        :param show: if `True` then print results to console, if `False` — return list of result only.
1259        :return: list of dictionaries with all found instruments.
1260        """
1261        if not self.iList:
1262            self.iList = self.Listing()
1263
1264        searchResults = {iType: {} for iType in self.iList}  # same as iList but will contain only filtered instruments
1265        compiledPattern = re.compile(pattern, re.IGNORECASE)
1266
1267        for iType in self.iList:
1268            for instrument in self.iList[iType].values():
1269                searchResult = compiledPattern.search(" ".join(
1270                    [instrument["ticker"], instrument["figi"], instrument["name"]]
1271                ))
1272
1273                if searchResult:
1274                    searchResults[iType][instrument["ticker"]] = instrument
1275
1276        resultsLen = sum([len(searchResults[iType]) for iType in searchResults])
1277        info = [
1278            "# Search results\n\n",
1279            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
1280            "* **Search pattern:** [{}]\n".format(pattern),
1281            "* **Found instruments:** [{}]\n\n".format(resultsLen),
1282            '**Note:** you can view info about found instruments with key "--info", e.g.: "tksbrokerapi -t TICKER --info" or "tksbrokerapi -f FIGI --info".\n'
1283        ]
1284        infoShort = info[:]
1285
1286        headerLine = "| Type       | Ticker       | Full name                                                      | FIGI         |\n"
1287        splitLine = "|------------|--------------|----------------------------------------------------------------|--------------|\n"
1288        skippedLine = "| ...        | ...          | ...                                                            | ...          |\n"
1289
1290        if resultsLen == 0:
1291            info.append("\nNo results\n")
1292            infoShort.append("\nNo results\n")
1293            uLogger.warning("No results. Try changing your search pattern.")
1294
1295        else:
1296            for iType in searchResults:
1297                iTypeValuesCount = len(searchResults[iType].values())
1298                if iTypeValuesCount > 0:
1299                    info.extend(["\n## {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1300                    infoShort.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1301
1302                    for instrument in searchResults[iType].values():
1303                        info.append("| {:<10} | {:<12} | {:<63}| {:<13}|\n".format(
1304                            instrument["type"],
1305                            instrument["ticker"],
1306                            "{}...".format(instrument["name"][:60]) if len(instrument["name"]) > 63 else instrument["name"],  # right trim for a long string
1307                            instrument["figi"],
1308                        ))
1309
1310                    if iTypeValuesCount <= 5:
1311                        infoShort.extend(info[-iTypeValuesCount:])
1312
1313                    else:
1314                        infoShort.extend(info[-5:])
1315                        infoShort.append(skippedLine)
1316
1317        infoText = "".join(info)
1318        infoTextShort = "".join(infoShort)
1319
1320        if show:
1321            uLogger.info(infoTextShort)
1322            uLogger.info("You can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t IBM --info` or `tksbrokerapi -f BBG000BLNNH6 --info`")
1323
1324        if self.searchResultsFile:
1325            with open(self.searchResultsFile, "w", encoding="UTF-8") as fH:
1326                fH.write(infoText)
1327
1328            uLogger.info("Full search results were saved to file: [{}]".format(os.path.abspath(self.searchResultsFile)))
1329
1330            if self.useHTMLReports:
1331                htmlFilePath = self.searchResultsFile.replace(".md", ".html") if self.searchResultsFile.endswith(".md") else self.searchResultsFile + ".html"
1332                with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1333                    fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Search results", commonCSS=COMMON_CSS, markdown=infoText))
1334
1335                uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1336
1337        return searchResults
1338
1339    def GetUniqueFIGIs(self, instruments: list[str]) -> list:
1340        """
1341        Creating list with unique instrument FIGIs from input list of tickers (priority) or FIGIs.
1342
1343        :param instruments: list of strings with tickers or FIGIs.
1344        :return: list with unique instrument FIGIs only.
1345        """
1346        requestedInstruments = []
1347        for iName in instruments:
1348            if iName not in self.aliases.keys():
1349                if iName not in requestedInstruments:
1350                    requestedInstruments.append(iName)
1351
1352            else:
1353                if iName not in requestedInstruments:
1354                    if self.aliases[iName] not in requestedInstruments:
1355                        requestedInstruments.append(self.aliases[iName])
1356
1357        uLogger.debug("Requested instruments without duplicates of tickers or FIGIs: {}".format(requestedInstruments))
1358
1359        onlyUniqueFIGIs = []
1360        for iName in requestedInstruments:
1361            if iName in TKS_TICKERS_OR_FIGI_EXCLUDED:
1362                continue
1363
1364            self._ticker = iName
1365            iData = self.SearchByTicker(requestPrice=False)  # trying to find instrument by ticker
1366
1367            if not iData:
1368                self._ticker = ""
1369                self._figi = iName
1370
1371                iData = self.SearchByFIGI(requestPrice=False)  # trying to find instrument by FIGI
1372
1373                if not iData:
1374                    self._figi = ""
1375                    uLogger.warning("Instrument [{}] not in list of available instruments for current token!".format(iName))
1376
1377            if iData and iData["figi"] not in onlyUniqueFIGIs:
1378                onlyUniqueFIGIs.append(iData["figi"])
1379
1380        uLogger.debug("Unique list of FIGIs: {}".format(onlyUniqueFIGIs))
1381
1382        return onlyUniqueFIGIs
1383
1384    def GetListOfPrices(self, instruments: list[str], show: bool = False) -> list[dict]:
1385        """
1386        This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!
1387
1388        See limits: https://tinkoff.github.io/investAPI/limits/
1389
1390        If `pricesFile` string is not empty then also save information to this file.
1391
1392        :param instruments: list of strings with tickers or FIGIs.
1393        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1394        :return: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1395                 One item is dict returned by `SearchByTicker()` or `SearchByFIGI()` methods.
1396        """
1397        if instruments is None or not instruments:
1398            uLogger.error("You must define some of tickers or FIGIs to request it's actual prices!")
1399            raise Exception("Ticker or FIGI required")
1400
1401        onlyUniqueFIGIs = self.GetUniqueFIGIs(instruments)
1402
1403        uLogger.debug("Requesting current prices from Tinkoff Broker server...")
1404
1405        iList = []  # trying to get info and current prices about all unique instruments:
1406        for self._figi in onlyUniqueFIGIs:
1407            iData = self.SearchByFIGI(requestPrice=True)
1408            iList.append(iData)
1409
1410        self.ShowListOfPrices(iList, show)
1411
1412        return iList
1413
1414    def ShowListOfPrices(self, iList: list, show: bool = True) -> str:
1415        """
1416        Show table contains current prices of given instruments.
1417
1418        :param iList: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1419                      One item is dict returned by `SearchByTicker(requestPrice=True)` or by `SearchByFIGI(requestPrice=True)` methods.
1420        :param show: if `True` then prints prices to console, if `False` — prints only to file `pricesFile`.
1421        :return: multilines text in Markdown format as a table contains current prices.
1422        """
1423        infoText = ""
1424
1425        if show or self.pricesFile:
1426            info = [
1427                "# Current prices\n\n* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1428                "| Ticker       | FIGI         | Type       | Prev. close | Last price  | Chg. %   | Day limits min/max  | Actual sell / buy   | Curr. |\n",
1429                "|--------------|--------------|------------|-------------|-------------|----------|---------------------|---------------------|-------|\n",
1430            ]
1431
1432            for item in iList:
1433                info.append("| {:<12} | {:<12} | {:<10} | {:>11} | {:>11} | {:>7}% | {:>19} | {:>19} | {:<5} |\n".format(
1434                    item["ticker"],
1435                    item["figi"],
1436                    item["type"],
1437                    "{:.2f}".format(float(item["currentPrice"]["closePrice"])),
1438                    "{:.2f}".format(float(item["currentPrice"]["lastPrice"])),
1439                    "{}{:.2f}".format("+" if item["currentPrice"]["changes"] > 0 else "", float(item["currentPrice"]["changes"])),
1440                    "{} / {}".format(
1441                        item["currentPrice"]["limitDown"] if item["currentPrice"]["limitDown"] is not None else "N/A",
1442                        item["currentPrice"]["limitUp"] if item["currentPrice"]["limitUp"] is not None else "N/A",
1443                    ),
1444                    "{} / {}".format(
1445                        item["currentPrice"]["sell"][0]["price"] if item["currentPrice"]["sell"] else "N/A",
1446                        item["currentPrice"]["buy"][0]["price"] if item["currentPrice"]["buy"] else "N/A",
1447                    ),
1448                    item["currency"],
1449                ))
1450
1451            infoText = "".join(info)
1452
1453            if show:
1454                uLogger.info("Only instruments with unique FIGIs are shown:\n{}".format(infoText))
1455
1456            if self.pricesFile:
1457                with open(self.pricesFile, "w", encoding="UTF-8") as fH:
1458                    fH.write(infoText)
1459
1460                uLogger.info("Price list for all instruments saved to file: [{}]".format(os.path.abspath(self.pricesFile)))
1461
1462                if self.useHTMLReports:
1463                    htmlFilePath = self.pricesFile.replace(".md", ".html") if self.pricesFile.endswith(".md") else self.pricesFile + ".html"
1464                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
1465                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Current prices", commonCSS=COMMON_CSS, markdown=infoText))
1466
1467                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
1468
1469        return infoText
1470
1471    def RequestTradingStatus(self) -> dict:
1472        """
1473        Requesting trading status for the instrument defined by `figi` variable.
1474
1475        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus
1476
1477        Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest
1478
1479        :return: dictionary with trading status attributes. Response example:
1480                 `{"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING",
1481                  "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}`
1482        """
1483        if self._figi is None or not self._figi:
1484            uLogger.error("Variable `figi` must be defined for using this method!")
1485            raise Exception("FIGI required")
1486
1487        uLogger.debug("Requesting current trading status, FIGI: [{}]. Wait, please...".format(self._figi))
1488
1489        self.body = str({"figi": self._figi, "instrumentId": self._figi})
1490        tradingStatusURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetTradingStatus"
1491        tradingStatus = self.SendAPIRequest(tradingStatusURL, reqType="POST")
1492
1493        if self.moreDebug:
1494            uLogger.debug("Records about current trading status successfully received")
1495
1496        return tradingStatus
1497
1498    def RequestPortfolio(self) -> dict:
1499        """
1500        Requesting actual user's portfolio for current `accountId`.
1501
1502        REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio
1503
1504        Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest
1505
1506        :return: dictionary with user's portfolio.
1507        """
1508        if self.accountId is None or not self.accountId:
1509            uLogger.error("Variable `accountId` must be defined for using this method!")
1510            raise Exception("Account ID required")
1511
1512        uLogger.debug("Requesting current actual user's portfolio. Wait, please...")
1513
1514        self.body = str({"accountId": self.accountId})
1515        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPortfolio"
1516        rawPortfolio = self.SendAPIRequest(portfolioURL, reqType="POST")
1517
1518        if self.moreDebug:
1519            uLogger.debug("Records about user's portfolio successfully received")
1520
1521        return rawPortfolio
1522
1523    def RequestPositions(self) -> dict:
1524        """
1525        Requesting open positions by currencies and instruments for current `accountId`.
1526
1527        REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions
1528
1529        Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest
1530
1531        :return: dictionary with open positions by instruments.
1532        """
1533        if self.accountId is None or not self.accountId:
1534            uLogger.error("Variable `accountId` must be defined for using this method!")
1535            raise Exception("Account ID required")
1536
1537        uLogger.debug("Requesting current open positions in currencies and instruments. Wait, please...")
1538
1539        self.body = str({"accountId": self.accountId})
1540        positionsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPositions"
1541        rawPositions = self.SendAPIRequest(positionsURL, reqType="POST")
1542
1543        if self.moreDebug:
1544            uLogger.debug("Records about current open positions successfully received")
1545
1546        return rawPositions
1547
1548    def RequestPendingOrders(self) -> list:
1549        """
1550        Requesting current actual pending limit orders for current `accountId`.
1551
1552        REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders
1553
1554        Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest
1555
1556        :return: list of dictionaries with pending limit orders.
1557        """
1558        if self.accountId is None or not self.accountId:
1559            uLogger.error("Variable `accountId` must be defined for using this method!")
1560            raise Exception("Account ID required")
1561
1562        uLogger.debug("Requesting current actual pending limit orders. Wait, please...")
1563
1564        self.body = str({"accountId": self.accountId})
1565        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/GetOrders"
1566        rawOrders = self.SendAPIRequest(ordersURL, reqType="POST")["orders"]
1567
1568        uLogger.debug("[{}] records about pending limit orders received".format(len(rawOrders)))
1569
1570        return rawOrders
1571
1572    def RequestStopOrders(self) -> list:
1573        """
1574        Requesting current actual stop orders for current `accountId`.
1575
1576        REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders
1577
1578        Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest
1579
1580        :return: list of dictionaries with stop orders.
1581        """
1582        if self.accountId is None or not self.accountId:
1583            uLogger.error("Variable `accountId` must be defined for using this method!")
1584            raise Exception("Account ID required")
1585
1586        uLogger.debug("Requesting current actual stop orders. Wait, please...")
1587
1588        self.body = str({"accountId": self.accountId})
1589        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/GetStopOrders"
1590        rawStopOrders = self.SendAPIRequest(ordersURL, reqType="POST")["stopOrders"]
1591
1592        uLogger.debug("[{}] records about stop orders received".format(len(rawStopOrders)))
1593
1594        return rawStopOrders
1595
1596    def Overview(self, show: bool = False, details: str = "full") -> dict:
1597        """
1598        Get portfolio: all open positions, orders and some statistics for current `accountId`.
1599        If `overviewFile`, `overviewDigestFile`, `overviewPositionsFile`, `overviewOrdersFile`, `overviewAnalyticsFile`
1600        and `overviewBondsCalendarFile` are defined then also save information to file.
1601
1602        WARNING! It is not recommended to run this method too many times in a loop! The server receives
1603        many requests about the state of the portfolio, and then, based on the received data, a large number
1604        of calculation and statistics are collected.
1605
1606        :param show: if `False` then only dictionary returns, if `True` then show more debug information.
1607        :param details: how detailed should the information be?
1608        - `full` — shows full available information about portfolio status (by default),
1609        - `positions` — shows only open positions,
1610        - `orders` — shows only sections of open limits and stop orders.
1611        - `digest` — show a short digest of the portfolio status,
1612        - `analytics` — shows only the analytics section and the distribution of the portfolio by various categories,
1613        - `calendar` — shows only the bonds calendar section (if these present in portfolio),
1614        :return: dictionary with client's raw portfolio and some statistics.
1615        """
1616        if self.accountId is None or not self.accountId:
1617            uLogger.error("Variable `accountId` must be defined for using this method!")
1618            raise Exception("Account ID required")
1619
1620        view = {
1621            "raw": {  # --- raw portfolio responses from broker with user portfolio data:
1622                "headers": {},  # list of dictionaries, response headers without "positions" section
1623                "Currencies": [],  # list of dictionaries, open trades with currencies from "positions" section
1624                "Shares": [],  # list of dictionaries, open trades with shares from "positions" section
1625                "Bonds": [],  # list of dictionaries, open trades with bonds from "positions" section
1626                "Etfs": [],  # list of dictionaries, open trades with etfs from "positions" section
1627                "Futures": [],  # list of dictionaries, open trades with futures from "positions" section
1628                "positions": {},  # raw response from broker: dictionary with current available or blocked currencies and instruments for client
1629                "orders": [],  # raw response from broker: list of dictionaries with all pending (market) orders
1630                "stopOrders": [],  # raw response from broker: list of dictionaries with all stop orders
1631                "currenciesCurrentPrices": {"rub": {"name": "Российский рубль", "currentPrice": 1.}},  # dict with prices of all currencies in RUB
1632            },
1633            "stat": {  # --- some statistics calculated using "raw" sections:
1634                "portfolioCostRUB": 0.,  # portfolio cost in RUB (Russian Rouble)
1635                "availableRUB": 0.,  # available rubles (without other currencies)
1636                "blockedRUB": 0.,  # blocked sum in Russian Rouble
1637                "totalChangesRUB": 0.,  # changes for all open trades in RUB
1638                "totalChangesPercentRUB": 0.,  # changes for all open trades in percents
1639                "allCurrenciesCostRUB": 0.,  # costs of all currencies (include rubles) in RUB
1640                "sharesCostRUB": 0.,  # costs of all shares in RUB
1641                "bondsCostRUB": 0.,  # costs of all bonds in RUB
1642                "etfsCostRUB": 0.,  # costs of all etfs in RUB
1643                "futuresCostRUB": 0.,  # costs of all futures in RUB
1644                "Currencies": [],  # list of dictionaries of all currencies statistics
1645                "Shares": [],  # list of dictionaries of all shares statistics
1646                "Bonds": [],  # list of dictionaries of all bonds statistics
1647                "Etfs": [],  # list of dictionaries of all etfs statistics
1648                "Futures": [],  # list of dictionaries of all futures statistics
1649                "orders": [],  # list of dictionaries of all pending (market) orders and it's parameters
1650                "stopOrders": [],  # list of dictionaries of all stop orders and it's parameters
1651                "blockedCurrencies": {},  # dict with blocked instruments and currencies, e.g. {"rub": 1291.87, "usd": 6.21}
1652                "blockedInstruments": {},  # dict with blocked  by FIGI, e.g. {}
1653                "funds": {},  # dict with free funds for trading (total - blocked), by all currencies, e.g. {"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}}
1654            },
1655            "analytics": {  # --- some analytics of portfolio:
1656                "distrByAssets": {},  # portfolio distribution by assets
1657                "distrByCompanies": {},  # portfolio distribution by companies
1658                "distrBySectors": {},  # portfolio distribution by sectors
1659                "distrByCurrencies": {},  # portfolio distribution by currencies
1660                "distrByCountries": {},  # portfolio distribution by countries
1661                "bondsCalendar": None,  # bonds payment calendar as Pandas DataFrame (if these present in portfolio)
1662            }
1663        }
1664
1665        details = details.lower()
1666        availableDetails = ["full", "positions", "orders", "analytics", "calendar", "digest"]
1667        if details not in availableDetails:
1668            details = "full"
1669            uLogger.debug("Requested incorrect details! The `details` must be one of this strings: {}. Details parameter set to `full` be default.".format(availableDetails))
1670
1671        uLogger.debug("Requesting portfolio of a client. Wait, please...")
1672
1673        portfolioResponse = self.RequestPortfolio()  # current user's portfolio (dict)
1674        view["raw"]["positions"] = self.RequestPositions()  # current open positions by instruments (dict)
1675        view["raw"]["orders"] = self.RequestPendingOrders()  # current actual pending limit orders (list)
1676        view["raw"]["stopOrders"] = self.RequestStopOrders()  # current actual stop orders (list)
1677
1678        # save response headers without "positions" section:
1679        for key in portfolioResponse.keys():
1680            if key != "positions":
1681                view["raw"]["headers"][key] = portfolioResponse[key]
1682
1683            else:
1684                continue
1685
1686        # Re-sorting and separating given raw instruments and currencies by type: https://tinkoff.github.io/investAPI/operations/#operation
1687        # Type of instrument must be only one of supported types in TKS_INSTRUMENTS
1688        for item in portfolioResponse["positions"]:
1689            if item["instrumentType"] == "currency":
1690                self._figi = item["figi"]
1691                curr = self.SearchByFIGI(requestPrice=False)
1692
1693                # current price of currency in RUB:
1694                view["raw"]["currenciesCurrentPrices"][curr["nominal"]["currency"]] = {
1695                    "name": curr["name"],
1696                    "currentPrice": NanoToFloat(
1697                        item["currentPrice"]["units"],
1698                        item["currentPrice"]["nano"]
1699                    ),
1700                }
1701
1702                view["raw"]["Currencies"].append(item)
1703
1704            elif item["instrumentType"] == "share":
1705                view["raw"]["Shares"].append(item)
1706
1707            elif item["instrumentType"] == "bond":
1708                view["raw"]["Bonds"].append(item)
1709
1710            elif item["instrumentType"] == "etf":
1711                view["raw"]["Etfs"].append(item)
1712
1713            elif item["instrumentType"] == "futures":
1714                view["raw"]["Futures"].append(item)
1715
1716            else:
1717                continue
1718
1719        # how many volume of currencies (by ISO currency name) are blocked:
1720        for item in view["raw"]["positions"]["blocked"]:
1721            blocked = NanoToFloat(item["units"], item["nano"])
1722            if blocked > 0:
1723                view["stat"]["blockedCurrencies"][item["currency"]] = blocked
1724
1725        # how many volume of instruments (by FIGI) are blocked:
1726        for item in view["raw"]["positions"]["securities"]:
1727            blocked = int(item["blocked"])
1728            if blocked > 0:
1729                view["stat"]["blockedInstruments"][item["figi"]] = blocked
1730
1731        allBlocked = {**view["stat"]["blockedCurrencies"], **view["stat"]["blockedInstruments"]}
1732
1733        if "rub" in allBlocked.keys():
1734            view["stat"]["blockedRUB"] = allBlocked["rub"]  # blocked rubles
1735
1736        # --- saving current total amount in RUB of all currencies (with ruble), shares, bonds, etfs, futures and currencies:
1737        view["stat"]["allCurrenciesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountCurrencies"]["units"], portfolioResponse["totalAmountCurrencies"]["nano"])
1738        view["stat"]["sharesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountShares"]["units"], portfolioResponse["totalAmountShares"]["nano"])
1739        view["stat"]["bondsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountBonds"]["units"], portfolioResponse["totalAmountBonds"]["nano"])
1740        view["stat"]["etfsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountEtf"]["units"], portfolioResponse["totalAmountEtf"]["nano"])
1741        view["stat"]["futuresCostRUB"] = NanoToFloat(portfolioResponse["totalAmountFutures"]["units"], portfolioResponse["totalAmountFutures"]["nano"])
1742        view["stat"]["portfolioCostRUB"] = sum([
1743            view["stat"]["allCurrenciesCostRUB"],
1744            view["stat"]["sharesCostRUB"],
1745            view["stat"]["bondsCostRUB"],
1746            view["stat"]["etfsCostRUB"],
1747            view["stat"]["futuresCostRUB"],
1748        ])
1749
1750        # --- calculating some portfolio statistics:
1751        byComp = {}  # distribution by companies
1752        bySect = {}  # distribution by sectors
1753        byCurr = {}  # distribution by currencies (include RUB)
1754        unknownCountryName = "All other countries"  # default name for instruments without "countryOfRisk" and "countryOfRiskName"
1755        byCountry = {unknownCountryName: {"cost": 0, "percent": 0.}}  # distribution by countries (currencies are included in their countries)
1756
1757        for item in portfolioResponse["positions"]:
1758            self._figi = item["figi"]
1759            instrument = self.SearchByFIGI(requestPrice=False)  # full raw info about instrument by FIGI
1760
1761            if instrument:
1762                if item["instrumentType"] == "currency" and instrument["nominal"]["currency"] in allBlocked.keys():
1763                    blocked = allBlocked[instrument["nominal"]["currency"]]  # blocked volume of currency
1764
1765                elif item["instrumentType"] != "currency" and item["figi"] in allBlocked.keys():
1766                    blocked = allBlocked[item["figi"]]  # blocked volume of other instruments
1767
1768                else:
1769                    blocked = 0
1770
1771                volume = NanoToFloat(item["quantity"]["units"], item["quantity"]["nano"])  # available volume of instrument
1772                lots = NanoToFloat(item["quantityLots"]["units"], item["quantityLots"]["nano"])  # available volume in lots of instrument
1773                direction = "Long" if lots >= 0 else "Short"  # direction of an instrument's position: short or long
1774                curPrice = NanoToFloat(item["currentPrice"]["units"], item["currentPrice"]["nano"])  # current instrument's price
1775                average = NanoToFloat(item["averagePositionPriceFifo"]["units"], item["averagePositionPriceFifo"]["nano"])  # current average position price
1776                profit = NanoToFloat(item["expectedYield"]["units"], item["expectedYield"]["nano"])  # expected profit at current moment
1777                currency = instrument["currency"] if (item["instrumentType"] == "share" or item["instrumentType"] == "etf" or item["instrumentType"] == "future") else instrument["nominal"]["currency"]  # currency name rub, usd, eur etc.
1778                cost = (curPrice + NanoToFloat(item["currentNkd"]["units"], item["currentNkd"]["nano"])) * volume  # current cost of all volume of instrument in basic asset
1779                baseCurrencyName = item["currentPrice"]["currency"]  # name of base currency (rub)
1780                countryName = "[{}] {}".format(instrument["countryOfRisk"], instrument["countryOfRiskName"]) if "countryOfRisk" in instrument.keys() and "countryOfRiskName" in instrument.keys() and instrument["countryOfRisk"] and instrument["countryOfRiskName"] else unknownCountryName
1781                costRUB = cost if item["instrumentType"] == "currency" else cost * view["raw"]["currenciesCurrentPrices"][currency]["currentPrice"]  # cost in rubles
1782                percentCostRUB = 100 * costRUB / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.  # instrument's part in percent of full portfolio cost
1783
1784                statData = {
1785                    "figi": item["figi"],  # FIGI from REST API "GetPortfolio" method
1786                    "ticker": instrument["ticker"],  # ticker by FIGI
1787                    "currency": currency,  # currency name rub, usd, eur etc. for instrument price
1788                    "volume": volume,  # available volume of instrument
1789                    "lots": lots,  # volume in lots of instrument
1790                    "direction": direction,  # direction of an instrument's position: short or long
1791                    "blocked": blocked,  # blocked volume of currency or instrument
1792                    "currentPrice": curPrice,  # current instrument's price in basic asset
1793                    "average": average,  # current average position price
1794                    "cost": cost,  # current cost of all volume of instrument in basic asset
1795                    "baseCurrencyName": baseCurrencyName,  # name of base currency (rub)
1796                    "costRUB": costRUB,  # cost of instrument in ruble
1797                    "percentCostRUB": percentCostRUB,  # instrument's part in percent of full portfolio cost in RUB
1798                    "profit": profit,  # expected profit at current moment
1799                    "percentProfit": 100 * profit / (average * volume) if average != 0 and volume != 0 else 0,  # expected percents of profit at current moment for this instrument
1800                    "sector": instrument["sector"] if "sector" in instrument.keys() and instrument["sector"] else "other",
1801                    "name": instrument["name"] if "name" in instrument.keys() else "",  # human-readable names of instruments
1802                    "isoCurrencyName": instrument["isoCurrencyName"] if "isoCurrencyName" in instrument.keys() else "",  # ISO name for currencies only
1803                    "country": countryName,  # e.g. "[RU] Российская Федерация" or unknownCountryName
1804                    "step": instrument["step"],  # minimum price increment
1805                }
1806
1807                # adding distribution by unique countries:
1808                if statData["country"] not in byCountry.keys():
1809                    byCountry[statData["country"]] = {"cost": costRUB, "percent": percentCostRUB}
1810
1811                else:
1812                    byCountry[statData["country"]]["cost"] += costRUB
1813                    byCountry[statData["country"]]["percent"] += percentCostRUB
1814
1815                if item["instrumentType"] != "currency":
1816                    # adding distribution by unique companies:
1817                    if statData["name"]:
1818                        if statData["name"] not in byComp.keys():
1819                            byComp[statData["name"]] = {"ticker": statData["ticker"], "cost": costRUB, "percent": percentCostRUB}
1820
1821                        else:
1822                            byComp[statData["name"]]["cost"] += costRUB
1823                            byComp[statData["name"]]["percent"] += percentCostRUB
1824
1825                    # adding distribution by unique sectors:
1826                    if statData["sector"] not in bySect.keys():
1827                        bySect[statData["sector"]] = {"cost": costRUB, "percent": percentCostRUB}
1828
1829                    else:
1830                        bySect[statData["sector"]]["cost"] += costRUB
1831                        bySect[statData["sector"]]["percent"] += percentCostRUB
1832
1833                # adding distribution by unique currencies:
1834                if currency not in byCurr.keys():
1835                    byCurr[currency] = {
1836                        "name": view["raw"]["currenciesCurrentPrices"][currency]["name"],
1837                        "cost": costRUB,
1838                        "percent": percentCostRUB
1839                    }
1840
1841                else:
1842                    byCurr[currency]["cost"] += costRUB
1843                    byCurr[currency]["percent"] += percentCostRUB
1844
1845                # saving statistics for every instrument:
1846                if item["instrumentType"] == "currency":
1847                    view["stat"]["Currencies"].append(statData)
1848
1849                    # update dict with free funds for trading (total - blocked) by currencies
1850                    # e.g. {"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}}
1851                    view["stat"]["funds"][currency] = {
1852                        "total": volume,
1853                        "totalCostRUB": costRUB,  # total volume cost in rubles
1854                        "free": volume - blocked,
1855                        "freeCostRUB": costRUB * ((volume - blocked) / volume) if volume > 0 else 0,  # free volume cost in rubles
1856                    }
1857
1858                elif item["instrumentType"] == "share":
1859                    view["stat"]["Shares"].append(statData)
1860
1861                elif item["instrumentType"] == "bond":
1862                    view["stat"]["Bonds"].append(statData)
1863
1864                elif item["instrumentType"] == "etf":
1865                    view["stat"]["Etfs"].append(statData)
1866
1867                elif item["instrumentType"] == "Futures":
1868                    view["stat"]["Futures"].append(statData)
1869
1870                else:
1871                    continue
1872
1873        # total changes in Russian Ruble:
1874        view["stat"]["availableRUB"] = view["stat"]["allCurrenciesCostRUB"] - sum([item["cost"] for item in view["stat"]["Currencies"]])  # available RUB without other currencies
1875        view["stat"]["totalChangesPercentRUB"] = NanoToFloat(view["raw"]["headers"]["expectedYield"]["units"], view["raw"]["headers"]["expectedYield"]["nano"]) if "expectedYield" in view["raw"]["headers"].keys() else 0.
1876        startCost = view["stat"]["portfolioCostRUB"] / (1 + view["stat"]["totalChangesPercentRUB"] / 100)
1877        view["stat"]["totalChangesRUB"] = view["stat"]["portfolioCostRUB"] - startCost
1878        view["stat"]["funds"]["rub"] = {
1879            "total": view["stat"]["availableRUB"],
1880            "totalCostRUB": view["stat"]["availableRUB"],
1881            "free": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1882            "freeCostRUB": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1883        }
1884
1885        # --- pending limit orders sector data:
1886        uniquePendingOrdersFIGIs = []  # unique FIGIs of pending limit orders to avoid many times price requests
1887        uniquePendingOrders = {}  # unique instruments with FIGIs as dictionary keys
1888
1889        for item in view["raw"]["orders"]:
1890            self._figi = item["figi"]
1891
1892            if item["figi"] not in uniquePendingOrdersFIGIs:
1893                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1894
1895                uniquePendingOrdersFIGIs.append(item["figi"])
1896                uniquePendingOrders[item["figi"]] = instrument
1897
1898            else:
1899                instrument = uniquePendingOrders[item["figi"]]
1900
1901            if instrument:
1902                action = TKS_ORDER_DIRECTIONS[item["direction"]]
1903                orderType = TKS_ORDER_TYPES[item["orderType"]]
1904                orderState = TKS_ORDER_STATES[item["executionReportStatus"]]
1905                orderDate = item["orderDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1906
1907                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1908                if item["direction"] == "ORDER_DIRECTION_BUY":
1909                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1910
1911                else:
1912                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1913
1914                # requested price for order execution:
1915                target = NanoToFloat(item["initialSecurityPrice"]["units"], item["initialSecurityPrice"]["nano"])
1916
1917                # necessary changes in percent to reach target from current price:
1918                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1919
1920                view["stat"]["orders"].append({
1921                    "orderID": item["orderId"],  # orderId number parameter of current order
1922                    "figi": item["figi"],  # FIGI identification
1923                    "ticker": instrument["ticker"],  # ticker name by FIGI
1924                    "lotsRequested": item["lotsRequested"],  # requested lots value
1925                    "lotsExecuted": item["lotsExecuted"],  # how many lots are executed
1926                    "currentPrice": lastPrice,  # current instrument's price for defined action
1927                    "targetPrice": target,  # requested price for order execution in base currency
1928                    "baseCurrencyName": item["initialSecurityPrice"]["currency"],  # name of base currency
1929                    "percentChanges": changes,  # changes in percent to target from current price
1930                    "currency": item["currency"],  # instrument's currency name
1931                    "action": action,  # sell / buy / Unknown from TKS_ORDER_DIRECTIONS
1932                    "type": orderType,  # type of order from TKS_ORDER_TYPES
1933                    "status": orderState,  # order status from TKS_ORDER_STATES
1934                    "date": orderDate,  # string with order date and time from UTC format (without nano seconds part)
1935                })
1936
1937        # --- stop orders sector data:
1938        uniqueStopOrdersFIGIs = []  # unique FIGIs of stop orders to avoid many times price requests
1939        uniqueStopOrders = {}  # unique instruments with FIGIs as dictionary keys
1940
1941        for item in view["raw"]["stopOrders"]:
1942            self._figi = item["figi"]
1943
1944            if item["figi"] not in uniqueStopOrdersFIGIs:
1945                instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI, price requests only one time
1946
1947                uniqueStopOrdersFIGIs.append(item["figi"])
1948                uniqueStopOrders[item["figi"]] = instrument
1949
1950            else:
1951                instrument = uniqueStopOrders[item["figi"]]
1952
1953            if instrument:
1954                action = TKS_STOP_ORDER_DIRECTIONS[item["direction"]]
1955                orderType = TKS_STOP_ORDER_TYPES[item["orderType"]]
1956                createDate = item["createDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1957
1958                # hack: server response can't contain "expirationTime" key if it is not "Until date" type of stop order
1959                if "expirationTime" in item.keys():
1960                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE"]
1961                    expDate = item["expirationTime"].replace("T", " ").replace("Z", "").split(".")[0]
1962
1963                else:
1964                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL"]
1965                    expDate = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"]
1966
1967                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1968                if item["direction"] == "STOP_ORDER_DIRECTION_BUY":
1969                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1970
1971                else:
1972                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1973
1974                # requested price when stop-order executed:
1975                target = NanoToFloat(item["stopPrice"]["units"], item["stopPrice"]["nano"])
1976
1977                # price for limit-order, set up when stop-order executed:
1978                limit = NanoToFloat(item["price"]["units"], item["price"]["nano"])
1979
1980                # necessary changes in percent to reach target from current price:
1981                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1982
1983                view["stat"]["stopOrders"].append({
1984                    "orderID": item["stopOrderId"],  # stopOrderId number parameter of current stop-order
1985                    "figi": item["figi"],  # FIGI identification
1986                    "ticker": instrument["ticker"],  # ticker name by FIGI
1987                    "lotsRequested": item["lotsRequested"],  # requested lots value
1988                    "currentPrice": lastPrice,  # current instrument's price for defined action
1989                    "targetPrice": target,  # requested price for stop-order execution in base currency
1990                    "limitPrice": limit,  # price for limit-order, set up when stop-order executed, 0 if market order
1991                    "baseCurrencyName": item["stopPrice"]["currency"],  # name of base currency
1992                    "percentChanges": changes,  # changes in percent to target from current price
1993                    "currency": item["currency"],  # instrument's currency name
1994                    "action": action,  # sell / buy / Unknown from TKS_STOP_ORDER_DIRECTIONS
1995                    "type": orderType,  # type of order from TKS_STOP_ORDER_TYPES
1996                    "expType": expType,  # expiration type of stop-order from TKS_STOP_ORDER_EXPIRATION_TYPES
1997                    "createDate": createDate,  # string with created order date and time from UTC format (without nano seconds part)
1998                    "expDate": expDate,  # string with expiration order date and time from UTC format (without nano seconds part)
1999                })
2000
2001        # --- calculating data for analytics section:
2002        # portfolio distribution by assets:
2003        view["analytics"]["distrByAssets"] = {
2004            "Ruble": {
2005                "uniques": 1,
2006                "cost": view["stat"]["availableRUB"],
2007                "percent": 100 * view["stat"]["availableRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2008            },
2009            "Currencies": {
2010                "uniques": len(view["stat"]["Currencies"]),  # all foreign currencies without RUB
2011                "cost": view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"],
2012                "percent": 100 * (view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"]) / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2013            },
2014            "Shares": {
2015                "uniques": len(view["stat"]["Shares"]),
2016                "cost": view["stat"]["sharesCostRUB"],
2017                "percent": 100 * view["stat"]["sharesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2018            },
2019            "Bonds": {
2020                "uniques": len(view["stat"]["Bonds"]),
2021                "cost": view["stat"]["bondsCostRUB"],
2022                "percent": 100 * view["stat"]["bondsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2023            },
2024            "Etfs": {
2025                "uniques": len(view["stat"]["Etfs"]),
2026                "cost": view["stat"]["etfsCostRUB"],
2027                "percent": 100 * view["stat"]["etfsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2028            },
2029            "Futures": {
2030                "uniques": len(view["stat"]["Futures"]),
2031                "cost": view["stat"]["futuresCostRUB"],
2032                "percent": 100 * view["stat"]["futuresCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2033            },
2034        }
2035
2036        # portfolio distribution by companies:
2037        view["analytics"]["distrByCompanies"]["All money cash"] = {
2038            "ticker": "",
2039            "cost": view["stat"]["allCurrenciesCostRUB"],
2040            "percent": 100 * view["stat"]["allCurrenciesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2041        }
2042        view["analytics"]["distrByCompanies"].update(byComp)
2043
2044        # portfolio distribution by sectors:
2045        view["analytics"]["distrBySectors"]["All money cash"] = {
2046            "cost": view["analytics"]["distrByCompanies"]["All money cash"]["cost"],
2047            "percent": view["analytics"]["distrByCompanies"]["All money cash"]["percent"],
2048        }
2049        view["analytics"]["distrBySectors"].update(bySect)
2050
2051        # portfolio distribution by currencies:
2052        if "rub" not in view["analytics"]["distrByCurrencies"].keys():
2053            view["analytics"]["distrByCurrencies"]["rub"] = {"name": "Российский рубль", "cost": 0, "percent": 0}
2054
2055            if self.moreDebug:
2056                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by currencies` section. Server not returned current available rubles!")
2057
2058        view["analytics"]["distrByCurrencies"].update(byCurr)
2059        view["analytics"]["distrByCurrencies"]["rub"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2060        view["analytics"]["distrByCurrencies"]["rub"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2061
2062        # portfolio distribution by countries:
2063        if "[RU] Российская Федерация" not in view["analytics"]["distrByCountries"].keys():
2064            view["analytics"]["distrByCountries"]["[RU] Российская Федерация"] = {"cost": 0, "percent": 0}
2065
2066            if self.moreDebug:
2067                uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by countries` section. Server not returned current available rubles!")
2068
2069        view["analytics"]["distrByCountries"].update(byCountry)
2070        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2071        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2072
2073        # --- Prepare text statistics overview in human-readable:
2074        if show:
2075            actualOnDate = datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)
2076
2077            # Whatever the value `details`, header not changes:
2078            info = [
2079                "# Client's portfolio\n\n",
2080                "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2081                "* **Account ID:** [{}]\n".format(self.accountId),
2082            ]
2083
2084            if details in ["full", "positions", "digest"]:
2085                info.extend([
2086                    "* **Portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2087                    "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n\n".format(
2088                        "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2089                        view["stat"]["totalChangesRUB"],
2090                        "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2091                        view["stat"]["totalChangesPercentRUB"],
2092                    ),
2093                ])
2094
2095            if details in ["full", "positions"]:
2096                info.extend([
2097                    "## Open positions\n\n",
2098                    "| Ticker [FIGI]               | Volume (blocked)                | Lots     | Curr. price  | Avg. price   | Current volume cost | Profit (%)                   |\n",
2099                    "|-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|------------------------------|\n",
2100                    "| Ruble                       | {:>31} |          |              |              |                     |                              |\n".format(
2101                        "{:.2f} ({:.2f}) rub".format(
2102                            view["stat"]["availableRUB"],
2103                            view["stat"]["blockedRUB"],
2104                        )
2105                    )
2106                ])
2107
2108                def _SplitStr(CostRUB: float = 0, typeStr: str = "", noTradeStr: str = "") -> list:
2109                    return [
2110                        "|                             |                                 |          |              |              |                     |                              |\n",
2111                        "| {:<27} |                                 |          |              |              | {:>19} |                              |\n".format(
2112                            noTradeStr if noTradeStr else typeStr,
2113                            "" if noTradeStr else "{:.2f} RUB".format(CostRUB),
2114                        ),
2115                    ]
2116
2117                def _InfoStr(data: dict, showCurrencyName: bool = False) -> str:
2118                    return "| {:<27} | {:>31} | {:<8} | {:>12} | {:>12} | {:>19} | {:<28} |\n".format(
2119                        "{} [{}]".format(data["ticker"], data["figi"]),
2120                        "{:.2f} ({:.2f}) {}".format(
2121                            data["volume"],
2122                            data["blocked"],
2123                            data["currency"],
2124                        ) if showCurrencyName else "{:.0f} ({:.0f})".format(
2125                            data["volume"],
2126                            data["blocked"],
2127                        ),
2128                        "{:.4f}".format(data["lots"]) if showCurrencyName else "{:.0f}".format(data["lots"]),
2129                        "{:.2f} {}".format(data["currentPrice"], data["baseCurrencyName"]) if data["currentPrice"] > 0 else "n/a",
2130                        "{:.2f} {}".format(data["average"], data["baseCurrencyName"]) if data["average"] > 0 else "n/a",
2131                        "{:.2f} {}".format(data["cost"], data["baseCurrencyName"]),
2132                        "{}{:.2f} {} ({}{:.2f}%)".format(
2133                            "+" if data["profit"] > 0 else "",
2134                            data["profit"], data["baseCurrencyName"],
2135                            "+" if data["percentProfit"] > 0 else "",
2136                            data["percentProfit"],
2137                        ),
2138                    )
2139
2140                # --- Show currencies section:
2141                if view["stat"]["Currencies"]:
2142                    info.extend(_SplitStr(CostRUB=view["analytics"]["distrByAssets"]["Currencies"]["cost"], typeStr="**Currencies:**"))
2143                    for item in view["stat"]["Currencies"]:
2144                        info.append(_InfoStr(item, showCurrencyName=True))
2145
2146                else:
2147                    info.extend(_SplitStr(noTradeStr="**Currencies:** no trades"))
2148
2149                # --- Show shares section:
2150                if view["stat"]["Shares"]:
2151                    info.extend(_SplitStr(CostRUB=view["stat"]["sharesCostRUB"], typeStr="**Shares:**"))
2152
2153                    for item in view["stat"]["Shares"]:
2154                        info.append(_InfoStr(item))
2155
2156                else:
2157                    info.extend(_SplitStr(noTradeStr="**Shares:** no trades"))
2158
2159                # --- Show bonds section:
2160                if view["stat"]["Bonds"]:
2161                    info.extend(_SplitStr(CostRUB=view["stat"]["bondsCostRUB"], typeStr="**Bonds:**"))
2162
2163                    for item in view["stat"]["Bonds"]:
2164                        info.append(_InfoStr(item))
2165
2166                else:
2167                    info.extend(_SplitStr(noTradeStr="**Bonds:** no trades"))
2168
2169                # --- Show etfs section:
2170                if view["stat"]["Etfs"]:
2171                    info.extend(_SplitStr(CostRUB=view["stat"]["etfsCostRUB"], typeStr="**Etfs:**"))
2172
2173                    for item in view["stat"]["Etfs"]:
2174                        info.append(_InfoStr(item))
2175
2176                else:
2177                    info.extend(_SplitStr(noTradeStr="**Etfs:** no trades"))
2178
2179                # --- Show futures section:
2180                if view["stat"]["Futures"]:
2181                    info.extend(_SplitStr(CostRUB=view["stat"]["futuresCostRUB"], typeStr="**Futures:**"))
2182
2183                    for item in view["stat"]["Futures"]:
2184                        info.append(_InfoStr(item))
2185
2186                else:
2187                    info.extend(_SplitStr(noTradeStr="**Futures:** no trades"))
2188
2189            if details in ["full", "orders"]:
2190                # --- Show pending limit orders section:
2191                if view["stat"]["orders"]:
2192                    info.extend([
2193                        "\n## Opened pending limit-orders: [{}]\n".format(len(view["stat"]["orders"])),
2194                        "\n| Ticker [FIGI]               | Order ID       | Lots (exec.) | Current price (% delta) | Target price  | Action    | Type      | Create date (UTC)       |\n",
2195                        "|-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|-------------------------|\n",
2196                    ])
2197
2198                    for item in view["stat"]["orders"]:
2199                        info.append("| {:<27} | {:<14} | {:<12} | {:>23} | {:>13} | {:<9} | {:<9} | {:<23} |\n".format(
2200                            "{} [{}]".format(item["ticker"], item["figi"]),
2201                            item["orderID"],
2202                            "{} ({})".format(item["lotsRequested"], item["lotsExecuted"]),
2203                            "{} {} ({}{:.2f}%)".format(
2204                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2205                                item["baseCurrencyName"],
2206                                "+" if item["percentChanges"] > 0 else "",
2207                                float(item["percentChanges"]),
2208                            ),
2209                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2210                            item["action"],
2211                            item["type"],
2212                            item["date"],
2213                        ))
2214
2215                else:
2216                    info.append("\n## Total pending limit-orders: [0]\n")
2217
2218                # --- Show stop orders section:
2219                if view["stat"]["stopOrders"]:
2220                    info.extend([
2221                        "\n## Opened stop-orders: [{}]\n".format(len(view["stat"]["stopOrders"])),
2222                        "\n| Ticker [FIGI]               | Stop order ID                        | Lots   | Current price (% delta) | Target price  | Limit price   | Action    | Type        | Expire type  | Create date (UTC)   | Expiration (UTC)    |\n",
2223                        "|-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|---------------------|\n",
2224                    ])
2225
2226                    for item in view["stat"]["stopOrders"]:
2227                        info.append("| {:<27} | {:<14} | {:<6} | {:>23} | {:>13} | {:>13} | {:<9} | {:<11} | {:<12} | {:<19} | {:<19} |\n".format(
2228                            "{} [{}]".format(item["ticker"], item["figi"]),
2229                            item["orderID"],
2230                            item["lotsRequested"],
2231                            "{} {} ({}{:.2f}%)".format(
2232                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2233                                item["baseCurrencyName"],
2234                                "+" if item["percentChanges"] > 0 else "",
2235                                float(item["percentChanges"]),
2236                            ),
2237                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2238                            "{:.2f} {}".format(float(item["limitPrice"]), item["baseCurrencyName"]) if item["limitPrice"] and item["limitPrice"] != item["targetPrice"] else TKS_ORDER_TYPES["ORDER_TYPE_MARKET"],
2239                            item["action"],
2240                            item["type"],
2241                            item["expType"],
2242                            item["createDate"],
2243                            item["expDate"],
2244                        ))
2245
2246                else:
2247                    info.append("\n## Total stop-orders: [0]\n")
2248
2249            if details in ["full", "analytics"]:
2250                # -- Show analytics section:
2251                if view["stat"]["portfolioCostRUB"] > 0:
2252                    info.extend([
2253                        "\n# Analytics\n\n"
2254                        "* **Actual on date:** [{} UTC]\n".format(actualOnDate),
2255                        "* **Current total portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2256                        "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n".format(
2257                            "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2258                            view["stat"]["totalChangesRUB"],
2259                            "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2260                            view["stat"]["totalChangesPercentRUB"],
2261                        ),
2262                        "\n## Portfolio distribution by assets\n"
2263                        "\n| Type                               | Uniques | Percent | Current cost       |\n",
2264                        "|------------------------------------|---------|---------|--------------------|\n",
2265                    ])
2266
2267                    for key in view["analytics"]["distrByAssets"].keys():
2268                        if view["analytics"]["distrByAssets"][key]["cost"] > 0:
2269                            info.append("| {:<34} | {:<7} | {:<7} | {:<18} |\n".format(
2270                                key,
2271                                view["analytics"]["distrByAssets"][key]["uniques"],
2272                                "{:.2f}%".format(view["analytics"]["distrByAssets"][key]["percent"]),
2273                                "{:.2f} rub".format(view["analytics"]["distrByAssets"][key]["cost"]),
2274                            ))
2275
2276                    aSepLine = "|----------------------------------------------|---------|--------------------|\n"
2277
2278                    info.extend([
2279                        "\n## Portfolio distribution by companies\n"
2280                        "\n| Company                                      | Percent | Current cost       |\n",
2281                        aSepLine,
2282                    ])
2283
2284                    for company in view["analytics"]["distrByCompanies"].keys():
2285                        if view["analytics"]["distrByCompanies"][company]["cost"] > 0:
2286                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2287                                "{}{}".format(
2288                                    "[{}] ".format(view["analytics"]["distrByCompanies"][company]["ticker"]) if view["analytics"]["distrByCompanies"][company]["ticker"] else "",
2289                                    company,
2290                                ),
2291                                "{:.2f}%".format(view["analytics"]["distrByCompanies"][company]["percent"]),
2292                                "{:.2f} rub".format(view["analytics"]["distrByCompanies"][company]["cost"]),
2293                            ))
2294
2295                    info.extend([
2296                        "\n## Portfolio distribution by sectors\n"
2297                        "\n| Sector                                       | Percent | Current cost       |\n",
2298                        aSepLine,
2299                    ])
2300
2301                    for sector in view["analytics"]["distrBySectors"].keys():
2302                        if view["analytics"]["distrBySectors"][sector]["cost"] > 0:
2303                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2304                                sector,
2305                                "{:.2f}%".format(view["analytics"]["distrBySectors"][sector]["percent"]),
2306                                "{:.2f} rub".format(view["analytics"]["distrBySectors"][sector]["cost"]),
2307                            ))
2308
2309                    info.extend([
2310                        "\n## Portfolio distribution by currencies\n"
2311                        "\n| Instruments currencies                       | Percent | Current cost       |\n",
2312                        aSepLine,
2313                    ])
2314
2315                    for curr in view["analytics"]["distrByCurrencies"].keys():
2316                        if view["analytics"]["distrByCurrencies"][curr]["cost"] > 0:
2317                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2318                                "[{}] {}".format(curr, view["analytics"]["distrByCurrencies"][curr]["name"]),
2319                                "{:.2f}%".format(view["analytics"]["distrByCurrencies"][curr]["percent"]),
2320                                "{:.2f} rub".format(view["analytics"]["distrByCurrencies"][curr]["cost"]),
2321                            ))
2322
2323                    info.extend([
2324                        "\n## Portfolio distribution by countries\n"
2325                        "\n| Assets by country                            | Percent | Current cost       |\n",
2326                        aSepLine,
2327                    ])
2328
2329                    for country in view["analytics"]["distrByCountries"].keys():
2330                        if view["analytics"]["distrByCountries"][country]["cost"] > 0:
2331                            info.append("| {:<44} | {:<7} | {:<18} |\n".format(
2332                                country,
2333                                "{:.2f}%".format(view["analytics"]["distrByCountries"][country]["percent"]),
2334                                "{:.2f} rub".format(view["analytics"]["distrByCountries"][country]["cost"]),
2335                            ))
2336
2337            if details in ["full", "calendar"]:
2338                # -- Show bonds payment calendar section:
2339                if view["stat"]["Bonds"]:
2340                    bondTickers = [item["ticker"] for item in view["stat"]["Bonds"]]
2341                    view["analytics"]["bondsCalendar"] = self.ExtendBondsData(instruments=bondTickers, xlsx=False)
2342                    info.append("\n" + self.ShowBondsCalendar(extBonds=view["analytics"]["bondsCalendar"], show=False))
2343
2344                else:
2345                    info.append("\n# Bond payments calendar\n\nNo bonds in the portfolio to create payments calendar\n")
2346
2347            infoText = "".join(info)
2348
2349            uLogger.info(infoText)
2350
2351            if details == "full" and self.overviewFile:
2352                filename = self.overviewFile
2353
2354            elif details == "digest" and self.overviewDigestFile:
2355                filename = self.overviewDigestFile
2356
2357            elif details == "positions" and self.overviewPositionsFile:
2358                filename = self.overviewPositionsFile
2359
2360            elif details == "orders" and self.overviewOrdersFile:
2361                filename = self.overviewOrdersFile
2362
2363            elif details == "analytics" and self.overviewAnalyticsFile:
2364                filename = self.overviewAnalyticsFile
2365
2366            elif details == "calendar" and self.overviewBondsCalendarFile:
2367                filename = self.overviewBondsCalendarFile
2368
2369            else:
2370                filename = ""
2371
2372            if filename:
2373                with open(filename, "w", encoding="UTF-8") as fH:
2374                    fH.write(infoText)
2375
2376                uLogger.info("Client's portfolio was saved to file: [{}]".format(os.path.abspath(filename)))
2377
2378                if self.useHTMLReports:
2379                    htmlFilePath = filename.replace(".md", ".html") if filename.endswith(".md") else filename + ".html"
2380                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2381                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="", commonCSS=COMMON_CSS, markdown=infoText))
2382
2383                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2384
2385        return view
2386
2387    def Deals(self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True) -> tuple[list[dict], dict]:
2388        """
2389        Returns history operations between two given dates for current `accountId`.
2390        If `reportFile` string is not empty then also save human-readable report.
2391        Shows some statistical data of closed positions.
2392
2393        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2394        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2395        :param show: if `True` then also prints all records to the console.
2396        :param showCancelled: if `False` then remove information about cancelled operations from the deals report.
2397        :return: original list of dictionaries with history of deals records from API ("operations" key):
2398                 https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2399                 and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.
2400        """
2401        if self.accountId is None or not self.accountId:
2402            uLogger.error("Variable `accountId` must be defined for using this method!")
2403            raise Exception("Account ID required")
2404
2405        startDate, endDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # Example: ("2000-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2406
2407        uLogger.debug("Requesting history of a client's operations. Wait, please...")
2408
2409        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2410        dealsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetOperations"
2411        self.body = str({"accountId": self.accountId, "from": startDate, "to": endDate})
2412        ops = self.SendAPIRequest(dealsURL, reqType="POST")["operations"]  # list of dict: operations returns by broker
2413        customStat = {}  # custom statistics in additional to responseJSON
2414
2415        # --- output report in human-readable format:
2416        if show or self.reportFile:
2417            splitLine1 = "|                            |                               |                              |                      |                        |\n"  # Summary section
2418            splitLine2 = "|                     |              |              |            |           |                 |            |                                                                    |\n"  # Operations section
2419            nextDay = ""
2420
2421            info = ["# Client's operations\n\n* **Period:** from [{}] to [{}]\n\n## Summary (operations executed only)\n\n".format(startDate.split("T")[0], endDate.split("T")[0])]
2422
2423            if len(ops) > 0:
2424                customStat = {
2425                    "opsCount": 0,  # total operations count
2426                    "buyCount": 0,  # buy operations
2427                    "sellCount": 0,  # sell operations
2428                    "buyTotal": {"rub": 0.},  # Buy sums in different currencies
2429                    "sellTotal": {"rub": 0.},  # Sell sums in different currencies
2430                    "payIn": {"rub": 0.},  # Deposit brokerage account
2431                    "payOut": {"rub": 0.},  # Withdrawals
2432                    "divs": {"rub": 0.},  # Dividends income
2433                    "coupons": {"rub": 0.},  # Coupon's income
2434                    "brokerCom": {"rub": 0.},  # Service commissions
2435                    "serviceCom": {"rub": 0.},  # Service commissions
2436                    "marginCom": {"rub": 0.},  # Margin commissions
2437                    "allTaxes": {"rub": 0.},  # Sum of withholding taxes and corrections
2438                }
2439
2440                # --- calculating statistics depends on operations type in TKS_OPERATION_TYPES:
2441                for item in ops:
2442                    if item["state"] == "OPERATION_STATE_EXECUTED":
2443                        payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2444
2445                        # count buy operations:
2446                        if "_BUY" in item["operationType"]:
2447                            customStat["buyCount"] += 1
2448
2449                            if item["payment"]["currency"] in customStat["buyTotal"].keys():
2450                                customStat["buyTotal"][item["payment"]["currency"]] += payment
2451
2452                            else:
2453                                customStat["buyTotal"][item["payment"]["currency"]] = payment
2454
2455                        # count sell operations:
2456                        elif "_SELL" in item["operationType"]:
2457                            customStat["sellCount"] += 1
2458
2459                            if item["payment"]["currency"] in customStat["sellTotal"].keys():
2460                                customStat["sellTotal"][item["payment"]["currency"]] += payment
2461
2462                            else:
2463                                customStat["sellTotal"][item["payment"]["currency"]] = payment
2464
2465                        # count incoming operations:
2466                        elif item["operationType"] in ["OPERATION_TYPE_INPUT"]:
2467                            if item["payment"]["currency"] in customStat["payIn"].keys():
2468                                customStat["payIn"][item["payment"]["currency"]] += payment
2469
2470                            else:
2471                                customStat["payIn"][item["payment"]["currency"]] = payment
2472
2473                        # count withdrawals operations:
2474                        elif item["operationType"] in ["OPERATION_TYPE_OUTPUT"]:
2475                            if item["payment"]["currency"] in customStat["payOut"].keys():
2476                                customStat["payOut"][item["payment"]["currency"]] += payment
2477
2478                            else:
2479                                customStat["payOut"][item["payment"]["currency"]] = payment
2480
2481                        # count dividends income:
2482                        elif item["operationType"] in ["OPERATION_TYPE_DIVIDEND", "OPERATION_TYPE_DIVIDEND_TRANSFER", "OPERATION_TYPE_DIV_EXT"]:
2483                            if item["payment"]["currency"] in customStat["divs"].keys():
2484                                customStat["divs"][item["payment"]["currency"]] += payment
2485
2486                            else:
2487                                customStat["divs"][item["payment"]["currency"]] = payment
2488
2489                        # count coupon's income:
2490                        elif item["operationType"] in ["OPERATION_TYPE_COUPON", "OPERATION_TYPE_BOND_REPAYMENT_FULL", "OPERATION_TYPE_BOND_REPAYMENT"]:
2491                            if item["payment"]["currency"] in customStat["coupons"].keys():
2492                                customStat["coupons"][item["payment"]["currency"]] += payment
2493
2494                            else:
2495                                customStat["coupons"][item["payment"]["currency"]] = payment
2496
2497                        # count broker commissions:
2498                        elif item["operationType"] in ["OPERATION_TYPE_BROKER_FEE", "OPERATION_TYPE_SUCCESS_FEE", "OPERATION_TYPE_TRACK_MFEE", "OPERATION_TYPE_TRACK_PFEE"]:
2499                            if item["payment"]["currency"] in customStat["brokerCom"].keys():
2500                                customStat["brokerCom"][item["payment"]["currency"]] += payment
2501
2502                            else:
2503                                customStat["brokerCom"][item["payment"]["currency"]] = payment
2504
2505                        # count service commissions:
2506                        elif item["operationType"] in ["OPERATION_TYPE_SERVICE_FEE"]:
2507                            if item["payment"]["currency"] in customStat["serviceCom"].keys():
2508                                customStat["serviceCom"][item["payment"]["currency"]] += payment
2509
2510                            else:
2511                                customStat["serviceCom"][item["payment"]["currency"]] = payment
2512
2513                        # count margin commissions:
2514                        elif item["operationType"] in ["OPERATION_TYPE_MARGIN_FEE"]:
2515                            if item["payment"]["currency"] in customStat["marginCom"].keys():
2516                                customStat["marginCom"][item["payment"]["currency"]] += payment
2517
2518                            else:
2519                                customStat["marginCom"][item["payment"]["currency"]] = payment
2520
2521                        # count withholding taxes:
2522                        elif "_TAX" in item["operationType"]:
2523                            if item["payment"]["currency"] in customStat["allTaxes"].keys():
2524                                customStat["allTaxes"][item["payment"]["currency"]] += payment
2525
2526                            else:
2527                                customStat["allTaxes"][item["payment"]["currency"]] = payment
2528
2529                        else:
2530                            continue
2531
2532                customStat["opsCount"] += customStat["buyCount"] + customStat["sellCount"]
2533
2534                # --- view "Actions" lines:
2535                info.extend([
2536                    "| Report sections            |                               |                              |                      |                        |\n",
2537                    "|----------------------------|-------------------------------|------------------------------|----------------------|------------------------|\n",
2538                    "| **Actions:**               | Trades: {:<21} | Trading volumes:             |                      |                        |\n".format(customStat["opsCount"]),
2539                    "|                            |   Buy: {:<22} | {:<28} |                      |                        |\n".format(
2540                        "{} ({:.1f}%)".format(customStat["buyCount"], 100 * customStat["buyCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2541                        "  rub, buy: {:<16}".format("{:.2f}".format(customStat["buyTotal"]["rub"])) if customStat["buyTotal"]["rub"] != 0 else "  —",
2542                    ),
2543                    "|                            |   Sell: {:<21} | {:<28} |                      |                        |\n".format(
2544                        "{} ({:.1f}%)".format(customStat["sellCount"], 100 * customStat["sellCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2545                        "  rub, sell: {:<13}".format("+{:.2f}".format(customStat["sellTotal"]["rub"])) if customStat["sellTotal"]["rub"] != 0 else "  —",
2546                    ),
2547                ])
2548
2549                opsKeys = sorted(list(set(list(customStat["buyTotal"].keys()) + list(customStat["sellTotal"].keys()))))
2550                for key in opsKeys:
2551                    if key == "rub":
2552                        continue
2553
2554                    info.extend([
2555                        "|                            |                               | {:<28} |                      |                        |\n".format(
2556                            "  {}, buy: {:<16}".format(key, "{:.2f}".format(customStat["buyTotal"][key]) if key and key in customStat["buyTotal"].keys() and customStat["buyTotal"][key] != 0 else 0)
2557                        ),
2558                        "|                            |                               | {:<28} |                      |                        |\n".format(
2559                            "  {}, sell: {:<13}".format(key, "+{:.2f}".format(customStat["sellTotal"][key]) if key and key in customStat["sellTotal"].keys() and customStat["sellTotal"][key] != 0 else 0)
2560                        ),
2561                    ])
2562
2563                info.append(splitLine1)
2564
2565                def _InfoStr(data1: dict, data2: dict, data3: dict, data4: dict, cur: str = "") -> str:
2566                    return "|                            | {:<29} | {:<28} | {:<20} | {:<22} |\n".format(
2567                            "  {}: {}{:.2f}".format(cur, "+" if data1[cur] > 0 else "", data1[cur]) if cur and cur in data1.keys() and data1[cur] != 0 else "  —",
2568                            "  {}: {}{:.2f}".format(cur, "+" if data2[cur] > 0 else "", data2[cur]) if cur and cur in data2.keys() and data2[cur] != 0 else "  —",
2569                            "  {}: {}{:.2f}".format(cur, "+" if data3[cur] > 0 else "", data3[cur]) if cur and cur in data3.keys() and data3[cur] != 0 else "  —",
2570                            "  {}: {}{:.2f}".format(cur, "+" if data4[cur] > 0 else "", data4[cur]) if cur and cur in data4.keys() and data4[cur] != 0 else "  —",
2571                    )
2572
2573                # --- view "Payments" lines:
2574                info.append("| **Payments:**              | Deposit on broker account:    | Withdrawals:                 | Dividends income:    | Coupons income:        |\n")
2575                paymentsKeys = sorted(list(set(list(customStat["payIn"].keys()) + list(customStat["payOut"].keys()) + list(customStat["divs"].keys()) + list(customStat["coupons"].keys()))))
2576
2577                for key in paymentsKeys:
2578                    info.append(_InfoStr(customStat["payIn"], customStat["payOut"], customStat["divs"], customStat["coupons"], key))
2579
2580                info.append(splitLine1)
2581
2582                # --- view "Commissions and taxes" lines:
2583                info.append("| **Commissions and taxes:** | Broker commissions:           | Service commissions:         | Margin commissions:  | All taxes/corrections: |\n")
2584                comKeys = sorted(list(set(list(customStat["brokerCom"].keys()) + list(customStat["serviceCom"].keys()) + list(customStat["marginCom"].keys()) + list(customStat["allTaxes"].keys()))))
2585
2586                for key in comKeys:
2587                    info.append(_InfoStr(customStat["brokerCom"], customStat["serviceCom"], customStat["marginCom"], customStat["allTaxes"], key))
2588
2589                info.extend([
2590                    "\n## All operations{}\n\n".format("" if showCancelled else " (without cancelled status)"),
2591                    "| Date and time       | FIGI         | Ticker       | Asset      | Value     | Payment         | Status     | Operation type                                                     |\n",
2592                    "|---------------------|--------------|--------------|------------|-----------|-----------------|------------|--------------------------------------------------------------------|\n",
2593                ])
2594
2595            else:
2596                info.append("Broker returned no operations during this period\n")
2597
2598            # --- view "Operations" section:
2599            for item in ops:
2600                if not showCancelled and TKS_OPERATION_STATES[item["state"]] == TKS_OPERATION_STATES["OPERATION_STATE_CANCELED"]:
2601                    continue
2602
2603                else:
2604                    self._figi = item["figi"] if item["figi"] else ""
2605                    payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2606                    instrument = self.SearchByFIGI(requestPrice=False) if self._figi else {}
2607
2608                    # group of deals during one day:
2609                    if nextDay and item["date"].split("T")[0] != nextDay:
2610                        info.append(splitLine2)
2611                        nextDay = ""
2612
2613                    else:
2614                        nextDay = item["date"].split("T")[0]  # saving current day for splitting
2615
2616                    info.append("| {:<19} | {:<12} | {:<12} | {:<10} | {:<9} | {:>15} | {:<10} | {:<66} |\n".format(
2617                        item["date"].replace("T", " ").replace("Z", "").split(".")[0],
2618                        self._figi if self._figi else "—",
2619                        instrument["ticker"] if instrument else "—",
2620                        instrument["type"] if instrument else "—",
2621                        item["quantity"] if int(item["quantity"]) > 0 else "—",
2622                        "{}{:.2f} {}".format("+" if payment > 0 else "", payment, item["payment"]["currency"]) if payment != 0 else "—",
2623                        TKS_OPERATION_STATES[item["state"]],
2624                        TKS_OPERATION_TYPES[item["operationType"]],
2625                    ))
2626
2627            infoText = "".join(info)
2628
2629            if show:
2630                if self.moreDebug:
2631                    uLogger.debug("Records about history of a client's operations successfully received")
2632
2633                uLogger.info(infoText)
2634
2635            if self.reportFile:
2636                with open(self.reportFile, "w", encoding="UTF-8") as fH:
2637                    fH.write(infoText)
2638
2639                uLogger.info("History of a client's operations are saved to file: [{}]".format(os.path.abspath(self.reportFile)))
2640
2641                if self.useHTMLReports:
2642                    htmlFilePath = self.reportFile.replace(".md", ".html") if self.reportFile.endswith(".md") else self.reportFile + ".html"
2643                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
2644                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Client's operations", commonCSS=COMMON_CSS, markdown=infoText))
2645
2646                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
2647
2648        return ops, customStat
2649
2650    def History(self, start: str = None, end: str = None, interval: str = "hour", onlyMissing: bool = False, csvSep: str = ",", show: bool = False) -> pd.DataFrame:
2651        """
2652        This method returns last history candles of the current instrument defined by `ticker` or `figi` (FIGI id).
2653
2654        History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`.
2655        Warning! Broker server used ISO UTC time by default.
2656
2657        If `historyFile` is not `None` then method save history to file, otherwise return only Pandas DataFrame.
2658        Also, `historyFile` used to update history with `onlyMissing` parameter.
2659
2660        See also: `LoadHistory()` and `ShowHistoryChart()` methods.
2661
2662        :param start: see docstring in `TradeRoutines.GetDatesAsString()` method.
2663        :param end: see docstring in `TradeRoutines.GetDatesAsString()` method.
2664        :param interval: this is a candle interval. Current available values are `"1min"`, `"5min"`, `"15min"`,
2665                         `"hour"`, `"day"`. Default: `"hour"`.
2666        :param onlyMissing: if `True` then add only last missing candles, do not request all history length from `start`.
2667                            False by default. Warning! History appends only from last candle to current time
2668                            with always update last candle!
2669        :param csvSep: separator if csv-file is used, `,` by default.
2670        :param show: if `True` then also prints Pandas DataFrame to the console.
2671        :return: Pandas DataFrame with prices history. Headers of columns are defined by default:
2672                 `["date", "time", "open", "high", "low", "close", "volume"]`.
2673        """
2674        strStartDate, strEndDate = GetDatesAsString(start, end, userFormat=TKS_DATE_FORMAT, outputFormat=TKS_DATE_TIME_FORMAT)  # example: ("2020-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2675        headers = ["date", "time", "open", "high", "low", "close", "volume"]  # sequence and names of column headers
2676        history = None  # empty pandas object for history
2677
2678        if interval not in TKS_CANDLE_INTERVALS.keys():
2679            uLogger.error("Interval parameter must be string with current available values: `1min`, `5min`, `15min`, `hour` and `day`.")
2680            raise Exception("Incorrect value")
2681
2682        if not (self._ticker or self._figi):
2683            uLogger.error("Ticker or FIGI must be defined!")
2684            raise Exception("Ticker or FIGI required")
2685
2686        if self._ticker and not self._figi:
2687            instrumentByTicker = self.SearchByTicker(requestPrice=False)
2688            self._figi = instrumentByTicker["figi"] if instrumentByTicker else ""
2689
2690        if self._figi and not self._ticker:
2691            instrumentByFIGI = self.SearchByFIGI(requestPrice=False)
2692            self._ticker = instrumentByFIGI["ticker"] if instrumentByFIGI else ""
2693
2694        dtStart = datetime.strptime(strStartDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from start time string
2695        dtEnd = datetime.strptime(strEndDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from end time string
2696        if interval.lower() != "day":
2697            dtEnd += timedelta(seconds=1)  # adds 1 sec for requests, because day end returned by `TradeRoutines.GetDatesAsString()` is 23:59:59
2698
2699        delta = dtEnd - dtStart  # current UTC time minus last time in file
2700        deltaMinutes = delta.days * 1440 + delta.seconds // 60  # minutes between start and end dates
2701
2702        # calculate history length in candles:
2703        length = deltaMinutes // TKS_CANDLE_INTERVALS[interval][1]
2704        if deltaMinutes % TKS_CANDLE_INTERVALS[interval][1] > 0:
2705            length += 1  # to avoid fraction time
2706
2707        # calculate data blocks count:
2708        blocks = 1 if length < TKS_CANDLE_INTERVALS[interval][2] else 1 + length // TKS_CANDLE_INTERVALS[interval][2]
2709
2710        uLogger.debug("Original requested time period in local time: from [{}] to [{}]".format(start, end))
2711        uLogger.debug("Requested time period is about from [{}] UTC to [{}] UTC".format(strStartDate, strEndDate))
2712        uLogger.debug("Calculated history length: [{}], interval: [{}]".format(length, interval))
2713        uLogger.debug("Data blocks, count: [{}], max candles in block: [{}]".format(blocks, TKS_CANDLE_INTERVALS[interval][2]))
2714        uLogger.debug("Requesting history candlesticks, ticker: [{}], FIGI: [{}]. Wait, please...".format(self._ticker, self._figi))
2715
2716        tempOld = None  # pandas object for old history, if --only-missing key present
2717        lastTime = None  # datetime object of last old candle in file
2718
2719        if onlyMissing and self.historyFile is not None and self.historyFile and os.path.exists(self.historyFile):
2720            uLogger.debug("--only-missing key present, add only last missing candles...")
2721            uLogger.debug("History file will be updated: [{}]".format(os.path.abspath(self.historyFile)))
2722
2723            tempOld = pd.read_csv(self.historyFile, sep=csvSep, header=None, names=headers)
2724
2725            tempOld["date"] = pd.to_datetime(tempOld["date"])  # load date "as is"
2726            tempOld["date"] = tempOld["date"].dt.strftime("%Y.%m.%d")  # convert date to string
2727            tempOld["time"] = pd.to_datetime(tempOld["time"])  # load time "as is"
2728            tempOld["time"] = tempOld["time"].dt.strftime("%H:%M")  # convert time to string
2729
2730            # get last datetime object from last string in file or minus 1 delta if file is empty:
2731            if len(tempOld) > 0:
2732                lastTime = datetime.strptime(tempOld.date.iloc[-1] + " " + tempOld.time.iloc[-1], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2733
2734            else:
2735                lastTime = dtEnd - timedelta(days=1)  # history file is empty, so last date set at -1 day
2736
2737            tempOld = tempOld[:-1]  # always remove last old candle because it may be incompletely at the current time
2738
2739        responseJSONs = []  # raw history blocks of data
2740
2741        blockEnd = dtEnd
2742        for item in range(blocks):
2743            tail = length % TKS_CANDLE_INTERVALS[interval][2] if item + 1 == blocks else TKS_CANDLE_INTERVALS[interval][2]
2744            blockStart = blockEnd - timedelta(minutes=TKS_CANDLE_INTERVALS[interval][1] * tail)
2745
2746            uLogger.debug("[Block #{}/{}] time period: [{}] UTC - [{}] UTC".format(
2747                item + 1, blocks, blockStart.strftime(TKS_DATE_TIME_FORMAT), blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2748            ))
2749
2750            if blockStart == blockEnd:
2751                uLogger.debug("Skipped this zero-length block...")
2752
2753            else:
2754                # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetCandles
2755                historyURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetCandles"
2756                self.body = str({
2757                    "figi": self._figi,
2758                    "from": blockStart.strftime(TKS_DATE_TIME_FORMAT),
2759                    "to": blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2760                    "interval": TKS_CANDLE_INTERVALS[interval][0]
2761                })
2762                responseJSON = self.SendAPIRequest(historyURL, reqType="POST", retry=1, pause=1)
2763
2764                if "code" in responseJSON.keys():
2765                    uLogger.debug("An issue occurred and block #{}/{} is empty".format(item + 1, blocks))
2766
2767                else:
2768                    if start is not None and (start.lower() == "yesterday" or start == end) and interval == "day" and len(responseJSON["candles"]) > 1:
2769                        responseJSON["candles"] = responseJSON["candles"][:-1]  # removes last candle for "yesterday" request
2770
2771                    responseJSONs = responseJSON["candles"] + responseJSONs  # add more old history behind newest dates
2772
2773            blockEnd = blockStart
2774
2775        printCount = len(responseJSONs)  # candles to show in console
2776        if responseJSONs:
2777            tempHistory = pd.DataFrame(
2778                data={
2779                    "date": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2780                    "time": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2781                    "open": [NanoToFloat(item["open"]["units"], item["open"]["nano"]) for item in responseJSONs],
2782                    "high": [NanoToFloat(item["high"]["units"], item["high"]["nano"]) for item in responseJSONs],
2783                    "low": [NanoToFloat(item["low"]["units"], item["low"]["nano"]) for item in responseJSONs],
2784                    "close": [NanoToFloat(item["close"]["units"], item["close"]["nano"]) for item in responseJSONs],
2785                    "volume": [int(item["volume"]) for item in responseJSONs],
2786                },
2787                index=range(len(responseJSONs)),
2788                columns=["date", "time", "open", "high", "low", "close", "volume"],
2789            )
2790            tempHistory["date"] = tempHistory["date"].dt.strftime("%Y.%m.%d")
2791            tempHistory["time"] = tempHistory["time"].dt.strftime("%H:%M")
2792
2793            # append only newest candles to old history if --only-missing key present:
2794            if onlyMissing and tempOld is not None and lastTime is not None:
2795                index = 0  # find start index in tempHistory data:
2796
2797                for i, item in tempHistory.iterrows():
2798                    curTime = datetime.strptime(item["date"] + " " + item["time"], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2799
2800                    if curTime == lastTime:
2801                        uLogger.debug("History will be updated starting from the date: [{}]".format(curTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
2802                        index = i
2803                        printCount = index + 1
2804                        break
2805
2806                history = pd.concat([tempOld, tempHistory[index:]], ignore_index=True)
2807
2808            else:
2809                history = tempHistory  # if no `--only-missing` key then load full data from server
2810
2811            uLogger.debug("Last 3 rows of received history:\n{}".format(pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-3:], max_cols=20, index=False)))
2812
2813        if history is not None and not history.empty:
2814            if show:
2815                uLogger.info("Here's requested history between [{}] UTC and [{}] UTC, not-empty candles count: [{}]\n{}".format(
2816                    strStartDate.replace("T", " ").replace("Z", ""), strEndDate.replace("T", " ").replace("Z", ""), len(history[-printCount:]),
2817                    pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-printCount:], max_cols=20, index=False),
2818                ))
2819
2820        else:
2821            uLogger.warning("Received an empty candles history!")
2822
2823        if self.historyFile is not None:
2824            if history is not None and not history.empty:
2825                history.to_csv(self.historyFile, sep=csvSep, index=False, header=None)
2826                uLogger.info("Ticker [{}], FIGI [{}], tf: [{}], history saved: [{}]".format(self._ticker, self._figi, interval, os.path.abspath(self.historyFile)))
2827
2828            else:
2829                uLogger.warning("Empty history received! File NOT updated: [{}]".format(os.path.abspath(self.historyFile)))
2830
2831        else:
2832            uLogger.debug("--output key is not defined. Parsed history file not saved to file, only Pandas DataFrame returns.")
2833
2834        return history
2835
2836    def LoadHistory(self, filePath: str) -> pd.DataFrame:
2837        """
2838        Load candles history from csv-file and return Pandas DataFrame object.
2839
2840        See also: `History()` and `ShowHistoryChart()` methods.
2841
2842        :param filePath: path to csv-file to open.
2843        """
2844        loadedHistory = None  # init candles data object
2845
2846        uLogger.debug("Loading candles history with PriceGenerator module. Wait, please...")
2847
2848        if os.path.exists(filePath):
2849            loadedHistory = self.priceModel.LoadFromFile(filePath)  # load data and get chain of candles as Pandas DataFrame
2850
2851            tfStr = self.priceModel.FormattedDelta(
2852                self.priceModel.timeframe,
2853                "{days} days {hours}h {minutes}m {seconds}s",
2854            ) if self.priceModel.timeframe >= timedelta(days=1) else self.priceModel.FormattedDelta(
2855                self.priceModel.timeframe,
2856                "{hours}h {minutes}m {seconds}s",
2857            )
2858
2859            if loadedHistory is not None and not loadedHistory.empty:
2860                uLogger.info("Rows count loaded: [{}], detected timeframe of candles: [{}]. Showing some last rows:\n{}".format(
2861                    len(loadedHistory),
2862                    tfStr,
2863                    pd.DataFrame.to_string(loadedHistory[-10:], max_cols=20)),
2864                )
2865
2866            else:
2867                uLogger.warning("It was loaded an empty history! Path: [{}]".format(os.path.abspath(filePath)))
2868
2869        else:
2870            uLogger.error("File with candles history does not exist! Check the path: [{}]".format(filePath))
2871
2872        return loadedHistory
2873
2874    def ShowHistoryChart(self, candles: Union[str, pd.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:
2875        """
2876        Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.
2877
2878        Self variable `htmlHistoryFile` can be use as html-file name to save interaction or non-interaction chart.
2879        Default: `index.html` (both for interact and non-interact candlesticks chart).
2880
2881        See also: `History()` and `LoadHistory()` methods.
2882
2883        :param candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
2884        :param interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart.
2885                         See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters
2886                         If False then chain of candlesticks will render as not interactive Google Candlestick chart.
2887                         See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
2888        :param openInBrowser: if True then immediately open chart in default browser, otherwise only path to
2889                              html-file prints to console. False by default, to avoid issues with `permissions denied` to html-file.
2890        """
2891        if isinstance(candles, str):
2892            self.priceModel.prices = self.LoadHistory(filePath=candles)  # load candles chain from file
2893            self.priceModel.ticker = os.path.basename(candles)  # use filename as ticker name in PriceGenerator
2894
2895        elif isinstance(candles, pd.DataFrame):
2896            self.priceModel.prices = candles  # set candles chain from variable
2897            self.priceModel.ticker = self._ticker  # use current TKSBrokerAPI ticker as ticker name in PriceGenerator
2898
2899            if "datetime" not in candles.columns:
2900                self.priceModel.prices["datetime"] = pd.to_datetime(candles.date + ' ' + candles.time, utc=True)  # PriceGenerator uses "datetime" column with date and time
2901
2902        else:
2903            uLogger.error("`candles` variable must be path string to the csv-file with candles in OHLCV-model or like Pandas Dataframe object!")
2904            raise Exception("Incorrect value")
2905
2906        self.priceModel.horizon = len(self.priceModel.prices)  # use length of candles data as horizon in PriceGenerator
2907
2908        if interact:
2909            uLogger.debug("Rendering interactive candles chart. Wait, please...")
2910
2911            self.priceModel.RenderBokeh(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2912
2913        else:
2914            uLogger.debug("Rendering non-interactive candles chart. Wait, please...")
2915
2916            self.priceModel.RenderGoogle(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2917
2918        uLogger.info("Rendered candles chart: [{}]".format(os.path.abspath(self.htmlHistoryFile)))
2919
2920    def Trade(self, operation: str, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2921        """
2922        Universal method to create market order and make deal at the current price for current `accountId`. Returns JSON data with response.
2923        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2924
2925        See also: `Order()` docstring. More simple methods than `Trade()` are `Buy()` and `Sell()`.
2926
2927        :param operation: string "Buy" or "Sell".
2928        :param lots: volume, integer count of lots >= 1.
2929        :param tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter `targetPrice` in `self.Order()`.
2930        :param sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter `targetPrice` in `self.Order()`.
2931        :param expDate: string "Undefined" by default or local date in future,
2932                        it is a string with format `%Y-%m-%d %H:%M:%S`.
2933        :return: JSON with response from broker server.
2934        """
2935        if self.accountId is None or not self.accountId:
2936            uLogger.error("Variable `accountId` must be defined for using this method!")
2937            raise Exception("Account ID required")
2938
2939        if operation is None or not operation or operation not in ("Buy", "Sell"):
2940            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
2941            raise Exception("Incorrect value")
2942
2943        if lots is None or lots < 1:
2944            uLogger.warning("You must define trade volume > 0: integer count of lots! For current operation lots reset to 1.")
2945            lots = 1
2946
2947        if tp is None or tp < 0:
2948            tp = 0
2949
2950        if sl is None or sl < 0:
2951            sl = 0
2952
2953        if expDate is None or not expDate:
2954            expDate = "Undefined"
2955
2956        if not (self._ticker or self._figi):
2957            uLogger.error("Ticker or FIGI must be defined!")
2958            raise Exception("Ticker or FIGI required")
2959
2960        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
2961        self._ticker = instrument["ticker"]
2962        self._figi = instrument["figi"]
2963
2964        uLogger.debug("Opening [{}] market order: ticker [{}], FIGI [{}], lots [{}], TP [{:.4f}], SL [{:.4f}], expiration date of TP/SL orders [{}]. Wait, please...".format(operation, self._ticker, self._figi, lots, tp, sl, expDate))
2965
2966        openTradeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
2967        self.body = str({
2968            "figi": self._figi,
2969            "quantity": str(lots),
2970            "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
2971            "accountId": str(self.accountId),
2972            "orderType": "ORDER_TYPE_MARKET",  # see: TKS_ORDER_TYPES
2973        })
2974        response = self.SendAPIRequest(openTradeURL, reqType="POST", retry=0)
2975
2976        if "orderId" in response.keys():
2977            uLogger.info("[{}] market order [{}] was executed: ticker [{}], FIGI [{}], lots [{}]. Total order price: [{:.4f} {}] (with commission: [{:.2f} {}]). Average price of lot: [{:.2f} {}]".format(
2978                operation, response["orderId"],
2979                self._ticker, self._figi, lots,
2980                NanoToFloat(response["totalOrderAmount"]["units"], response["totalOrderAmount"]["nano"]), response["totalOrderAmount"]["currency"],
2981                NanoToFloat(response["initialCommission"]["units"], response["initialCommission"]["nano"]), response["initialCommission"]["currency"],
2982                NanoToFloat(response["executedOrderPrice"]["units"], response["executedOrderPrice"]["nano"]), response["executedOrderPrice"]["currency"],
2983            ))
2984
2985            if tp > 0:
2986                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=tp, limitPrice=tp, stopType="TP", expDate=expDate)
2987
2988            if sl > 0:
2989                self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=sl, limitPrice=sl, stopType="SL", expDate=expDate)
2990
2991        else:
2992            uLogger.warning("Not `oK` status received! Market order not executed. See full debug log and try again open order later.")
2993
2994        return response
2995
2996    def Buy(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2997        """
2998        More simple method than `Trade()`. Create `Buy` market order and make deal at the current price. Returns JSON data with response.
2999        If `tp` or `sl` > 0, then in additional will opens stop-orders with "TP" and "SL" flags for `stopType` parameter.
3000
3001        See also: `Order()` and `Trade()` docstrings.
3002
3003        :param lots: volume, integer count of lots >= 1.
3004        :param tp: float > 0, take profit price of stop-order.
3005        :param sl: float > 0, stop loss price of stop-order.
3006        :param expDate: it's a local date in future.
3007                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3008        :return: JSON with response from broker server.
3009        """
3010        return self.Trade(operation="Buy", lots=lots, tp=tp, sl=sl, expDate=expDate)
3011
3012    def Sell(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
3013        """
3014        More simple method than `Trade()`. Create `Sell` market order and make deal at the current price. Returns JSON data with response.
3015        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
3016
3017        See also: `Order()` and `Trade()` docstrings.
3018
3019        :param lots: volume, integer count of lots >= 1.
3020        :param tp: float > 0, take profit price of stop-order.
3021        :param sl: float > 0, stop loss price of stop-order.
3022        :param expDate: it's a local date in the future.
3023                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3024        :return: JSON with response from broker server.
3025        """
3026        return self.Trade(operation="Sell", lots=lots, tp=tp, sl=sl, expDate=expDate)
3027
3028    def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:
3029        """
3030        Close position of given instruments.
3031
3032        :param instruments: list of instruments defined by tickers or FIGIs that must be closed.
3033        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3034                         This avoids unnecessary downloading data from the server.
3035        """
3036        if instruments is None or not instruments:
3037            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3038            raise Exception("Ticker or FIGI required")
3039
3040        if isinstance(instruments, str):
3041            instruments = [instruments]
3042
3043        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3044        if uniqueInstruments:
3045            if portfolio is None or not portfolio:
3046                portfolio = self.Overview(show=False)
3047
3048            allOpened = [item["figi"] for iType in TKS_INSTRUMENTS for item in portfolio["stat"][iType]]
3049            uLogger.debug("All opened instruments by it's FIGI: {}".format(", ".join(allOpened)))
3050
3051            for self._figi in uniqueInstruments:
3052                if self._figi not in allOpened:
3053                    uLogger.warning("Instrument with FIGI [{}] not in open positions list!".format(self._figi))
3054                    continue
3055
3056                # search open trade info about instrument by ticker:
3057                instrument = {}
3058                for iType in TKS_INSTRUMENTS:
3059                    if instrument:
3060                        break
3061
3062                    for item in portfolio["stat"][iType]:
3063                        if item["figi"] == self._figi:
3064                            instrument = item
3065                            break
3066
3067                if instrument:
3068                    self._ticker = instrument["ticker"]
3069                    self._figi = instrument["figi"]
3070
3071                    uLogger.debug("Closing trade of instrument: ticker [{}], FIGI[{}], lots [{}]{}. Wait, please...".format(
3072                        self._ticker,
3073                        self._figi,
3074                        int(instrument["volume"]),
3075                        ", blocked [{}]".format(instrument["blocked"]) if instrument["blocked"] > 0 else "",
3076                    ))
3077
3078                    tradeLots = abs(instrument["lots"]) - instrument["blocked"]  # available volumes in lots for close operation
3079
3080                    if tradeLots > 0:
3081                        if instrument["blocked"] > 0:
3082                            uLogger.warning("Just for your information: there are [{}] lots blocked for instrument [{}]! Available only [{}] lots to closing trade.".format(
3083                                instrument["blocked"],
3084                                self._ticker,
3085                                tradeLots,
3086                            ))
3087
3088                        # if direction is "Long" then we need sell, if direction is "Short" then we need buy:
3089                        self.Trade(operation="Sell" if instrument["direction"] == "Long" else "Buy", lots=tradeLots)
3090
3091                    else:
3092                        uLogger.warning("There are no available lots for instrument [{}] to closing trade at this moment! Try again later or cancel some orders.".format(self._ticker))
3093
3094    def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:
3095        """
3096        Close all positions of given instruments with defined type.
3097
3098        :param iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
3099        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3100                         This avoids unnecessary downloading data from the server.
3101        """
3102        if iType not in TKS_INSTRUMENTS:
3103            uLogger.warning("Type of the instrument must be one of supported types: {}. Given: [{}]".format(", ".join(TKS_INSTRUMENTS), iType))
3104
3105        else:
3106            if portfolio is None or not portfolio:
3107                portfolio = self.Overview(show=False)
3108
3109            tickers = [item["ticker"] for item in portfolio["stat"][iType]]
3110            uLogger.debug("Instrument tickers with type [{}] that will be closed: {}".format(iType, tickers))
3111
3112            if tickers and portfolio:
3113                self.CloseTrades(tickers, portfolio)
3114
3115            else:
3116                uLogger.info("Instrument tickers with type [{}] not found, nothing to close.".format(iType))
3117
3118    def Order(self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3119        """
3120        Universal method to create market or limit orders with all available parameters for current `accountId`.
3121        See more simple methods: `BuyLimit()`, `BuyStop()`, `SellLimit()`, `SellStop()`.
3122
3123        If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above
3124        current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.
3125
3126        Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell"
3127        then broker immediately open market order as you can do simple --buy or --sell operations!
3128
3129        If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell".
3130        When current price will go up or down to target price value then broker opens a limit order.
3131        Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.
3132
3133        Only one attempt and no retry for opens order. If network issue occurred you can create new request.
3134
3135        :param operation: string "Buy" or "Sell".
3136        :param orderType: string "Limit" or "Stop".
3137        :param lots: volume, integer count of lots >= 1.
3138        :param targetPrice: target price > 0. This is open trade price for limit order.
3139        :param limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice.
3140                           Broker will creates limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
3141        :param stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types
3142                         "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3143                         Stop loss order always executed by market price.
3144        :param expDate: string "Undefined" by default or local date in future.
3145                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3146                        This date is converting to UTC format for server. This parameter only makes sense for stop-order.
3147                        A limit order has no expiration date, it lasts until the end of the trading day.
3148        :return: JSON with response from broker server.
3149        """
3150        if self.accountId is None or not self.accountId:
3151            uLogger.error("Variable `accountId` must be defined for using this method!")
3152            raise Exception("Account ID required")
3153
3154        if operation is None or not operation or operation not in ("Buy", "Sell"):
3155            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3156            raise Exception("Incorrect value")
3157
3158        if orderType is None or not orderType or orderType not in ("Limit", "Stop"):
3159            uLogger.error("You must define order type only one of them: `Limit` or `Stop`!")
3160            raise Exception("Incorrect value")
3161
3162        if lots is None or lots < 1:
3163            uLogger.error("You must define trade volume > 0: integer count of lots!")
3164            raise Exception("Incorrect value")
3165
3166        if targetPrice is None or targetPrice <= 0:
3167            uLogger.error("Target price for limit-order must be greater than 0!")
3168            raise Exception("Incorrect value")
3169
3170        if limitPrice is None or limitPrice <= 0:
3171            limitPrice = targetPrice
3172
3173        if stopType is None or not stopType or stopType not in ("SL", "TP", "Limit"):
3174            stopType = "Limit"
3175
3176        if expDate is None or not expDate:
3177            expDate = "Undefined"
3178
3179        if not (self._ticker or self._figi):
3180            uLogger.error("Tocker or FIGI must be defined!")
3181            raise Exception("Ticker or FIGI required")
3182
3183        response = {}
3184        instrument = self.SearchByTicker(requestPrice=True) if self._ticker else self.SearchByFIGI(requestPrice=True)
3185        self._ticker = instrument["ticker"]
3186        self._figi = instrument["figi"]
3187
3188        if orderType == "Limit":
3189            uLogger.debug(
3190                "Creating pending limit-order: ticker [{}], FIGI [{}], action [{}], lots [{}] and the target price [{:.2f} {}]. Wait, please...".format(
3191                    self._ticker, self._figi,
3192                    operation, lots, targetPrice, instrument["currency"],
3193                ))
3194
3195            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3196            self.body = str({
3197                "figi": self._figi,
3198                "quantity": str(lots),
3199                "price": FloatToNano(targetPrice),
3200                "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3201                "accountId": str(self.accountId),
3202                "orderType": "ORDER_TYPE_LIMIT",  # see: TKS_ORDER_TYPES
3203            })
3204            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3205
3206            if "orderId" in response.keys():
3207                uLogger.info(
3208                    "Limit-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}]".format(
3209                        response["orderId"],
3210                        self._ticker, self._figi,
3211                        operation, lots, targetPrice, instrument["currency"],
3212                    ))
3213
3214                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3215                    if operation == "Buy" and targetPrice > instrument["currentPrice"]["lastPrice"]:
3216                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was higher than current price [{:.2f} {}] broker immediately opened `Buy` market order, such as if you did simple `--buy` operation.".format(
3217                            targetPrice, instrument["currency"],
3218                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3219                        ))
3220
3221                    if operation == "Sell" and targetPrice < instrument["currentPrice"]["lastPrice"]:
3222                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was lower than current price [{:.2f} {}] broker immediately opened `Sell` market order, such as if you did simple `--sell` operation.".format(
3223                            targetPrice, instrument["currency"],
3224                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3225                        ))
3226
3227            else:
3228                uLogger.warning("Not `oK` status received! Limit order not opened. See full debug log and try again open order later.")
3229
3230        if orderType == "Stop":
3231            uLogger.debug(
3232                "Creating stop-order: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and local expiration date [{}]. Wait, please...".format(
3233                    self._ticker, self._figi,
3234                    operation, lots,
3235                    targetPrice, instrument["currency"],
3236                    limitPrice, instrument["currency"],
3237                    stopType, expDate,
3238                ))
3239
3240            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/PostStopOrder"
3241            expDateUTC = "" if expDate == "Undefined" else datetime.strptime(expDate, TKS_PRINT_DATE_TIME_FORMAT).replace(tzinfo=tzlocal()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT_EXT)
3242            stopOrderType = "STOP_ORDER_TYPE_STOP_LOSS" if stopType == "SL" else "STOP_ORDER_TYPE_TAKE_PROFIT" if stopType == "TP" else "STOP_ORDER_TYPE_STOP_LIMIT"
3243
3244            body = {
3245                "figi": self._figi,
3246                "quantity": str(lots),
3247                "price": FloatToNano(limitPrice),
3248                "stopPrice": FloatToNano(targetPrice),
3249                "direction": "STOP_ORDER_DIRECTION_BUY" if operation == "Buy" else "STOP_ORDER_DIRECTION_SELL",  # see: TKS_STOP_ORDER_DIRECTIONS
3250                "accountId": str(self.accountId),
3251                "expirationType": "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE" if expDateUTC else "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL",  # see: TKS_STOP_ORDER_EXPIRATION_TYPES
3252                "stopOrderType": stopOrderType,  # see: TKS_STOP_ORDER_TYPES
3253            }
3254
3255            if expDateUTC:
3256                body["expireDate"] = expDateUTC
3257
3258            self.body = str(body)
3259            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3260
3261            if "stopOrderId" in response.keys():
3262                uLogger.info(
3263                    "Stop-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and expiration date in UTC [{}]".format(
3264                        response["stopOrderId"],
3265                        self._ticker, self._figi,
3266                        operation, lots,
3267                        targetPrice, instrument["currency"],
3268                        limitPrice, instrument["currency"],
3269                        TKS_STOP_ORDER_TYPES[stopOrderType],
3270                        datetime.strptime(expDateUTC, TKS_DATE_TIME_FORMAT_EXT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if expDateUTC else TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"],
3271                    ))
3272
3273                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3274                    if operation == "Buy" and targetPrice < instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3275                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target buy price [{:.2f} {}] is lower than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3276                            targetPrice, instrument["currency"],
3277                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3278                        ))
3279
3280                    if operation == "Sell" and targetPrice > instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3281                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target sell price [{:.2f} {}] is higher than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3282                            targetPrice, instrument["currency"],
3283                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3284                        ))
3285
3286            else:
3287                uLogger.warning("Not `oK` status received! Stop order not opened. See full debug log and try again open order later.")
3288
3289        return response
3290
3291    def BuyLimit(self, lots: int, targetPrice: float) -> dict:
3292        """
3293        Create pending `Buy` limit-order (below current price). You must specify only 2 parameters:
3294        `lots` and `target price` to open buy limit-order. If you try to create buy limit-order above current price then
3295        broker immediately open `Buy` market order, such as if you do simple `--buy` operation!
3296        See also: `Order()` docstring.
3297
3298        :param lots: volume, integer count of lots >= 1.
3299        :param targetPrice: target price > 0. This is open trade price for limit order.
3300        :return: JSON with response from broker server.
3301        """
3302        return self.Order(operation="Buy", orderType="Limit", lots=lots, targetPrice=targetPrice)
3303
3304    def BuyStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3305        """
3306        Create `Buy` stop-order. You must specify at least 2 parameters: `lots` `target price` to open buy stop-order.
3307        In additional you can specify 3 parameters for buy stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3308        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3309        target price value then broker opens a limit order. See also: `Order()` docstring.
3310
3311        :param lots: volume, integer count of lots >= 1.
3312        :param targetPrice: target price > 0. This is trigger price for buy stop-order.
3313        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3314                           with price equal to limitPrice, when current price goes to target price of buy stop-order.
3315        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3316                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3317        :param expDate: string "Undefined" by default or local date in future.
3318                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3319                        This date is converting to UTC format for server.
3320        :return: JSON with response from broker server.
3321        """
3322        return self.Order(operation="Buy", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3323
3324    def SellLimit(self, lots: int, targetPrice: float) -> dict:
3325        """
3326        Create pending `Sell` limit-order (above current price). You must specify only 2 parameters:
3327        `lots` and `target price` to open sell limit-order. If you try to create sell limit-order below current price then
3328        broker immediately open `Sell` market order, such as if you do simple `--sell` operation!
3329        See also: `Order()` docstring.
3330
3331        :param lots: volume, integer count of lots >= 1.
3332        :param targetPrice: target price > 0. This is open trade price for limit order.
3333        :return: JSON with response from broker server.
3334        """
3335        return self.Order(operation="Sell", orderType="Limit", lots=lots, targetPrice=targetPrice)
3336
3337    def SellStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3338        """
3339        Create `Sell` stop-order. You must specify at least 2 parameters: `lots` `target price` to open sell stop-order.
3340        In additional you can specify 3 parameters for sell stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3341        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3342        target price value then broker opens a limit order. See also: `Order()` docstring.
3343
3344        :param lots: volume, integer count of lots >= 1.
3345        :param targetPrice: target price > 0. This is trigger price for sell stop-order.
3346        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3347                           with price equal to limitPrice, when current price goes to target price of sell stop-order.
3348        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3349                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3350        :param expDate: string "Undefined" by default or local date in future.
3351                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3352                        This date is converting to UTC format for server.
3353        :return: JSON with response from broker server.
3354        """
3355        return self.Order(operation="Sell", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3356
3357    def CloseOrders(self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:
3358        """
3359        Cancel order or list of orders by its `orderId` or `stopOrderId` for current `accountId`.
3360
3361        :param orderIDs: list of integers with `orderId` or `stopOrderId`.
3362        :param allOrdersIDs: pre-received lists of all active pending limit orders.
3363                             This avoids unnecessary downloading data from the server.
3364        :param allStopOrdersIDs: pre-received lists of all active stop orders.
3365        """
3366        if self.accountId is None or not self.accountId:
3367            uLogger.error("Variable `accountId` must be defined for using this method!")
3368            raise Exception("Account ID required")
3369
3370        if orderIDs:
3371            if allOrdersIDs is None:
3372                rawOrders = self.RequestPendingOrders()
3373                allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3374
3375            if allStopOrdersIDs is None:
3376                rawStopOrders = self.RequestStopOrders()
3377                allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3378
3379            for orderID in orderIDs:
3380                idInPendingOrders = orderID in allOrdersIDs
3381                idInStopOrders = orderID in allStopOrdersIDs
3382
3383                if not (idInPendingOrders or idInStopOrders):
3384                    uLogger.warning("Order not found by ID: [{}]. Maybe cancelled already? Check it with `--overview` key.".format(orderID))
3385                    continue
3386
3387                else:
3388                    if idInPendingOrders:
3389                        uLogger.debug("Cancelling pending order with ID: [{}]. Wait, please...".format(orderID))
3390
3391                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_CancelOrder
3392                        self.body = str({"accountId": self.accountId, "orderId": orderID})
3393                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/CancelOrder"
3394                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3395
3396                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3397                            if self.moreDebug:
3398                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3399
3400                            uLogger.info("Pending order with ID [{}] successfully cancel".format(orderID))
3401
3402                        else:
3403                            uLogger.warning("Unknown issue occurred when cancelling pending order with ID: [{}]. Check ID and try again.".format(orderID))
3404
3405                    elif idInStopOrders:
3406                        uLogger.debug("Cancelling stop order with ID: [{}]. Wait, please...".format(orderID))
3407
3408                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_CancelStopOrder
3409                        self.body = str({"accountId": self.accountId, "stopOrderId": orderID})
3410                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/CancelStopOrder"
3411                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3412
3413                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3414                            if self.moreDebug:
3415                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3416
3417                            uLogger.info("Stop order with ID [{}] successfully cancel".format(orderID))
3418
3419                        else:
3420                            uLogger.warning("Unknown issue occurred when cancelling stop order with ID: [{}]. Check ID and try again.".format(orderID))
3421
3422                    else:
3423                        continue
3424
3425    def CloseAllOrders(self) -> None:
3426        """
3427        Gets a list of open pending and stop orders and cancel it all.
3428        """
3429        rawOrders = self.RequestPendingOrders()
3430        allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending limit orders ID
3431        lenOrders = len(allOrdersIDs)
3432
3433        rawStopOrders = self.RequestStopOrders()
3434        allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3435        lenSOrders = len(allStopOrdersIDs)
3436
3437        if lenOrders > 0 or lenSOrders > 0:
3438            uLogger.info("Found: [{}] opened pending and [{}] stop orders. Let's trying to cancel it all. Wait, please...".format(lenOrders, lenSOrders))
3439
3440            self.CloseOrders(allOrdersIDs + allStopOrdersIDs, allOrdersIDs, allStopOrdersIDs)
3441
3442        else:
3443            uLogger.info("Orders not found, nothing to cancel.")
3444
3445    def CloseAll(self, *args) -> None:
3446        """
3447        Close all available (not blocked) opened trades and orders.
3448
3449        Also, you can select one or more keywords case-insensitive:
3450        `orders`, `shares`, `bonds`, `etfs` and `futures` from `TKS_INSTRUMENTS` enum to specify trades type.
3451
3452        Currency positions you must close manually using buy or sell operations, `CloseTrades()` or `CloseAllTrades()` methods.
3453        """
3454        overview = self.Overview(show=False)  # get all open trades info
3455
3456        if len(args) == 0:
3457            uLogger.debug("Closing all available (not blocked) opened trades and orders. Currency positions you must closes manually using buy or sell operations! Wait, please...")
3458            self.CloseAllOrders()  # close all pending and stop orders
3459
3460            for iType in TKS_INSTRUMENTS:
3461                if iType != "Currencies":
3462                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3463
3464        else:
3465            uLogger.debug("Closing all available {}. Currency positions you must closes manually using buy or sell operations! Wait, please...".format(list(args)))
3466            lowerArgs = [x.lower() for x in args]
3467
3468            if "orders" in lowerArgs:
3469                self.CloseAllOrders()  # close all pending and stop orders
3470
3471            for iType in TKS_INSTRUMENTS:
3472                if iType.lower() in lowerArgs and iType != "Currencies":
3473                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3474
3475    def CloseAllByTicker(self, instrument: str) -> None:
3476        """
3477        Close all available (not blocked) opened trades and orders for one instrument defined by its ticker.
3478
3479        This method searches opened trade and orders of instrument throw all portfolio and then use
3480        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3481
3482        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3483
3484        :param instrument: string with ticker.
3485        """
3486        if instrument is None or not instrument:
3487            uLogger.error("Ticker name must be defined for using this method!")
3488            raise Exception("Ticker required")
3489
3490        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3491
3492        self._ticker = instrument  # try to set instrument as ticker
3493        self._figi = ""
3494
3495        if self.IsInPortfolio(portfolio=overview):
3496            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with ticker [{}]. Wait, please...")
3497            self.CloseTrades(instruments=[instrument], portfolio=overview)
3498
3499        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3500        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3501
3502        if limitAll and self.IsInLimitOrders(portfolio=overview):
3503            uLogger.debug("Closing all opened pending limit orders for the instrument with ticker [{}]. Wait, please...")
3504            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3505
3506        if stopAll and self.IsInStopOrders(portfolio=overview):
3507            uLogger.debug("Closing all opened stop orders for the instrument with ticker [{}]. Wait, please...")
3508            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3509
3510    def CloseAllByFIGI(self, instrument: str) -> None:
3511        """
3512        Close all available (not blocked) opened trades and orders for one instrument defined by its FIGI id.
3513
3514        This method searches opened trade and orders of instrument throw all portfolio and then use
3515        `CloseTrades()` and `CloseOrders()` methods to close trade and cancel all orders for that instrument.
3516
3517        See also: `IsInLimitOrders()`, `GetLimitOrderIDs()`, `IsInStopOrders()`, `GetStopOrderIDs()`, `CloseTrades()` and `CloseOrders()`.
3518
3519        :param instrument: string with FIGI id.
3520        """
3521        if instrument is None or not instrument:
3522            uLogger.error("FIGI id must be defined for using this method!")
3523            raise Exception("FIGI required")
3524
3525        overview = self.Overview(show=False)  # get user portfolio with all open trades info
3526
3527        self._ticker = ""
3528        self._figi = instrument  # try to set instrument as FIGI id
3529
3530        if self.IsInPortfolio(portfolio=overview):
3531            uLogger.debug("Closing all available (not blocked) opened trade for the instrument with FIGI [{}]. Wait, please...")
3532            self.CloseTrades(instruments=[instrument], portfolio=overview)
3533
3534        limitAll = [item["orderID"] for item in overview["stat"]["orders"]]  # list of all pending limit order IDs
3535        stopAll = [item["orderID"] for item in overview["stat"]["stopOrders"]]  # list of all stop order IDs
3536
3537        if limitAll and self.IsInLimitOrders(portfolio=overview):
3538            uLogger.debug("Closing all opened pending limit orders for the instrument with FIGI [{}]. Wait, please...")
3539            self.CloseOrders(orderIDs=self.GetLimitOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3540
3541        if stopAll and self.IsInStopOrders(portfolio=overview):
3542            uLogger.debug("Closing all opened stop orders for the instrument with FIGI [{}]. Wait, please...")
3543            self.CloseOrders(orderIDs=self.GetStopOrderIDs(portfolio=overview), allOrdersIDs=limitAll, allStopOrdersIDs=stopAll)
3544
3545    @staticmethod
3546    def ParseOrderParameters(operation, **inputParameters):
3547        """
3548        Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.
3549
3550        :param operation: string "Buy" or "Sell".
3551        :param inputParameters: this is dict of strings that looks like this
3552               `{"lots": "L_int,...", "prices": "P_float,..."}` where
3553               "lots" key: one or more lot values (integer numbers) to open with every limit-order
3554               "prices" key: one or more prices to open limit-orders
3555               Counts of values in lots and prices lists must be equals!
3556        :return: list of dictionaries with all lots and prices to open orders that looks like this `[{"lot": lots_1, "price": price_1}, {...}, ...]`
3557        """
3558        # TODO: update order grid work with api v2
3559        pass
3560        # uLogger.debug("Input parameters: {}".format(inputParameters))
3561        #
3562        # if operation is None or not operation or operation not in ("Buy", "Sell"):
3563        #     uLogger.error("You must define operation type: 'Buy' or 'Sell'!")
3564        #     raise Exception("Incorrect value")
3565        #
3566        # if "l" in inputParameters.keys():
3567        #     inputParameters["lots"] = inputParameters.pop("l")
3568        #
3569        # if "p" in inputParameters.keys():
3570        #     inputParameters["prices"] = inputParameters.pop("p")
3571        #
3572        # if "lots" not in inputParameters.keys() or "prices" not in inputParameters.keys():
3573        #     uLogger.error("Both of 'lots' and 'prices' keys must be define to open grid orders!")
3574        #     raise Exception("Incorrect value")
3575        #
3576        # lots = [int(item.strip()) for item in inputParameters["lots"].split(",")]
3577        # prices = [float(item.strip()) for item in inputParameters["prices"].split(",")]
3578        #
3579        # if len(lots) != len(prices):
3580        #     uLogger.error("'lots' and 'prices' lists must have equal length of values!")
3581        #     raise Exception("Incorrect value")
3582        #
3583        # uLogger.debug("Extracted parameters for orders:")
3584        # uLogger.debug("lots = {}".format(lots))
3585        # uLogger.debug("prices = {}".format(prices))
3586        #
3587        # # list of dictionaries with order's parameters: [{"lot": lots_1, "price": price_1}, {...}, ...]
3588        # result = [{"lot": lots[item], "price": prices[item]} for item in range(len(prices))]
3589        # uLogger.debug("Order parameters: {}".format(result))
3590        #
3591        # return result
3592
3593    def IsInPortfolio(self, portfolio: dict = None) -> bool:
3594        """
3595        Checks if instrument is in the user's portfolio. Instrument must be defined by `ticker` (highly priority) or `figi`.
3596
3597        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3598        :return: `True` if portfolio contains open position with given instrument, `False` otherwise.
3599        """
3600        result = False
3601        msg = "Instrument not defined!"
3602
3603        if portfolio is None or not portfolio:
3604            portfolio = self.Overview(show=False)
3605
3606        if self._ticker:
3607            uLogger.debug("Searching instrument with ticker [{}] throw opened positions list...".format(self._ticker))
3608            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3609
3610            for iType in TKS_INSTRUMENTS:
3611                for instrument in portfolio["stat"][iType]:
3612                    if instrument["ticker"] == self._ticker:
3613                        result = True
3614                        msg = "Instrument with ticker [{}] is present in open positions".format(self._ticker)
3615                        break
3616
3617        elif self._figi:
3618            uLogger.debug("Searching instrument with FIGI [{}] throw opened positions list...".format(self._figi))
3619            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3620
3621            for iType in TKS_INSTRUMENTS:
3622                for instrument in portfolio["stat"][iType]:
3623                    if instrument["figi"] == self._figi:
3624                        result = True
3625                        msg = "Instrument with FIGI [{}] is present in open positions".format(self._figi)
3626                        break
3627
3628        else:
3629            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3630
3631        uLogger.debug(msg)
3632
3633        return result
3634
3635    def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:
3636        """
3637        Returns instrument from the user's portfolio if it presents there.
3638        Instrument must be defined by `ticker` (highly priority) or `figi`.
3639
3640        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3641        :return: dict with instrument if portfolio contains open position with this instrument, `None` otherwise.
3642        """
3643        result = None
3644        msg = "Instrument not defined!"
3645
3646        if portfolio is None or not portfolio:
3647            portfolio = self.Overview(show=False)
3648
3649        if self._ticker:
3650            uLogger.debug("Searching instrument with ticker [{}] in opened positions...".format(self._ticker))
3651            msg = "Instrument with ticker [{}] is not present in open positions".format(self._ticker)
3652
3653            for iType in TKS_INSTRUMENTS:
3654                for instrument in portfolio["stat"][iType]:
3655                    if instrument["ticker"] == self._ticker:
3656                        result = instrument
3657                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(self._ticker, instrument["figi"])
3658                        break
3659
3660        elif self._figi:
3661            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self._figi))
3662            msg = "Instrument with FIGI [{}] is not present in open positions".format(self._figi)
3663
3664            for iType in TKS_INSTRUMENTS:
3665                for instrument in portfolio["stat"][iType]:
3666                    if instrument["figi"] == self._figi:
3667                        result = instrument
3668                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(instrument["ticker"], self._figi)
3669                        break
3670
3671        else:
3672            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3673
3674        uLogger.debug(msg)
3675
3676        return result
3677
3678    def IsInLimitOrders(self, portfolio: dict = None) -> bool:
3679        """
3680        Checks if instrument is in the limit orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3681
3682        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3683
3684        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3685        :return: `True` if limit orders list contains some limit orders for the instrument, `False` otherwise.
3686        """
3687        result = False
3688        msg = "Instrument not defined!"
3689
3690        if portfolio is None or not portfolio:
3691            portfolio = self.Overview(show=False)
3692
3693        if self._ticker:
3694            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3695            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3696
3697            for instrument in portfolio["stat"]["orders"]:
3698                if instrument["ticker"] == self._ticker:
3699                    result = True
3700                    msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3701                    break
3702
3703        elif self._figi:
3704            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3705            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3706
3707            for instrument in portfolio["stat"]["orders"]:
3708                if instrument["figi"] == self._figi:
3709                    result = True
3710                    msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3711                    break
3712
3713        else:
3714            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3715
3716        uLogger.debug(msg)
3717
3718        return result
3719
3720    def GetLimitOrderIDs(self, portfolio: dict = None) -> list[str]:
3721        """
3722        Returns list with all `orderID`s of opened pending limit orders for the instrument.
3723        Instrument must be defined by `ticker` (highly priority) or `figi`.
3724
3725        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3726
3727        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3728        :return: list with `orderID`s of limit orders.
3729        """
3730        result = []
3731        msg = "Instrument not defined!"
3732
3733        if portfolio is None or not portfolio:
3734            portfolio = self.Overview(show=False)
3735
3736        if self._ticker:
3737            uLogger.debug("Searching instrument with ticker [{}] throw opened pending limit orders list...".format(self._ticker))
3738            msg = "Instrument with ticker [{}] is not present in opened pending limit orders list".format(self._ticker)
3739
3740            for instrument in portfolio["stat"]["orders"]:
3741                if instrument["ticker"] == self._ticker:
3742                    result.append(instrument["orderID"])
3743
3744            if result:
3745                msg = "Instrument with ticker [{}] is present in limit orders list".format(self._ticker)
3746
3747        elif self._figi:
3748            uLogger.debug("Searching instrument with FIGI [{}] throw opened pending limit orders list...".format(self._figi))
3749            msg = "Instrument with FIGI [{}] is not present in opened pending limit orders list".format(self._figi)
3750
3751            for instrument in portfolio["stat"]["orders"]:
3752                if instrument["figi"] == self._figi:
3753                    result.append(instrument["orderID"])
3754
3755            if result:
3756                msg = "Instrument with FIGI [{}] is present in opened pending limit orders list".format(self._figi)
3757
3758        else:
3759            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3760
3761        uLogger.debug(msg)
3762
3763        return result
3764
3765    def IsInStopOrders(self, portfolio: dict = None) -> bool:
3766        """
3767        Checks if instrument is in the stop orders list. Instrument must be defined by `ticker` (highly priority) or `figi`.
3768
3769        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3770
3771        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3772        :return: `True` if stop orders list contains some stop orders for the instrument, `False` otherwise.
3773        """
3774        result = False
3775        msg = "Instrument not defined!"
3776
3777        if portfolio is None or not portfolio:
3778            portfolio = self.Overview(show=False)
3779
3780        if self._ticker:
3781            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3782            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3783
3784            for instrument in portfolio["stat"]["stopOrders"]:
3785                if instrument["ticker"] == self._ticker:
3786                    result = True
3787                    msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3788                    break
3789
3790        elif self._figi:
3791            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3792            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3793
3794            for instrument in portfolio["stat"]["stopOrders"]:
3795                if instrument["figi"] == self._figi:
3796                    result = True
3797                    msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3798                    break
3799
3800        else:
3801            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3802
3803        uLogger.debug(msg)
3804
3805        return result
3806
3807    def GetStopOrderIDs(self, portfolio: dict = None) -> list[str]:
3808        """
3809        Returns list with all `orderID`s of opened stop orders for the instrument.
3810        Instrument must be defined by `ticker` (highly priority) or `figi`.
3811
3812        See also: `CloseAllByTicker()` and `CloseAllByFIGI()`.
3813
3814        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3815        :return: list with `orderID`s of stop orders.
3816        """
3817        result = []
3818        msg = "Instrument not defined!"
3819
3820        if portfolio is None or not portfolio:
3821            portfolio = self.Overview(show=False)
3822
3823        if self._ticker:
3824            uLogger.debug("Searching instrument with ticker [{}] throw opened stop orders list...".format(self._ticker))
3825            msg = "Instrument with ticker [{}] is not present in opened stop orders list".format(self._ticker)
3826
3827            for instrument in portfolio["stat"]["stopOrders"]:
3828                if instrument["ticker"] == self._ticker:
3829                    result.append(instrument["orderID"])
3830
3831            if result:
3832                msg = "Instrument with ticker [{}] is present in stop orders list".format(self._ticker)
3833
3834        elif self._figi:
3835            uLogger.debug("Searching instrument with FIGI [{}] throw opened stop orders list...".format(self._figi))
3836            msg = "Instrument with FIGI [{}] is not present in opened stop orders list".format(self._figi)
3837
3838            for instrument in portfolio["stat"]["stopOrders"]:
3839                if instrument["figi"] == self._figi:
3840                    result.append(instrument["orderID"])
3841
3842            if result:
3843                msg = "Instrument with FIGI [{}] is present in opened stop orders list".format(self._figi)
3844
3845        else:
3846            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3847
3848        uLogger.debug(msg)
3849
3850        return result
3851
3852    def RequestLimits(self) -> dict:
3853        """
3854        Method for obtaining the available funds for withdrawal for current `accountId`.
3855
3856        See also:
3857        - REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
3858        - `OverviewLimits()` method
3859
3860        :return: dict with raw data from server that contains free funds for withdrawal. Example of dict:
3861                 `{"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}`.
3862                 Here `money` is an array of portfolio currency positions, `blocked` is an array of blocked currency
3863                 positions of the portfolio and `blockedGuarantee` is locked money under collateral for futures.
3864        """
3865        if self.accountId is None or not self.accountId:
3866            uLogger.error("Variable `accountId` must be defined for using this method!")
3867            raise Exception("Account ID required")
3868
3869        uLogger.debug("Requesting current available funds for withdrawal. Wait, please...")
3870
3871        self.body = str({"accountId": self.accountId})
3872        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetWithdrawLimits"
3873        rawLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3874
3875        if self.moreDebug:
3876            uLogger.debug("Records about available funds for withdrawal successfully received")
3877
3878        return rawLimits
3879
3880    def OverviewLimits(self, show: bool = False) -> dict:
3881        """
3882        Method for parsing and show table with available funds for withdrawal for current `accountId`.
3883
3884        See also: `RequestLimits()`.
3885
3886        :param show: if `False` then only dictionary returns, if `True` then also print withdrawal limits to log.
3887        :return: dict with raw parsed data from server and some calculated statistics about it.
3888        """
3889        if self.accountId is None or not self.accountId:
3890            uLogger.error("Variable `accountId` must be defined for using this method!")
3891            raise Exception("Account ID required")
3892
3893        rawLimits = self.RequestLimits()  # raw response with current available funds for withdrawal
3894
3895        view = {
3896            "rawLimits": rawLimits,
3897            "limits": {  # parsed data for every currency:
3898                "money": {  # this is an array of portfolio currency positions
3899                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["money"]
3900                },
3901                "blocked": {  # this is an array of blocked currency
3902                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blocked"]
3903                },
3904                "blockedGuarantee": {  # this is locked money under collateral for futures
3905                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blockedGuarantee"]
3906                },
3907            },
3908        }
3909
3910        # --- Prepare text table with limits in human-readable format:
3911        if show:
3912            info = [
3913                "# Withdrawal limits\n\n",
3914                "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
3915                "* **Account ID:** [{}]\n".format(self.accountId),
3916            ]
3917
3918            if view["limits"]["money"]:
3919                info.extend([
3920                    "\n| Currencies | Total         | Available for withdrawal | Blocked for trade | Futures guarantee |\n",
3921                    "|------------|---------------|--------------------------|-------------------|-------------------|\n",
3922                ])
3923
3924            else:
3925                info.append("\nNo withdrawal limits\n")
3926
3927            for curr in view["limits"]["money"].keys():
3928                blocked = view["limits"]["blocked"][curr] if curr in view["limits"]["blocked"].keys() else 0
3929                blockedGuarantee = view["limits"]["blockedGuarantee"][curr] if curr in view["limits"]["blockedGuarantee"].keys() else 0
3930                availableMoney = view["limits"]["money"][curr] - (blocked + blockedGuarantee)
3931
3932                infoStr = "| {:<10} | {:<13} | {:<24} | {:<17} | {:<17} |\n".format(
3933                    "[{}]".format(curr),
3934                    "{:.2f}".format(view["limits"]["money"][curr]),
3935                    "{:.2f}".format(availableMoney),
3936                    "{:.2f}".format(view["limits"]["blocked"][curr]) if curr in view["limits"]["blocked"].keys() else "—",
3937                    "{:.2f}".format(view["limits"]["blockedGuarantee"][curr]) if curr in view["limits"]["blockedGuarantee"].keys() else "—",
3938                )
3939
3940                if curr == "rub":
3941                    info.insert(5, infoStr)  # hack: insert "rub" at the first position in table and after headers
3942
3943                else:
3944                    info.append(infoStr)
3945
3946            infoText = "".join(info)
3947
3948            uLogger.info(infoText)
3949
3950            if self.withdrawalLimitsFile:
3951                with open(self.withdrawalLimitsFile, "w", encoding="UTF-8") as fH:
3952                    fH.write(infoText)
3953
3954                uLogger.info("Client's withdrawal limits was saved to file: [{}]".format(os.path.abspath(self.withdrawalLimitsFile)))
3955
3956                if self.useHTMLReports:
3957                    htmlFilePath = self.withdrawalLimitsFile.replace(".md", ".html") if self.withdrawalLimitsFile.endswith(".md") else self.withdrawalLimitsFile + ".html"
3958                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
3959                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Withdrawal limits", commonCSS=COMMON_CSS, markdown=infoText))
3960
3961                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
3962
3963        return view
3964
3965    def RequestAccounts(self) -> dict:
3966        """
3967        Method for requesting all brokerage accounts (`accountId`s) of current user detected by `token`.
3968
3969        See also:
3970        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
3971        - What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
3972        - `OverviewUserInfo()` method
3973
3974        :return: dict with raw data from server that contains accounts info. Example of dict:
3975                 `{"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account",
3976                   "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z",
3977                   "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}`.
3978                 If `closedDate="1970-01-01T00:00:00Z"` it means that account is active now.
3979        """
3980        uLogger.debug("Requesting all brokerage accounts of current user detected by its token. Wait, please...")
3981
3982        self.body = str({})
3983        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetAccounts"
3984        rawAccounts = self.SendAPIRequest(portfolioURL, reqType="POST")
3985
3986        if self.moreDebug:
3987            uLogger.debug("Records about available accounts successfully received")
3988
3989        return rawAccounts
3990
3991    def RequestUserInfo(self) -> dict:
3992        """
3993        Method for requesting common user's information.
3994
3995        See also:
3996        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
3997        - What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
3998        - What does `qualified_for_work_with` field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
3999        - `OverviewUserInfo()` method
4000
4001        :return: dict with raw data from server that contains user's information. Example of dict:
4002                 `{"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage",
4003                   "russian_shares", "structured_income_bonds"], "tariff": "premium"}`.
4004        """
4005        uLogger.debug("Requesting common user's information. Wait, please...")
4006
4007        self.body = str({})
4008        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetInfo"
4009        rawUserInfo = self.SendAPIRequest(portfolioURL, reqType="POST")
4010
4011        if self.moreDebug:
4012            uLogger.debug("Records about current user successfully received")
4013
4014        return rawUserInfo
4015
4016    def RequestMarginStatus(self, accountId: str = None) -> dict:
4017        """
4018        Method for requesting margin calculation for defined account ID.
4019
4020        See also:
4021        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
4022        - What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
4023        - `OverviewUserInfo()` method
4024
4025        :param accountId: string with numeric account ID. If `None`, then used class field `accountId`.
4026        :return: dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict.
4027                 Example of responses:
4028                 status code 400: `{"code": 3, "message": "account margin status is disabled", "description": "30051" }`, returns: `{}`.
4029                 status code 200: `{"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000},
4030                                    "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000},
4031                                    "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000},
4032                                    "fundsSufficiencyLevel": {"units": "1", "nano": 280000000},
4033                                    "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}`.
4034        """
4035        if accountId is None or not accountId:
4036            if self.accountId is None or not self.accountId:
4037                uLogger.error("Variable `accountId` must be defined for using this method!")
4038                raise Exception("Account ID required")
4039
4040            else:
4041                accountId = self.accountId  # use `self.accountId` (main ID) by default
4042
4043        uLogger.debug("Requesting margin calculation for accountId [{}]. Wait, please...".format(accountId))
4044
4045        self.body = str({"accountId": accountId})
4046        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetMarginAttributes"
4047        rawMargin = self.SendAPIRequest(portfolioURL, reqType="POST")
4048
4049        if rawMargin == {"code": 3, "message": "account margin status is disabled", "description": "30051"}:
4050            uLogger.debug("Server response: margin status is disabled for current accountId [{}]".format(accountId))
4051            rawMargin = {}
4052
4053        else:
4054            if self.moreDebug:
4055                uLogger.debug("Records with margin calculation for accountId [{}] successfully received".format(accountId))
4056
4057        return rawMargin
4058
4059    def RequestTariffLimits(self) -> dict:
4060        """
4061        Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by `token`.
4062
4063        See also:
4064        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
4065        - What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
4066        - Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
4067        - Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
4068        - `OverviewUserInfo()` method
4069
4070        :return: dict with raw data from server that contains limits of current tariff. Example of dict:
4071                 `{"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...],
4072                   "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}`.
4073        """
4074        uLogger.debug("Requesting limits of current tariff. Wait, please...")
4075
4076        self.body = str({})
4077        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetUserTariff"
4078        rawTariffLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
4079
4080        if self.moreDebug:
4081            uLogger.debug("Records with limits of current tariff successfully received")
4082
4083        return rawTariffLimits
4084
4085    def RequestBondCoupons(self, iJSON: dict) -> dict:
4086        """
4087        Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown
4088        then requesting dates `"from": "1970-01-01T00:00:00.000Z"` and `"to": "2099-12-31T23:59:59.000Z"`.
4089        All dates are in UTC timezone.
4090
4091        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons
4092        Documentation:
4093        - request: https://tinkoff.github.io/investAPI/instruments/#getbondcouponsrequest
4094        - response: https://tinkoff.github.io/investAPI/instruments/#coupon
4095
4096        See also: `ExtendBondsData()`.
4097
4098        :param iJSON: raw json data of a bond from broker server, example `iJSON = self.iList["Bonds"][self._ticker]`
4099                      If raw iJSON is not data of bond then server returns an error [400] with message:
4100                      `{"code": 3, "message": "instrument type is not bond", "description": "30048"}`.
4101        :return: dictionary with bond payment calendar. Response example
4102                 `{"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12",
4103                   "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000},
4104                   "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z",
4105                   "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}`
4106        """
4107        if iJSON["figi"] is None or not iJSON["figi"]:
4108            uLogger.error("FIGI must be defined for using this method!")
4109            raise Exception("FIGI required")
4110
4111        startDate = iJSON["placementDate"] if "placementDate" in iJSON.keys() else "1970-01-01T00:00:00.000Z"
4112        endDate = iJSON["maturityDate"] if "maturityDate" in iJSON.keys() else "2099-12-31T23:59:59.000Z"
4113
4114        uLogger.debug("Requesting bond payment calendar, {}FIGI: [{}], from: [{}], to: [{}]. Wait, please...".format(
4115            "ticker: [{}], ".format(iJSON["ticker"]) if "ticker" in iJSON.keys() else "",
4116            self._figi,
4117            startDate,
4118            endDate,
4119        ))
4120
4121        self.body = str({"figi": iJSON["figi"], "from": startDate, "to": endDate})
4122        calendarURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/GetBondCoupons"
4123        calendar = self.SendAPIRequest(calendarURL, reqType="POST")
4124
4125        if calendar == {"code": 3, "message": "instrument type is not bond", "description": "30048"}:
4126            uLogger.warning("Instrument type is not bond!")
4127
4128        else:
4129            if self.moreDebug:
4130                uLogger.debug("Records about bond payment calendar successfully received")
4131
4132        return calendar
4133
4134    def ExtendBondsData(self, instruments: list[str], xlsx: bool = False) -> pd.DataFrame:
4135        """
4136        Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider
4137        Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar,
4138        coupon yields, current yields and some statistics etc.
4139
4140        WARNING! This is too long operation if a lot of bonds requested from broker server.
4141
4142        See also: `ShowInstrumentInfo()`, `CreateBondsCalendar()`, `ShowBondsCalendar()`, `RequestBondCoupons()`.
4143
4144        :param instruments: list of strings with tickers or FIGIs.
4145        :param xlsx: if True then also exports Pandas DataFrame to xlsx-file `bondsXLSXFile`, default `ext-bonds.xlsx`,
4146                     for further used by data scientists or stock analytics.
4147        :return: wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker.
4148                 In XLSX-file and Pandas DataFrame fields mean:
4149                 - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond
4150                 - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon
4151        """
4152        if instruments is None or not instruments:
4153            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
4154            raise Exception("Ticker or FIGI required")
4155
4156        if isinstance(instruments, str):
4157            instruments = [instruments]
4158
4159        uniqueInstruments = self.GetUniqueFIGIs(instruments)
4160
4161        uLogger.debug("Requesting raw bonds calendar from server, transforming and extending it. Wait, please...")
4162
4163        iCount = len(uniqueInstruments)
4164        tooLong = iCount >= 20
4165        if tooLong:
4166            uLogger.warning("You requested a lot of bonds! Operation will takes more time. Wait, please...")
4167
4168        bonds = None
4169        for i, self._figi in enumerate(uniqueInstruments):
4170            instrument = self.SearchByFIGI(requestPrice=False)  # raw data about instrument from server
4171
4172            if "type" in instrument.keys() and instrument["type"] == "Bonds":
4173                # raw bond data from server where fields mean: https://tinkoff.github.io/investAPI/instruments/#bond
4174                rawBond = self.SearchByFIGI(requestPrice=True)
4175
4176                # Widen raw data with UTC current time (iData["actualDateTime"]):
4177                actualDate = datetime.now(tzutc())
4178                iData = {"actualDateTime": actualDate.strftime(TKS_DATE_TIME_FORMAT)} | rawBond
4179
4180                # Widen raw data with bond payment calendar (iData["rawCalendar"]):
4181                iData = iData | {"rawCalendar": self.RequestBondCoupons(iJSON=iData)}
4182
4183                # Replace some values with human-readable:
4184                iData["nominalCurrency"] = iData["nominal"]["currency"]
4185                iData["nominal"] = NanoToFloat(iData["nominal"]["units"], iData["nominal"]["nano"])
4186                iData["placementPrice"] = NanoToFloat(iData["placementPrice"]["units"], iData["placementPrice"]["nano"])
4187                iData["aciCurrency"] = iData["aciValue"]["currency"]
4188                iData["aciValue"] = NanoToFloat(iData["aciValue"]["units"], iData["aciValue"]["nano"])
4189                iData["issueSize"] = int(iData["issueSize"])
4190                iData["issueSizePlan"] = int(iData["issueSizePlan"])
4191                iData["tradingStatus"] = TKS_TRADING_STATUSES[iData["tradingStatus"]]
4192                iData["step"] = iData["step"] if "step" in iData.keys() else 0
4193                iData["realExchange"] = TKS_REAL_EXCHANGES[iData["realExchange"]]
4194                iData["klong"] = NanoToFloat(iData["klong"]["units"], iData["klong"]["nano"]) if "klong" in iData.keys() else 0
4195                iData["kshort"] = NanoToFloat(iData["kshort"]["units"], iData["kshort"]["nano"]) if "kshort" in iData.keys() else 0
4196                iData["dlong"] = NanoToFloat(iData["dlong"]["units"], iData["dlong"]["nano"]) if "dlong" in iData.keys() else 0
4197                iData["dshort"] = NanoToFloat(iData["dshort"]["units"], iData["dshort"]["nano"]) if "dshort" in iData.keys() else 0
4198                iData["dlongMin"] = NanoToFloat(iData["dlongMin"]["units"], iData["dlongMin"]["nano"]) if "dlongMin" in iData.keys() else 0
4199                iData["dshortMin"] = NanoToFloat(iData["dshortMin"]["units"], iData["dshortMin"]["nano"]) if "dshortMin" in iData.keys() else 0
4200
4201                # Widen raw data with price fields from `currentPrice` values (all prices are actual at `actualDateTime` date):
4202                iData["limitUpPercent"] = iData["currentPrice"]["limitUp"]  # max price on current day in percents of nominal
4203                iData["limitDownPercent"] = iData["currentPrice"]["limitDown"]  # min price on current day in percents of nominal
4204                iData["lastPricePercent"] = iData["currentPrice"]["lastPrice"]  # last price on market in percents of nominal
4205                iData["closePricePercent"] = iData["currentPrice"]["closePrice"]  # previous day close in percents of nominal
4206                iData["changes"] = iData["currentPrice"]["changes"]  # this is percent of changes between `currentPrice` and `lastPrice`
4207                iData["limitUp"] = iData["limitUpPercent"] * iData["nominal"] / 100  # max price on current day is `limitUpPercent` * `nominal`
4208                iData["limitDown"] = iData["limitDownPercent"] * iData["nominal"] / 100  # min price on current day is `limitDownPercent` * `nominal`
4209                iData["lastPrice"] = iData["lastPricePercent"] * iData["nominal"] / 100  # last price on market is `lastPricePercent` * `nominal`
4210                iData["closePrice"] = iData["closePricePercent"] * iData["nominal"] / 100  # previous day close is `closePricePercent` * `nominal`
4211                iData["changesDelta"] = iData["lastPrice"] - iData["closePrice"]  # this is delta between last deal price and last close
4212
4213                # Widen raw data with calendar data from `rawCalendar` values:
4214                calendarData = []
4215                if "events" in iData["rawCalendar"].keys():
4216                    for item in iData["rawCalendar"]["events"]:
4217                        calendarData.append({
4218                            "couponDate": item["couponDate"],
4219                            "couponNumber": int(item["couponNumber"]),
4220                            "fixDate": item["fixDate"] if "fixDate" in item.keys() else "",
4221                            "payCurrency": item["payOneBond"]["currency"],
4222                            "payOneBond": NanoToFloat(item["payOneBond"]["units"], item["payOneBond"]["nano"]),
4223                            "couponType": TKS_COUPON_TYPES[item["couponType"]],
4224                            "couponStartDate": item["couponStartDate"],
4225                            "couponEndDate": item["couponEndDate"],
4226                            "couponPeriod": item["couponPeriod"],
4227                        })
4228
4229                    # if maturity date is unknown then uses the latest date in bond payment calendar for it:
4230                    if "maturityDate" not in iData.keys():
4231                        iData["maturityDate"] = datetime.strptime(calendarData[0]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT) if calendarData else ""
4232
4233                # Widen raw data with Coupon Rate.
4234                # This is sum of all coupon payments divided on nominal price and expire days sum and then multiple on 365 days and 100%:
4235                iData["sumCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData])
4236                iData["periodDays"] = sum([coupon["couponPeriod"] for coupon in calendarData])
4237                iData["couponsYield"] = 100 * 365 * (iData["sumCoupons"] / iData["nominal"]) / iData["periodDays"] if iData["nominal"] != 0 and iData["periodDays"] != 0 else 0.
4238
4239                # Widen raw data with Yield to Maturity (YTM) on current date.
4240                # This is sum of all stayed coupons to maturity minus ACI and divided on current bond price and then multiple on stayed days and 100%:
4241                maturityDate = datetime.strptime(iData["maturityDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) if iData["maturityDate"] else None
4242                iData["daysToMaturity"] = (maturityDate - actualDate).days if iData["maturityDate"] else None
4243                iData["sumLastCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData if datetime.strptime(coupon["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) > actualDate])
4244                iData["lastPayments"] = iData["sumLastCoupons"] - iData["aciValue"]  # sum of all last coupons minus current ACI value
4245                iData["currentYield"] = 100 * 365 * (iData["lastPayments"] / iData["lastPrice"]) / iData["daysToMaturity"] if iData["lastPrice"] != 0 and iData["daysToMaturity"] != 0 else 0.
4246
4247                iData["calendar"] = calendarData  # adds calendar at the end
4248
4249                # Remove not used data:
4250                iData.pop("uid")
4251                iData.pop("positionUid")
4252                iData.pop("currentPrice")
4253                iData.pop("rawCalendar")
4254
4255                colNames = list(iData.keys())
4256                if bonds is None:
4257                    bonds = pd.DataFrame(data=pd.DataFrame.from_records(data=[iData], columns=colNames))
4258
4259                else:
4260                    bonds = pd.concat([bonds, pd.DataFrame.from_records(data=[iData], columns=colNames)], axis=0, ignore_index=True)
4261
4262            else:
4263                uLogger.warning("Instrument is not a bond!")
4264
4265            processed = round(100 * (i + 1) / iCount, 1)
4266            if tooLong and processed % 5 == 0:
4267                uLogger.info("{}% processed [{} / {}]...".format(round(processed), i + 1, iCount))
4268
4269            else:
4270                uLogger.debug("{}% bonds processed [{} / {}]...".format(processed, i + 1, iCount))
4271
4272        bonds.index = bonds["ticker"].tolist()  # replace indexes with ticker names
4273
4274        # Saving bonds from Pandas DataFrame to XLSX sheet:
4275        if xlsx and self.bondsXLSXFile:
4276            with pd.ExcelWriter(
4277                    path=self.bondsXLSXFile,
4278                    date_format=TKS_DATE_FORMAT,
4279                    datetime_format=TKS_DATE_TIME_FORMAT,
4280                    mode="w",
4281            ) as writer:
4282                bonds.to_excel(
4283                    writer,
4284                    sheet_name="Extended bonds data",
4285                    index=True,
4286                    encoding="UTF-8",
4287                    freeze_panes=(1, 1),
4288                )  # saving as XLSX-file with freeze first row and column as headers
4289
4290            uLogger.info("XLSX-file with extended bonds data for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(self.bondsXLSXFile)))
4291
4292        return bonds
4293
4294    def CreateBondsCalendar(self, extBonds: pd.DataFrame, xlsx: bool = False) -> pd.DataFrame:
4295        """
4296        Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, `calendar.xlsx` by default.
4297
4298        WARNING! This is too long operation if a lot of bonds requested from broker server.
4299
4300        See also: `ShowBondsCalendar()`, `ExtendBondsData()`.
4301
4302        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4303                        extended information about bonds: main info, current prices, bond payment calendar,
4304                        coupon yields, current yields and some statistics etc.
4305                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4306        :param xlsx: if True then also exports Pandas DataFrame to file `calendarFile` + `".xlsx"`, `calendar.xlsx` by default,
4307                     for further used by data scientists or stock analytics.
4308        :return: Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon
4309        """
4310        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4311            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=False)
4312
4313        uLogger.debug("Generating bond payments calendar data. Wait, please...")
4314
4315        colNames = ["Paid", "Payment date", "FIGI", "Ticker", "Name", "No.", "Value", "Currency", "Coupon type", "Period", "End registry date", "Coupon start date", "Coupon end date"]
4316        colID = ["paid", "couponDate", "figi", "ticker", "name", "couponNumber", "payOneBond", "payCurrency", "couponType", "couponPeriod", "fixDate", "couponStartDate", "couponEndDate"]
4317        calendar = None
4318        for bond in extBonds.iterrows():
4319            for item in bond[1]["calendar"]:
4320                cData = {
4321                    "paid": datetime.now(tzutc()) > datetime.strptime(item["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()),
4322                    "couponDate": item["couponDate"],
4323                    "figi": bond[1]["figi"],
4324                    "ticker": bond[1]["ticker"],
4325                    "name": bond[1]["name"],
4326                    "couponNumber": item["couponNumber"],
4327                    "payOneBond": item["payOneBond"],
4328                    "payCurrency": item["payCurrency"],
4329                    "couponType": item["couponType"],
4330                    "couponPeriod": item["couponPeriod"],
4331                    "fixDate": item["fixDate"],
4332                    "couponStartDate": item["couponStartDate"],
4333                    "couponEndDate": item["couponEndDate"],
4334                }
4335
4336                if calendar is None:
4337                    calendar = pd.DataFrame(data=pd.DataFrame.from_records(data=[cData], columns=colID))
4338
4339                else:
4340                    calendar = pd.concat([calendar, pd.DataFrame.from_records(data=[cData], columns=colID)], axis=0, ignore_index=True)
4341
4342        if calendar is not None:
4343            calendar = calendar.sort_values(by=["couponDate"], axis=0, ascending=True)  # sort all payments for all bonds by payment date
4344
4345            # Saving calendar from Pandas DataFrame to XLSX sheet:
4346            if xlsx:
4347                xlsxCalendarFile = self.calendarFile.replace(".md", ".xlsx") if self.calendarFile.endswith(".md") else self.calendarFile + ".xlsx"
4348
4349                with pd.ExcelWriter(
4350                        path=xlsxCalendarFile,
4351                        date_format=TKS_DATE_FORMAT,
4352                        datetime_format=TKS_DATE_TIME_FORMAT,
4353                        mode="w",
4354                ) as writer:
4355                    humanReadable = calendar.copy(deep=True)
4356                    humanReadable["couponDate"] = humanReadable["couponDate"].apply(lambda x: x.split("T")[0])
4357                    humanReadable["fixDate"] = humanReadable["fixDate"].apply(lambda x: x.split("T")[0])
4358                    humanReadable["couponStartDate"] = humanReadable["couponStartDate"].apply(lambda x: x.split("T")[0])
4359                    humanReadable["couponEndDate"] = humanReadable["couponEndDate"].apply(lambda x: x.split("T")[0])
4360                    humanReadable.columns = colNames  # human-readable column names
4361
4362                    humanReadable.to_excel(
4363                        writer,
4364                        sheet_name="Bond payments calendar",
4365                        index=False,
4366                        encoding="UTF-8",
4367                        freeze_panes=(1, 2),
4368                    )  # saving as XLSX-file with freeze first row and column as headers
4369
4370                    del humanReadable  # release df in memory
4371
4372                uLogger.info("XLSX-file with bond payments calendar for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxCalendarFile)))
4373
4374        return calendar
4375
4376    def ShowBondsCalendar(self, extBonds: pd.DataFrame, show: bool = True) -> str:
4377        """
4378        Show bond payments calendar as a table. One row in input `bonds` dataframe contains one bond.
4379        Also, creates Markdown file with calendar data, `calendar.md` by default.
4380
4381        See also: `ShowInstrumentInfo()`, `RequestBondCoupons()`, `CreateBondsCalendar()` and `ExtendBondsData()`.
4382
4383        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4384                        extended information about bonds: main info, current prices, bond payment calendar,
4385                        coupon yields, current yields and some statistics etc.
4386                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4387        :param show: if `True` then also printing bonds payment calendar to the console,
4388                     otherwise save to file `calendarFile` only. `False` by default.
4389        :return: multilines text in Markdown format with bonds payment calendar as a table.
4390        """
4391        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4392            extBonds = self.ExtendBondsData(instruments=[self._figi, self._ticker], xlsx=False)
4393
4394        infoText = "# Bond payments calendar\n\n"
4395
4396        calendar = self.CreateBondsCalendar(extBonds, xlsx=True)  # generate Pandas DataFrame with full calendar data
4397
4398        if not (calendar is None or calendar.empty):
4399            splitLine = "|       |                 |              |              |     |               |           |        |                   |\n"
4400
4401            info = [
4402                "* **Actual on date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4403                "| Paid  | Payment date    | FIGI         | Ticker       | No. | Value         | Type      | Period | End registry date |\n",
4404                "|-------|-----------------|--------------|--------------|-----|---------------|-----------|--------|-------------------|\n",
4405            ]
4406
4407            newMonth = False
4408            notOneBond = calendar["figi"].nunique() > 1
4409            for i, bond in enumerate(calendar.iterrows()):
4410                if newMonth and notOneBond:
4411                    info.append(splitLine)
4412
4413                info.append(
4414                    "| {:<5} | {:<15} | {:<12} | {:<12} | {:<3} | {:<13} | {:<9} | {:<6} | {:<17} |\n".format(
4415                        "  √" if bond[1]["paid"] else "  —",
4416                        bond[1]["couponDate"].split("T")[0],
4417                        bond[1]["figi"],
4418                        bond[1]["ticker"],
4419                        bond[1]["couponNumber"],
4420                        "{} {}".format(
4421                            "{}".format(round(bond[1]["payOneBond"], 6)).rstrip("0").rstrip("."),
4422                            bond[1]["payCurrency"],
4423                        ),
4424                        bond[1]["couponType"],
4425                        bond[1]["couponPeriod"],
4426                        bond[1]["fixDate"].split("T")[0],
4427                    )
4428                )
4429
4430                if i < len(calendar.values) - 1:
4431                    curDate = datetime.strptime(bond[1]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4432                    nextDate = datetime.strptime(calendar["couponDate"].values[i + 1], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4433                    newMonth = False if curDate.month == nextDate.month else True
4434
4435                else:
4436                    newMonth = False
4437
4438            infoText += "".join(info)
4439
4440            if show:
4441                uLogger.info("{}".format(infoText))
4442
4443            if self.calendarFile is not None:
4444                with open(self.calendarFile, "w", encoding="UTF-8") as fH:
4445                    fH.write(infoText)
4446
4447                uLogger.info("Bond payments calendar was saved to file: [{}]".format(os.path.abspath(self.calendarFile)))
4448
4449                if self.useHTMLReports:
4450                    htmlFilePath = self.calendarFile.replace(".md", ".html") if self.calendarFile.endswith(".md") else self.calendarFile + ".html"
4451                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4452                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="Bond payments calendar", commonCSS=COMMON_CSS, markdown=infoText))
4453
4454                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4455
4456        else:
4457            infoText += "No data\n"
4458
4459        return infoText
4460
4461    def OverviewAccounts(self, show: bool = False) -> dict:
4462        """
4463        Method for parsing and show simple table with all available user accounts.
4464
4465        See also: `RequestAccounts()` and `OverviewUserInfo()` methods.
4466
4467        :param show: if `False` then only dictionary with accounts data returns, if `True` then also print it to log.
4468        :return: dict with parsed accounts data received from `RequestAccounts()` method. Example of dict:
4469                 `view = {"rawAccounts": {rawAccounts from RequestAccounts() method...},
4470                          "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1",
4471                                                        "status": "Opened and active account", "opened": "2018-05-23 00:00:00",
4472                                                        "closed": "—", "access": "Full access" }, ...}}`
4473        """
4474        rawAccounts = self.RequestAccounts()  # Raw responses with accounts
4475
4476        # This is an array of dict with user accounts, its `accountId`s and some parsed data:
4477        accounts = {
4478            item["id"]: {
4479                "type": TKS_ACCOUNT_TYPES[item["type"]],
4480                "name": item["name"],
4481                "status": TKS_ACCOUNT_STATUSES[item["status"]],
4482                "opened": datetime.strptime(item["openedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4483                "closed": datetime.strptime(item["closedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if item["closedDate"] != "1970-01-01T00:00:00Z" else "—",
4484                "access": TKS_ACCESS_LEVELS[item["accessLevel"]],
4485            } for item in rawAccounts["accounts"]
4486        }
4487
4488        # Raw and parsed data with some fields replaced in "stat" section:
4489        view = {
4490            "rawAccounts": rawAccounts,
4491            "stat": accounts,
4492        }
4493
4494        # --- Prepare simple text table with only accounts data in human-readable format:
4495        if show:
4496            info = [
4497                "# User accounts\n\n",
4498                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4499                "| Account ID   | Type                      | Status                    | Name                           |\n",
4500                "|--------------|---------------------------|---------------------------|--------------------------------|\n",
4501            ]
4502
4503            for account in view["stat"].keys():
4504                info.extend([
4505                    "| {:<12} | {:<25} | {:<25} | {:<30} |\n".format(
4506                        account,
4507                        view["stat"][account]["type"],
4508                        view["stat"][account]["status"],
4509                        view["stat"][account]["name"],
4510                    )
4511                ])
4512
4513            infoText = "".join(info)
4514
4515            uLogger.info(infoText)
4516
4517            if self.userAccountsFile:
4518                with open(self.userAccountsFile, "w", encoding="UTF-8") as fH:
4519                    fH.write(infoText)
4520
4521                uLogger.info("User accounts were saved to file: [{}]".format(os.path.abspath(self.userAccountsFile)))
4522
4523                if self.useHTMLReports:
4524                    htmlFilePath = self.userAccountsFile.replace(".md", ".html") if self.userAccountsFile.endswith(".md") else self.userAccountsFile + ".html"
4525                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4526                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User accounts", commonCSS=COMMON_CSS, markdown=infoText))
4527
4528                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4529
4530        return view
4531
4532    def OverviewUserInfo(self, show: bool = False) -> dict:
4533        """
4534        Method for parsing and show all available user's data (`accountId`s, common user information, margin status and tariff connections limit).
4535
4536        See also: `OverviewAccounts()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()` methods.
4537
4538        :param show: if `False` then only dictionary returns, if `True` then also print user's data to log.
4539        :return: dict with raw parsed data from server and some calculated statistics about it.
4540        """
4541        rawUserInfo = self.RequestUserInfo()  # Raw response with common user info
4542        overviewAccount = self.OverviewAccounts(show=False)  # Raw and parsed accounts data
4543        rawAccounts = overviewAccount["rawAccounts"]  # Raw response with user accounts data
4544        accounts = overviewAccount["stat"]  # Dict with only statistics about user accounts
4545        rawMargins = {account: self.RequestMarginStatus(accountId=account) for account in accounts.keys()}  # Raw response with margin calculation for every account ID
4546        rawTariffLimits = self.RequestTariffLimits()  # Raw response with limits of current tariff
4547
4548        # This is dict with parsed common user data:
4549        userInfo = {
4550            "premium": "Yes" if rawUserInfo["premStatus"] else "No",
4551            "qualified": "Yes" if rawUserInfo["qualStatus"] else "No",
4552            "allowed": [TKS_QUALIFIED_TYPES[item] for item in rawUserInfo["qualifiedForWorkWith"]],
4553            "tariff": rawUserInfo["tariff"],
4554        }
4555
4556        # This is an array of dict with parsed margin statuses for every account IDs:
4557        margins = {}
4558        for accountId in accounts.keys():
4559            if rawMargins[accountId]:
4560                margins[accountId] = {
4561                    "currency": rawMargins[accountId]["liquidPortfolio"]["currency"],
4562                    "liquid": NanoToFloat(rawMargins[accountId]["liquidPortfolio"]["units"], rawMargins[accountId]["liquidPortfolio"]["nano"]),
4563                    "start": NanoToFloat(rawMargins[accountId]["startingMargin"]["units"], rawMargins[accountId]["startingMargin"]["nano"]),
4564                    "min": NanoToFloat(rawMargins[accountId]["minimalMargin"]["units"], rawMargins[accountId]["minimalMargin"]["nano"]),
4565                    "level": NanoToFloat(rawMargins[accountId]["fundsSufficiencyLevel"]["units"], rawMargins[accountId]["fundsSufficiencyLevel"]["nano"]),
4566                    "missing": NanoToFloat(rawMargins[accountId]["amountOfMissingFunds"]["units"], rawMargins[accountId]["amountOfMissingFunds"]["nano"]),
4567                }
4568
4569            else:
4570                margins[accountId] = {}  # Server response: margin status is disabled for current accountId
4571
4572        unary = {}  # unary-connection limits
4573        for item in rawTariffLimits["unaryLimits"]:
4574            if item["limitPerMinute"] in unary.keys():
4575                unary[item["limitPerMinute"]].extend(item["methods"])
4576
4577            else:
4578                unary[item["limitPerMinute"]] = item["methods"]
4579
4580        stream = {}  # stream-connection limits
4581        for item in rawTariffLimits["streamLimits"]:
4582            if item["limit"] in stream.keys():
4583                stream[item["limit"]].extend(item["streams"])
4584
4585            else:
4586                stream[item["limit"]] = item["streams"]
4587
4588        # This is dict with parsed limits of current tariff (connections, API methods etc.):
4589        limits = {
4590            "unary": unary,
4591            "stream": stream,
4592        }
4593
4594        # Raw and parsed data as an output result:
4595        view = {
4596            "rawUserInfo": rawUserInfo,
4597            "rawAccounts": rawAccounts,
4598            "rawMargins": rawMargins,
4599            "rawTariffLimits": rawTariffLimits,
4600            "stat": {
4601                "userInfo": userInfo,
4602                "accounts": accounts,
4603                "margins": margins,
4604                "limits": limits,
4605            },
4606        }
4607
4608        # --- Prepare text table with user information in human-readable format:
4609        if show:
4610            info = [
4611                "# Full user information\n\n",
4612                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4613                "## Common information\n\n",
4614                "* **Qualified user:** {}\n".format(view["stat"]["userInfo"]["qualified"]),
4615                "* **Tariff name:** {}\n".format(view["stat"]["userInfo"]["tariff"]),
4616                "* **Premium user:** {}\n".format(view["stat"]["userInfo"]["premium"]),
4617                "* **Allowed to work with instruments:**\n{}\n".format("".join(["  - {}\n".format(item) for item in view["stat"]["userInfo"]["allowed"]])),
4618                "\n## User accounts\n\n",
4619            ]
4620
4621            for account in view["stat"]["accounts"].keys():
4622                info.extend([
4623                    "### ID: [{}]\n\n".format(account),
4624                    "| Parameters           | Values                                                       |\n",
4625                    "|----------------------|--------------------------------------------------------------|\n",
4626                    "| Account type:        | {:<60} |\n".format(view["stat"]["accounts"][account]["type"]),
4627                    "| Account name:        | {:<60} |\n".format(view["stat"]["accounts"][account]["name"]),
4628                    "| Account status:      | {:<60} |\n".format(view["stat"]["accounts"][account]["status"]),
4629                    "| Access level:        | {:<60} |\n".format(view["stat"]["accounts"][account]["access"]),
4630                    "| Date opened:         | {:<60} |\n".format(view["stat"]["accounts"][account]["opened"]),
4631                    "| Date closed:         | {:<60} |\n".format(view["stat"]["accounts"][account]["closed"]),
4632                ])
4633
4634                if margins[account]:
4635                    info.extend([
4636                        "| Margin status:       | Enabled                                                      |\n",
4637                        "| - Liquid portfolio:  | {:<60} |\n".format("{} {}".format(margins[account]["liquid"], margins[account]["currency"])),
4638                        "| - Margin starting:   | {:<60} |\n".format("{} {}".format(margins[account]["start"], margins[account]["currency"])),
4639                        "| - Margin minimum:    | {:<60} |\n".format("{} {}".format(margins[account]["min"], margins[account]["currency"])),
4640                        "| - Sufficiency level: | {:<60} |\n".format("{:.2f} ({:.2f}%)".format(margins[account]["level"], margins[account]["level"] * 100)),
4641                        "| - Missing funds:     | {:<60} |\n\n".format("{} {}".format(margins[account]["missing"], margins[account]["currency"])),
4642                    ])
4643
4644                else:
4645                    info.append("| Margin status:       | Disabled                                                     |\n\n")
4646
4647            info.extend([
4648                "\n## Current user tariff limits\n",
4649                "\n### See also\n",
4650                "* Tinkoff limit policy: https://tinkoff.github.io/investAPI/limits/\n",
4651                "* Tinkoff Invest API: https://tinkoff.github.io/investAPI/\n",
4652                "  - More about REST API requests: https://tinkoff.github.io/investAPI/swagger-ui/\n",
4653                "  - More about gRPC requests for stream connections: https://tinkoff.github.io/investAPI/grpc/\n",
4654                "\n### Unary limits\n",
4655            ])
4656
4657            if unary:
4658                for key, values in sorted(unary.items()):
4659                    info.append("\n* Max requests per minute: {}\n".format(key))
4660
4661                    for value in values:
4662                        info.append("  - {}\n".format(value))
4663
4664            else:
4665                info.append("\nNot available\n")
4666
4667            info.append("\n### Stream limits\n")
4668
4669            if stream:
4670                for key, values in sorted(stream.items()):
4671                    info.append("\n* Max stream connections: {}\n".format(key))
4672
4673                    for value in values:
4674                        info.append("  - {}\n".format(value))
4675
4676            else:
4677                info.append("\nNot available\n")
4678
4679            infoText = "".join(info)
4680
4681            uLogger.info(infoText)
4682
4683            if self.userInfoFile:
4684                with open(self.userInfoFile, "w", encoding="UTF-8") as fH:
4685                    fH.write(infoText)
4686
4687                uLogger.info("User data was saved to file: [{}]".format(os.path.abspath(self.userInfoFile)))
4688
4689                if self.useHTMLReports:
4690                    htmlFilePath = self.userInfoFile.replace(".md", ".html") if self.userInfoFile.endswith(".md") else self.userInfoFile + ".html"
4691                    with open(htmlFilePath, "w", encoding="UTF-8") as fH:
4692                        fH.write(Template(text=MAIN_INFO_TEMPLATE).render(mainTitle="User info", commonCSS=COMMON_CSS, markdown=infoText))
4693
4694                    uLogger.info("The report has also been converted to an HTML file: [{}]".format(os.path.abspath(htmlFilePath)))
4695
4696        return view
4697
4698
4699class Args:
4700    """
4701    If `Main()` function is imported as module, then this class used to convert arguments from **kwargs as object.
4702    """
4703    def __init__(self, **kwargs):
4704        self.__dict__.update(kwargs)
4705
4706    def __getattr__(self, item):
4707        return None
4708
4709
4710def ParseArgs():
4711    """This function get and parse command line keys."""
4712    parser = ArgumentParser()  # command-line string parser
4713
4714    parser.description = "TKSBrokerAPI is a trading platform for automation on Python to simplify the implementation of trading scenarios and work with Tinkoff Invest API server via the REST protocol. See examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md"
4715    parser.usage = "\n/as module/ python TKSBrokerAPI.py [some options] [one command]\n/as CLI tool/ tksbrokerapi [some options] [one command]"
4716
4717    # --- options:
4718
4719    parser.add_argument("--no-cache", action="store_true", default=False, help="Option: not use local cache `dump.json`, but update raw instruments data when starting the platform. `False` by default.")
4720    parser.add_argument("--token", type=str, help="Option: Tinkoff service's api key. If not set then used environment variable `TKS_API_TOKEN`. See how to use: https://tinkoff.github.io/investAPI/token/")
4721    parser.add_argument("--account-id", type=str, default=None, help="Option: string with an user numeric account ID in Tinkoff Broker. It can be found in any broker's reports (see the contract number). Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.")
4722
4723    parser.add_argument("--ticker", "-t", type=str, help="Option: instrument's ticker, e.g. `IBM`, `YNDX`, `GOOGL` etc. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR`.")
4724    parser.add_argument("--figi", "-f", type=str, help="Option: instrument's FIGI, e.g. `BBG006L8G4H1` (for `YNDX`).")
4725
4726    parser.add_argument("--depth", type=int, default=1, help="Option: Depth of Market (DOM) can be >=1, 1 by default.")
4727    parser.add_argument("--no-cancelled", "--no-canceled", action="store_true", default=False, help="Option: remove information about cancelled operations from the deals report by the `--deals` key. `False` by default.")
4728
4729    parser.add_argument("--output", type=str, default=None, help="Option: replace default paths to output files for some commands. If `None` then used default files.")
4730    parser.add_argument("--html", "--HTML", action="store_true", default=False, help="Option: if key present then TKSBrokerAPI generate also HTML reports from Markdown. False by default.")
4731
4732    parser.add_argument("--interval", type=str, default="hour", help="Option: available values are `1min`, `5min`, `15min`, `hour` and `day`. Used only with `--history` key. This is time period of one candle. Default: `hour` for every history candles.")
4733    parser.add_argument("--only-missing", action="store_true", default=False, help="Option: if history file define by `--output` key then add only last missing candles, do not request all history length. `False` by default.")
4734    parser.add_argument("--csv-sep", type=str, default=",", help="Option: separator if csv-file is used, `,` by default.")
4735
4736    parser.add_argument("--debug-level", "--log-level", "--verbosity", "-v", type=int, default=20, help="Option: showing STDOUT messages of minimal debug level, e.g. 10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50 = CRITICAL. INFO (20) by default.")
4737    parser.add_argument("--more", "--more-debug", action="store_true", default=False, help="Option: `--debug-level` key only switch log level verbosity, but in addition `--more` key enable all debug information, such as net request and response headers in all methods.")
4738
4739    # --- commands:
4740
4741    parser.add_argument("--version", "--ver", action="store_true", help="Action: shows current semantic version, looks like `major.minor.buildnumber`. If TKSBrokerAPI not installed via pip, then used local build number `.dev0`.")
4742
4743    parser.add_argument("--list", "-l", action="store_true", help="Action: get and print all available instruments and some information from broker server. Also, you can define `--output` key to save list of instruments to file, default: `instruments.md`.")
4744    parser.add_argument("--list-xlsx", "-x", action="store_true", help="Action: get all available instruments from server for current account and save raw data into xlsx-file for further used by data scientists or stock analytics, default: `dump.xlsx`.")
4745    parser.add_argument("--bonds-xlsx", "-b", type=str, nargs="*", help="Action: get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc. And then export data to XLSX-file, default: `ext-bonds.xlsx` or you can change it with `--output` key. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4746    parser.add_argument("--search", "-s", type=str, nargs=1, help="Action: search for an instruments by part of the name, ticker or FIGI. Also, you can define `--output` key to save results to file, default: `search-results.md`.")
4747    parser.add_argument("--info", "-i", action="store_true", help="Action: get information from broker server about instrument by it's ticker or FIGI. `--ticker` key or `--figi` key must be defined!")
4748    parser.add_argument("--calendar", "-c", type=str, nargs="*", help="Action: show bonds payment calendar as a table. Calendar build for one or more tickers or FIGIs, or for all bonds if only key present. If the `--output` key present then calendar saves to file, default: `calendar.md`. Also, created XLSX-file with bond payments calendar for further used by data scientists or stock analytics, `calendar.xlsx` by default. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4749    parser.add_argument("--price", action="store_true", help="Action: show actual price list for current instrument. Also, you can use `--depth` key. `--ticker` key or `--figi` key must be defined!")
4750    parser.add_argument("--prices", "-p", type=str, nargs="+", help="Action: get and print current prices for list of given instruments (by it's tickers or by FIGIs). WARNING! This is too long operation if you request a lot of instruments! Also, you can define `--output` key to save list of prices to file, default: `prices.md`.")
4751
4752    parser.add_argument("--overview", "-o", action="store_true", help="Action: shows all open positions, orders and some statistics. Also, you can define `--output` key to save this information to file, default: `overview.md`.")
4753    parser.add_argument("--overview-digest", action="store_true", help="Action: shows a short digest of the portfolio status. Also, you can define `--output` key to save this information to file, default: `overview-digest.md`.")
4754    parser.add_argument("--overview-positions", action="store_true", help="Action: shows only open positions. Also, you can define `--output` key to save this information to file, default: `overview-positions.md`.")
4755    parser.add_argument("--overview-orders", action="store_true", help="Action: shows only sections of open limits and stop orders. Also, you can define `--output` key to save orders to file, default: `overview-orders.md`.")
4756    parser.add_argument("--overview-analytics", action="store_true", help="Action: shows only the analytics section and the distribution of the portfolio by various categories. Also, you can define `--output` key to save this information to file, default: `overview-analytics.md`.")
4757    parser.add_argument("--overview-calendar", action="store_true", help="Action: shows only the bonds calendar section (if these present in portfolio). Also, you can define `--output` key to save this information to file, default: `overview-calendar.md`.")
4758
4759    parser.add_argument("--deals", "-d", type=str, nargs="*", help="Action: show all deals between two given dates. Start day may be an integer number: -1, -2, -3 days ago. Also, you can use keywords: `today`, `yesterday` (-1), `week` (-7), `month` (-30) and `year` (-365). Dates format must be: `%%Y-%%m-%%d`, e.g. 2020-02-03. With `--no-cancelled` key information about cancelled operations will be removed from the deals report. Also, you can define `--output` key to save all deals to file, default: `deals.md`.")
4760    parser.add_argument("--history", type=str, nargs="*", help="Action: get last history candles of the current instrument defined by `--ticker` or `--figi` (FIGI id) keys. History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`. This action may be used together with the `--render-chart` key. Also, you can define `--output` key to save history candlesticks to file.")
4761    parser.add_argument("--load-history", type=str, help="Action: try to load history candles from given csv-file as a Pandas Dataframe and print it in to the console. This action may be used together with the `--render-chart` key.")
4762    parser.add_argument("--render-chart", type=str, help="Action: render candlesticks chart. This key may only used with `--history` or `--load-history` together. Action has 1 parameter with two possible string values: `interact` (`i`) or `non-interact` (`ni`).")
4763
4764    parser.add_argument("--trade", nargs="*", help="Action: universal action to open market position for defined ticker or FIGI. You must specify 1-5 parameters: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. See examples in readme.")
4765    parser.add_argument("--buy", nargs="*", help="Action: immediately open BUY market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4766    parser.add_argument("--sell", nargs="*", help="Action: immediately open SELL market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4767
4768    parser.add_argument("--order", nargs="*", help="Action: universal action to open limit or stop-order in any directions. You must specify 4-7 parameters: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]]. See examples in readme.")
4769    parser.add_argument("--buy-limit", type=float, nargs=2, help="Action: open pending BUY limit-order (below current price). You must specify only 2 parameters: [lots] [target price] to open BUY limit-order. If you try to create `Buy` limit-order above current price then broker immediately open `Buy` market order, such as if you do simple `--buy` operation!")
4770    parser.add_argument("--sell-limit", type=float, nargs=2, help="Action: open pending SELL limit-order (above current price). You must specify only 2 parameters: [lots] [target price] to open SELL limit-order. If you try to create `Sell` limit-order below current price then broker immediately open `Sell` market order, such as if you do simple `--sell` operation!")
4771    parser.add_argument("--buy-stop", nargs="*", help="Action: open BUY stop-order. You must specify at least 2 parameters: [lots] [target price] to open BUY stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4772    parser.add_argument("--sell-stop", nargs="*", help="Action: open SELL stop-order. You must specify at least 2 parameters: [lots] [target price] to open SELL stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4773    # parser.add_argument("--buy-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending BUY limit-orders (below current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4774    # parser.add_argument("--sell-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending SELL limit-orders (above current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4775
4776    parser.add_argument("--close-order", "--cancel-order", type=str, nargs=1, help="Action: close only one order by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4777    parser.add_argument("--close-orders", "--cancel-orders", type=str, nargs="+", help="Action: close one or list of orders by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4778    parser.add_argument("--close-trade", "--cancel-trade", action="store_true", help="Action: close only one position for instrument defined by `--ticker` (high priority) or `--figi` keys, including for currencies tickers.")
4779    parser.add_argument("--close-trades", "--cancel-trades", type=str, nargs="+", help="Action: close positions for list of tickers or FIGIs, including for currencies tickers or FIGIs.")
4780    parser.add_argument("--close-all", "--cancel-all", type=str, nargs="*", help="Action: close all available (not blocked) opened trades and orders, excluding for currencies. Also you can select one or more keywords case insensitive to specify trades type: `orders`, `shares`, `bonds`, `etfs` and `futures`, but not `currencies`. Currency positions you must closes manually using `--buy`, `--sell`, `--close-trade` or `--close-trades` operations. If the `--close-all` key present with the `--ticker` or `--figi` keys, then positions and all open limit and stop orders for the specified instrument are closed.")
4781
4782    parser.add_argument("--limits", "--withdrawal-limits", "-w", action="store_true", help="Action: show table of funds available for withdrawal for current `accountId`. You can change `accountId` with the key `--account-id`. Also, you can define `--output` key to save this information to file, default: `limits.md`.")
4783    parser.add_argument("--user-info", "-u", action="store_true", help="Action: show all available user's data (`accountId`s, common user information, margin status and tariff connections limit). Also, you can define `--output` key to save this information to file, default: `user-info.md`.")
4784    parser.add_argument("--account", "--accounts", "-a", action="store_true", help="Action: show simple table with all available user accounts. Also, you can define `--output` key to save this information to file, default: `accounts.md`.")
4785
4786    cmdArgs = parser.parse_args()
4787    return cmdArgs
4788
4789
4790def Main(**kwargs):
4791    """
4792    Main function for work with TKSBrokerAPI in the console.
4793
4794    See examples:
4795    - in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
4796    - in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md
4797    """
4798    args = Args(**kwargs) if kwargs else ParseArgs()  # get and parse command-line parameters or use **kwarg parameters
4799
4800    if args.debug_level:
4801        uLogger.level = 10  # always debug level by default
4802        uLogger.handlers[0].level = args.debug_level  # level for STDOUT
4803
4804    exitCode = 0
4805    start = datetime.now(tzutc())
4806    uLogger.debug("=-" * 50)
4807    uLogger.debug(">>> TKSBrokerAPI module started at: [{}] UTC, it is [{}] local time".format(
4808        start.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4809        start.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4810    ))
4811
4812    # trying to calculate full current version:
4813    buildVersion = __version__
4814    try:
4815        v = version("tksbrokerapi")
4816        buildVersion = v if v.startswith(buildVersion) else buildVersion + ".dev0"  # set version as major.minor.dev0 if run as local build or local script
4817
4818    except Exception:
4819        buildVersion = __version__ + ".dev0"  # if an errors occurred then also set version as major.minor.dev0
4820
4821    uLogger.debug("TKSBrokerAPI major.minor.build version used: [{}]".format(buildVersion))
4822    uLogger.debug("Host CPU count: [{}]".format(CPU_COUNT))
4823
4824    try:
4825        if args.version:
4826            print("TKSBrokerAPI {}".format(buildVersion))
4827            uLogger.debug("User requested current TKSBrokerAPI major.minor.build version: [{}]".format(buildVersion))
4828
4829        else:
4830            # Init class for trading with Tinkoff Broker:
4831            trader = TinkoffBrokerServer(
4832                token=args.token,
4833                accountId=args.account_id,
4834                useCache=not args.no_cache,
4835            )
4836
4837            # --- set some options:
4838
4839            if args.more:
4840                trader.moreDebug = True
4841                uLogger.warning("More debug info mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
4842
4843            if args.html:
4844                trader.useHTMLReports = True
4845
4846            if args.ticker:
4847                ticker = str(args.ticker).upper()  # Tickers may be upper case only
4848
4849                if ticker in trader.aliasesKeys:
4850                    trader.ticker = trader.aliases[ticker]  # Replace some tickers with its aliases
4851
4852                else:
4853                    trader.ticker = ticker
4854
4855            if args.figi:
4856                trader.figi = str(args.figi).upper()  # FIGIs may be upper case only
4857
4858            if args.depth is not None:
4859                trader.depth = args.depth
4860
4861            # --- do one command:
4862
4863            if args.list:
4864                if args.output is not None:
4865                    trader.instrumentsFile = args.output
4866
4867                trader.ShowInstrumentsInfo(show=True)
4868
4869            elif args.list_xlsx:
4870                trader.DumpInstrumentsAsXLSX(forceUpdate=False)
4871
4872            elif args.bonds_xlsx is not None:
4873                if args.output is not None:
4874                    trader.bondsXLSXFile = args.output
4875
4876                if len(args.bonds_xlsx) == 0:
4877                    trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=True)  # request bonds with all available tickers
4878
4879                else:
4880                    trader.ExtendBondsData(instruments=args.bonds_xlsx, xlsx=True)  # request list of given bonds
4881
4882            elif args.search:
4883                if args.output is not None:
4884                    trader.searchResultsFile = args.output
4885
4886                trader.SearchInstruments(pattern=args.search[0], show=True)
4887
4888            elif args.info:
4889                if not (args.ticker or args.figi):
4890                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4891                    raise Exception("Ticker or FIGI required")
4892
4893                if args.output is not None:
4894                    trader.infoFile = args.output
4895
4896                if args.ticker:
4897                    trader.SearchByTicker(requestPrice=True, show=True)  # show info and current prices by ticker name
4898
4899                else:
4900                    trader.SearchByFIGI(requestPrice=True, show=True)  # show info and current prices by FIGI id
4901
4902            elif args.calendar is not None:
4903                if args.output is not None:
4904                    trader.calendarFile = args.output
4905
4906                if len(args.calendar) == 0:
4907                    bondsData = trader.ExtendBondsData(instruments=trader.iList["Bonds"].keys(), xlsx=False)  # request bonds with all available tickers
4908
4909                else:
4910                    bondsData = trader.ExtendBondsData(instruments=args.calendar, xlsx=False)  # request list of given bonds
4911
4912                trader.ShowBondsCalendar(extBonds=bondsData, show=True)  # shows bonds payment calendar only
4913
4914            elif args.price:
4915                if not (args.ticker or args.figi):
4916                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4917                    raise Exception("Ticker or FIGI required")
4918
4919                trader.GetCurrentPrices(show=True)
4920
4921            elif args.prices is not None:
4922                if args.output is not None:
4923                    trader.pricesFile = args.output
4924
4925                trader.GetListOfPrices(instruments=args.prices, show=True)  # WARNING: too long wait for a lot of instruments prices
4926
4927            elif args.overview:
4928                if args.output is not None:
4929                    trader.overviewFile = args.output
4930
4931                trader.Overview(show=True, details="full")
4932
4933            elif args.overview_digest:
4934                if args.output is not None:
4935                    trader.overviewDigestFile = args.output
4936
4937                trader.Overview(show=True, details="digest")
4938
4939            elif args.overview_positions:
4940                if args.output is not None:
4941                    trader.overviewPositionsFile = args.output
4942
4943                trader.Overview(show=True, details="positions")
4944
4945            elif args.overview_orders:
4946                if args.output is not None:
4947                    trader.overviewOrdersFile = args.output
4948
4949                trader.Overview(show=True, details="orders")
4950
4951            elif args.overview_analytics:
4952                if args.output is not None:
4953                    trader.overviewAnalyticsFile = args.output
4954
4955                trader.Overview(show=True, details="analytics")
4956
4957            elif args.overview_calendar:
4958                if args.output is not None:
4959                    trader.overviewAnalyticsFile = args.output
4960
4961                trader.Overview(show=True, details="calendar")
4962
4963            elif args.deals is not None:
4964                if args.output is not None:
4965                    trader.reportFile = args.output
4966
4967                if 0 <= len(args.deals) < 3:
4968                    trader.Deals(
4969                        start=args.deals[0] if len(args.deals) >= 1 else None,
4970                        end=args.deals[1] if len(args.deals) == 2 else None,
4971                        show=True,  # Always show deals report in console
4972                        showCancelled=not args.no_cancelled,  # If --no-cancelled key then remove cancelled operations from the deals report. False by default.
4973                    )
4974
4975                else:
4976                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
4977                    raise Exception("Incorrect value")
4978
4979            elif args.history is not None:
4980                if args.output is not None:
4981                    trader.historyFile = args.output
4982
4983                if 0 <= len(args.history) < 3:
4984                    dataReceived = trader.History(
4985                        start=args.history[0] if len(args.history) >= 1 else None,
4986                        end=args.history[1] if len(args.history) == 2 else None,
4987                        interval="hour" if args.interval is None or not args.interval else args.interval,
4988                        onlyMissing=False if args.only_missing is None or not args.only_missing else args.only_missing,
4989                        csvSep="," if args.csv_sep is None or not args.csv_sep else args.csv_sep,
4990                        show=True,  # shows all downloaded candles in console
4991                    )
4992
4993                    if args.render_chart is not None and dataReceived is not None:
4994                        iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
4995
4996                        trader.ShowHistoryChart(
4997                            candles=dataReceived,
4998                            interact=iChart,
4999                            openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5000                        )
5001
5002                else:
5003                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
5004                    raise Exception("Incorrect value")
5005
5006            elif args.load_history is not None:
5007                histData = trader.LoadHistory(filePath=args.load_history)  # load data from file and show history in console
5008
5009                if args.render_chart is not None and histData is not None:
5010                    iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
5011                    trader.ticker = os.path.basename(args.load_history)  # use filename as ticker name for PriceGenerator's chart
5012
5013                    trader.ShowHistoryChart(
5014                        candles=histData,
5015                        interact=iChart,
5016                        openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
5017                    )
5018
5019            elif args.trade is not None:
5020                if 1 <= len(args.trade) <= 5:
5021                    trader.Trade(
5022                        operation=args.trade[0],
5023                        lots=int(args.trade[1]) if len(args.trade) >= 2 else 1,
5024                        tp=float(args.trade[2]) if len(args.trade) >= 3 else 0.,
5025                        sl=float(args.trade[3]) if len(args.trade) >= 4 else 0.,
5026                        expDate=args.trade[4] if len(args.trade) == 5 else "Undefined",
5027                    )
5028
5029                else:
5030                    uLogger.error("You must specify 1-5 parameters to open trade: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5031
5032            elif args.buy is not None:
5033                if 0 <= len(args.buy) <= 4:
5034                    trader.Buy(
5035                        lots=int(args.buy[0]) if len(args.buy) >= 1 else 1,
5036                        tp=float(args.buy[1]) if len(args.buy) >= 2 else 0.,
5037                        sl=float(args.buy[2]) if len(args.buy) >= 3 else 0.,
5038                        expDate=args.buy[3] if len(args.buy) == 4 else "Undefined",
5039                    )
5040
5041                else:
5042                    uLogger.error("You must specify 0-4 parameters to open buy position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5043
5044            elif args.sell is not None:
5045                if 0 <= len(args.sell) <= 4:
5046                    trader.Sell(
5047                        lots=int(args.sell[0]) if len(args.sell) >= 1 else 1,
5048                        tp=float(args.sell[1]) if len(args.sell) >= 2 else 0.,
5049                        sl=float(args.sell[2]) if len(args.sell) >= 3 else 0.,
5050                        expDate=args.sell[3] if len(args.sell) == 4 else "Undefined",
5051                    )
5052
5053                else:
5054                    uLogger.error("You must specify 0-4 parameters to open sell position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5055
5056            elif args.order:
5057                if 4 <= len(args.order) <= 7:
5058                    trader.Order(
5059                        operation=args.order[0],
5060                        orderType=args.order[1],
5061                        lots=int(args.order[2]),
5062                        targetPrice=float(args.order[3]),
5063                        limitPrice=float(args.order[4]) if len(args.order) >= 5 else 0.,
5064                        stopType=args.order[5] if len(args.order) >= 6 else "Limit",
5065                        expDate=args.order[6] if len(args.order) == 7 else "Undefined",
5066                    )
5067
5068                else:
5069                    uLogger.error("You must specify 4-7 parameters to open order: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]]. See: `python TKSBrokerAPI.py --help`")
5070
5071            elif args.buy_limit:
5072                trader.BuyLimit(lots=int(args.buy_limit[0]), targetPrice=args.buy_limit[1])
5073
5074            elif args.sell_limit:
5075                trader.SellLimit(lots=int(args.sell_limit[0]), targetPrice=args.sell_limit[1])
5076
5077            elif args.buy_stop:
5078                if 2 <= len(args.buy_stop) <= 7:
5079                    trader.BuyStop(
5080                        lots=int(args.buy_stop[0]),
5081                        targetPrice=float(args.buy_stop[1]),
5082                        limitPrice=float(args.buy_stop[2]) if len(args.buy_stop) >= 3 else 0.,
5083                        stopType=args.buy_stop[3] if len(args.buy_stop) >= 4 else "Limit",
5084                        expDate=args.buy_stop[4] if len(args.buy_stop) == 5 else "Undefined",
5085                    )
5086
5087                else:
5088                    uLogger.error("You must specify 2-5 parameters for buy stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
5089
5090            elif args.sell_stop:
5091                if 2 <= len(args.sell_stop) <= 7:
5092                    trader.SellStop(
5093                        lots=int(args.sell_stop[0]),
5094                        targetPrice=float(args.sell_stop[1]),
5095                        limitPrice=float(args.sell_stop[2]) if len(args.sell_stop) >= 3 else 0.,
5096                        stopType=args.sell_stop[3] if len(args.sell_stop) >= 4 else "Limit",
5097                        expDate=args.sell_stop[4] if len(args.sell_stop) == 5 else "Undefined",
5098                    )
5099
5100                else:
5101                    uLogger.error("You must specify 2-5 parameters for sell stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: python TKSBrokerAPI.py --help")
5102
5103            # elif args.buy_order_grid is not None:
5104            #     # update order grid work with api v2
5105            #     if len(args.buy_order_grid) == 2:
5106            #         orderParams = trader.ParseOrderParameters(operation="Buy", **dict(kw.split('=') for kw in args.buy_order_grid))
5107            #
5108            #         for order in orderParams:
5109            #             trader.Order(operation="Buy", lots=order["lot"], price=order["price"])
5110            #
5111            #     else:
5112            #         uLogger.error("To open grid of pending BUY limit-orders (below current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5113            #
5114            # elif args.sell_order_grid is not None:
5115            #     # update order grid work with api v2
5116            #     if len(args.sell_order_grid) >= 2:
5117            #         orderParams = trader.ParseOrderParameters(operation="Sell", **dict(kw.split('=') for kw in args.sell_order_grid))
5118            #
5119            #         for order in orderParams:
5120            #             trader.Order(operation="Sell", lots=order["lot"], price=order["price"])
5121            #
5122            #     else:
5123            #         uLogger.error("To open grid of pending SELL limit-orders (above current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
5124
5125            elif args.close_order is not None:
5126                trader.CloseOrders(args.close_order)  # close only one order
5127
5128            elif args.close_orders is not None:
5129                trader.CloseOrders(args.close_orders)  # close list of orders
5130
5131            elif args.close_trade:
5132                if not (args.ticker or args.figi):
5133                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
5134                    raise Exception("Ticker or FIGI required")
5135
5136                if args.ticker:
5137                    trader.CloseTrades([str(args.ticker).upper()])  # close only one trade by ticker (priority)
5138
5139                else:
5140                    trader.CloseTrades([str(args.figi).upper()])  # close only one trade by FIGI
5141
5142            elif args.close_trades is not None:
5143                trader.CloseTrades(args.close_trades)  # close trades for list of tickers
5144
5145            elif args.close_all is not None:
5146                if args.ticker:
5147                    trader.CloseAllByTicker(instrument=str(args.ticker).upper())
5148
5149                elif args.figi:
5150                    trader.CloseAllByFIGI(instrument=str(args.figi).upper())
5151
5152                else:
5153                    trader.CloseAll(*args.close_all)
5154
5155            elif args.limits:
5156                if args.output is not None:
5157                    trader.withdrawalLimitsFile = args.output
5158
5159                trader.OverviewLimits(show=True)
5160
5161            elif args.user_info:
5162                if args.output is not None:
5163                    trader.userInfoFile = args.output
5164
5165                trader.OverviewUserInfo(show=True)
5166
5167            elif args.account:
5168                if args.output is not None:
5169                    trader.userAccountsFile = args.output
5170
5171                trader.OverviewAccounts(show=True)
5172
5173            else:
5174                uLogger.error("There is no command to execute! One of the possible commands must be selected. See help with `--help` key.")
5175                raise Exception("There is no command to execute")
5176
5177    except Exception:
5178        trace = tb.format_exc()
5179        for e in ["socket.gaierror", "nodename nor servname provided", "or not known", "NewConnectionError", "[Errno 8]", "Failed to establish a new connection"]:
5180            if e in trace:
5181                uLogger.error("Check your Internet connection! Failed to establish connection to broker server!")
5182                break
5183
5184        uLogger.debug(trace)
5185        uLogger.debug("Please, check issues or request a new one at https://github.com/Tim55667757/TKSBrokerAPI/issues")
5186        exitCode = 255  # an error occurred, must be open a ticket for this issue
5187
5188    finally:
5189        finish = datetime.now(tzutc())
5190
5191        if exitCode == 0:
5192            if args.more:
5193                uLogger.debug("All operations were finished success (summary code is 0).")
5194
5195        else:
5196            uLogger.error("An issue occurred with TKSBrokerAPI module! See full debug log in [{}] or run TKSBrokerAPI once again with the key `--debug-level 10`. Summary code: {}".format(
5197                os.path.abspath(uLog.defaultLogFile), exitCode,
5198            ))
5199
5200        uLogger.debug(">>> TKSBrokerAPI module work duration: [{}]".format(finish - start))
5201        uLogger.debug(">>> TKSBrokerAPI module finished: [{} UTC], it is [{}] local time".format(
5202            finish.strftime(TKS_PRINT_DATE_TIME_FORMAT),
5203            finish.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
5204        ))
5205        uLogger.debug("=-" * 50)
5206
5207        if not kwargs:
5208            sys.exit(exitCode)
5209
5210        else:
5211            return exitCode
5212
5213
5214if __name__ == "__main__":
5215    Main()