Implement ability to customize default values

This is a fairly big change for usability, but it shouldn't change
behavior unless you opt-in to new values yourself.

IBKR uses a strictly typed API where integer fields can only send
integers and float fields can only send floats and string fields can
only send strings.

This is why, in some places, IBKR uses FLOAT_MAX of
"1.7976931348623157e+308" to mean "no data available" while in other
places IBKR uses "price=-1, size=0" to mean "no data available," and
historically ib_insync has also uses `nan` to mean "field is not
initialized with API data yet."

So there are potentially 4 different ways to check if data is not
actually real data. This causes more problems when people are being lazy
(and who isn't?) when just using price data, but price=-1 when price is
missing (and many negative prices _are_ valid when using credit
spreads), so it can cause actual problems.

Now we have a way to request different defaults.

The `IB()` constructor now takes an optional argument as:

```python
ib = IB(IBDefaults(
    emptyPrice=None,
    emptySize=None,
    unset=None,
    timezone=pytz.timezone("US/Eastern")
)
```

Providing an `IBDefaults()` object will overwrite the IBKR defaults of
`emptyPrice=-1, emptySize=0, unset=nan, timezone=datetime.timezone.utc`
with your own defaults.

You can technically set any value there, but it's your own fault if you
set `emptySize=3` or something awful on your own.

You can be even more explicit and define your _own_ empty objects or
enums to represent empty data too. Just make sure if you do use things
like `None` for price, you run your checks as `price is not None`
because for certain spread opportunities, prices _can_ be valid limit
prices to execute (so `if price:` would fail a valid price of `0`).

This is currently still undergoing more testing, but it works so far for
me (and it's nicer having timestamps in my own exchange timezone instead
of utc when printing tickers and order event logs everywhere).

We may add another couple default types to allow removing `UNSET_DOUBLE`
from showing up in user API output anywhere too.

Author: mattsta

ib_async/__init__.py

@@ -54,6 +54,7 @@
     HistoricalTick,
     HistoricalTickBidAsk,
     HistoricalTickLast,
+    IBDefaults,
     MktDepthData,
     NewsArticle,
     NewsBulletin,

ib_async/decoder.py

@@ -465,7 +465,7 @@ def execDetails(self, fields):
             if tz:
                 time = time.replace(tzinfo=ZoneInfo(str(tz)))
 
-        ex.time = time.astimezone(timezone.utc)
+        ex.time = time.astimezone(self.wrapper.defaultTimezone)
         self.wrapper.execDetails(int(reqId), c, ex)
 
     def historicalData(self, fields):
@@ -779,7 +779,7 @@ def historicalTicks(self, fields):
             get()
             price = float(get())
             size = float(get())
-            dt = datetime.fromtimestamp(time, timezone.utc)
+            dt = datetime.fromtimestamp(time, self.wrapper.defaultTimezone)
             ticks.append(HistoricalTick(dt, price, size))
 
         done = bool(int(get()))
@@ -800,7 +800,7 @@ def historicalTicksBidAsk(self, fields):
             priceAsk = float(get())
             sizeBid = float(get())
             sizeAsk = float(get())
-            dt = datetime.fromtimestamp(time, timezone.utc)
+            dt = datetime.fromtimestamp(time, self.wrapper.defaultTimezone)
             ticks.append(
                 HistoricalTickBidAsk(dt, attrib, priceBid, priceAsk, sizeBid, sizeAsk)
             )
@@ -821,7 +821,7 @@ def historicalTicksLast(self, fields):
             size = float(get())
             exchange = get()
             specialConditions = get()
-            dt = datetime.fromtimestamp(time, timezone.utc)
+            dt = datetime.fromtimestamp(time, self.wrapper.defaultTimezone)
             ticks.append(
                 HistoricalTickLast(dt, attrib, price, size, exchange, specialConditions)
             )
@@ -914,6 +914,7 @@ def openOrder(self, fields):
             o.faPercentage,
             *fields,
         ) = fields
+
         if self.serverVersion < 177:
             o.faProfile, *fields = fields
 

ib_async/ib.py

@@ -23,6 +23,7 @@
     HistogramData,
     HistoricalNews,
     HistoricalSchedule,
+    IBDefaults,
     NewsArticle,
     NewsBulletin,
     NewsProvider,
@@ -271,9 +272,9 @@ class IB:
     MaxSyncedSubAccounts: int = 50
     TimezoneTWS: str = ""
 
-    def __init__(self):
+    def __init__(self, defaults: IBDefaults = IBDefaults()):
         self._createEvents()
