Documentation for itch

docs/api_reference.rst

@@ -5,5 +5,7 @@ API Reference
    :maxdepth: 1
    :caption: Contents:
 
-   common_api_reference
-   soup_api_reference
+   api_reference_soup
+   api_reference_itch
+   api_reference_ouch
+   api_reference_common

docs/api_reference_itch.rst

@@ -0,0 +1,22 @@
+.. _api-reference-itch:
+ITCH API Reference
+==================
+
+Itch
+----
+.. automodule:: nasdaq_protocols.itch
+
+
+Itch Session
+^^^^^^^^^^^^
+.. autoclass:: nasdaq_protocols.itch.session.ItchSessionId
+    :show-inheritance: True
+
+.. autoclass:: nasdaq_protocols.itch.session.ClientSession
+    :show-inheritance: True
+    :undoc-members: ['send_heartbeat']
+
+
+Itch Messages
+^^^^^^^^^^^^^
+.. automodule:: nasdaq_protocols.itch.core

docs/api_reference_ouch.rst

@@ -0,0 +1,22 @@
+.. _api-reference-ouch:
+OUCH API Reference
+==================
+
+Ouch
+----
+.. automodule:: nasdaq_protocols.ouch
+
+
+Ouch Session
+^^^^^^^^^^^^
+.. autoclass:: nasdaq_protocols.ouch.session.OuchSessionId
+    :show-inheritance: True
+
+.. autoclass:: nasdaq_protocols.ouch.session.ClientSession
+    :show-inheritance: True
+    :undoc-members: ['send_heartbeat']
+
+
+Ouch Messages
+^^^^^^^^^^^^^
+.. automodule:: nasdaq_protocols.ouch.core

docs/soup_api_reference.rst → docs/api_reference_soup.rst

@@ -1,4 +1,5 @@
-SOUP api reference
+.. _api-reference-soup:
+SOUP API Reference
 ==================
 
 Soup

docs/index.rst

@@ -8,13 +8,25 @@ Welcome to nasdaq-protocols's documentation!
 
 .. automodule:: nasdaq_protocols
 
+nasdaq-protocols contains client side implementations of the various
+publicly available protocols used by Nasdaq ecosystem.
+
+This package contains only the core implementations of the protocols like message
+serialization, deserialization, message validation and session handling. It does not
+contain any actual messages that are exchanged between the client and the server.
+
+The actual messages are application specific and hence has to be defined by the
+user of this library. The user has to define the messages as per the protocol specification
+by extending the base message class defined in the package.
+
+Refer to the :ref:`user-guide`. for more information on how to define the messages and use this package.
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
-   install
-   api_reference
    user_guide
+   api_reference
    developer_guide
    LICENSE
 

docs/install.rst

@@ -1,8 +1,10 @@
+.. _install-guide:
+
 Installation
 ============
 
 To use nasdaq-protocols, install it using pip:
 
 .. code-block:: console
 
-   (.venv) $ pip install nasdaq-protocols
+   $ pip install nasdaq-protocols

docs/user_guide.rst

@@ -1,35 +1,14 @@
+.. _user-guide:
+
 User Guide
 ==========
 
-SOUP
-____
-
-Connect to Soup session
------------------------
-Example of connecting to a Soup session and receiving messages.
-
-.. code-block:: python
-
-    import asyncio
-    from nasdaq_protocols import Soup
-
-    stopped = asyncio.Event()
-
-    async def on_msg(msg):
-        print(msg)
-
-    async def on_close():
-        stopped.set()
-        print('closed')
-
-    async def main():
-        session = await soup.connect_async(
-            ('host', port), 'user', 'password',
-            sequence=1, on_msg_coro=on_msg, on_close_coro=on_close
-        )
-        await stopped.wait()
-
-    if __name__ == '__main__':
-        asyncio.run(main())
+.. toctree::
+   :maxdepth: 1
+   :caption: User Guides:
 
-*A simple soup tail program*
+   install
+   user_guide_soup
+   user_guide_ouch
+   user_guide_itch
+   user_guide_create_new_project

docs/user_guide_create_new_project.rst

