Skip to content

Commit 872b9ab

Browse files
alimantualimantu
authored
Merge pull request #13 from dxFeed/EN-1328-add-oop-level
En 1328 add oop level
2 parents 073f5d5 + d0a4912 commit 872b9ab

24 files changed

+1243
-209
lines changed

‎README.md

+97-29
Original file line numberDiff line numberDiff line change
@@ -34,59 +34,127 @@ pip3 install dxfeed
3434

3535
## Basic usage
3636

37-
All the functions in C API have similar ones in Python with the same name. Not all arguments are
38-
supported by now, this work is in progress.
37+
Following steps should be performed:
3938

40-
**Import dxfeed library**:
39+
* Import
40+
* Create Endpoint
41+
* Create Subscription
42+
* Attach listener
43+
* Add tickers
44+
* Finally close subscription and connection
45+
46+
### Import package
4147

4248
```python
4349
import dxfeed as dx
44-
```
50+
from datetime import datetime # for timed subscription
51+
```
52+
53+
### Configure and create connection with Endpoint class
54+
Create instance of Endpoint class which will connect provided address.
55+
56+
57+
```python
58+
endpoint = dx.Endpoint('demo.dxfeed.com:7300')
59+
```
60+
61+
Endpoint instance contains information about the connection, e.g. connection address or status
62+
63+
64+
```python
65+
print(f'Connected address: {endpoint.address}')
66+
print(f'Connection status: {endpoint.connection_status}')
67+
```
68+
69+
```text
70+
Connected address: demo.dxfeed.com:7300
71+
Connection status: Connected and authorized
72+
```
73+
74+
### Configure and create subscription
75+
You should specify event type. For timed subscription (conflated stream) you should also provide time to start subscription from.
76+
77+
78+
```python
79+
trade_sub = endpoint.create_subscription('Trade', data_len=-1)
80+
```
81+
82+
**Attach default listener** - function that process incoming events
83+
84+
85+
```python
86+
trade_sub = trade_sub.attach_listener()
87+
```
88+
89+
**Add tikers** you want to recieve events for
90+
91+
92+
```python
93+
trade_sub = trade_sub.add_symbols(['C', 'TSLA'])
94+
```
95+
96+
For timed subscription you may provide either datetime object or string. String might be incomlete, in this case you will get warning with how your provided date parsed automatically
97+
98+
99+
```python
100+
tns_sub = endpoint.create_subscription('TimeAndSale', date_time=datetime.now()) \
101+
.attach_listener() \
102+
.add_symbols(['AMZN'])
103+
```
45104

46-
**Create connection**:
47105

48106
```python
49-
con = dx.dxf_create_connection(address='demo.dxfeed.com:7300')
107+
candle_sub = endpoint.create_subscription('Candle', date_time='2020-04-16 13:05')
108+
candle_sub = candle_sub.attach_listener()
109+
candle_sub = candle_sub.add_symbols(['AAPL', 'MSFT'])
50110
```
51111

52-
**Create one or several subscriptions of certain event types**:
112+
#### Subscription instance properties
113+
114+
53115
```python
54-
sub1 = dx.dxf_create_subscription(con, 'Trade')
55-
sub2 = dx.dxf_create_subscription(con, 'Quote')
116+
print(f'Subscription event type: {tns_sub.event_type}')
117+
print(f'Subscription symbols: {candle_sub.symbols}')
118+
```
119+
120+
```text
121+
Subscription event type: TimeAndSale
122+
Subscription symbols: ['AAPL', 'MSFT']
56123
```
57-
'Trade', 'Quote', 'Summary', 'Profile', 'Order', 'TimeAndSale', 'Candle', 'TradeETH', 'SpreadOrder',
58-
'Greeks', 'TheoPrice', 'Underlying', 'Series', 'Configuration' event types are supported.
59124

60-
**Attach listeners**:
125+
### Access data
126+
Data is stored as deque. Its length is configured with data_len parameter and by default is 100000. When you call method below you extracts all data recieved to the moment and clears the buffer in class.
127+
128+
61129
```python
62-
dx.dxf_attach_listener(sub1)
63-
dx.dxf_attach_listener(sub2)
130+
candle_sub.get_data()
64131
```
65132

66-
**Add tickers you want to get data for**:
133+
### Close connection
134+
135+
67136
```python
68-
dx.dxf_add_symbols(sub1, ['AAPL', 'MSFT'])
69-
dx.dxf_add_symbols(sub2, ['AAPL', 'C'])
137+
endpoint.close_connection()
138+
print(f'Connection status: {endpoint.connection_status}')
139+
```
140+
141+
```text
142+
Connection status: Not connected
70143
```
71144

72-
`dxfeed` has default listeners for each event type, but you are able to write
73-
your custom one. You can find how to do it at `example/Custom listener example.ipynb`.
145+
### Transform data to pandas DataFrame
146+
74147

75-
**Look at the data**:
76148
```python
77-
sub1.get_data()
78-
sub2.get_data()
149+
trade_df = trade_sub.get_dataframe()
79150
```
80-
The data is stored in Subscription class. You can also turn dict to pandas DataFrame simply calling
81-
`sub1.to_dataframe()`.
82151

83-
**Detach the listener, if you want to stop recieving data**:
152+
84153
```python
85-
dx.dxf_detach_listener(sub1)
86-
dx.dxf_detach_listener(sub2)
154+
tns_df = tns_sub.get_dataframe()
87155
```
88156

89-
**Finally, close your connection**:
157+
90158
```python
91-
dx.dxf_close_connection(con)
159+
candle_df = candle_sub.get_dataframe()
92160
```

‎docs/_static/custom.css

+3
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,6 @@
1010
.current.reference.internal {
1111
font-weight: bold;
1212
}
13+
.attribute {
14+
margin-left: 30px;
15+
}

‎docs/api.rst

+13-2
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,19 @@
33
API Reference
44
=============
55

6-
Core functions
7-
--------------
6+
API
7+
------------------------
8+
9+
.. automodule:: dxfeed.wrappers.endpoint
10+
:members:
11+
:inherited-members:
12+
13+
.. automodule:: dxfeed.wrappers.subscription
14+
:members:
15+
:inherited-members:
16+
17+
Low-level API
18+
-----------------------
819

920
.. automodule:: dxfeed.core.DXFeedPy
1021
:members:

‎docs/basic_usage.rst

+80-48
Original file line numberDiff line numberDiff line change
@@ -3,83 +3,115 @@
33
Basic Usage
44
===========
55

6-
All the functions in C API have similar ones in Python with the same name. Not all arguments are
7-
supported by now, this work is in progress.
6+
Import package
7+
~~~~~~~~~~~~~~
88

9-
First of all you have to import the package:
10-
11-
.. code-block:: python
9+
.. code:: python3
1210
1311
import dxfeed as dx
12+
from datetime import datetime # for timed subscription
13+
14+
Configure and create connection with Endpoint class
15+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16+
17+
Create instance of Endpoint class which will connect provided address.
18+
19+
.. code:: python3
20+
21+
endpoint = dx.Endpoint('demo.dxfeed.com:7300')
22+
23+
Endpoint instance contains information about the connection,
24+
e.g. connection address or status
25+
26+
.. code:: python3
27+
28+
print(f'Connected address: {endpoint.address}')
29+
print(f'Connection status: {endpoint.connection_status}')
30+
31+
.. code:: text
32+
33+
Connected address: demo.dxfeed.com:7300
34+
Connection status: Connected and authorized
35+
36+
Configure and create subscription
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38+
39+
You should specify event type. For timed subscription (conflated stream)
40+
you should also provide time to start subscription from.
41+
42+
.. code:: python3
1443
15-
Next, the connection to dxfeed server should be established:
44+
trade_sub = endpoint.create_subscription('Trade', data_len=-1)
1645
17-
.. code-block:: python
46+
**Attach default listener** - function that process incoming events
1847

19-
con = dx.dxf_create_connection(address='demo.dxfeed.com:7300')
48+
.. code:: python3
2049
21-
To get events of certain types the subscription with this type should be
22-
create. One connection may have several subscriptions.
50+
trade_sub = trade_sub.attach_listener()
2351
24-
.. code-block:: python
52+
**Add tikers** you want to recieve events for
2553

26-
sub1 = dx.dxf_create_subscription(con, 'Trade')
27-
sub2 = dx.dxf_create_subscription(con, 'Quote')
54+
.. code:: python3
2855
29-
.. note::
56+
trade_sub = trade_sub.add_symbols(['C', 'AAPL'])
3057
31-
'Trade', 'Quote', 'Summary', 'Profile', 'Order', 'TimeAndSale', 'Candle', 'TradeETH', 'SpreadOrder',
32-
'Greeks', 'TheoPrice', 'Underlying', 'Series', 'Configuration' event types are supported.
58+
For timed subscription you may provide either datetime object or string.
59+
String might be incomlete, in this case you will get warning with how
60+
your provided date parsed automatically
3361

34-
Special function called listener should be attached to the subscription to start receiving
35-
events. There are default listeners already implemented in dxpyfeed, but you
36-
can write your own with cython: :ref:`custom_listener`. To attach
37-
default listener just call `dxf_attach_listener`
62+
.. code:: python3
3863
39-
.. code-block:: python
64+
tns_sub = endpoint.create_subscription('TimeAndSale', date_time=datetime.now()) \
65+
.attach_listener() \
66+
.add_symbols(['AMZN'])
4067
41-
dx.dxf_attach_listener(sub1)
42-
dx.dxf_attach_listener(sub2)
68+
.. code:: python3
4369
44-
Each subscription should be provided with tickers to get events for:
70+
candle_sub = endpoint.create_subscription('Candle', date_time='2020-04-16 13:05')
71+
candle_sub = candle_sub.attach_listener()
72+
candle_sub = candle_sub.add_symbols(['AAPL', 'MSFT'])
4573
46-
.. code-block:: python
74+
Subscription instance properties
75+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4776

48-
dx.dxf_add_symbols(sub1, ['AAPL', 'MSFT'])
49-
dx.dxf_add_symbols(sub2, ['AAPL', 'C'])
77+
.. code:: python3
5078
51-
The data can be extracted with `get_data()` method. It is stored as dict with list of columns and list
52-
of events. Note that `get_data` extracts the data and then clean the field. To look at data call this property:
79+
print(f'Subscription event type: {tns_sub.event_type}')
80+
print(f'Subscription symbols: {candle_sub.symbols}')
5381
54-
.. code-block:: python
82+
.. code:: text
5583
56-
sub1.get_data()
57-
sub2.get_data()
84+
Subscription event type: TimeAndSale
85+
Subscription symbols: ['AAPL', 'MSFT']
5886
59-
The more convenient way to look at data is to convert it into pandas DataFrame.
60-
`to_dataframe` method of subscription class is responsible for that:
87+
Access data
88+
~~~~~~~~~~~
6189

62-
.. code-block:: python
90+
Data is stored as deque. Its length is configured with data_len
91+
parameter and by default is 100000. When you call method below you
92+
extracts all data recieved to the moment and clears the buffer in class.
6393

64-
sub1.to_dataframe()
65-
sub2.to_dataframe()
94+
.. code:: python3
6695
67-
To stop receiving events just detach the listener:
96+
candle_sub.get_data()
6897
69-
.. code-block:: python
98+
Close connection
99+
~~~~~~~~~~~~~~~~
70100

71-
dx.dxf_detach_listener(sub1)
72-
dx.dxf_detach_listener(sub2)
101+
.. code:: python3
73102
74-
When you are done with subscription you'd better close it:
103+
endpoint.close_connection()
104+
print(f'Connection status: {endpoint.connection_status}')
75105
76-
.. code-block:: python
106+
.. code:: text
77107
78-
dx.dxf_close_subscription(sub1)
79-
dx.dxf_close_subscription(sub2)
108+
Connection status: Not connected
80109
81-
Same with connection:
110+
Transform data to pandas DataFrame
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82112

83-
.. code-block:: python
113+
.. code:: python3
84114
85-
dx.dxf_close_connection(con)
115+
trade_df = trade_sub.to_dataframe()
116+
tns_df = tns_sub.to_dataframe()
117+
candle_df = candle_sub.to_dataframe()

‎docs/conf.py

-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,6 @@
5555
# The theme to use for HTML and HTML Help pages.
5656
html_theme = 'alabaster'
5757
html_theme_options = {
58-
'body_max_width': '80%',
5958
'show_powered_by': False,
6059
'sidebar_collapse': True
6160
}

0 commit comments

Comments
 (0)