-        self.wrapper = Wrapper(self)
+        self.wrapper = Wrapper(self, defaults=defaults)
         self.client = Client(self.wrapper)
         self.errorEvent += self._onError
         self.client.apiEnd += self.disconnectedEvent
@@ -779,7 +780,7 @@ def placeOrder(self, contract: Contract, order: Order) -> Trade:
         """
         orderId = order.orderId or self.client.getReqId()
         self.client.placeOrder(orderId, contract, order)
-        now = datetime.datetime.now(datetime.timezone.utc)
+        now = datetime.datetime.now(self.wrapper.defaultTimezone)
         key = self.wrapper.orderKey(self.wrapper.clientId, orderId, order.permId)
         trade = self.wrapper.trades.get(key)
         if trade:
@@ -814,7 +815,7 @@ def cancelOrder(
             manualCancelOrderTime: For audit trail.
         """
         self.client.cancelOrder(order.orderId, manualCancelOrderTime)
-        now = datetime.datetime.now(datetime.timezone.utc)
+        now = datetime.datetime.now(self.wrapper.defaultTimezone)
         key = self.wrapper.orderKey(order.clientId, order.orderId, order.permId)
         trade = self.wrapper.trades.get(key)
         if trade:

ib_async/objects.py

@@ -1,8 +1,8 @@
 """Object hierarchy."""
 
 from dataclasses import dataclass, field
-from datetime import date as date_, datetime
-from typing import List, NamedTuple, Optional, Union
+from datetime import date as date_, datetime, timezone
+from typing import Any, List, NamedTuple, Optional, Union
 
 from eventkit import Event
 
@@ -488,3 +488,18 @@ class FundamentalRatios(DynamicObject):
     """
 
     pass
+
+
+@dataclass
+class IBDefaults:
+    """A simple way to provide default values when populating API data."""
+
+    # optionally replace IBKR using -1 price and 0 size when quotes don't exist
+    emptyPrice: Any = -1
+    emptySize: Any = 0
+
+    # optionally replace ib_async default for all instance variable values before popualted from API updates
+    unset: Any = nan
+
+    # optionally change the timezone used for log history events in objects (no impact on orders or data processing)
+    timezone: timezone = timezone.utc

ib_async/order.py

@@ -163,8 +163,10 @@ def __repr__(self):
         attrs = dataclassNonDefaults(self)
         if self.__class__ is not Order:
             attrs.pop("orderType", None)
+
         if not self.softDollarTier:
             attrs.pop("softDollarTier")
+
         clsName = self.__class__.__qualname__
         kwargs = ", ".join(f"{k}={v!r}" for k, v in attrs.items())
         return f"{clsName}({kwargs})"

ib_async/ticker.py

@@ -2,7 +2,7 @@
 
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import ClassVar, List, Optional, Union
+from typing import Any, ClassVar, List, Optional, Union
 
 from eventkit import Event, Op
 
@@ -11,6 +11,7 @@
     DOMLevel,
     Dividends,
     FundamentalRatios,
+    IBDefaults,
     MktDepthData,
     OptionComputation,
     TickByTickAllLast,
@@ -48,8 +49,8 @@ class Ticker:
 
     events: ClassVar = ("updateEvent",)
 
-    contract: Optional[Contract] = None
-    time: Optional[datetime] = None
+    contract: Contract | None = None
+    time: datetime | None = None
     marketDataType: int = 1
     minTick: float = nan
     bid: float = nan
@@ -129,8 +130,72 @@ class Ticker:
     bboExchange: str = ""
     snapshotPermissions: int = 0
 
+    defaults: IBDefaults = field(default_factory=IBDefaults)
+    created: bool = False
+
     def __post_init__(self):
-        self.updateEvent = TickerUpdateEvent("updateEvent")
+        # when copying a dataclass, the __post_init__ runs again, so we
+        # want to make sure if this was _already_ created, we don't overwrite
+        # everything with _another_ post_init clear.
+        if not self.created:
+            self.updateEvent = TickerUpdateEvent("updateEvent")
+            self.minTick = self.defaults.unset
+            self.bid = self.defaults.unset
+            self.bidSize = self.defaults.unset
+            self.ask = self.defaults.unset
+            self.askSize = self.defaults.unset
+            self.last = self.defaults.unset
+            self.lastSize = self.defaults.unset
+            self.prevBid = self.defaults.unset
+            self.prevBidSize = self.defaults.unset
+            self.prevAsk = self.defaults.unset
+            self.prevAskSize = self.defaults.unset
+            self.prevLast = self.defaults.unset
+            self.prevLastSize = self.defaults.unset
+            self.volume = self.defaults.unset
+            self.open = self.defaults.unset
+            self.high = self.defaults.unset
+            self.low = self.defaults.unset
+            self.close = self.defaults.unset
+            self.vwap = self.defaults.unset
+            self.low13week = self.defaults.unset
+            self.high13week = self.defaults.unset
+            self.low26week = self.defaults.unset
+            self.high26week = self.defaults.unset
+            self.low52week = self.defaults.unset
+            self.high52week = self.defaults.unset
+            self.bidYield = self.defaults.unset
+            self.askYield = self.defaults.unset
+            self.lastYield = self.defaults.unset
+            self.markPrice = self.defaults.unset
+            self.halted = self.defaults.unset
+            self.rtHistVolatility = self.defaults.unset
+            self.rtVolume = self.defaults.unset
+            self.rtTradeVolume = self.defaults.unset
+            self.avVolume = self.defaults.unset
+            self.tradeCount = self.defaults.unset
+            self.tradeRate = self.defaults.unset
+            self.volumeRate = self.defaults.unset
+            self.volumeRate3Min = self.defaults.unset
+            self.volumeRate5Min = self.defaults.unset
+            self.volumeRate10Min = self.defaults.unset
+            self.shortable = self.defaults.unset
+            self.shortableShares = self.defaults.unset
+            self.indexFuturePremium = self.defaults.unset
+            self.futuresOpenInterest = self.defaults.unset
+            self.putOpenInterest = self.defaults.unset
+            self.callOpenInterest = self.defaults.unset
+            self.putVolume = self.defaults.unset
+            self.callVolume = self.defaults.unset
+            self.avOptionVolume = self.defaults.unset
+            self.histVolatility = self.defaults.unset
+            self.impliedVolatility = self.defaults.unset
+            self.auctionVolume = self.defaults.unset
+            self.auctionPrice = self.defaults.unset
+            self.auctionImbalance = self.defaults.unset
+            self.regulatoryImbalance = self.defaults.unset
+
+            self.created = True
 
     def __eq__(self, other):
         return self is other
@@ -141,23 +206,29 @@ def __hash__(self):
     __repr__ = dataclassRepr
     __str__ = dataclassRepr
 
+    def isUnset(self, value) -> bool:
+        # if default value is nan and value is nan, it is unset.
+        # else, if value matches default value, it is unset.
+        dev = self.defaults.unset
+        return (dev != dev and value != value) or (value == dev)
+
     def hasBidAsk(self) -> bool:
         """See if this ticker has a valid bid and ask."""
         return (
             self.bid != -1
-            and not isNan(self.bid)
+            and not self.isUnset(self.bid)
             and self.bidSize > 0
             and self.ask != -1
-            and not isNan(self.ask)
+            and not self.isUnset(self.ask)
             and self.askSize > 0
         )
 
     def midpoint(self) -> float:
         """
