ibflex 1.1__tar.gz → 1.2__tar.gz

{ibflex-1.1 → ibflex-1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ibflex
-Version: 1.1
+Version: 1.2
 Summary: Parse Interactive Brokers Flex XML reports and convert to Python types
 Author-email: Christopher Singley <csingley@gmail.com>
 License-Expression: MIT
@@ -148,6 +148,16 @@ them:
     In [5]: response[:215]
     Out[5]: b'<FlexQueryResponse queryName="Get Everything" type="AF">\n<FlexStatements count="1">\n<FlexStatement accountId="U111111" fromDate="2018-01-01" toDate="2018-01-31" period="LastMonth" whenGenerated="2018-02-01;211353">\n'
 
+You can override the report's date range per request with ``period`` (the
+``p`` parameter - a lookback in days, up to 365) or ``fd``/``td`` (explicit
+``yyyymmdd`` from/to dates, given together); the two forms are mutually
+exclusive. This is useful because the v3 Flex Web Service may not honor a
+query's saved "Last N Calendar Days" period:
+
+.. code:: python
+
+    In [6]: response = client.download(token, query_id, period=90)
+
 
 ``pip install ibflex[web]`` also installs a ``flexget`` console script:
 
@@ -156,6 +166,24 @@ them:
     $ flexget -t 111111111111111111111111 -q 111111 > 2018-01_ibkr.xml
 
 
+Releasing
+=========
+Releases are published to PyPI automatically via GitHub Actions using
+`trusted publishing`_ (OIDC).  No API tokens are needed.
+
+To cut a release:
+
+1. Bump the version in ``pyproject.toml`` and ``ibflex/__version__.py``.
+2. Commit, push to ``master``.
+3. Create a GitHub release with a tag matching the version (e.g. ``v1.1``).
+
+The ``Publish to PyPI`` workflow will build and upload the package.
+
+Any repository collaborator who can create a GitHub release **and** has access
+to the ``pypi`` deployment environment can publish.  Environment access is
+managed under Settings → Environments → pypi.
+
+
 Resources
 =========
 * Interactive Brokers `Activity Flex Query Reference`_
@@ -168,5 +196,6 @@ Resources
 .. _Interactive Brokers account management: https://www.interactivebrokers.com/sso/Login
 .. _Activity Flex Query Reference: https://www.interactivebrokers.com/en/software/reportguide/reportguide.htm#reportguide/activity_flex_query_reference.htm
 .. _FlexWeb Service Reference: https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm
+.. _trusted publishing: https://docs.pypi.org/trusted-publishers/
 .. _capgains: https://github.com/csingley/capgains
 .. _ib-flex-analyzer: https://github.com/wesm/ib-flex-analyzer

{ibflex-1.1 → ibflex-1.2}/README.rst

@@ -116,6 +116,16 @@ them:
     In [5]: response[:215]
     Out[5]: b'<FlexQueryResponse queryName="Get Everything" type="AF">\n<FlexStatements count="1">\n<FlexStatement accountId="U111111" fromDate="2018-01-01" toDate="2018-01-31" period="LastMonth" whenGenerated="2018-02-01;211353">\n'
 
+You can override the report's date range per request with ``period`` (the
+``p`` parameter - a lookback in days, up to 365) or ``fd``/``td`` (explicit
+``yyyymmdd`` from/to dates, given together); the two forms are mutually
+exclusive. This is useful because the v3 Flex Web Service may not honor a
+query's saved "Last N Calendar Days" period:
+
+.. code:: python
+
+    In [6]: response = client.download(token, query_id, period=90)
+
 
 ``pip install ibflex[web]`` also installs a ``flexget`` console script:
 
@@ -124,6 +134,24 @@ them:
     $ flexget -t 111111111111111111111111 -q 111111 > 2018-01_ibkr.xml
 
 
