Basic Usage¶

There are three levels in the dxfeed package. The lowest is the C API library, the highest is Python wrapper classes. Cython level in the middle aims to connect these two. Here we are going to look into Python level.

Python level, in its turn, mainly consists of three class types:

Endpoint
Subscription
EventHandler

The Endpoint is responsible for connection management and creating dependent classes, for example Subscription. One Endpoint may have several different Subscriptions, but each Subscription is related to one Endpoint.

Subscription class sets the type of subscription (stream or timed), the type of events (e.g. Trade, Candle), etc.

After you specified the data you want to receive, you have to specify how to process upcoming events. This is where the EventHandler class and its children come into play. Every time an event arrives Cython event listener will call self.update(event) method. You have to inherit from the EventHandler class and redefine the update method. Or you may use DefaultHandler which stores upcoming data in deque of the length 100k.

Import package¶

import dxfeed as dx
from datetime import datetime  # for timed subscription

Configure and create connection with Endpoint class¶

Create instance of Endpoint class which will connect provided address.

endpoint = dx.Endpoint('demo.dxfeed.com:7300')

Endpoint instance contains information about the connection, e.g. connection address or status

print(f'Connected address: {endpoint.address}')
print(f'Connection status: {endpoint.connection_status}')

Connected address: demo.dxfeed.com:7300
Connection status: Connected and authorized

Configure and create subscription¶

You should specify event type. For timed subscription (conflated stream) you should also provide time to start subscription from.

trade_sub = endpoint.create_subscription('Trade')

Set event handler - class that process incoming events. Here we use default one

trade_handler = dx.DefaultHandler()
trade_sub.set_event_handler(trade_handler);

Add tikers you want to recieve events for

trade_sub = trade_sub.add_symbols(['C', 'IBM'])

For timed subscription you should provide either datetime object or string. String might be incomlete, in this case you will get warning with how your provided date parsed automatically. For Candle event type along with base symbol, you should specify an aggregation period. You can also set price type. More details: https://kb.dxfeed.com/display/DS/REST+API#RESTAPI-Candlesymbols.

tns_sub = endpoint.create_subscription('TimeAndSale', date_time=datetime.now()) \
                  .add_symbols(['AMZN'])

candle_sub = endpoint.create_subscription('Candle', date_time='2020-04-16 13:05')
candle_sub = candle_sub.add_symbols(['AAPL{=d}', 'MSFT{=d}'])

c:\job\python-api\dxfeed\wrappers\class_utils.py:38: UserWarning: Datetime argument does not exactly match %Y-%m-%d %H:%M:%S.%f format, date was parsed automatically as 2020-04-16 13:05:00.000000
  warn(warn_message, UserWarning)

Note Two previous subscriptions attached DefaultHandler implicitly. To retrieve instances just call get_event_handler() method.

tns_handler = tns_sub.get_event_handler()
candle_handler = candle_sub.get_event_handler()

Subscription instance properties¶

print(f'TimeAndSale subscription event type: {tns_sub.event_type}')
print(f'Candle subscription event type: {candle_sub.event_type}')
print(f'Candle subscription symbols: {candle_sub.symbols}')

TimeAndSale subscription event type: TimeAndSale
Candle subscription event type: Candle
Candle subscription symbols: ['AAPL{=d}', 'MSFT{=d}']

Access data from DefaultHandler instance¶

You can get colums, list or dataframe. You are also allowed to write handler that stores no data.

print(f'Trade columns: {trade_handler.columns}')
print(f'Candle columns: {candle_handler.columns}')

Trade columns: ['Symbol', 'Price', 'ExchangeCode', 'Size', 'Tick', 'Change', 'DayVolume', 'Time', 'IsETH']
Candle columns: ['Symbol', 'Index', 'Time', 'Sequence', 'Count', 'Open', 'High', 'Low', 'Close', 'Volume', 'VWap', 'BidVolume', 'AskVolume', 'OpenInterest', 'ImpVolatility']

candle_handler.get_list()[-5:]

[['MSFT{=d}', 6816463568083353600, 1587081600000, 0, 189986.0, 179.5, 180.0, 175.87, 178.6, 52765625.0, 177.90622, 24188832.0, 22094602.0, 0, 0.4384],
 ['MSFT{=d}', 6816294775868620800, 1587042300000, 0, 189986.0, 179.5, 180.0, 175.87, 178.6, 52765625.0, 177.90622, 24188832.0, 22094602.0, 0, 0.4384],
 ['AAPL{=d}', 6839841934068940800, 1592524800000, 0, 827.0, 354.05, 355.55, 353.35, 354.72, 188804.0, 354.45941, 78039.0, 110765.0, 0, 0.3691],
 ['AAPL{=d}', 6839841934068940800, 1592524800000, 0, 831.0, 354.05, 355.55, 353.35, 354.9, 189555.0, 354.4611, 78039.0, 111516.0, 0, 0.3691],
 ['AAPL{=d}', 6839841934068940800, 1592524800000, 0, 832.0, 354.05, 355.55, 353.35, 354.72, 190055.0, 354.46178, 78539.0, 111516.0, 0, 0.3691]]

candle_handler.get_dataframe().head(3)

	Symbol	Index	Time	Count	Open	High	Low	Close	Volume	VWap	BidVolume	AskVolume	ImpVolatility
0	AAPL{=d}	6839841934068940800	2020-06-19	827.0	354.05	355.55	353.35	354.72	188804.0	354.45941	78039.0	110765.0	0.3691
1	AAPL{=d}	6839470848894566400	2020-06-18	96172.0	351.41	353.45	349.22	351.73	24205096.0	351.56873	8565421.0	10394906.0	0.3673
2	AAPL{=d}	6839099763720192000	2020-06-17	110438.0	355.15	355.40	351.09	351.59	28601626.0	353.70998	10686232.0	12141490.0	0.3713

Close subscription¶

trade_sub.close_subscription()
tns_sub.close_subscription()
candle_sub.close_subscription()

Close connection¶

endpoint.close_connection()
print(f'Connection status: {endpoint.connection_status}')

Connection status: Not connected