ibflex2 1.0.0__py3-none-any.whl

ibflex/__init__.py

@@ -0,0 +1,19 @@
+from . import enums
+from .enums import *
+from . import Types
+from .Types import *
+from . import parser
+from .parser import parse
+from . import utils
+from . import client
+
+from .__version__ import (
+    __title__,
+    __description__,
+    __url__,
+    __version__,
+    __author__,
+    __author_email__,
+    __license__,
+    __copyright__,
+)

ibflex/__version__.py

@@ -0,0 +1,26 @@
+"""
+Get a job, save your money, listen to Jane
+Everybody knows umbrellas cost more in the rain
+All the news is bad
+Is there any other kind?
+Everybody's talking at the same time
+
+It's hard times for some
+For others it's sweet
+Someone makes money when there's blood in the street
+Don't take any lip
+Stay in line
+Everybody's talking at the same time
+"""
+__title__ = "ibflex2"
+__description__ = (
+    "Parse Interactive Brokers Flex XML reports and convert to Python types (maintained fork)"
+),
+__url__ = "https://github.com/robcohen/ibflex2"
+__upstream_url__ = "https://github.com/csingley/ibflex"
+__version__ = "1.0.0"
+__author__ = "Christopher Singley"
+__author_email__ = "csingley@gmail.com"
+__maintainer__ = "robcohen"
+__license__ = "MIT"
+__copyright__ = "Copyright 2017 Christopher Singley"

ibflex/client.py