-        Return average of bid and ask, or NaN if no valid bid and ask
+        Return average of bid and ask, or defaults.unset if no valid bid and ask
         are available.
         """
-        return (self.bid + self.ask) * 0.5 if self.hasBidAsk() else nan
+        return (self.bid + self.ask) * 0.5 if self.hasBidAsk() else self.defaults.unset
 
     def marketPrice(self) -> float:
         """
@@ -173,6 +244,7 @@ def marketPrice(self) -> float:
                 price = self.midpoint()
         else:
             price = self.last
+
         return price
 
 
@@ -302,8 +374,10 @@ def on_source(self, time, price, size):
         if not self.bars:
             return
         bar = self.bars[-1]
+
         if isNan(bar.open):
             bar.open = bar.high = bar.low = price
+
         bar.high = max(bar.high, price)
         bar.low = min(bar.low, price)
         bar.close = price
@@ -314,10 +388,12 @@ def on_source(self, time, price, size):
     def _on_timer(self, time):
         if self.bars:
             bar = self.bars[-1]
-            if isNan(bar.close) and len(self.bars) > 1:
+            if self.isUnset(bar.close) and len(self.bars) > 1:
                 bar.open = bar.high = bar.low = bar.close = self.bars[-2].close
+
             self.bars.updateEvent.emit(self.bars, True)
             self.emit(bar)
+
         self.bars.append(Bar(time))
 
     def _on_timer_done(self, timer):

ib_async/util.py

@@ -101,7 +101,8 @@ def dataclassNonDefaults(obj) -> dict:
     return {
         field.name: value
         for field, value in zip(fields(obj), values)
-        if value != field.default
+        if value is not None
+        and value != field.default
         and value == value
         and not (
             (isinstance(value, list) and value == [])