[EN-1570] subscription example

Author: iamishalkin

docs/basic_usage.rst

@@ -3,7 +3,6 @@
 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
@@ -15,20 +14,21 @@ Python level, in its turn, mainly consists of three class types:
 2. Subscription
 3. 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.
+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.
+**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.
+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
 ~~~~~~~~~~~~~~
@@ -56,7 +56,7 @@ e.g. connection address or status
     print(f'Connection status: {endpoint.connection_status}')
 
 
-.. code-block:: text
+.. code:: text
 
     Connected address: demo.dxfeed.com:7300
     Connection status: Connected and authorized
@@ -88,7 +88,10 @@ default one
 
 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
+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.
 
 .. code:: python3
 
@@ -98,10 +101,10 @@ with how your provided date parsed automatically
 .. code:: python3
 
     candle_sub = endpoint.create_subscription('Candle', date_time='2020-04-16 13:05')
-    candle_sub = candle_sub.add_symbols(['AAPL', 'MSFT'])
+    candle_sub = candle_sub.add_symbols(['AAPL{=d}', 'MSFT{=d}'])
 
 
-.. code-block:: text
+.. code:: text
 
     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)
@@ -125,11 +128,11 @@ Subscription instance properties
     print(f'Candle subscription symbols: {candle_sub.symbols}')
 
 
-.. code-block:: text
+.. code:: text
 
     TimeAndSale subscription event type: TimeAndSale
     Candle subscription event type: Candle
-    Candle subscription symbols: ['AAPL', 'MSFT']
+    Candle subscription symbols: ['AAPL{=d}', 'MSFT{=d}']
     
 
 Access data from DefaultHandler instance
@@ -144,12 +147,29 @@ handler that stores no data.
     print(f'Candle columns: {candle_handler.columns}')
 
 
-.. code-block:: text
+.. code:: text
 
     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']
     
 
+.. code:: python3
+
+    candle_handler.get_list()[-5:]
+
+
+
+
+.. code:: text
+
+    [['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]]
+
+
+
 .. code:: python3
 
     candle_handler.get_dataframe().head(3)
@@ -197,79 +217,64 @@ handler that stores no data.
       <tbody>
         <tr>
           <th>0</th>
-          <td>MSFT</td>
-          <td>6838531241273198328</td>
-          <td>2020-06-15 11:13:50.566</td>
-          <td>1784</td>
-          <td>1.0</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>635.0</td>
-          <td>184.17</td>
-          <td>635.0</td>
-          <td>NaN</td>
+          <td>AAPL{=d}</td>
+          <td>6839841934068940800</td>
+          <td>2020-06-19</td>
+          <td>0</td>
+          <td>827.0</td>
+          <td>354.05</td>
+          <td>355.55</td>
+          <td>353.35</td>
+          <td>354.72</td>
+          <td>188804.0</td>
+          <td>354.45941</td>
+          <td>78039.0</td>
+          <td>110765.0</td>
           <td>0</td>
-          <td>NaN</td>
+          <td>0.3691</td>
         </tr>
         <tr>
           <th>1</th>
-          <td>MSFT</td>
-          <td>6838531241273198326</td>
-          <td>2020-06-15 11:13:50.566</td>
-          <td>1782</td>
-          <td>1.0</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>100.0</td>
-          <td>184.17</td>
-          <td>100.0</td>
-          <td>NaN</td>
+          <td>AAPL{=d}</td>
+          <td>6839470848894566400</td>
+          <td>2020-06-18</td>
           <td>0</td>
-          <td>NaN</td>
+          <td>96172.0</td>
+          <td>351.41</td>
+          <td>353.45</td>
+          <td>349.22</td>
+          <td>351.73</td>
+          <td>24205096.0</td>
+          <td>351.56873</td>
+          <td>8565421.0</td>
+          <td>10394906.0</td>
+          <td>0</td>
+          <td>0.3673</td>
         </tr>
         <tr>
           <th>2</th>
-          <td>MSFT</td>
-          <td>6838531058896471782</td>
-          <td>2020-06-15 11:13:08.092</td>
-          <td>1766</td>
-          <td>1.0</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>184.17</td>
-          <td>100.0</td>
-          <td>184.17</td>
-          <td>100.0</td>
-          <td>NaN</td>
+          <td>AAPL{=d}</td>
+          <td>6839099763720192000</td>
+          <td>2020-06-17</td>
+          <td>0</td>
+          <td>110438.0</td>
+          <td>355.15</td>
+          <td>355.40</td>
+          <td>351.09</td>
+          <td>351.59</td>
+          <td>28601626.0</td>
+          <td>353.70998</td>
+          <td>10686232.0</td>
+          <td>12141490.0</td>
           <td>0</td>
-          <td>NaN</td>
+          <td>0.3713</td>
         </tr>
       </tbody>
     </table>
     </div>
 
 
 
-.. code:: python3
-
-    candle_handler.get_list()[:3]
-
-
-
-
-.. code-block:: text
-
-    [['MSFT', 6838531241273198328, 1592219630566, 1784, 1.0, 184.17, 184.17, 184.17, 184.17, 635.0, 184.17, 635.0, nan, 0, nan],
-     ['MSFT', 6838531241273198326, 1592219630566, 1782, 1.0, 184.17, 184.17, 184.17, 184.17, 100.0, 184.17, 100.0, nan, 0, nan],
-     ['MSFT', 6838531058896471782, 1592219588092, 1766, 1.0, 184.17, 184.17, 184.17, 184.17, 100.0, 184.17, 100.0, nan, 0, nan]]
-
-
-
 Close subscription
 ~~~~~~~~~~~~~~~~~~
 
@@ -288,7 +293,7 @@ Close connection
     print(f'Connection status: {endpoint.connection_status}')
 
 
-.. code-block:: text
+.. code:: text
 
     Connection status: Not connected
     

examples/SubscriptionExample.ipynb

@@ -229,7 +229,7 @@
    },
    "outputs": [],
    "source": [
-    "candle_handler.get_list()"
+    "candle_handler.get_list()[-5:]"
    ]
   },
   {
@@ -238,7 +238,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "candle_handler.get_dataframe()"
+    "candle_handler.get_dataframe().head(3)"
    ]
   },
   {