itchfeed 1.0.0__py3-none-any.whl

itch/parser.py

@@ -0,0 +1,180 @@
+from queue import Queue
+from typing import BinaryIO, List
+
+from itch import messages as msg
+from itch.messages import MarketMessage
+
+class MessageParser(object):
+    """
+    A market message parser for ITCH 5.0 data.
+
+    """
+
+    def __init__(self, message_type: bytes = msg.MESSAGES):
+        self.message_type = message_type
+
+    def read_message_from_file(
+        self,
+        file: BinaryIO,
+        cachesize: int = 4096,
+    ) -> List[MarketMessage]:
+        max_message_size = 52
+        file_end_reached = False
+
+        data_buffer = file.read(cachesize)
+        buffer_len = len(data_buffer)
+        messages: List[MarketMessage] = []
+
+        while not file_end_reached:
+            if buffer_len < 2:
+                new_data = file.read(cachesize)
+                if not new_data:
+                    break
+                data_buffer += new_data
+                buffer_len = len(data_buffer)
+                continue
+
+            if data_buffer[0:1] != b"\x00":
+                raise ValueError(
+                    "Unexpected byte: " + str(data_buffer[0:1], encoding="ascii")
+                )
+
+            message_len = data_buffer[1]
+            total_len = 2 + message_len
+
+            if buffer_len < total_len:
+                # Wait for more data if message is incomplete
+                new_data = file.read(cachesize)
+                if not new_data:
+                    break
+                data_buffer += new_data
+                buffer_len = len(data_buffer)
+                continue
+            message_data = data_buffer[2:total_len]
+            message = self.get_message_type(message_data)
+
+            if message.message_type in self.message_type:
+                messages.append(message)
+
+            if message.message_type == b"S":  # System message
+                if message.event_code == b"C":  # End of messages
+                    break
+
+            # Update buffer
+            data_buffer = data_buffer[total_len:]
+            buffer_len = len(data_buffer)
+
+            if buffer_len < max_message_size and not file_end_reached:
+                new_data = file.read(cachesize)
+                if not new_data:
+                    file_end_reached = True
+                else:
+                    data_buffer += new_data
+                    buffer_len = len(data_buffer)
+
+        return messages
+
+    def read_message_from_bytes(self, data: bytes):
+        """
+        Process one or multiple ITCH binary messages from a raw bytes input.
+
+        Args:
+            data (bytes): Binary blob containing one or more ITCH messages.
+
+        Returns:
+            Queue: A queue containing parsed ITCH message objects.
+
+        Notes:
+            - Each message must be prefixed with a 0x00 header and a length byte.
+            - No buffering is done here — this is meant for real-time decoding.
+        """
+
+        offset = 0
+        messages = Queue()
+        while offset + 2 <= len(data):
+            # Each message starts with: 1-byte header (0x00) 1-byte length
+            if data[offset : offset + 1] != b"\x00":
+                raise ValueError(
+                    f"Unexpected start byte at offset {offset}: "
+                    f"{str(data[offset : offset + 1], encoding='ascii')}"
+                )
+
+            msg_len = data[offset + 1]
+            total_len = 2 + msg_len
+
+            if offset + total_len > len(data):
+                break
+
+            raw_msg = data[offset + 2 : offset + total_len]
+            message = self.get_message_type(raw_msg)
+
+            if message.message_type in self.message_type:
+                messages.put(message)
+
+            if message.message_type == b"S":  # System message
+                if message.event_code == b"C":  # End of messages
+                    break
+
+            offset += total_len
+
+        return messages
+
+    def get_message_type(self, message: bytes):
+        """
+        Take an entire bytearray and return the appropriate ITCH message
+        instance based on the message type indicator (first byte of the message).
+
+        All message type indicators are single ASCII characters.
+        """
+        message_type = message[0:1]
+        match message_type:
+            case b"S":
+                return msg.SystemEventMessage(message)
+            case b"R":
+                return msg.StockDirectoryMessage(message)
+            case b"H":
+                return msg.StockTradingActionMessage(message)
+            case b"Y":
+                return msg.RegSHOMessage(message)
+            case b"L":
+                return msg.MarketParticipantPositionMessage(message)
+            case b"V":
+                return msg.MWCBDeclineLeveMessage(message)
+            case b"W":
+                return msg.MWCBStatusMessage(message)
+            case b"K":
+                return msg.IPOQuotingPeriodUpdateMessage(message)
+            case b"J":
+                return msg.LULDAuctionCollarMessage(message)
+            case b"h":
+                return msg.OperationalHaltMessage(message)
+            case b"A":
+                return msg.AddOrderNoMPIAttributionMessage(message)
+            case b"F":
+                return msg.AddOrderMPIDAttribution(message)
+            case b"E":
+                return msg.OrderExecutedMessage(message)
+            case b"C":
+                return msg.OrderExecutedWithPriceMessage(message)
+            case b"X":
+                return msg.OrderCancelMessage(message)
+            case b"D":
+                return msg.OrderDeleteMessage(message)
+            case b"U":
+                return msg.OrderReplaceMessage(message)
+            case b"P":
+                return msg.NonCrossTradeMessage(message)
+            case b"Q":
+                return msg.CrossTradeMessage(message)
+            case b"B":
+                return msg.BrokenTradeMessage(message)
+            case b"I":
+                return msg.NOIIMessage(message)
+            case b"N":
+                return msg.RetailPriceImprovementIndicator(message)
+            case b"O":
+                return msg.DLCRMessage(message)
+            case _:
+                raise ValueError(
+                    f"Unknown message type: {message_type.decode(encoding='ascii')}"
+                )