@@ -0,0 +1,259 @@
+# coding: utf-8
+"""
+Download Flex queries without logging into Account Management web page.
+
+https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm
+"""
+# stdlib imports
+from dataclasses import dataclass
+import xml.etree.ElementTree as ET
+from datetime import datetime
+import time
+from typing import Union, Optional
+
+
+# 3rd party imports
+import requests
+
+
+###############################################################################
+# SERVICE LOCATIONS
+###############################################################################
+FLEX_URL = 'https://gdcdyn.interactivebrokers.com/Universal/servlet/'
+REQUEST_URL = FLEX_URL + 'FlexStatementService.SendRequest'
+STMT_URL = FLEX_URL + 'FlexStatementService.GetStatement'
+
+
+###############################################################################
+# ERRORS
+###############################################################################
+ERRORS = [
+    ("1003", "Statement is not available."),
+    ("1004", "Statement is incomplete at this time. Please try again shortly."),
+    ("1005", "Settlement data is not ready at this time. Please try again shortly."),
+    ("1006", "FIFO P/L data is not ready at this time. Please try again shortly."),
+    ("1007", "MTM P/L data is not ready at this time. Please try again shortly."),
+    ("1008", "MTM and FIFO P/L data is not ready at this time. Please try again shortly."),
+    ("1009", "The server is under heavy load. Statement could not be generated at this time. Please try again shortly."),
+    ("1010", "Legacy Flex Queries are no longer supported. Please convert over to Activity Flex."),
+    ("1011", "Service account is inactive."),
+    ("1012", "Token has expired."),
+    ("1013", "IP restriction."),
+    ("1014", "Query is invalid."),
+    ("1015", "Token is invalid."),
+    ("1016", "Account in invalid."),
+    ("1017", "Reference code is invalid."),
+    ("1018", "Too many requests have been made from this token. Please try again shortly."),
+    ("1019", "Statement generation in progress. Please try again shortly."),
+    ("1020", "Invalid request or unable to validate request."),
+    ("1021", "Statement could not be retrieved at this time. Please try again shortly."),
+]
+ERROR_CODES, ERROR_MSGS = zip(*ERRORS)
+
+SERVER_BUSY = ("1009", "1019", )
+CLIENT_THROTTLED = ("1018", )
+
+
+class IbflexClientError(Exception):
+    """ Base class for Exceptions defined in this module """
+
+
+class BadResponseError(IbflexClientError):
+    """
+    Exception raised for malformed Flex response.
+    """
+    def __init__(self, response: requests.Response):
+        self.response = response
+        super(BadResponseError, self).__init__(response.content)
+        
+
+class StatementGenerationTimeout(IbflexClientError):
+    """ Exception raised when the Flex server says it is generating the response,
+        but does not finish generating the statement in a timely fashion.
+    """
+
+
+class ResponseCodeError(IbflexClientError):
+    """
+    Exception raised when Flex server returns a response with an error code.
+    """
+    def __init__(self, code: str, msg: str):
+        self.code = code
+        self.msg = msg
+        super(ResponseCodeError, self).__init__(f"Code={code}: {msg}")
+
+
+###############################################################################
+#  FlexStatementResponse TYPES
+###############################################################################
+@dataclass(frozen=True)
+class StatementAccess:
+    timestamp: datetime
+    ReferenceCode: str
+    Url: str
+
+
+@dataclass(frozen=True)
+class StatementError:
+    timestamp: datetime
+    ErrorCode: str
+    ErrorMessage: str
+
+
+###############################################################################
+# FUNCTIONS
+###############################################################################
+def download(token: str, query_id: str, max_tries: Optional[int] = 5) -> bytes:
+    """2-step FlexQueryReport download process.
+
+    Args:
+        token: Current access token from Reports > Settings > FlexWeb Service.
+        query_id: Flex Query ID from
+                  Reports > Flex Queries > Custom Flex Queries > Configure.
+    """
+    stmt_access = request_statement(token, query_id)
+    status = 0
+    tries = 0
+    while status is not True:
+        time.sleep(status)
+        tries += 1
+        response = submit_request(
+            url=stmt_access.Url or STMT_URL,
+            token=token,
+            query=stmt_access.ReferenceCode,
+        )
+        status = check_statement_response(response)
+        if max_tries and tries > max_tries:
+            raise StatementGenerationTimeout(
+                "Exceeded max number of tries while attempting download"
+            )
+    return response.content
+
+
+def request_statement(
+    token: str, query_id: str, url: Optional[str] = None
+) -> StatementAccess:
+    """First part of the 2-step download process.
+    """
+    url = url or REQUEST_URL
+    ### AKE FIX
+    url = 'https://ndcdyn.interactivebrokers.com/portal.flexweb/api/v1/flexQuery'
+    response = submit_request(url, token, query=query_id)
+    stmt_access = parse_stmt_response(response)
+    if isinstance(stmt_access, StatementError):
+        raise ResponseCodeError(
+            stmt_access.ErrorCode,
+            stmt_access.ErrorMessage,
+        )
+    return stmt_access
+
+
+def submit_request(url: str, token: str, query: str) -> requests.Response:
+    """Post a query to an API access point, along with an authentication token.
+
+    Retry with a progressive timeout window.
+    """
+    MAX_REQUESTS = 3
+    TIMEOUT_INCREMENT = 5
+
+    response = None
+    req_count = 1
+    while (not response):
+        try:
+            response = requests.get(
+                url,
+                params={"v": "3", "t": token, "q": query},
+                headers={"user-agent": "Java"},
+                timeout=req_count * TIMEOUT_INCREMENT,
+            )
+        except requests.exceptions.Timeout:
+            if req_count >= MAX_REQUESTS:
+                raise
+            else:
+                print("Request Timeout, re-sending...")
+                req_count += 1
+
+    return response
+
+
+def parse_stmt_response(
+    response: requests.Response
+) -> Union[StatementAccess, StatementError]:
+    """Read 1st step response; parse into StatementAccess or StatementError.
+    """
+    try:
+        elem = ET.fromstring(response.content)
+        assert elem.tag == 'FlexStatementResponse'
+
+        timestamp = elem.attrib['timestamp']
+        # Convert "EST"/"EDT" to UTC offset so datetime.strptime can understand
+        tz = {'EST': '-0500', 'EDT': '-0400'}[timestamp[-3:]]
+        timestamp = timestamp[:-3] + tz
+        datetime_ = datetime.strptime(timestamp, '%d %B, %Y %I:%M %p %z')
+
+        data = {child.tag: child.text for child in elem}
+        status = data.pop("Status")
+        assert status in {"Success", "Fail", "Warn"}
+        Type = {
+            "Success": StatementAccess,
+            "Fail": StatementError,
+            "Warn": StatementError,
+        }[status]
+        return Type(timestamp=datetime_, **data)  # type: ignore
+    except Exception:
+        raise BadResponseError(response=response)
+
+
+def check_statement_response(response: requests.Response) -> Union[bool, int]:
+    """Validate response received from 2nd step of download.
+
+    Returns:
+        True if `response` contains a FlexQueryResponse.
+        Retry delay (seconds) if `response` is an error indicating that
+            'please try again shortly' means 'within several seconds'.
+
+    Raises:
+        ResponseCodeError if `response` is any other kind of error.
+        BadResponseError if we can't parse `response`.
+    """
+    #  FlexQueryResponses can be massive; avoid parsing them.
+    resp_str = str(response.content)
+    if 'FlexQueryResponse' in resp_str:
+        return True
+    elif 'FlexStatementResponse' in resp_str:
+        try:
+            error = parse_stmt_response(response)
+            assert isinstance(error, StatementError)
+        except Exception:
+            raise BadResponseError(response)
+        if error.ErrorCode in SERVER_BUSY:
+            #  Statement generation in progress. Please try again shortly.
+            return 5
+        elif error.ErrorCode in CLIENT_THROTTLED:
+            #  Too many requests have been made from this token. Please try again shortly.
+            return 10
+        else:
+            raise ResponseCodeError(error.ErrorCode, error.ErrorMessage)
+    else:
+        raise BadResponseError(response)
+
+
+##############################################################################
+# CLI SCRIPT
+###############################################################################
+def main():
+    from argparse import ArgumentParser
+    description = 'Download Flex brokerage statement from Interactive Brokers'
+    argparser = ArgumentParser(description=description)
+    argparser.add_argument('--token', '-t', required=True,
+                           help='Current Flex Web Service token')
+    argparser.add_argument('--query', '-q', required=True,
+                           help='Flex Query ID#')
+    args = argparser.parse_args()
+
+    statement = download(args.token, args.query)
+    print(statement.decode())
+
+
+if __name__ == '__main__':
+    main()

