Source code for ib_insync.contract

"""Financial instrument types used by Interactive Brokers."""

import datetime as dt
from dataclasses import dataclass, field
from typing import List, NamedTuple, Optional

import ib_insync.util as util


[docs] @dataclass class Contract: """ ``Contract(**kwargs)`` can create any contract using keyword arguments. To simplify working with contracts, there are also more specialized contracts that take optional positional arguments. Some examples:: Contract(conId=270639) Stock('AMD', 'SMART', 'USD') Stock('INTC', 'SMART', 'USD', primaryExchange='NASDAQ') Forex('EURUSD') CFD('IBUS30') Future('ES', '20180921', 'GLOBEX') Option('SPY', '20170721', 240, 'C', 'SMART') Bond(secIdType='ISIN', secId='US03076KAA60') Crypto('BTC', 'PAXOS', 'USD') Args: conId (int): The unique IB contract identifier. symbol (str): The contract (or its underlying) symbol. secType (str): The security type: * 'STK' = Stock (or ETF) * 'OPT' = Option * 'FUT' = Future * 'IND' = Index * 'FOP' = Futures option * 'CASH' = Forex pair * 'CFD' = CFD * 'BAG' = Combo * 'WAR' = Warrant * 'BOND' = Bond * 'CMDTY' = Commodity * 'NEWS' = News * 'FUND' = Mutual fund * 'CRYPTO' = Crypto currency * 'EVENT' = Bet on an event lastTradeDateOrContractMonth (str): The contract's last trading day or contract month (for Options and Futures). Strings with format YYYYMM will be interpreted as the Contract Month whereas YYYYMMDD will be interpreted as Last Trading Day. strike (float): The option's strike price. right (str): Put or Call. Valid values are 'P', 'PUT', 'C', 'CALL', or '' for non-options. multiplier (str): The instrument's multiplier (i.e. options, futures). exchange (str): The destination exchange. currency (str): The underlying's currency. localSymbol (str): The contract's symbol within its primary exchange. For options, this will be the OCC symbol. primaryExchange (str): The contract's primary exchange. For smart routed contracts, used to define contract in case of ambiguity. Should be defined as native exchange of contract, e.g. ISLAND for MSFT. For exchanges which contain a period in name, will only be part of exchange name prior to period, i.e. ENEXT for ENEXT.BE. tradingClass (str): The trading class name for this contract. Available in TWS contract description window as well. For example, GBL Dec '13 future's trading class is "FGBL". includeExpired (bool): If set to true, contract details requests and historical data queries can be performed pertaining to expired futures contracts. Expired options or other instrument types are not available. secIdType (str): Security identifier type. Examples for Apple: * secIdType='ISIN', secId='US0378331005' * secIdType='CUSIP', secId='037833100' secId (str): Security identifier. comboLegsDescription (str): Description of the combo legs. comboLegs (List[ComboLeg]): The legs of a combined contract definition. deltaNeutralContract (DeltaNeutralContract): Delta and underlying price for Delta-Neutral combo orders. """ secType: str = '' conId: int = 0 symbol: str = '' lastTradeDateOrContractMonth: str = '' strike: float = 0.0 right: str = '' multiplier: str = '' exchange: str = '' primaryExchange: str = '' currency: str = '' localSymbol: str = '' tradingClass: str = '' includeExpired: bool = False secIdType: str = '' secId: str = '' description: str = '' issuerId: str = '' comboLegsDescrip: str = '' comboLegs: List['ComboLeg'] = field(default_factory=list) deltaNeutralContract: Optional['DeltaNeutralContract'] = None
[docs] @staticmethod def create(**kwargs) -> 'Contract': """ Create and a return a specialized contract based on the given secType, or a general Contract if secType is not given. """ secType = kwargs.get('secType', '') cls = { '': Contract, 'STK': Stock, 'OPT': Option, 'FUT': Future, 'CONTFUT': ContFuture, 'CASH': Forex, 'IND': Index, 'CFD': CFD, 'BOND': Bond, 'CMDTY': Commodity, 'FOP': FuturesOption, 'FUND': MutualFund, 'WAR': Warrant, 'IOPT': Warrant, 'BAG': Bag, 'CRYPTO': Crypto, 'NEWS': Contract, 'EVENT': Contract, }.get(secType, Contract) if cls is not Contract: kwargs.pop('secType', '') return cls(**kwargs)
[docs] def isHashable(self) -> bool: """ See if this contract can be hashed by conId. Note: Bag contracts always get conId=28812380, so they're not hashable. """ return bool( self.conId and self.conId != 28812380 and self.secType != 'BAG')
def __eq__(self, other): return ( isinstance(other, Contract) and ( self.conId and self.conId == other.conId or util.dataclassAsDict(self) == util.dataclassAsDict(other))) def __hash__(self): if not self.isHashable(): raise ValueError(f'Contract {self} can\'t be hashed') if self.secType == 'CONTFUT': # CONTFUT gets the same conId as the front contract, invert it here h = -self.conId else: h = self.conId return h def __repr__(self): attrs = util.dataclassNonDefaults(self) if self.__class__ is not Contract: attrs.pop('secType', '') clsName = self.__class__.__qualname__ kwargs = ', '.join(f'{k}={v!r}' for k, v in attrs.items()) return f'{clsName}({kwargs})' __str__ = __repr__
[docs] class Stock(Contract): def __init__( self, symbol: str = '', exchange: str = '', currency: str = '', **kwargs): """ Stock contract. Args: symbol: Symbol name. exchange: Destination exchange. currency: Underlying currency. """ Contract.__init__( self, secType='STK', symbol=symbol, exchange=exchange, currency=currency, **kwargs)
[docs] class Option(Contract): def __init__( self, symbol: str = '', lastTradeDateOrContractMonth: str = '', strike: float = 0.0, right: str = '', exchange: str = '', multiplier: str = '', currency: str = '', **kwargs): """ Option contract. Args: symbol: Symbol name. lastTradeDateOrContractMonth: The option's last trading day or contract month. * YYYYMM format: To specify last month * YYYYMMDD format: To specify last trading day strike: The option's strike price. right: Put or call option. Valid values are 'P', 'PUT', 'C' or 'CALL'. exchange: Destination exchange. multiplier: The contract multiplier. currency: Underlying currency. """ Contract.__init__( self, 'OPT', symbol=symbol, lastTradeDateOrContractMonth=lastTradeDateOrContractMonth, strike=strike, right=right, exchange=exchange, multiplier=multiplier, currency=currency, **kwargs)
[docs] class Future(Contract): def __init__( self, symbol: str = '', lastTradeDateOrContractMonth: str = '', exchange: str = '', localSymbol: str = '', multiplier: str = '', currency: str = '', **kwargs): """ Future contract. Args: symbol: Symbol name. lastTradeDateOrContractMonth: The option's last trading day or contract month. * YYYYMM format: To specify last month * YYYYMMDD format: To specify last trading day exchange: Destination exchange. localSymbol: The contract's symbol within its primary exchange. multiplier: The contract multiplier. currency: Underlying currency. """ Contract.__init__( self, 'FUT', symbol=symbol, lastTradeDateOrContractMonth=lastTradeDateOrContractMonth, exchange=exchange, localSymbol=localSymbol, multiplier=multiplier, currency=currency, **kwargs)
[docs] class ContFuture(Contract): def __init__( self, symbol: str = '', exchange: str = '', localSymbol: str = '', multiplier: str = '', currency: str = '', **kwargs): """ Continuous future contract. Args: symbol: Symbol name. exchange: Destination exchange. localSymbol: The contract's symbol within its primary exchange. multiplier: The contract multiplier. currency: Underlying currency. """ Contract.__init__( self, 'CONTFUT', symbol=symbol, exchange=exchange, localSymbol=localSymbol, multiplier=multiplier, currency=currency, **kwargs)
[docs] class Forex(Contract): def __init__( self, pair: str = '', exchange: str = 'IDEALPRO', symbol: str = '', currency: str = '', **kwargs): """ Foreign exchange currency pair. Args: pair: Shortcut for specifying symbol and currency, like 'EURUSD'. exchange: Destination exchange. symbol: Base currency. currency: Quote currency. """ if pair: assert len(pair) == 6 symbol = symbol or pair[:3] currency = currency or pair[3:] Contract.__init__( self, 'CASH', symbol=symbol, exchange=exchange, currency=currency, **kwargs) def __repr__(self): attrs = util.dataclassNonDefaults(self) attrs.pop('secType') s = 'Forex(' if 'symbol' in attrs and 'currency' in attrs: pair = attrs.pop('symbol') pair += attrs.pop('currency') s += "'" + pair + "'" + (", " if attrs else "") s += ', '.join(f'{k}={v!r}' for k, v in attrs.items()) s += ')' return s __str__ = __repr__
[docs] def pair(self) -> str: """Short name of pair.""" return self.symbol + self.currency
[docs] class Index(Contract): def __init__( self, symbol: str = '', exchange: str = '', currency: str = '', **kwargs): """ Index. Args: symbol: Symbol name. exchange: Destination exchange. currency: Underlying currency. """ Contract.__init__( self, 'IND', symbol=symbol, exchange=exchange, currency=currency, **kwargs)
[docs] class CFD(Contract): def __init__( self, symbol: str = '', exchange: str = '', currency: str = '', **kwargs): """ Contract For Difference. Args: symbol: Symbol name. exchange: Destination exchange. currency: Underlying currency. """ Contract.__init__( self, 'CFD', symbol=symbol, exchange=exchange, currency=currency, **kwargs)
[docs] class Commodity(Contract): def __init__( self, symbol: str = '', exchange: str = '', currency: str = '', **kwargs): """ Commodity. Args: symbol: Symbol name. exchange: Destination exchange. currency: Underlying currency. """ Contract.__init__( self, 'CMDTY', symbol=symbol, exchange=exchange, currency=currency, **kwargs)
[docs] class Bond(Contract): def __init__(self, **kwargs): """Bond.""" Contract.__init__(self, 'BOND', **kwargs)
[docs] class FuturesOption(Contract): def __init__( self, symbol: str = '', lastTradeDateOrContractMonth: str = '', strike: float = 0.0, right: str = '', exchange: str = '', multiplier: str = '', currency: str = '', **kwargs): """ Option on a futures contract. Args: symbol: Symbol name. lastTradeDateOrContractMonth: The option's last trading day or contract month. * YYYYMM format: To specify last month * YYYYMMDD format: To specify last trading day strike: The option's strike price. right: Put or call option. Valid values are 'P', 'PUT', 'C' or 'CALL'. exchange: Destination exchange. multiplier: The contract multiplier. currency: Underlying currency. """ Contract.__init__( self, 'FOP', symbol=symbol, lastTradeDateOrContractMonth=lastTradeDateOrContractMonth, strike=strike, right=right, exchange=exchange, multiplier=multiplier, currency=currency, **kwargs)
[docs] class MutualFund(Contract): def __init__(self, **kwargs): """Mutual fund.""" Contract.__init__(self, 'FUND', **kwargs)
[docs] class Warrant(Contract): def __init__(self, **kwargs): """Warrant option.""" Contract.__init__(self, 'WAR', **kwargs)
[docs] class Bag(Contract): def __init__(self, **kwargs): """Bag contract.""" Contract.__init__(self, 'BAG', **kwargs)
[docs] class Crypto(Contract): def __init__( self, symbol: str = '', exchange: str = '', currency: str = '', **kwargs): """ Crypto currency contract. Args: symbol: Symbol name. exchange: Destination exchange. currency: Underlying currency. """ Contract.__init__( self, secType='CRYPTO', symbol=symbol, exchange=exchange, currency=currency, **kwargs)
[docs] class TagValue(NamedTuple): tag: str value: str
[docs] @dataclass class ComboLeg: conId: int = 0 ratio: int = 0 action: str = '' exchange: str = '' openClose: int = 0 shortSaleSlot: int = 0 designatedLocation: str = '' exemptCode: int = -1
[docs] @dataclass class DeltaNeutralContract: conId: int = 0 delta: float = 0.0 price: float = 0.0
[docs] class TradingSession(NamedTuple): start: dt.datetime end: dt.datetime
[docs] @dataclass class ContractDetails: contract: Optional[Contract] = None marketName: str = '' minTick: float = 0.0 orderTypes: str = '' validExchanges: str = '' priceMagnifier: int = 0 underConId: int = 0 longName: str = '' contractMonth: str = '' industry: str = '' category: str = '' subcategory: str = '' timeZoneId: str = '' tradingHours: str = '' liquidHours: str = '' evRule: str = '' evMultiplier: int = 0 mdSizeMultiplier: int = 1 # obsolete aggGroup: int = 0 underSymbol: str = '' underSecType: str = '' marketRuleIds: str = '' secIdList: List[TagValue] = field(default_factory=list) realExpirationDate: str = '' lastTradeTime: str = '' stockType: str = '' minSize: float = 0.0 sizeIncrement: float = 0.0 suggestedSizeIncrement: float = 0.0 # minCashQtySize: float = 0.0 cusip: str = '' ratings: str = '' descAppend: str = '' bondType: str = '' couponType: str = '' callable: bool = False putable: bool = False coupon: float = 0 convertible: bool = False maturity: str = '' issueDate: str = '' nextOptionDate: str = '' nextOptionType: str = '' nextOptionPartial: bool = False notes: str = ''
[docs] def tradingSessions(self) -> List[TradingSession]: return self._parseSessions(self.tradingHours)
[docs] def liquidSessions(self) -> List[TradingSession]: return self._parseSessions(self.liquidHours)
def _parseSessions(self, s: str) -> List[TradingSession]: tz = util.ZoneInfo(self.timeZoneId) sessions = [] for sess in s.split(';'): if not sess or 'CLOSED' in sess: continue sessions.append(TradingSession(*[ dt.datetime.strptime(t, '%Y%m%d:%H%M').replace(tzinfo=tz) for t in sess.split('-')])) return sessions
[docs] @dataclass class ContractDescription: contract: Optional[Contract] = None derivativeSecTypes: List[str] = field(default_factory=list)
[docs] @dataclass class ScanData: rank: int contractDetails: ContractDetails distance: str benchmark: str projection: str legsStr: str