From 378d0ed6dde0357538381bb17cd83ca87c66a12a Mon Sep 17 00:00:00 2001 From: SamDanielThangarajan <12202554+SamDanielThangarajan@users.noreply.github.com> Date: Wed, 22 Jan 2025 18:19:31 +0100 Subject: [PATCH] readme changes --- README.md | 17 +++ README.rst | 34 ------ docs/LICENSE.rst | 2 +- docs/api_reference.rst | 1 + docs/api_reference_sqf.rst | 23 ++++ docs/user_guide.rst | 1 + docs/user_guide_create_new_project.rst | 10 +- docs/user_guide_sqf.rst | 141 +++++++++++++++++++++++++ 8 files changed, 191 insertions(+), 38 deletions(-) create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/api_reference_sqf.rst create mode 100644 docs/user_guide_sqf.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..9ef9e91 --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +Nasdaq Protocols Python Library +=============================== + +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. + + +More documentation can be found in the [github-pages/nasdaq-protocols-python](https://nasdaq-protocols.github.io/nasdaq-protocols-python/) + diff --git a/README.rst b/README.rst deleted file mode 100644 index a9f8d0f..0000000 --- a/README.rst +++ /dev/null @@ -1,34 +0,0 @@ -Nasdaq Protocols Python Library -=============================== - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - docs/install - docs/user_guide - docs/developer_guide - LICENSE - - -Introduction ------------- -This library provides a Python implementation of the Nasdaq protocols and FIX protocol. - -Currently, the library supports the following protocols: -1. SOUP -2. OUCH -3. ITCH -4. FIX - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - - - diff --git a/docs/LICENSE.rst b/docs/LICENSE.rst index 4626aff..17708b7 100644 --- a/docs/LICENSE.rst +++ b/docs/LICENSE.rst @@ -1,7 +1,7 @@ MIT License =========== -Copyright (c) 2024 Nasdaq +Copyright (c) 2025 Nasdaq Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/api_reference.rst b/docs/api_reference.rst index 7b99123..68d0d06 100644 --- a/docs/api_reference.rst +++ b/docs/api_reference.rst @@ -9,4 +9,5 @@ API Reference api_reference_itch api_reference_ouch api_reference_fix + api_reference_sqf api_reference_common \ No newline at end of file diff --git a/docs/api_reference_sqf.rst b/docs/api_reference_sqf.rst new file mode 100644 index 0000000..dc042c9 --- /dev/null +++ b/docs/api_reference_sqf.rst @@ -0,0 +1,23 @@ +.. _api-reference-sqf: + +SQF API Reference +================== + +SQF +---- +.. automodule:: nasdaq_protocols.sqf + + +Sqf Session +^^^^^^^^^^^^ +.. autoclass:: nasdaq_protocols.sqf.session.SqfSessionId + :show-inheritance: True + +.. autoclass:: nasdaq_protocols.sqf.session.ClientSession + :show-inheritance: True + :undoc-members: ['send_heartbeat'] + + +Sqf Messages +^^^^^^^^^^^^^ +.. automodule:: nasdaq_protocols.sqf.core \ No newline at end of file diff --git a/docs/user_guide.rst b/docs/user_guide.rst index ce5e354..ebc21d7 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -11,4 +11,5 @@ User Guide user_guide_soup user_guide_ouch user_guide_itch + user_guide_sqf 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 index 5b3527e..988357d 100644 --- a/docs/user_guide_create_new_project.rst +++ b/docs/user_guide_create_new_project.rst @@ -33,14 +33,15 @@ Refer to the `tox documentation `_ 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: + For example, to create a project named `nasdaq-protocols-messages` in the current directory, with 3 applications `ouch_oe`, + `itch_feed` and `sqf_qe`, 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 + --application itch_feed:itch \ + --application sqf_qe:sqf 3. The `nasdaq-protocols-create-new-project` command will create a new python package with the following structure: @@ -56,12 +57,15 @@ Refer to the `tox documentation `_ | │ │ └── ouch_oe.xml | │ └── itch_feed/ | │ └── itch_feed.xml + | │ └── sqf_qe/ + | │ └── sqf_qe.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. + - **sqf_qe.xml** is the file where you define all the messages for the `sqf_qe` application. The XML file contains the format and guidelines on how to define the messages. diff --git a/docs/user_guide_sqf.rst b/docs/user_guide_sqf.rst new file mode 100644 index 0000000..10873fc --- /dev/null +++ b/docs/user_guide_sqf.rst @@ -0,0 +1,141 @@ +.. _user-guide-sqf: + +SQF User Guide +=============== + +The `nasdaq_protocols.sqf` module provides an API to interact with SQF servers. +Refer :ref:`api-reference-sqf`. for more information on the API. + +This package **only** provides the core implementation of the SQF protocols, like message serialization +deserialization, session handling, etc. It **does not** define any actual SQF messages. The actual SQF +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 `sqf_.py` which will contain the following + - SQF message definitions + - SQF Client Session for this application + +Using the generated code, you can connect to a SQF server and start sending/receiving messages. + + +The `nasdaq_protocols.sqf` module provides an API to interact with SQF servers. +Refer :ref:`api-reference-sqf`. for more information on the API. + + +Sending Message to a SQF Server +-------------------------------- + +Sample Message Definition +^^^^^^^^^^^^^^^^^^^^^^^^^ +For our test sqf app, lets define our sqf messages in the file `.xml` as follows, + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Sending and Receiving SQF messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the above message definition, we can now send the SQF 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 sqf_oe + + + port = 1234 # give the proper SQF server port + + + async def main(): + # Step1: connect + sqf_session = await sqf_oe.connect_async( + ('hostname', port), + 'sqf username', # SQF username, max 6 characters + 'pwdchange', # SQF 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 + quotes = [] + for i in range(1, 2): + quote = sqf_oe.Quote() + quote.instrumentId = i + quote.bidPrice = i * 100 + quote.askPrice = i * 1000 + quote.bidQuantity = i * 10 + quote.askQuantity = i * 100 + quotes.append(quote) + + msg = sqf_oe.QuoteMessage() + msg.timestamp = key + msg.someInfo = 'a' * 32 + msg.quotes = quotes + return msg + + # Step3: Send the message to the server. + sqf_session.send_message(msg) + + # Step4: receive the first message from the server. + output = await sqf_session.receive_message() + if isinstance(output, sqf_oe.QuoteAccepted): + print("Quote accepted") + + # Step5: Close the session + print("Closing the sqf session...") + await sqf_session.close() + + + if __name__ == '__main__': + asyncio.run(main()) + +*A simple SQF send and receive program*