ibflex/enums.py

@@ -0,0 +1,295 @@
+# coding: utf-8
+"""Enumerated values (Python enum.Enum subclasses) used to define ibflex.Types.
+
+Values are the text sent by IB in XML element attribute.
+Names keep the convention of using UPPERCASE for Enums.
+
+When creating a new Enum subclass, be sure to add it to ENUMS
+and EnumType (as Optional type) at the end of the file.
+"""
+
+__all__ = [
+    "CashAction",
+    "Code",
+    "AssetClass",
+    "TradeType",
+    "BuySell",
+    "OpenClose",
+    "OrderType",
+    "Reorg",
+    "OptionAction",
+    "LongShort",
+    "TransferType",
+    "ToFrom",
+    "InOut",
+    "DeliveredReceived",
+    "ENUMS",
+    "EnumType",
+    "PutCall"
+]
+
+import enum
+import typing
+
+
+@enum.unique
+class CashAction(str, enum.Enum):
+    DEPOSITWITHDRAW = "Deposits & Withdrawals"
+    BROKERINTPAID = "Broker Interest Paid"
+    BROKERINTRCVD = "Broker Interest Received"
+    WHTAX = "Withholding Tax"
+    BONDINTRCVD = "Bond Interest Received"
+    BONDINTPAID = "Bond Interest Paid"
+    FEES = "Other Fees"
+    DIVIDEND = "Dividends"
+    PAYMENTINLIEU = "Payment In Lieu Of Dividends"
+    COMMADJ = "Commission Adjustments"
+    ADVISORFEES = "Advisor Fees"
+
+@enum.unique
+class Code(str, enum.Enum):
+    """Used for both `code` and `notes` attributes.
+    """
+    ASSIGNMENT = "A"
+    AUTOEXERCISE = "AEx"  # Automatic exercise for dividend-related recommendation
+    AUTOFX = "AFx" # AutoFX conversion resulting from trading
+    ADJUSTMENT = "Adj"  # Adjustment
+    ALLOCATION = "Al"  # Allocation
+    AWAY = "Aw"  # Away Trade
+    BUYIN = "B"  # Automatic Buy-in
+    BORROW = "Bo"  # Direct Borrow
+    CLOSING = "C"  # Closing Trade
+    CASHDELIVERY = "CD"  # Cash Delivery
+    COMPLEX = "CP"  # Complex Position
+    CANCEL = "Ca"  # Cancelled
+    CORRECT = "Co"  # Corrected Trade
+    CROSSING = "Cx"  # Part or all of this transaction was a Crossing executed as dual agent by IB for two IB customers
+    DUAL = "D"  # IB acted as Dual Agent, UNIQUE TO TRADE CONFIRM REPORT
+    ETF = "ETF"  # ETF Creation/Redemption
+    EXPIRED = "Ep"  # Resulted from an Expired Position
+    EXERCISE = "Ex"  # Exercise
+    GUARANTEED = "G"  # Trade in Guaranteed Account Segment
+    HIGHESTCOST = "HC"  # Highest Cost tax lot-matching method
+    HFINVESTMENT = "HFI"  # Investment Transferred to Hedge Fund
+    HFREDEMPTION = "HFR"  # Redemption from Hedge Fund
+    INTERNAL = "I"  # Internal Transfer
+    AFFILIATE = "IA"  # This transaction was executed against an IB affiliate
+    INVESTOR = "INV"  # Investment Transfer from Investor
+    MARGINLOW = "L"  # Ordered by IB (Margin Violation)
+    WASHSALE = "LD"  # Adjusted by Loss Disallowed from Wash Sale
+    LIFO = "LI"  # Last In, First Out (LIFO) tax lot-matching method
+    LTCG = "LT"  # Long-term P/L
+    LOAN = "Lo"  # Direct Loan
+    MANUAL = "M"  # Entered manually by IB
+    MANUALEXERCISE = "MEx"  # Manual exercise for dividend-related recommendation
+    MAXLOSS = "ML"  # Maximize Losses tax basis election
+    MAXLTCG = "MLG"  # Maximize Long-Term Gain tax lot-matching method
+    MINLTCG = "MLL"  # Maximize Long-Term Loss tax lot-matching method
+    MAXSTCG = "MSG"  # Maximize Short-Term Gain tax lot-matching method
+    MINSTCG = "MSL"  # Maximize Short-Term Loss tax lot-matching method
+    OPENING = "O"  # Opening Trade
+    PARTIAL = "P"  # Partial Execution
+    FRACRISKLESSPRINCIPAL = "RP"  # IB acted as riskless principal for the fractional share portion of this trade
+    FRACPRINCIPAL = "FP"  # IB acted as principal for the fractional share portion of this trade
+    PRICEIMPROVEMENT = "PI"  # Price Improvement
+    POSTACCRUAL = "Po"  # Interest or Dividend Accrual Posting
+    PRINCIPAL = "Pr"  # Part or all of this transaction was executed by the Exchange as a Crossing by IB against an IB affiliate and is therefore classified as a Principal and not an agency trade
+    REINVESTMENT = "R"  # Dividend Reinvestment
+    REDEMPTION = "RED"  # Redemption to Investor
+    REVERSE = "Re"  # Interest or Dividend Accrual Reversal
+    REIMBURSEMENT = "RI"  # Reimbursement
+    SOLICITEDIB = "SI"  # This order was solicited by Interactive Brokers
+    SPECIFICLOT = "SL"  # Specific Lot tax lot-matching method
+    SOLICITEDOTHER = "SO"  # This order was marked as solicited by your Introducing Broker
+    SHORTENEDSETTLEMENT = "SS"  # Customer designated this trade for shortened settlement and so is subject to execution at prices above the prevailing market
+    STCG = "ST"  # Short-term P/L
+    STOCKYIELD = "SY"  # Positions that may be eligible for Stock Yield.
+    TRANSFER = "T"  # Transfer
+
+
+@enum.unique
+class AssetClass(str, enum.Enum):
+    CASH = "CASH"
+    BILL = "BILL"
+    BOND = "BOND"
+    STOCK = "STK"
+    OPTION = "OPT"
+    WARRANT = "WAR"
+    FUTURE = "FUT"
+    FUTUREOPTION = "FOP"
+    CFD = "CFD"
+    FOREXCFD = "FXCFD"
+    CRYPTOCURRENCY = "CRYPTO"
+    STRUCTUREDPRODUCTS = "IOPT"
+    METALS = "CMDTY"
+    OPTIONSONFUTURES = "FSFOP"
+    OPTIONSFUTURESSTYLE = "FSOPT"
+    MUTUALFUND = "FUND"
+
+
+@enum.unique
+class TradeType(str, enum.Enum):
+    EXCHTRADE = "ExchTrade"
+    TRADECANCEL = "TradeCancel"
+    FRACSHARE = "FracShare"
+    FRACSHARECANCEL = "FracShareCancel"
+    TRADECORRECT = "TradeCorrect"
+    BOOKTRADE = "BookTrade"
+    DVPTRADE = "DvpTrade"
+
+
+@enum.unique
+class BuySell(str, enum.Enum):
+    BUY = "BUY"
+    CANCELBUY = "BUY (Ca.)"
+    SELL = "SELL"
+    CANCELSELL = "SELL (Ca.)"
+
+
+@enum.unique
+class OpenClose(str, enum.Enum):
+    OPEN = "O"
+    CLOSE = "C"
+    OPENCLOSE = "C;O"
+    UNKNOWN = "-"
+
+
+@enum.unique
+class OrderType(str, enum.Enum):
+    LIMIT = "LMT"
+    MARKET = "MKT"
+    STOP = "STP"
+    STOPLIMIT = "STPLMT"
+    MARKETONCLOSE = "MOC"
+    LIMITONCLOSE = "LOC"
+    # MULTIPLE is not an actual IB order type. It is a catch-all value to use when an Order has an orderType like "LMT;MKT".
+    # This way OrderType can remian a enum and not be a Tuple.
+    MULTIPLE = "MULTIPLE"
+    TRAILLMT = "TRAILLMT"
+    MIDPX = "MIDPX"
+    TRAIL = "TRAIL"
+    REL = "REL"
+    MIT = "MIT"
+
+@enum.unique
+class Reorg(str, enum.Enum):
+    BONDCONVERSION = "BC"
+    BONDMATURITY = "BM"
+    CONTRACTSOULTE = "CA"
+    CONTRACTCONSOLIDATION = "CC"
+    CASHDIV = "CD"
+    CHOICEDIV = "CH"
+    CONVERTIBLEISSUE = "CI"
+    CONTRACTSPINOFF = "CO"
+    COUPONPAYMENT = "CP"
+    CONTRACTSPLIT = "CS"
+    CFDTERMINATION = "CT"
+    DIVRIGHTSISSUE = "DI"
+    DELISTWORTHLESS = "DW"
+    EXPIREDIVRIGHT = "ED"
+    FEEALLOCATION = "FA"
+    FORWARDSPLITISSUE = "FI"
+    FORWARDSPLIT = "FS"
+    GENERICVOLUNTARY = "GV"
+    CHOICEDIVDELIVERY = "HD"
+    CHOICEDIVISSUE = "HI"
+    ISSUECHANGE = "IC"
+    ASSETPURCHASE = "OR"
+    PURCHASEISSUE = "PI"
+    PROXYVOTE = "PV"
+    RIGHTSISSUE = "RI"
+    REVERSESPLIT = "RS"
+    STOCKDIV = "SD"
+    SPINOFF = "SO"
+    SUBSCRIBERIGHTS = "SR"
+    MERGER = "TC"
+    TENDERISSUE = "TI"
+    TENDER = "TO"
+    TBILLMATURITY = "TM"
+
+
+@enum.unique
+class OptionAction(str, enum.Enum):
+    ASSIGN = "Assignment"
+    EXERCISE = "Exercise"
+    EXPIRE = "Expiration"
+    SELL = "Sell"
+    BUY = "Buy"
+    CASHSETTLEMENT = "Cash Settlement"
+
+
+@enum.unique
+class LongShort(str, enum.Enum):
+    LONG = "Long"
+    SHORT = "Short"
+
+
+@enum.unique
+class ToFrom(str, enum.Enum):
+    TO = "To"
+    FROM = "From"
+
+
+@enum.unique
+class TransferType(str, enum.Enum):
+    INTERNAL = "INTERNAL"
+    ACATS = "ACATS"
+    ATON = "ATON"
+    FOP = "FOP"
+
+
+@enum.unique
+class InOut(str, enum.Enum):
+    IN = "IN"
+    OUT = "OUT"
+
+
+@enum.unique
+class DeliveredReceived(str, enum.Enum):
+    DELIVERED = "Delivered"
+    RECEIVED = "Received"
+
+
+@enum.unique
+class PutCall(str, enum.Enum):
+    PUT = "P"
+    CALL = "C"
+
+
+ENUMS = [
+    CashAction,
+    Code,
+    AssetClass,
+    TradeType,
+    BuySell,
+    OpenClose,
+    OrderType,
+    Reorg,
+    OptionAction,
+    LongShort,
+    ToFrom,
+    TransferType,
+    InOut,
+    DeliveredReceived,
+    PutCall,
+]
+"""Used by ibflex.parser.ATTRIB_CONVERTERS"""
+
+EnumType = typing.Union[
+    typing.Optional[CashAction],
+    typing.Optional[Code],
+    typing.Optional[AssetClass],
+    typing.Optional[TradeType],
+    typing.Optional[BuySell],
+    typing.Optional[OpenClose],
+    typing.Optional[OrderType],
+    typing.Optional[Reorg],
+    typing.Optional[OptionAction],
+    typing.Optional[LongShort],
+    typing.Optional[ToFrom],
+    typing.Optional[TransferType],
+    typing.Optional[InOut],
+    typing.Optional[DeliveredReceived],
+    typing.Optional[PutCall],
+]
+"""Used by ibflex.parser.DataType"""