From b565ccbf3717c612276e91a6fd56491e60d6be88 Mon Sep 17 00:00:00 2001 From: SamDanielThangarajan <12202554+SamDanielThangarajan@users.noreply.github.com> Date: Tue, 3 Sep 2024 10:01:47 +0530 Subject: [PATCH] Documentation for itch and ouch --- docs/api_reference.rst | 6 +- ...reference.rst => api_reference_common.rst} | 0 docs/api_reference_itch.rst | 22 +++++ docs/api_reference_ouch.rst | 22 +++++ ...i_reference.rst => api_reference_soup.rst} | 3 +- docs/index.rst | 16 +++- docs/install.rst | 2 +- docs/user_guide.rst | 40 ++------- docs/user_guide_itch.rst | 5 ++ docs/user_guide_ouch.rst | 5 ++ docs/user_guide_soup.rst | 89 +++++++++++++++++++ src/nasdaq_protocols/__init__.py | 4 - 12 files changed, 173 insertions(+), 41 deletions(-) rename docs/{common_api_reference.rst => api_reference_common.rst} (100%) create mode 100644 docs/api_reference_itch.rst create mode 100644 docs/api_reference_ouch.rst rename docs/{soup_api_reference.rst => api_reference_soup.rst} (91%) create mode 100644 docs/user_guide_itch.rst create mode 100644 docs/user_guide_ouch.rst create mode 100644 docs/user_guide_soup.rst 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..8693f82 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -5,4 +5,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..b46349e 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,35 +1,13 @@ +.. _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 diff --git a/docs/user_guide_itch.rst b/docs/user_guide_itch.rst new file mode 100644 index 0000000..8dec2f0 --- /dev/null +++ b/docs/user_guide_itch.rst @@ -0,0 +1,5 @@ +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. diff --git a/docs/user_guide_ouch.rst b/docs/user_guide_ouch.rst new file mode 100644 index 0000000..482898c --- /dev/null +++ b/docs/user_guide_ouch.rst @@ -0,0 +1,5 @@ +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..2859571 --- /dev/null +++ b/docs/user_guide_soup.rst @@ -0,0 +1,89 @@ +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. -"""