itchfeed-1.0.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: itchfeed
+Version: 1.0.0
+Summary: Simple parser for ITCH messages
+Home-page: https://github.com/bbalouki/itch
+Author: Bertin Balouki SIMYELI
+Author-email: <bertin@bbstrader.com>
+Maintainer: Bertin Balouki SIMYELI
+License: The MIT License (MIT)
+Project-URL: Source Code, https://github.com/bbalouki/itch
+Keywords: Finance,Financial,Quantitative,Equities,Data,Feed,ETFs,Funds,Trading,Investing,Portfolio,Optimization,Performance
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
+
+# Nasdaq TotalView-ITCH 5.0 Parser
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) <!-- Choose your license -->
+
+A Python library for parsing binary data conforming to the Nasdaq TotalView-ITCH 5.0 protocol specification. This parser converts the raw byte stream into structured Python objects, making it easier to work with Nasdaq market data.
+
+## Overview
+
+The Nasdaq TotalView-ITCH 5.0 protocol is a binary protocol used by Nasdaq to disseminate full order book depth, trade information, and system events for equities traded on its execution system. This parser handles the low-level details of reading the binary format, unpacking fields according to the specification, and presenting the data as intuitive Python objects.
+
+## Features
+
+*   **Parses ITCH 5.0 Binary Data:** Accurately interprets the binary message structures defined in the official specification.
+*   **Supports All Standard Message Types:** Implements classes for all messages defined in the ITCH 5.0 specification (System Event, Stock Directory, Add Order, Trade, etc.).
+*   **Object-Oriented Representation:** Each ITCH message type is represented by a dedicated Python class (`SystemEventMessage`, `AddOrderMessage`, etc.), inheriting from a common `MarketMessage` base class.
+*   **Flexible Input:** Reads and parses messages from:
+    *   Binary files (`.gz` or similar).
+    *   Raw byte streams (e.g., from network sockets).
+*   **Data Decoding:** Provides a `.decode()` method on each message object to convert it into a human-readable `dataclass` representation, handling:
+    *   Byte-to-string conversion (ASCII).
+    *   Stripping padding spaces.
+    *   Price decoding based on defined precision.
+*   **Timestamp Handling:** Correctly reconstructs the 6-byte (48-bit) nanosecond timestamps.
+*   **Price Handling:** Decodes fixed-point price fields into floating-point numbers based on the standard 4 or 8 decimal place precision.
+*   **Pure Python:** Relies only on the Python standard library . No external dependencies required.
+
+## Installation
+
+You can install this project using ``pip``
+
+1.  **Clone the repository (or download the source code):**
+    ```bash
+    pip install itch
+    ```
+2.  **Import the necessary modules** directly into your Python project:
+    ```python
+    from itch.parser import MessageParser
+    from itch.messages import ModifyOrderMessage
+    ```
+
+## Usage
+
+### Parsing from a Binary File
+
+This is useful for processing historical ITCH data stored in files. The `MessageParser` handles buffering efficiently.
+
+```python
+from itch import MessageParser
+from itch.messages import AddOrderMessage, TradeMessage
+
+# Initialize the parser. Optionally filter messages by type.
+# parser = MessageParser(message_type=b"AP") # Only parse AddOrder and NonCrossTrade messages
+parser = MessageParser()
+
+# Path to your ITCH 5.0 data file
+itch_file_path = 'path/to/your/data'
+# you can find sample data [here](https://emi.nasdaq.com/ITCH/Nasdaq%20ITCH/)
+
+try:
+    with open(itch_file_path, 'rb') as itch_file:
+        # read_message_from_file returns a list of parsed message objects
+        parsed_messages = parser.read_message_from_file(itch_file)
+
+        print(f"Parsed {len(parsed_messages)} messages.")
+
+        # Process the messages
+        for message in parsed_messages:
+            # Access attributes directly
+            print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
+
+            if isinstance(message, AddOrderMessage):
+                print(f"  Add Order: Ref={message.order_reference_number}, "
+                      f"Side={message.buy_sell_indicator.decode()}, "
+                      f"Shares={message.shares}, Stock={message.stock.decode().strip()}, "
+                      f"Price={message.decode_price('price')}") 
+
+            elif isinstance(message, TradeMessage): 
+                 print(f"  Trade: Match={message.match_number}")
+                 # Access specific trade type attributes...
+
+            # Get a human-readable dataclass representation
+            decoded_msg = message.decode()
+            print(f"  Decoded: {decoded_msg}")
+
+except FileNotFoundError:
+    print(f"Error: File not found at {itch_file_path}")
+except Exception as e:
+    print(f"An error occurred: {e}")
+
+```
+
+### Parsing from Raw Bytes
+
+This is suitable for real-time processing, such as reading from a network stream.
+
+```python
+from itch import MessageParser
+from itch.messages import AddOrderMessage
+from queue import Queue
+
+# Initialize the parser
+parser = MessageParser()
+
+# Simulate receiving a chunk of binary data (e.g., from a network socket)
+# This chunk contains multiple ITCH messages, each prefixed with 0x00 and length byte
+# Example: \x00\x0bS...\x00\x25R...\x00\x27F...
+raw_binary_data: bytes = b"..." # Your raw ITCH 5.0 data chunk
+
+# read_message_from_bytes returns a queue of parsed message objects
+message_queue: Queue = parser.read_message_from_bytes(raw_binary_data)
+
+print(f"Parsed {message_queue.qsize()} messages from the byte chunk.")
+
+# Process messages from the queue
+while not message_queue.empty():
+    message = message_queue.get()
+
+    print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
+
+    if isinstance(message, AddOrderMessage):
+         print(f"  Add Order: Ref={message.order_reference_number}, "
+               f"Stock={message.stock.decode().strip()}, Price={message.decode_price('price')}")
+
+    # Use the decoded representation
+    decoded_msg = message.decode(prefix="Decoded")
+    print(f"  Decoded: {decoded_msg}")
+
+```
+
+## Supported Message Types
+
+The parser supports the following ITCH 5.0 message types. Each message object has attributes corresponding to the fields defined in the specification. Refer to the class docstrings in `itch.messages` for detailed attribute descriptions.
+
+| Type (Byte) | Class Name                        | Description                                      |
+| :---------- | :-------------------------------- | :----------------------------------------------- |
+| `S`         | `SystemEventMessage`              | System Event Message                             |
+| `R`         | `StockDirectoryMessage`           | Stock Directory Message                          |
+| `H`         | `StockTradingActionMessage`       | Stock Trading Action Message                     |
+| `Y`         | `RegSHOMessage`                   | Reg SHO Short Sale Price Test Restricted Indicator |
+| `L`         | `MarketParticipantPositionMessage`| Market Participant Position message              |
+| `V`         | `MWCBDeclineLeveMessage`          | Market-Wide Circuit Breaker (MWCB) Decline Level |
+| `W`         | `MWCBStatusMessage`               | Market-Wide Circuit Breaker (MWCB) Status        |
+| `K`         | `IPOQuotingPeriodUpdateMessage`   | IPO Quoting Period Update Message                |
+| `J`         | `LULDAuctionCollarMessage`        | LULD Auction Collar Message                      |
+| `h`         | `OperationalHaltMessage`          | Operational Halt Message                         |
+| `A`         | `AddOrderNoMPIAttributionMessage` | Add Order (No MPID Attribution)                  |
+| `F`         | `AddOrderMPIDAttribution`         | Add Order (MPID Attribution)                     |
+| `E`         | `OrderExecutedMessage`            | Order Executed Message                           |
+| `C`         | `OrderExecutedWithPriceMessage`   | Order Executed With Price Message                |
+| `X`         | `OrderCancelMessage`              | Order Cancel Message                             |
+| `D`         | `OrderDeleteMessage`              | Order Delete Message                             |
+| `U`         | `OrderReplaceMessage`             | Order Replace Message                            |
+| `P`         | `NonCrossTradeMessage`            | Trade Message (Non-Cross)                        |
+| `Q`         | `CrossTradeMessage`               | Cross Trade Message                              |
+| `B`         | `BrokenTradeMessage`              | Broken Trade / Order Execution Message           |
+| `I`         | `NOIIMessage`                     | Net Order Imbalance Indicator (NOII) Message     |
+| `N`         | `RetailPriceImprovementIndicator` | Retail Price Improvement Indicator (RPII)        |
+| `O`         | `DLCRMessage`                     | Direct Listing with Capital Raise Message        |
+
+## Data Representation
+
+*   **Base Class:** All message classes inherit from `itch.messages.MarketMessage`. This base class provides common attributes like `message_type`, `description`, `stock_locate`, `tracking_number`, and `timestamp`.
+*   **Timestamp:** Timestamps are stored as 64-bit integers representing nanoseconds since midnight. The `set_timestamp` and `split_timestamp` methods handle the conversion from/to the 6-byte representation used in the raw messages.
+*   **Prices:** Price fields (e.g., `price`, `execution_price`, `level1_price`) are stored as integers in the raw message objects. Use the `message.decode_price('attribute_name')` method to get the correctly scaled floating-point value (usually 4 or 8 decimal places, defined by `message.price_precision`).
+*   **Strings:** Alpha fields are stored as `bytes`. The `.decode()` method converts these to ASCII strings and removes right-padding spaces.
+*   **Decoded Objects:** The `message.decode()` method returns a standard Python `dataclass` instance. This provides a clean, immutable, and easily inspectable representation of the message content with correct data types (float for prices, string for text).
+
+## Contributing
+
+Contributions are welcome! If you find a bug, have a suggestion, or want to add a feature:
+
+1.  **Check Issues:** See if an issue for your topic already exists.
+2.  **Open an Issue:** If not, open a new issue describing the bug or feature request.
+3.  **Fork and Branch:** Fork the repository and create a new branch for your changes.
+4.  **Implement Changes:** Make your code changes, ensuring adherence to the ITCH 5.0 specification. Add tests if applicable.
+5.  **Submit Pull Request:** Open a pull request from your branch to the main repository, referencing the relevant issue.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## References
+*   **Nasdaq TotalView-ITCH 5.0 Specification:** The official [documentation](https://www.nasdaqtrader.com/content/technicalsupport/specifications/dataproducts/NQTVITCHspecification.pdf) is the definitive source for protocol details.

itchfeed-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+itch/__init__.py,sha256=dDZxG37vg_z0nHAcdP1U1qDwneSZwVZsFHUBya57Pos,346
+itch/indicators.py,sha256=-4LJpga7foAcVz1cJnUy4tsIwZO8AtUlRp5Qq79_9xE,6748
+itch/messages.py,sha256=6pEf2mAkeHozBq5GqgBiRqGBLZeA8uJUAQrjqx6TWQk,63481
+itch/parser.py,sha256=7SOfZZN9E8ApAK6Vsy94c0VBa-olZ1vq6YgZ0PNA10g,6391
+itchfeed-1.0.0.dist-info/licenses/LICENSE,sha256=gpnhiId0PkFDCAB3XYbwhFHhw_J0AZ5pey1ntsjxDkk,1110
+itchfeed-1.0.0.dist-info/METADATA,sha256=WkE4w13zoNiACriXCxMJ1x3qiADx8yB11bJQsYA1p3Y,11933
+itchfeed-1.0.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+itchfeed-1.0.0.dist-info/top_level.txt,sha256=xwsOYShvy3gc1rfyitCTgSxBZDGG1y6bfQxkdhIGmEM,5
+itchfeed-1.0.0.dist-info/RECORD,,

itchfeed-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

itchfeed-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Bertin Balouki SIMYELI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

itchfeed-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+itch