@@ -0,0 +1,78 @@
+.. _user-guide-create-new-project:
+
+Create New Project Guide
+========================
+
+This guide will walk you through creating a new python package that contains the message definitions
+of the applications you want to use with the nasdaq-protocols.
+
+.. note::
+
+    This guide assumes you have already installed the nasdaq-protocols package. If you have not, please
+    refer to the :ref:`installation guide <install-guide>`.
+
+
+Steps
+-----
+
+1. Install `tox` if you have not already done so.
+
+    .. code-block:: bash
+
+        bash$ pip install tox
+
+Refer to the `tox documentation <https://tox.wiki/en/latest/installation.html>`_ for detailed information.
+
+2. Create a new python package structure using the `nasdaq-protocols-create-new-project` command line tool.
+
+        .. code-block:: bash
+
+            bash$ nasdaq-protocols-create-new-project --name <project-name> \
+                     --application app:proto [--target-dir <target-dir>]
+
+        Replace `<project-name>` with the name of your project and `<target-dir>` with the directory where you want to
+        create the project.
+
+        For example, to create a project named `nasdaq-protocols-messages` in the current directory, with 2 applications `ouch_oe`
+        and `itch_feed`, you would run the following command:
+
+        .. code-block:: bash
+
+            bash$ nasdaq-protocols-create-new-project --name nasdaq-protocols-messages \
+                    --application ouch_oe:ouch \
+                    --application itch_feed:itch
+
+3. The `nasdaq-protocols-create-new-project` command will create a new python package with the following structure:
+
+    For the above example, the following directory structure will be created.
+
+    .. code-block:: bash
+
+        nasdaq-protocols-messages/
+        ├── src/
+        |    ├── nasdaq_protocols_messages/
+        |    │   ├── __init__.py
+        |    │   ├── ouch_oe/
+        |    │   │   └── ouch_oe.xml
+        |    │   └── itch_feed/
+        |    │       └── itch_feed.xml
+        ├── pyproject.toml
+        └── tox.ini
+
+    .. note::
+        - **ouch_oe.xml** is the file where you define all the messages for the `ouch_oe` application.
+        - **itch_feed.xml** is the file where you define all the messages for the `itch_feed` application.
+
+        The XML file contains the format and guidelines on how to define the messages.
+
+4. Edit the XML files to define the messages for the applications you want to use with the nasdaq-protocols.
+
+5. Build the package
+
+        .. code-block:: bash
+
+            bash$ cd target-dir/nasdaq-protocols-messages
+            bash$ tox r
+
+6. The package will be built and stored in the `dist` directory. This can be uploaded to your PyPI repository or
+   installed locally.

docs/user_guide_itch.rst

@@ -0,0 +1,126 @@
+.. _user-guide-itch:
+
+ITCH User Guide
+===============
+
+The `nasdaq_protocols.itch` module provides an API to interact with ITCH servers.
+Refer :ref:`api-reference-itch`. for more information on the API.
+
+This package **only** provides the core implementation of the ITCH protocols, like message serialization
+deserialization, session handling, etc. It **does not** define any actual ITCH messages. The actual ITCH
+messages has to be defined by the user of this package. The first step is to create a new python package
+which contains the messages definitions for all the protocols that the user wants to use.
+
+This package provides a command line utility `nasdaq-protocols-create-new-project` to create a new python package
+and all the necessary files.
+
+Follow the steps in :ref:`user-guide-create-new-project` to create a new python package for application specific
+messages.
+
+
+.. note::
+
+    This rest of the guide assumes that you have built a new python project using the steps mentioned in
+    :ref:`user-guide-create-new-project`.
+
+
+The generated project will contain a file `itch_<app_name>.py` which will contain the following
+    - ITCH message definitions
+    - ITCH Client Session for this application
+
+Using the generated code, you can connect to a ITCH server and start receiving messages.
+
+
+The `nasdaq_protocols.itch` module provides an API to interact with ITCH servers.
+Refer :ref:`api-reference-itch`. for more information on the API.
+
+
+Connecting to a ITCH Server
+---------------------------
+Use the example below to implement a program that will tail itch messages from the server.
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    import asyncio
+    # from the generated package we import the application we want to use
+    from nasdaq_protocols_messages import itch_feed
+
+
+    stopped = asyncio.Event()
+
+
+    async def itch_output(itch_message):
+        """
+        This function will be called whenever a new ITCH message is received
+        """
+        print('')
+        print(f'received: {itch_message}')
+        print('')
+
+
+    async def itch_close():
+        """
+        This function will be called when the ITCH session is closed
+        """
+        stopped.set()
+        print('')
+        print('itch session closed, Bye Bye')
+        print('')
+
+
+    async def main():
+        # Step1: connect
+        port = 1234  # give the proper itch server port
+        itch_session = await itch_feed.connect_async(
+            ('hostname', port),
+            'itch username',  # itch username, max 6 characters
+            'pwdchange', # itch password, max 10 characters
+            '', # session id
+            on_msg_coro=itch_output,  # function to call when a new message is received
+            on_close_coro=itch_close, # function to call when the session is closed
+            sequence=1  # 0 to listen from HEAD, 1 to listen from start, n to listen from n
+        )
+
+        # Wait forever until the server closes the connection
+        await asyncio.sleep(5)
+
+        print("Closing the itch session...")
+        await stopped.wait()
+
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+*A simple itch tail program*
+
+Slightly modified version where we do not use dispatchers instead explicitely call `receive_message()` method.
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    import asyncio
+    from nasdaq_protocols_messages import itch_feed
+
+
+    async def main():
+        # Step1: connect
+        port = 1234  # give the proper itch server port
+        itch_session = await itch_feed.connect_async(
+            ('hostname', port),
+            'itch username',  # itch username, max 6 characters
+            'pwdchange', # itch password, max 10 characters
+            '', # session id
+            sequence=1  # 0 to listen from HEAD, 1 to listen from start, n to listen from n
+        )
+
+        # receive the first message from the server.
+        itch_message = await itch_session.receive_message()
+        print(itch_message)
+
+        print("Closing the itch session...")
+        await itch_session.close()
+
+
+    if __name__ == '__main__':
+        asyncio.run(main())

docs/user_guide_ouch.rst

@@ -0,0 +1,7 @@
+.. _user-guide-ouch:
+
+OUCH User Guide
+===============
+
+The `nasdaq_protocols.ouch` module provides an API to interact with OUCH servers.
+Refer :ref:`api-reference-ouch`. for more information on the API.