From 0658c7616b473693f536accfa64dad847274e010 Mon Sep 17 00:00:00 2001 From: SamDanielThangarajan <12202554+SamDanielThangarajan@users.noreply.github.com> Date: Thu, 5 Sep 2024 22:24:06 +0530 Subject: [PATCH] ouch_doc: added ouch user guide --- docs/user_guide_itch.rst | 13 +- docs/user_guide_ouch.rst | 114 ++++++++++++++++++ .../tools/templates/toml.mustache | 2 +- 3 files changed, 121 insertions(+), 8 deletions(-) diff --git a/docs/user_guide_itch.rst b/docs/user_guide_itch.rst index 2edef00..246fdb1 100644 --- a/docs/user_guide_itch.rst +++ b/docs/user_guide_itch.rst @@ -48,6 +48,7 @@ Use the example below to implement a program that will tail itch messages from t stopped = asyncio.Event() + port = 1234 # give the proper itch server port async def itch_output(itch_message): @@ -71,7 +72,6 @@ Use the example below to implement a program that will tail itch messages from t 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 @@ -82,10 +82,7 @@ Use the example below to implement a program that will tail itch messages from t 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...") + print("wait for server to close the session") await stopped.wait() @@ -94,7 +91,7 @@ Use the example below to implement a program that will tail itch messages from t *A simple itch tail program* -Slightly modified version where we do not use dispatchers instead explicitely call `receive_message()` method. +Slightly modified version where we do not use dispatchers instead explicitly call `receive_message()` method. .. code-block:: python @@ -103,9 +100,11 @@ Slightly modified version where we do not use dispatchers instead explicitely ca from nasdaq_protocols_messages import itch_feed + port = 1234 # give the proper itch server port + + 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 diff --git a/docs/user_guide_ouch.rst b/docs/user_guide_ouch.rst index 203c529..9f3f8d9 100644 --- a/docs/user_guide_ouch.rst +++ b/docs/user_guide_ouch.rst @@ -5,3 +5,117 @@ 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. + +This package **only** provides the core implementation of the OUCH protocols, like message serialization +deserialization, session handling, etc. It **does not** define any actual OUCH messages. The actual OUCH +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 `ouch_.py` which will contain the following + - OUCH message definitions + - OUCH Client Session for this application + +Using the generated code, you can connect to a OUCH server and start sending/receiving messages. + + +The `nasdaq_protocols.ouch` module provides an API to interact with OUCH servers. +Refer :ref:`api-reference-ouch`. for more information on the API. + + +Sending Message to a OUCH Server +-------------------------------- + +Sample Message Definition +^^^^^^^^^^^^^^^^^^^^^^^^^ +For our test ouch app, lets define our OUCH messages in the file `.xml` as follows, + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + + + +Sending and Receiving OUCH messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the above message definition, we can now send the ouch message as follows. + +.. 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 ouch_oe + + + port = 1234 # give the proper ouch server port + + + async def main(): + # Step1: connect + ouch_session = await ouch_oe.connect_async( + ('hostname', port), + 'ouch username', # ouch username, max 6 characters + 'pwdchange', # ouch password, max 10 characters + '', # session id + sequence=0 # 0 to listen from HEAD, 1 to listen from start, n to listen from n + ) + + # Step2: Prepare a message + enter_order = ouch_oe.EnterOrder() # This is the message we defined in the xml file + enter_order.orderBookId = 1 + enter_order.side = 'B' + enter_order.quantity = 100 + enter_order.price = 20 + + # Step3: Send the message to the server. + ouch_session.send_message(enter_order) + + # Step4: receive the first message from the server. + output = await ouch_session.receive_message() + if isinstance(output, ouch_oe.Accepted): + print("Order accepted") + elif isinstance(output, ouch_oe.Rejected): + print("Order rejected") + + # Step5: Close the session + print("Closing the ouch session...") + await ouch_session.close() + + + if __name__ == '__main__': + asyncio.run(main()) + +*A simple ouch send and receive program* diff --git a/src/nasdaq_protocols/tools/templates/toml.mustache b/src/nasdaq_protocols/tools/templates/toml.mustache index 72b0260..f0b231e 100644 --- a/src/nasdaq_protocols/tools/templates/toml.mustache +++ b/src/nasdaq_protocols/tools/templates/toml.mustache @@ -21,7 +21,7 @@ version = "0.0.1" # DEPENDENCIES # add your dependencies to the below list dependencies = [ - 'nasdaq-protocols>=0.0.1', + 'nasdaq-protocols', ] # VERSION