diff --git a/docs/api_reference.rst b/docs/api_reference.rst index db656ea..4976463 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -5,5 +5,7 @@ API Reference :maxdepth: 1 :caption: Contents: - common_api_reference - soup_api_reference \ No newline at end of file + api_reference_soup + api_reference_itch + api_reference_ouch + api_reference_common \ No newline at end of file diff --git a/docs/common_api_reference.rst b/docs/api_reference_common.rst similarity index 100% rename from docs/common_api_reference.rst rename to docs/api_reference_common.rst diff --git a/docs/api_reference_itch.rst b/docs/api_reference_itch.rst new file mode 100644 index 0000000..771f8a0 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/api_reference_ouch.rst b/docs/api_reference_ouch.rst new file mode 100644 index 0000000..c621bf9 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/soup_api_reference.rst b/docs/api_reference_soup.rst similarity index 91% rename from docs/soup_api_reference.rst rename to docs/api_reference_soup.rst index 828f9f3..6dc367a 100644 --- a/docs/soup_api_reference.rst +++ b/docs/api_reference_soup.rst @@ -1,4 +1,5 @@ -SOUP api reference +.. _api-reference-soup: +SOUP API Reference ================== Soup diff --git a/docs/index.rst b/docs/index.rst index 33fc5bf..421e199 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/install.rst b/docs/install.rst index 9ef5f4a..3510a7f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,3 +1,5 @@ +.. _install-guide: + Installation ============ @@ -5,4 +7,4 @@ To use nasdaq-protocols, install it using pip: .. code-block:: console - (.venv) $ pip install nasdaq-protocols \ No newline at end of file + $ pip install nasdaq-protocols \ No newline at end of file diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 554cd16..ce5e354 100644 --- a/docs/user_guide.rst +++ b/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* \ No newline at end of file + install + user_guide_soup + user_guide_ouch + user_guide_itch + user_guide_create_new_project \ No newline at end of file diff --git a/docs/user_guide_create_new_project.rst b/docs/user_guide_create_new_project.rst new file mode 100644 index 0000000..5b3527e --- /dev/null +++ b/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 `. + + +Steps +----- + +1. Install `tox` if you have not already done so. + + .. code-block:: bash + + bash$ pip install tox + +Refer to the `tox documentation `_ 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 \ + --application app:proto [--target-dir ] + + Replace `` with the name of your project and `` 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. \ No newline at end of file diff --git a/docs/user_guide_itch.rst b/docs/user_guide_itch.rst new file mode 100644 index 0000000..2edef00 --- /dev/null +++ b/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_.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()) diff --git a/docs/user_guide_ouch.rst b/docs/user_guide_ouch.rst new file mode 100644 index 0000000..203c529 --- /dev/null +++ b/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. diff --git a/docs/user_guide_soup.rst b/docs/user_guide_soup.rst new file mode 100644 index 0000000..e2e5a5b --- /dev/null +++ b/docs/user_guide_soup.rst @@ -0,0 +1,91 @@ +.. _user-guide-soup: + +SOUP User Guide +=============== + +SoupBinTCP 4.00 is a lightweight point-to-point protocol, built on top of TCP/IP +sockets that allow delivery of a set of sequenced and unsequenced messages from a +server to a client in real-time. SoupBinTCP guarantees that the client receives each +sequenced message generated by the server in the correct order, even across +underlying TCP/IP socket connection failures. + +Refer to the `Official SOUP Documentation `_ for more information +on how SOUP protocol works. + +The `nasdaq_protocols.soup` module provides an API to interact with SOUP servers and clients. +Refer :ref:`api-reference-soup`. for more information on the API. + + +Connect to Soup Server +---------------------- +Example of connecting to a Soup server and receiving messages. + +.. code-block:: python + + #!/usr/bin/env python3 + 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(): + port = 1234 # Give the actual port number + session = await soup.connect_async( + ('hostname or ip', port), + 'username', # Soup username, max 6 characters (as per spec) + 'password', # Soup password, max 10 characters (as per spec) + sequence=1, # 0 to listen from HEAD, 1 to listen from start, n to listen from n + on_msg_coro=on_msg, # callback for receiving messages + on_close_coro=on_close # callback for indicating server closed the connection + ) + + # To send a message to the server + # session.send_unseq_data(b'some bytes') + + await stopped.wait() + + + if __name__ == '__main__': + asyncio.run(main()) + +*A simple soup tail program* + + +A slightly modified version of the same example but not using dispatchers for `on_msg` and `on_close` callbacks. + + +.. code-block:: python + + #!/usr/bin/env python3 + import asyncio + from nasdaq_protocols import soup + + + async def main(): + port = 1234 # Give the actual port number + session = await soup.connect_async( + ('hostname or ip', port), 'username', 'password', + sequence=1 + ) + print(await session.receive_msg()) + await session.close() + + # To send a message to the server + # session.send_unseq_data(b'some bytes') + + + if __name__ == '__main__': + asyncio.run(main()) + +*A simple soup tail program without dispatchers* \ No newline at end of file diff --git a/src/nasdaq_protocols/__init__.py b/src/nasdaq_protocols/__init__.py index 0e05291..e69de29 100644 --- a/src/nasdaq_protocols/__init__.py +++ b/src/nasdaq_protocols/__init__.py @@ -1,4 +0,0 @@ -""" -nasdaq-protocols contains client side implementations of the various -publicly available protocols used by Nasdaq ecosystem. -"""