+Releasing
+=========
+Releases are published to PyPI automatically via GitHub Actions using
+`trusted publishing`_ (OIDC).  No API tokens are needed.
+
+To cut a release:
+
+1. Bump the version in ``pyproject.toml`` and ``ibflex/__version__.py``.
+2. Commit, push to ``master``.
+3. Create a GitHub release with a tag matching the version (e.g. ``v1.1``).
+
+The ``Publish to PyPI`` workflow will build and upload the package.
+
+Any repository collaborator who can create a GitHub release **and** has access
+to the ``pypi`` deployment environment can publish.  Environment access is
+managed under Settings → Environments → pypi.
+
+
 Resources
 =========
 * Interactive Brokers `Activity Flex Query Reference`_
@@ -136,5 +164,6 @@ Resources
 .. _Interactive Brokers account management: https://www.interactivebrokers.com/sso/Login
 .. _Activity Flex Query Reference: https://www.interactivebrokers.com/en/software/reportguide/reportguide.htm#reportguide/activity_flex_query_reference.htm
 .. _FlexWeb Service Reference: https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm
+.. _trusted publishing: https://docs.pypi.org/trusted-publishers/
 .. _capgains: https://github.com/csingley/capgains
 .. _ib-flex-analyzer: https://github.com/wesm/ib-flex-analyzer

{ibflex-1.1 → ibflex-1.2}/ibflex/Types.py

@@ -485,6 +485,7 @@ class MTDYTDPerformanceSummaryUnderlying(FlexElement):
     """Wrapped in <MTDYTDPerformanceSummary>"""
 
     assetCategory: enums.AssetClass | None = None
+    subCategory: enums.SubCategory | None = None
     accountId: str | None = None
     acctAlias: str | None = None
     model: str | None = None
@@ -494,6 +495,7 @@ class MTDYTDPerformanceSummaryUnderlying(FlexElement):
     securityID: str | None = None
     cusip: str | None = None
     isin: str | None = None
+    figi: str | None = None
     listingExchange: str | None = None
     underlyingConid: str | None = None
     underlyingSecurityID: str | None = None
@@ -2796,6 +2798,7 @@ class SalesTax(FlexElement):
     securityIDType: str | None = None
     cusip: str | None = None
     isin: str | None = None
+    figi: str | None = None
     listingExchange: str | None = None
     underlyingConid: str | None = None
     underlyingSecurityID: str | None = None

{ibflex-1.1 → ibflex-1.2}/ibflex/__version__.py

@@ -17,7 +17,7 @@ __description__ = (
     "Parse Interactive Brokers Flex XML reports and convert to Python types"
 ),
 __url__ = "https://github.com/csingley/ibflex"
-__version__ = "1.1"
+__version__ = "1.2"
 __author__ = "Christopher Singley"
 __author_email__ = "csingley@gmail.com"
 __license__ = "MIT"

{ibflex-1.1 → ibflex-1.2}/ibflex/client.py

@@ -17,7 +17,7 @@ import requests
 # SERVICE LOCATIONS
 ###############################################################################
 REQUEST_URL = 'https://ndcdyn.interactivebrokers.com/AccountManagement/FlexWebService/SendRequest'
-STMT_URL = 'https://gdcdyn.interactivebrokers.com/AccountManagement/FlexWebService/GetStatement'
+STMT_URL = 'https://ndcdyn.interactivebrokers.com/AccountManagement/FlexWebService/GetStatement'
 
 
 ###############################################################################
@@ -99,15 +99,34 @@ class StatementError:
 ###############################################################################
 # FUNCTIONS
 ###############################################################################
