readme changes

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/)
+

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

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

docs/api_reference_sqf.rst

@@ -0,0 +1,22 @@
+.. _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

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

docs/user_guide_create_new_project.rst

@@ -33,14 +33,15 @@ Refer to the `tox documentation <https://tox.wiki/en/latest/installation.html>`_
         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:
+        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 <https://tox.wiki/en/latest/installation.html>`_
         |    │   │   └── 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.
 

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_<app_name>.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 `<app_name>.xml` as follows,
+
+.. code-block:: XML
+
+    <root>
+        <fielddef-root>
+            <field name="instrumentId" type="uint_8"/>
+            <field name="price" type="uint_8"/>
+            <field name="quantity" type="uint_8"/>
+            <field name="timestamp" type="uint_8"/>
+            <field name="someInfo" type="str_iso-8859-1_n" length="32"/>
+        </fielddef-root>
+        <records-root>
+            <record id="Quote">
+                <fields>
+                    <field def="instrumentId"/>
+                    <field name="bidPrice" def="price"/>
+                    <field name="askPrice" def="price"/>
+                    <field name="bidQuantity" def="quantity"/>
+                    <field name="askQuantity" def="quantity"/>
+                </fields>
+            </record>
+        </records-root>
+        <messages-root>
+            <message id="QuoteMessage" message-id="1" direction="incoming">
+                <fields>
+                    <field def="timestamp"/>
+                    <field def="someInfo"/>
+                    <field name="quotes" type="record:Quote" array="true" endian="big"/>
+                </fields>
+            </message>
+            <message id="QuoteAccepted" message-id="2" direction="outgoing">
+                <fields>
+                    <field name="quoteId" type="uint_8"/>
+                </fields>
+            </message>
+        </messages-root>
+    </root>
+
+
+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*