-def download(token: str, query_id: str, max_tries: int | None = 5) -> bytes:
+def download(
+    token: str,
+    query_id: str,
+    max_tries: int | None = 5,
+    period: int | None = None,
+    fd: str | None = None,
+    td: str | None = None,
+    timeout: float = 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.
+        max_tries: Number of times to poll for statement generation before
+                   raising StatementGenerationTimeout.
+        period: Optional lookback override, in days (max 365), sent as the
+                ``p`` SendRequest parameter.
+        fd, td: Optional explicit from/to date override (``yyyymmdd``, at most
+                365 days apart), sent as the ``fd``/``td`` SendRequest
+                parameters; must be given together. ``period`` and
+                ``fd``/``td`` are mutually exclusive.
+        timeout: Seconds to wait for the first attempt of each HTTP request
     """
-    stmt_access = request_statement(token, query_id)
+    stmt_access = request_statement(
+        token, query_id, period=period, fd=fd, td=td, timeout=timeout
+    )
     status = 0
     tries = 0
     while status is not True:
@@ -117,6 +136,7 @@ def download(token: str, query_id: str, max_tries: int | None = 5) -> bytes:
             url=stmt_access.Url or STMT_URL,
             token=token,
             query=stmt_access.ReferenceCode,
+            timeout_increment=timeout,
         )
         status = check_statement_response(response)
         if max_tries and tries > max_tries:
@@ -127,12 +147,24 @@ def download(token: str, query_id: str, max_tries: int | None = 5) -> bytes:
 
 
 def request_statement(
-    token: str, query_id: str, url: str | None = None
+    token: str,
+    query_id: str,
+    url: str | None = None,
+    period: int | None = None,
+    fd: str | None = None,
+    td: str | None = None,
+    timeout: float = 5,
 ) -> StatementAccess:
     """First part of the 2-step download process.
+
+    ``period``/``fd``/``td`` are optional date-range overrides applied only
+    to this SendRequest, not to the GetStatement polls.
     """
     url = url or REQUEST_URL
-    response = submit_request(url, token, query=query_id)
+    response = submit_request(
+        url, token, query=query_id, period=period, fd=fd, td=td,
+        timeout_increment=timeout
+    )
     stmt_access = parse_stmt_response(response)
     if isinstance(stmt_access, StatementError):
         raise ResponseCodeError(
@@ -142,13 +174,37 @@ def request_statement(
     return stmt_access
 
 
-def submit_request(url: str, token: str, query: str) -> requests.Response:
+def submit_request(
+    url: str,
+    token: str,
+    query: str,
+    period: int | None = None,
+    fd: str | None = None,
+    td: str | None = None,
+    timeout_increment: float = 5,
+) -> requests.Response:
     """Post a query to an API access point, along with an authentication token.
 
+    ``period`` (``p``), ``fd`` and ``td`` are optional date-range overrides
+    added to the query string after the required ``v``/``t``/``q`` params.
+    ``period`` and ``fd``/``td`` are mutually exclusive, and ``fd``/``td``
+    must be given together.
+
     Retry with a progressive timeout window.
     """
+    if period is not None and (fd is not None or td is not None):
+        raise ValueError("Pass either `period` or `fd`/`td`, not both")
+    if (fd is None) != (td is None):
+        raise ValueError("Pass both `fd` and `td`, or neither")
+
     MAX_REQUESTS = 3
-    TIMEOUT_INCREMENT = 5
+    params = {"v": "3", "t": token, "q": query}
+    if period is not None:
+        params["p"] = str(period)
+    if fd is not None:
+        params["fd"] = fd
+    if td is not None:
+        params["td"] = td
 
     response = None
     req_count = 1
@@ -156,9 +212,9 @@ def submit_request(url: str, token: str, query: str) -> requests.Response:
         try:
             response = requests.get(
                 url,
-                params={"v": "3", "t": token, "q": query},
+                params=params,
                 headers={"user-agent": "Java"},
-                timeout=req_count * TIMEOUT_INCREMENT,
+                timeout=req_count * timeout_increment,
             )
         except requests.exceptions.Timeout:
             if req_count >= MAX_REQUESTS:
@@ -186,6 +242,9 @@ def parse_stmt_response(
         datetime_ = datetime.strptime(timestamp, '%d %B, %Y %I:%M %p %z')
 
         data = {child.tag: child.text for child in elem}
+        # Live responses use <Url>, but IB docs show <url>; accept either
+        if "url" in data:
+            data["Url"] = data.pop("url")
         status = data.pop("Status")
         assert status in {"Success", "Fail", "Warn"}
         Type = {
@@ -243,9 +302,20 @@ def main():
                            help='Current Flex Web Service token')
     argparser.add_argument('--query', '-q', required=True,
                            help='Flex Query ID#')
+    argparser.add_argument('--period', '-p', type=int, default=None,
+                           help='Lookback override in days (max 365)')
+    argparser.add_argument('--fromdate', '--fd', dest='fd', default=None,
+                           help='From-date override (yyyymmdd)')
+    argparser.add_argument('--todate', '--td', dest='td', default=None,
+                           help='To-date override (yyyymmdd)')
     args = argparser.parse_args()
 
-    statement = download(args.token, args.query)
+    try:
+        statement = download(
+            args.token, args.query, period=args.period, fd=args.fd, td=args.td
+        )
+    except ValueError as exc:
+        argparser.error(str(exc))
     print(statement.decode())
 
 

{ibflex-1.1 → ibflex-1.2}/ibflex/enums.py

@@ -68,6 +68,7 @@ class Code(str, enum.Enum):
     ETF = "ETF"  # ETF Creation/Redemption
     EXPIRED = "Ep"  # Resulted from an Expired Position
     EXERCISE = "Ex"  # Exercise
+    MUTUALFUNDEXCHANGE = "XCH"  # Mutual fund exchange (FUND trade routed via FUNDSERV)
     GUARANTEED = "G"  # Trade in Guaranteed Account Segment
     HIGHESTCOST = "HC"  # Highest Cost tax lot-matching method
     HFINVESTMENT = "HFI"  # Investment Transferred to Hedge Fund
@@ -129,6 +130,15 @@ class AssetClass(str, enum.Enum):
     MUTUALFUND = "FUND"
 
 
+@enum.unique
+class SubCategory(str, enum.Enum):
+    COMMON = "COMMON"
+    ADR = "ADR"
+    ETF = "ETF"
+    P = "P"
+    C = "C"
+
+
 @enum.unique
 class TradeType(str, enum.Enum):
     EXCHTRADE = "ExchTrade"
@@ -146,6 +156,8 @@ class BuySell(str, enum.Enum):
     CANCELBUY = "BUY (Ca.)"
     SELL = "SELL"
     CANCELSELL = "SELL (Ca.)"
+    EXCHANGEBUY = "EXCHANGE BUY"
+    EXCHANGESELL = "EXCHANGE SELL"
 
 
 @enum.unique
@@ -173,6 +185,7 @@ class OrderType(str, enum.Enum):
     REL = "REL"
     MIT = "MIT"
     LIT = "LIT"
+    SNAPMID = "SNAPMID"
 
 @enum.unique
 class Reorg(str, enum.Enum):
@@ -266,6 +279,7 @@ ENUMS = [
     CashAction,
     Code,
     AssetClass,
+    SubCategory,
     TradeType,
     BuySell,
     OpenClose,

{ibflex-1.1 → ibflex-1.2}/ibflex/parser.py

@@ -132,11 +132,15 @@ def parse_data_element(
 
     #  FlexQueryResponse & FlexStatement are the only data elements
     #  that contain other data elements.
-    contained_elements = {
-        child.tag: parsed
-        for child in elem
-        if (parsed := parse_element(child)) is not None
-    }
+    #  Skip sections the class has no field for (e.g. a statement section IB
+    #  added after this release), with a warning instead of failing the parse.
+    contained_elements = {}
+    for child in elem:
+        if child.tag not in Class.__dataclass_fields__:
+            warnings.warn(f"{Class.__name__} has no attribute '{child.tag}'; skipping")
+            continue
+        if (parsed := parse_element(child)) is not None:
+            contained_elements[child.tag] = parsed
     if contained_elements:
         assert elem.tag in ("FlexQueryResponse", "FlexStatement")
         attrs.update(contained_elements)
@@ -295,7 +299,7 @@ def prep_code_sequence(value: str) -> Iterable[enums.Code]:
     """
     sep = ";" if ";" in value else ","
     return (
-        enums.Code(v)
+        convert_enum(Type=enums.Code, value=v)
         for v in value.split(sep)
         if v
     ) if value != "" else []
@@ -373,7 +377,14 @@ def convert_enum(Type, value):
     #  Enums bind custom names to the IB-supplied values.
     #  To convert, just do a by-value lookup on the incoming string.
     #  https://docs.python.org/3/library/enum.html#programmatic-access-to-enumeration-members-and-their-attributes
-    return Type(value) if value != "" else None
+    try:
+        return Type(value) if value != "" else None
+    except ValueError:
+        warnings.warn(
+            f"{value!r} is not a valid {Type.__name__}."
+            " Possibly a new update from IBKR; passing through as a plain string"
+        )
+        return value
 
 
 ATTRIB_CONVERTERS = {

{ibflex-1.1 → ibflex-1.2}/ibflex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ibflex
-Version: 1.1
+Version: 1.2
 Summary: Parse Interactive Brokers Flex XML reports and convert to Python types
 Author-email: Christopher Singley <csingley@gmail.com>
 License-Expression: MIT
@@ -148,6 +148,16 @@ them:
     In [5]: response[:215]
     Out[5]: b'<FlexQueryResponse queryName="Get Everything" type="AF">\n<FlexStatements count="1">\n<FlexStatement accountId="U111111" fromDate="2018-01-01" toDate="2018-01-31" period="LastMonth" whenGenerated="2018-02-01;211353">\n'
 
+You can override the report's date range per request with ``period`` (the
+``p`` parameter - a lookback in days, up to 365) or ``fd``/``td`` (explicit
+``yyyymmdd`` from/to dates, given together); the two forms are mutually
+exclusive. This is useful because the v3 Flex Web Service may not honor a
+query's saved "Last N Calendar Days" period:
+
+.. code:: python
+
+    In [6]: response = client.download(token, query_id, period=90)
+
 
 ``pip install ibflex[web]`` also installs a ``flexget`` console script:
 
@@ -156,6 +166,24 @@ them:
     $ flexget -t 111111111111111111111111 -q 111111 > 2018-01_ibkr.xml
 
 
+Releasing
+=========
+Releases are published to PyPI automatically via GitHub Actions using
+`trusted publishing`_ (OIDC).  No API tokens are needed.
+
+To cut a release:
+
+1. Bump the version in ``pyproject.toml`` and ``ibflex/__version__.py``.
+2. Commit, push to ``master``.
+3. Create a GitHub release with a tag matching the version (e.g. ``v1.1``).
+
+The ``Publish to PyPI`` workflow will build and upload the package.
+
+Any repository collaborator who can create a GitHub release **and** has access
+to the ``pypi`` deployment environment can publish.  Environment access is
+managed under Settings → Environments → pypi.
+
+
 Resources
 =========
 * Interactive Brokers `Activity Flex Query Reference`_
@@ -168,5 +196,6 @@ Resources
 .. _Interactive Brokers account management: https://www.interactivebrokers.com/sso/Login
 .. _Activity Flex Query Reference: https://www.interactivebrokers.com/en/software/reportguide/reportguide.htm#reportguide/activity_flex_query_reference.htm
 .. _FlexWeb Service Reference: https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm
+.. _trusted publishing: https://docs.pypi.org/trusted-publishers/
 .. _capgains: https://github.com/csingley/capgains
 .. _ib-flex-analyzer: https://github.com/wesm/ib-flex-analyzer

{ibflex-1.1 → ibflex-1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ibflex"
-version = "1.1"
+version = "1.2"
 description = "Parse Interactive Brokers Flex XML reports and convert to Python types"
 readme = "README.rst"
 license = "MIT"

{ibflex-1.1 → ibflex-1.2}/tests/test_client.py

@@ -14,7 +14,7 @@ RESPONSE_SUCCESS = (
     '<FlexStatementResponse timestamp="28 August, 2012 10:37 AM EDT">'
     '<Status>Success</Status>'
     '<ReferenceCode>1234567890</ReferenceCode>'
-    '<Url>https://gdcdyn.interactivebrokers.com/AccountManagement/FlexWebService/GetStatement</Url>'
+    '<Url>https://ndcdyn.interactivebrokers.com/AccountManagement/FlexWebService/GetStatement</Url>'
     '</FlexStatementResponse>'
 )
 
@@ -119,6 +119,15 @@ class RequestStatementTestCase(unittest.TestCase):
         self.assertEqual(output.Url, client.STMT_URL)
 
 
+class ParseStmtResponseTestCase(unittest.TestCase):
+    def test_lowercase_url_element(self):
+        response = Mock()
+        response.content = RESPONSE_SUCCESS.replace("Url>", "url>").encode()
+        output = client.parse_stmt_response(response)
+        self.assertIsInstance(output, client.StatementAccess)
+        self.assertEqual(output.Url, client.STMT_URL)
+
+
 @patch("requests.get", side_effect=mock_response)
 class DownloadTestCase(unittest.TestCase):
     def test_request_statement(self, mock_requests_get: Mock):
@@ -150,5 +159,85 @@ class DownloadTestCase(unittest.TestCase):
         self.assertIsInstance(response, Types.FlexQueryResponse)
 
 
+@patch("requests.get", side_effect=mock_response)
+class DateRangeOverrideTestCase(unittest.TestCase):
+    def test_period_override_sent_on_send_request_only(self, mock_requests_get):
+        #  `period` is forwarded to SendRequest as `p`, but the GetStatement
+        #  poll must NOT carry it.
+        output = client.download(
+            token="DEADBEEF",
+            query_id="0987654321",
+            period=90,
+        )
+        self.assertIsInstance(output, bytes)
+
+        self.assertEqual(
+            mock_requests_get.call_args_list,
+            [
+                call(
+                    client.REQUEST_URL,
+                    params={
+                        "v": "3", "t": "DEADBEEF", "q": "0987654321", "p": "90",
+                    },
+                    headers={"user-agent": "Java"},
+                    timeout=5,
+                ),
+                call(
+                    client.STMT_URL,
+                    params={"v": "3", "t": "DEADBEEF", "q": "1234567890"},
+                    headers={"user-agent": "Java"},
+                    timeout=5,
+                ),
+            ],
+        )
+
+    def test_from_to_date_override(self, mock_requests_get):
+        client.request_statement(
+            token="DEADBEEF",
+            query_id="0987654321",
+            fd="20260101",
+            td="20260331",
+        )
+
+        mock_requests_get.assert_called_once_with(
+            client.REQUEST_URL,
+            params={
+                "v": "3", "t": "DEADBEEF", "q": "0987654321",
+                "fd": "20260101", "td": "20260331",
+            },
+            headers={"user-agent": "Java"},
+            timeout=5,
+        )
+
+    def test_period_and_dates_are_mutually_exclusive(self, mock_requests_get):
+        with self.assertRaises(ValueError):
+            client.download(
+                token="DEADBEEF",
+                query_id="0987654321",
+                period=90,
+                fd="20260101",
+                td="20260131",
+            )
+        mock_requests_get.assert_not_called()
+
+    def test_fd_and_td_must_be_given_together(self, mock_requests_get):
+        for kwargs in ({"fd": "20260101"}, {"td": "20260131"}):
+            with self.assertRaises(ValueError):
+                client.download(
+                    token="DEADBEEF", query_id="0987654321", **kwargs
+                )
+        mock_requests_get.assert_not_called()
+
+    def test_no_override_leaves_params_unchanged(self, mock_requests_get):
+        client.request_statement(token="DEADBEEF", query_id="0987654321")
+
+        mock_requests_get.assert_called_once_with(
+            client.REQUEST_URL,
+            params={"v": "3", "t": "DEADBEEF", "q": "0987654321"},
+            headers={"user-agent": "Java"},
+            timeout=5,
+        )
+
+
 if __name__ == '__main__':
     unittest.main(verbosity=3)

{ibflex-1.1 → ibflex-1.2}/tests/test_parser.py

@@ -297,9 +297,13 @@ class ParseElementAttrTestCase(unittest.TestCase):
                 ("foobar", TestEnum.BAR)
             )
 
-            #  Illegal enum values raise FlexParserError
-            with self.assertRaises(parser.FlexParserError):
-                parser.parse_element_attr(TestClass, "foobar", "3")
+            #  Unknown enum values (e.g. new categories added by IBKR
+            #  upstream) pass through as plain strings with a warning.
+            with self.assertWarns(UserWarning):
+                self.assertEqual(
+                    parser.parse_element_attr(TestClass, "foobar", "3"),
+                    ("foobar", "3")
+                )
 
     def testCurrency(self):
         """parse_element_attr() checks attributes named 'currency' vs ISO4217.