itchfeed 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
itch/__init__.py CHANGED
@@ -6,5 +6,6 @@ __author__ = "Bertin Balouki SIMYELI"
6
6
  __copyright__ = "2025 Bertin Balouki SIMYELI"
7
7
  __email__ = "bertin@bbstrader.com"
8
8
  __license__ = "MIT"
9
- __version__ = "1.0.0"
9
+ __version__ = "1.0.4"
10
+
10
11
 
itch/messages.py CHANGED
@@ -35,6 +35,13 @@ class MarketMessage(object):
35
35
  def __repr__(self):
36
36
  return repr(self.decode())
37
37
 
38
+ def pack(self) -> bytes:
39
+ """
40
+ Packs the message into bytes using the defined message_pack_format.
41
+ This method should be overridden by subclasses to include specific fields.
42
+ """
43
+ pass
44
+
38
45
  def set_timestamp(self, ts1: int, ts2: int):
39
46
  """
40
47
  Reconstructs a 6-byte timestamp (48 bits) from two 32-bit unsigned integers.
@@ -1598,3 +1605,51 @@ messages: Dict[bytes, Type[MarketMessage]] = {
1598
1605
  b"N": RetailPriceImprovementIndicator,
1599
1606
  b"O": DLCRMessage,
1600
1607
  }
1608
+
1609
+
1610
+ def create_message(message_type: bytes, **kwargs) -> Type[MarketMessage]:
1611
+ """
1612
+ Creates a new message of a given type with specified attributes.
1613
+
1614
+ This function simplifies the process of message creation by handling
1615
+ the instantiation and attribute setting for any valid message type.
1616
+ It's particularly useful for simulating trading environments or
1617
+ generating test data without manually packing and unpacking bytes.
1618
+
1619
+ Args:
1620
+ message_type (bytes):
1621
+ A single-byte identifier for the message type (e.g., b'A'
1622
+ for AddOrderNoMPIAttributionMessage).
1623
+ **kwargs:
1624
+ Keyword arguments representing the attributes of the message.
1625
+ These must match the attributes expected by the message class
1626
+ (e.g., `stock_locate`, `timestamp`, `price`).
1627
+
1628
+ Returns:
1629
+ MarketMessage:
1630
+ An instance of the corresponding message class, populated with
1631
+ the provided attributes.
1632
+
1633
+ Raises:
1634
+ ValueError:
1635
+ If the `message_type` is not found in the registered messages.
1636
+ """
1637
+ message_class = messages.get(message_type)
1638
+ if not message_class:
1639
+ raise ValueError(f"Unknown message type: {message_type.decode()}")
1640
+
1641
+ # Create a new instance without calling __init__
1642
+ # __init__ is for unpacking, not creating
1643
+ instance = message_class.__new__(message_class)
1644
+
1645
+ # Set attributes from kwargs
1646
+ for key, value in kwargs.items():
1647
+ if key == 'timestamp':
1648
+ # Timestamps are 48-bit, so we need to mask the original value
1649
+ value &= ((1 << 48) - 1)
1650
+ setattr(instance, key, value)
1651
+
1652
+ # Set the message_type attribute on the instance, as it's used by pack()
1653
+ instance.message_type = message_type
1654
+
1655
+ return instance
itch/parser.py CHANGED
@@ -1,5 +1,5 @@
1
1
  from queue import Queue
2
- from typing import BinaryIO, List
2
+ from typing import BinaryIO, List, Type
3
3
 
4
4
  from itch.messages import MESSAGES, MarketMessage
5
5
  from itch.messages import messages as msgs
@@ -157,7 +157,7 @@ class MessageParser(object):
157
157
 
158
158
  return messages
159
159
 
160
- def get_message_type(self, message: bytes):
160
+ def get_message_type(self, message: bytes) -> Type[MarketMessage]:
161
161
  """
162
162
  Take an entire bytearray and return the appropriate ITCH message
163
163
  instance based on the message type indicator (first byte of the message).
@@ -0,0 +1,496 @@
1
+ Metadata-Version: 2.4
2
+ Name: itchfeed
3
+ Version: 1.0.4
4
+ Summary: Simple parser for ITCH messages
5
+ Home-page: https://github.com/bbalouki/itch
6
+ Download-URL: https://pypi.org/project/itchfeed/
7
+ Author: Bertin Balouki SIMYELI
8
+ Author-email: <bertin@bbstrader.com>
9
+ Maintainer: Bertin Balouki SIMYELI
10
+ License: The MIT License (MIT)
11
+ Project-URL: Source Code, https://github.com/bbalouki/itch
12
+ Keywords: Finance,Financial,Quantitative,Equities,Totalview-ITCH,Totalview,Nasdaq-ITCH,Nasdaq,ITCH,Data,Feed,ETFs,Funds,Trading,Investing
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Financial and Insurance Industry
16
+ Classifier: Topic :: Office/Business :: Financial :: Investment
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Operating System :: OS Independent
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: pytest
22
+ Dynamic: author
23
+ Dynamic: author-email
24
+ Dynamic: classifier
25
+ Dynamic: description
26
+ Dynamic: description-content-type
27
+ Dynamic: download-url
28
+ Dynamic: home-page
29
+ Dynamic: keywords
30
+ Dynamic: license
31
+ Dynamic: license-file
32
+ Dynamic: maintainer
33
+ Dynamic: project-url
34
+ Dynamic: requires-dist
35
+ Dynamic: summary
36
+
37
+ # Nasdaq TotalView-ITCH 5.0 Parser
38
+ [![PYPI Version](https://img.shields.io/pypi/v/itchfeed)](https://pypi.org/project/itchfeed/)
39
+ [![PyPi status](https://img.shields.io/pypi/status/itchfeed.svg?maxAge=60)](https://pypi.python.org/pypi/itchfeed)
40
+ [![Supported Python Versions](https://img.shields.io/pypi/pyversions/itchfeed)](https://pypi.org/project/itchfeed/)
41
+ [![PyPI Downloads](https://static.pepy.tech/badge/itchfeed)](https://pepy.tech/projects/itchfeed)
42
+ [![CodeFactor](https://www.codefactor.io/repository/github/bbalouki/itch/badge)](https://www.codefactor.io/repository/github/bbalouki/itch)
43
+ [![LinkedIn](https://img.shields.io/badge/LinkedIn-grey?logo=Linkedin&logoColor=white)](https://www.linkedin.com/in/bertin-balouki-simyeli-15b17a1a6/)
44
+ [![PayPal Me](https://img.shields.io/badge/PayPal%20Me-blue?logo=paypal)](https://paypal.me/bertinbalouki?country.x=SN&locale.x=en_US)
45
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
46
+
47
+ ## Table of Contents
48
+
49
+ * [Overview](#overview)
50
+ * [Features](#features)
51
+ * [Installation](#installation)
52
+ * [Usage](#usage)
53
+ * [Parsing from a Binary File](#parsing-from-a-binary-file)
54
+ * [Parsing from Raw Bytes](#parsing-from-raw-bytes)
55
+ * [Creating Messages Programmatically](#creating-messages-programmatically)
56
+ * [Example with Real-World Sample Data](#example-with-real-world-sample-data)
57
+ * [Interpreting Market Data (Conceptual Overview)](#interpreting-market-data-conceptual-overview)
58
+ * [Supported Message Types](#supported-message-types)
59
+ * [Data Representation](#data-representation)
60
+ * [Common Attributes of `MarketMessage`](#common-attributes-of-marketmessage)
61
+ * [Common Methods of `MarketMessage`](#common-methods-of-marketmessage)
62
+ * [Serializing Messages with `pack()`](#serializing-messages-with-pack)
63
+ * [Data Types in Parsed Messages](#data-types-in-parsed-messages)
64
+ * [Error Handling](#error-handling)
65
+ * [Handling Strategies](#handling-strategies)
66
+ * [Contributing](#contributing)
67
+ * [License](#license)
68
+ * [References](#references)
69
+
70
+ 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.
71
+
72
+ ## Overview
73
+
74
+ 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.
75
+
76
+ ## Features
77
+
78
+ * **Parses ITCH 5.0 Binary Data:** Accurately interprets the binary message structures defined in the official specification.
79
+ * **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.).
80
+ * **Object-Oriented Representation:** Each ITCH message type is represented by a dedicated Python class (`SystemEventMessage`, `AddOrderMessage`, etc.), inheriting from a common `MarketMessage` base class.
81
+ * **Flexible Input:** Reads and parses messages from:
82
+ * Binary files (`.gz` or similar).
83
+ * Raw byte streams (e.g., from network sockets).
84
+ * **Data Decoding:** Provides a `.decode()` method on each message object to convert it into a human-readable `dataclass` representation, handling:
85
+ * Byte-to-string conversion (ASCII).
86
+ * Stripping padding spaces.
87
+ * Price decoding based on defined precision.
88
+ * **Timestamp Handling:** Correctly reconstructs the 6-byte (48-bit) nanosecond timestamps.
89
+ * **Price Handling:** Decodes fixed-point price fields into floating-point numbers based on the standard 4 or 8 decimal place precision.
90
+ * **Pure Python:** Relies only on the Python standard library. No external dependencies required.
91
+
92
+ ## Installation
93
+
94
+ The recommended way to install `itchfeed` is from PyPI using `pip`:
95
+ ```bash
96
+ pip install itchfeed
97
+ ```
98
+
99
+ If you want to contribute to development or need the latest unreleased version, you can clone the repository:
100
+ ```bash
101
+ git clone https://github.com/bbalouki/itch.git
102
+ cd itch
103
+ # Then you might install it in editable mode or run tests, etc.
104
+ ```
105
+
106
+ After installation (typically via pip), import the necessary modules directly into your Python project:
107
+ ```python
108
+ from itch.parser import MessageParser
109
+ from itch.messages import ModifyOrderMessage
110
+ ```
111
+
112
+ ## Usage
113
+
114
+ ### Parsing from a Binary File
115
+
116
+ This is useful for processing historical ITCH data stored in files. The `MessageParser` handles buffering efficiently.
117
+
118
+ ```python
119
+ from itch.parser import MessageParser
120
+ from itch.messages import AddOrderMessage, TradeMessage
121
+
122
+ # Initialize the parser.
123
+ # By default, MessageParser() will parse all known message types.
124
+ # Optionally, you can filter for specific messages by providing the `message_type` parameter.
125
+ # This parameter takes a bytes string containing the characters of the message types you want to parse.
126
+ # For example, to only parse Add Order (No MPID 'A'), Stock Directory ('R'), and Stock Trading Action ('H') messages:
127
+ # parser = MessageParser(message_type=b"ARH")
128
+ # Refer to the MESSAGES constant in `itch.messages` or the table in the "Supported Message Types"
129
+ # section for all available type codes.
130
+ parser = MessageParser() # Parses all messages by default
131
+
132
+ # Path to your ITCH 5.0 data file
133
+ itch_file_path = 'path/to/your/data'
134
+ # you can find sample data [here](https://emi.nasdaq.com/ITCH/Nasdaq%20ITCH/)
135
+
136
+ # The `read_message_from_file()` method reads the ITCH data in chunks.
137
+ # - `cachesize` (optional, default: 65536 bytes): This parameter determines the size of data chunks
138
+ # read from the file at a time. Adjusting this might impact performance for very large files
139
+ # or memory usage, but the default is generally suitable.
140
+ # The parsing process stops when either:
141
+ # 1. The end of the file is reached.
142
+ # 2. A System Event Message (type 'S') with an event_code of 'C' (End of Messages)
143
+ # is encountered, signaling the end of the ITCH feed for the session.
144
+
145
+ try:
146
+ with open(itch_file_path, 'rb') as itch_file:
147
+ # read_message_from_file returns a list of parsed message objects
148
+ parsed_messages = parser.read_message_from_file(itch_file) # You can also pass cachesize here, e.g., parser.read_message_from_file(itch_file, cachesize=131072)
149
+
150
+ print(f"Parsed {len(parsed_messages)} messages.")
151
+
152
+ # Process the messages
153
+ for message in parsed_messages:
154
+ # Access attributes directly
155
+ print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
156
+
157
+ if isinstance(message, AddOrderMessage):
158
+ print(f" Add Order: Ref={message.order_reference_number}, "
159
+ f"Side={message.buy_sell_indicator.decode()}, "
160
+ f"Shares={message.shares}, Stock={message.stock.decode().strip()}, "
161
+ f"Price={message.decode_price('price')}")
162
+
163
+ elif isinstance(message, TradeMessage):
164
+ print(f" Trade: Match={message.match_number}")
165
+ # Access specific trade type attributes...
166
+
167
+ # Get a human-readable dataclass representation
168
+ decoded_msg = message.decode()
169
+ print(f" Decoded: {decoded_msg}")
170
+
171
+ except FileNotFoundError:
172
+ print(f"Error: File not found at {itch_file_path}")
173
+ except Exception as e:
174
+ print(f"An error occurred: {e}")
175
+
176
+ ```
177
+
178
+ ### Parsing from Raw Bytes
179
+
180
+ This is suitable for real-time processing, such as reading from a network stream.
181
+
182
+ ```python
183
+ from itch.parser import MessageParser
184
+ from itch.messages import AddOrderMessage
185
+ from queue import Queue
186
+
187
+ # Initialize the parser
188
+ parser = MessageParser()
189
+
190
+ # Simulate receiving a chunk of binary data (e.g., from a network socket)
191
+ # This chunk contains multiple ITCH messages, each prefixed with 0x00 and length byte
192
+ # Example: \x00\x0bS...\x00\x25R...\x00\x27F...
193
+ raw_binary_data: bytes = b"..." # Your raw ITCH 5.0 data chunk
194
+
195
+ # read_message_from_bytes returns a queue of parsed message objects
196
+ message_queue: Queue = parser.read_message_from_bytes(raw_binary_data)
197
+
198
+ print(f"Parsed {message_queue.qsize()} messages from the byte chunk.")
199
+
200
+ # Process messages from the queue
201
+ while not message_queue.empty():
202
+ message = message_queue.get()
203
+
204
+ print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
205
+
206
+ if isinstance(message, AddOrderMessage):
207
+ print(f" Add Order: Ref={message.order_reference_number}, "
208
+ f"Stock={message.stock.decode().strip()}, Price={message.decode_price('price')}")
209
+
210
+ # Use the decoded representation
211
+ decoded_msg = message.decode(prefix="Decoded")
212
+ print(f" Decoded: {decoded_msg}")
213
+
214
+ ```
215
+
216
+ ### Creating Messages Programmatically
217
+
218
+ In addition to parsing, `itch` provides a simple way to create ITCH message objects from scratch. This is particularly useful for:
219
+ - **Testing:** Generating specific message sequences to test your own downstream applications.
220
+ - **Simulation:** Building custom market simulators that produce ITCH-compliant data streams.
221
+ - **Data Generation:** Creating custom datasets for analysis or backtesting.
222
+
223
+ The `create_message` function is the primary tool for this purpose. It takes a `message_type` and keyword arguments corresponding to the desired message attributes.
224
+
225
+ Here's a basic example of how to create a `SystemEventMessage` to signal the "Start of Messages":
226
+
227
+ ```python
228
+ from itch.messages import create_message, SystemEventMessage
229
+
230
+ # Define the attributes for the message
231
+ event_attributes = {
232
+ "stock_locate": 1,
233
+ "tracking_number": 2,
234
+ "timestamp": 1651500000 * 1_000_000_000,
235
+ "event_code": b"O"
236
+ }
237
+
238
+ # Create the message object
239
+ system_event_message = create_message(b"S", **event_attributes)
240
+
241
+ # You can now work with this object just like one from the parser
242
+ print(isinstance(system_event_message, SystemEventMessage))
243
+ # Expected output: True
244
+
245
+ print(system_event_message)
246
+ # Expected output: SystemEventMessage(description='System Event Message', event_code='O', message_format='!HHHIc', message_pack_format='!cHHHIc', message_size=12, message_type='S', price_precision=4, stock_locate=1, timestamp=86311638581248, tracking_number=2)
247
+ ```
248
+
249
+ ### Example with Real-World Sample Data
250
+
251
+ You can also use the sample data provided in `tests/data.py` to create messages, simulating a more realistic scenario.
252
+
253
+ ```python
254
+ from itch.messages import create_message, AddOrderNoMPIAttributionMessage
255
+ from tests.data import TEST_DATA
256
+
257
+ # Get the sample data for an "Add Order" message (type 'A')
258
+ add_order_data = TEST_DATA[b"A"]
259
+
260
+ # Create the message
261
+ add_order_message = create_message(b"A", **add_order_data)
262
+
263
+ # Verify the type
264
+ print(isinstance(add_order_message, AddOrderNoMPIAttributionMessage))
265
+ # Expected output: True
266
+
267
+ # Access its attributes
268
+ print(f"Stock: {add_order_message.stock.decode().strip()}")
269
+ # Expected output: Stock: AAPL
270
+
271
+ print(f"Price: {add_order_message.decode_price('price')}")
272
+ # Expected output: Price: 150.1234
273
+
274
+ # Test all message types in the sample data
275
+ for message_type, sample_data in TEST_DATA.items():
276
+ print(f"Creating message of type {message_type}")
277
+ message = create_message(message_type, **sample_data)
278
+ print(f"Created message: {message}")
279
+ print(f"Packed message: {message.pack()}")
280
+ print(f"Message size: {message.message_size}")
281
+ print(f"Message Attributes: {message.get_attributes()}")
282
+ assert len(message.pack()) == message.message_size
283
+ print()
284
+ ```
285
+
286
+ By leveraging `create_message`, you can build robust test suites for your trading algorithms, compliance checks, or data analysis pipelines without needing a live data feed.
287
+
288
+ ## Interpreting Market Data (Conceptual Overview)
289
+
290
+ Parsing individual ITCH messages is the first step; understanding market dynamics often requires processing and correlating a sequence of these messages. This library provides the tools to decode messages, but interpreting their collective meaning requires building further logic.
291
+
292
+ A common use case is to build and maintain a local representation of the order book for a particular stock. Here's a simplified, high-level overview of how different messages interact in this context:
293
+
294
+ * **Building the Book:**
295
+ * `AddOrderNoMPIAttributionMessage` (Type `A`) and `AddOrderMPIDAttribution` (Type `F`) represent new orders being added to the order book. These messages provide the initial size, price, and side (buy/sell) of the order, along with a unique `order_reference_number`.
296
+
297
+ * **Modifying and Removing Orders:**
298
+ * `OrderExecutedMessage` (Type `E`) and `OrderExecutedWithPriceMessage` (Type `C`) indicate that a portion or all of an existing order (identified by `order_reference_number`) has been executed. The executed shares should be subtracted from the remaining quantity of the order on the book. If the execution fully fills the order, it's removed.
299
+ * `OrderCancelMessage` (Type `X`) indicates that a number of shares from an existing order (identified by `order_reference_number`) have been canceled. The canceled shares should be subtracted from the order's quantity. If this results in zero shares, the order is removed.
300
+ * `OrderDeleteMessage` (Type `D`) indicates that an entire existing order (identified by `order_reference_number`) has been deleted from the book.
301
+ * `OrderReplaceMessage` (Type `U`) is effectively a cancel-and-replace operation. The order identified by `order_reference_number` should be removed, and a new order with a `new_order_reference_number` and new characteristics (size, price) should be added to the book.
302
+
303
+ * **Observing Trades:**
304
+ * `NonCrossTradeMessage` (Type `P`) and `CrossTradeMessage` (Type `Q`) provide information about actual trades that have occurred. While `OrderExecutedMessage` and `OrderExecutedWithPriceMessage` detail the impact on specific orders in the book, `TradeMessage` types provide a direct stream of trade prints.
305
+
306
+ **Important Considerations:**
307
+
308
+ This is a very simplified overview. Building a complete and accurate order book or a sophisticated trading analysis tool requires:
309
+ * Careful handling of message sequences and their `timestamp` order.
310
+ * Managing state for each `order_reference_number` across multiple messages.
311
+ * Understanding the nuances of different order types, market events (like halts or auctions signaled by `StockTradingActionMessage` or `NOIIMessage`), and how they impact the book.
312
+ * Adhering closely to the official Nasdaq TotalView-ITCH 5.0 specification for detailed business logic.
313
+
314
+ This library aims to handle the binary parsing, allowing you to focus on implementing this higher-level interpretative logic.
315
+
316
+ ## Supported Message Types
317
+
318
+ 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.
319
+
320
+ | Type (Byte) | Class Name | Description |
321
+ | :---------- | :-------------------------------- | :----------------------------------------------- |
322
+ | `S` | `SystemEventMessage` | System Event Message. Signals a market or data feed handler event. <br> `event_code` indicates the type: <br> - `O`: Start of Messages <br> - `S`: Start of System Hours <br> - `Q`: Start of Market Hours <br> - `M`: End of Market Hours <br> - `E`: End of System Hours <br> - `C`: End of Messages |
323
+ | `R` | `StockDirectoryMessage` | Stock Directory Message. Disseminated for all active symbols at the start of each trading day. <br> Key fields include: <br> - `market_category`: (e.g., `Q`: NASDAQ Global Select Market) <br> - `financial_status_indicator`: (e.g., `D`: Deficient) <br> - `issue_classification`: (e.g., `A`: American Depositary Share) <br> - `issue_sub_type`: (e.g., `AI`: ADR representing an underlying foreign issuer) |
324
+ | `H` | `StockTradingActionMessage` | Stock Trading Action Message. Indicates the current trading status of a security. <br> Key fields: <br> - `trading_state`: (e.g., `H`: Halted, `T`: Trading) <br> - `reason`: (e.g., `T1`: Halt due to news pending) |
325
+ | `Y` | `RegSHOMessage` | Reg SHO Short Sale Price Test Restricted Indicator. <br> `reg_sho_action` indicates status: <br> - `0`: No price test in place <br> - `1`: Restriction in effect (intra-day drop) <br> - `2`: Restriction remains in effect |
326
+ | `L` | `MarketParticipantPositionMessage`| Market Participant Position message. Provides status for each Nasdaq market participant firm in an issue. <br> Key fields: <br> - `primary_market_maker`: (e.g., `Y`: Yes, `N`: No) <br> - `market_maker_mode`: (e.g., `N`: Normal) <br> - `market_participant_state`: (e.g., `A`: Active) |
327
+ | `V` | `MWCBDeclineLeveMessage` | Market-Wide Circuit Breaker (MWCB) Decline Level Message. Informs recipients of the daily MWCB breach points. |
328
+ | `W` | `MWCBStatusMessage` | Market-Wide Circuit Breaker (MWCB) Status Message. Informs when a MWCB level has been breached. |
329
+ | `K` | `IPOQuotingPeriodUpdateMessage` | IPO Quoting Period Update Message. Indicates anticipated IPO quotation release time. |
330
+ | `J` | `LULDAuctionCollarMessage` | LULD Auction Collar Message. Indicates auction collar thresholds for a paused security. |
331
+ | `h` | `OperationalHaltMessage` | Operational Halt Message. Indicates an interruption of service on the identified security impacting only the designated Market Center. |
332
+ | `A` | `AddOrderNoMPIAttributionMessage` | Add Order (No MPID Attribution). A new unattributed order has been accepted and added to the displayable book. |
333
+ | `F` | `AddOrderMPIDAttribution` | Add Order (MPID Attribution). A new attributed order or quotation has been accepted. |
334
+ | `E` | `OrderExecutedMessage` | Order Executed Message. An order on the book has been executed in whole or in part. |
335
+ | `C` | `OrderExecutedWithPriceMessage` | Order Executed With Price Message. An order on the book has been executed at a price different from its initial display price. |
336
+ | `X` | `OrderCancelMessage` | Order Cancel Message. An order on the book is modified due to a partial cancellation. |
337
+ | `D` | `OrderDeleteMessage` | Order Delete Message. An order on the book is being cancelled. |
338
+ | `U` | `OrderReplaceMessage` | Order Replace Message. An order on the book has been cancel-replaced. |
339
+ | `P` | `NonCrossTradeMessage` | Trade Message (Non-Cross). Provides execution details for normal match events involving non-displayable order types. |
340
+ | `Q` | `CrossTradeMessage` | Cross Trade Message. Indicates completion of a cross process (Opening, Closing, Halt/IPO) for a specific security. |
341
+ | `B` | `BrokenTradeMessage` | Broken Trade / Order Execution Message. An execution on Nasdaq has been broken. |
342
+ | `I` | `NOIIMessage` | Net Order Imbalance Indicator (NOII) Message. <br> Key fields: <br> - `cross_type`: Context of the imbalance (e.g., `O`: Opening Cross, `C`: Closing Cross, `H`: Halt/IPO Cross, `A`: Extended Trading Close). <br> - `price_variation_indicator`: Deviation of Near Indicative Clearing Price from Current Reference Price (e.g., `L`: Less than 1%). <br> - `imbalance_direction`: (e.g., `B`: Buy imbalance, `S`: Sell imbalance, `N`: No imbalance, `O`: Insufficient orders to calculate) |
343
+ | `N` | `RetailPriceImprovementIndicator` | Retail Price Improvement Indicator (RPII). Identifies retail interest on Bid, Ask, or both. |
344
+ | `O` | `DLCRMessage` | Direct Listing with Capital Raise Message. Disseminated for DLCR securities once volatility test passes. |
345
+
346
+ ## Data Representation
347
+
348
+ All message classes inherit from `itch.messages.MarketMessage`. This base class provides a common structure and utility methods for all ITCH message types.
349
+
350
+ ### Common Attributes of `MarketMessage`
351
+
352
+ Each instance of a `MarketMessage` (and its subclasses) will have the following attributes:
353
+
354
+ * `message_type` (bytes): A single byte character identifying the type of the ITCH message (e.g., `b'S'` for System Event, `b'A'` for Add Order).
355
+ * `description` (str): A human-readable description of the message type (e.g., "System Event Message", "Add Order No MPID Attribution Message").
356
+ * `message_format` (str): An internal string defining the `struct` format for packing/unpacking the core message fields. This is primarily for internal parser use.
357
+ * `message_pack_format` (str): An internal string, often similar to `message_format`, specifically for packing operations. This is primarily for internal parser use.
358
+ * `message_size` (int): The size of the binary message in bytes, as read from the message header or defined by the specification.
359
+ * `timestamp` (int): A 64-bit integer representing the time of the event in nanoseconds since midnight. This is reconstructed from the 6-byte raw timestamp. See `set_timestamp()` and `split_timestamp()` methods.
360
+ * `stock_locate` (int): A code used to identify the stock for Nasdaq messages. Usually, this is the first field after the Message Type.
361
+ * `tracking_number` (int): A tracking number assigned by Nasdaq to each message.
362
+ * `price_precision` (int): An integer (typically 4 or 8) indicating the number of decimal places for price fields within this message type. This is crucial for correctly interpreting price data. See `decode_price()`.
363
+
364
+ ### Common Methods of `MarketMessage`
365
+
366
+ The `MarketMessage` base class, and therefore all specific message classes, provide these useful methods:
367
+
368
+ * `set_timestamp(timestamp_high: int, timestamp_low: int)`:
369
+ * This method is typically used internally by the parser. It reconstructs the full 48-bit nanosecond timestamp from two parts provided by unpacking the raw message bytes.
370
+ * `timestamp_high`: The higher-order 2 bytes (16 bits) of the 6-byte ITCH timestamp.
371
+ * `timestamp_low`: The lower-order 4 bytes (32 bits) of the 6-byte ITCH timestamp.
372
+ * These are combined to set the `timestamp` attribute (a 64-bit integer representing nanoseconds since midnight) of the message object. The full 48-bit value is stored within this 64-bit integer.
373
+ * `split_timestamp(timestamp_nanoseconds: int = None) -> tuple[int, int]`:
374
+ * Takes an optional 64-bit integer timestamp (nanoseconds since midnight); if `None`, it uses the message's current `timestamp` attribute (which holds the 48-bit value).
375
+ * Splits this timestamp into two integer components: the higher-order 2 bytes (16 bits) and the lower-order 4 bytes (32 bits), matching how they are packed in the raw ITCH message. This is primarily for internal use during packing.
376
+ * `decode_price(attribute_name: str) -> float`:
377
+ * Takes the string name of a price attribute within the message object (e.g., `'price'`, `'execution_price'`).
378
+ * Retrieves the raw integer value of that attribute.
379
+ * Divides the raw integer by `10 ** self.price_precision` to convert it into a floating-point number with the correct decimal places. For example, if `price_precision` is 4 and the raw price is `1234500`, this method returns `123.45`.
380
+ * `decode() -> dataclass`:
381
+ * This is a key method for usability. It processes the raw byte fields of the message object and converts them into a more human-readable Python `dataclass`.
382
+ * Specifically, it:
383
+ * Converts alpha-numeric byte strings (like stock symbols or MPIDs) into standard Python strings, stripping any right-padding spaces.
384
+ * Converts price fields into floating-point numbers using the `decode_price()` logic internally.
385
+ * Keeps other fields (like share counts or reference numbers) in their appropriate integer or byte format if no further conversion is needed.
386
+ * The returned `dataclass` provides a clean, immutable, and easily inspectable representation of the message content.
387
+ * `get_attributes() -> dict`:
388
+ * Returns a dictionary of all attributes (fields) of the message instance, along with their current values.
389
+ * This can be useful for generic inspection or logging of message contents without needing to know the specific type of the message beforehand.
390
+
391
+ ### Serializing Messages with `pack()`
392
+
393
+ Each specific message class (e.g., `SystemEventMessage`, `AddOrderNoMPIAttributionMessage`) also provides a `pack()` method. This method is the inverse of the parsing process.
394
+
395
+ * **Purpose:** It serializes the message object, with its current attribute values, back into its raw ITCH 5.0 binary format. The output is a `bytes` object representing the exact byte sequence that would appear in an ITCH data feed for that message.
396
+ * **Usefulness:**
397
+ * **Generating Test Data:** Create custom ITCH messages for testing your own ITCH processing applications.
398
+ * **Modifying Messages:** Parse an existing message, modify some of its attributes, and then `pack()` it back into binary form.
399
+ * **Creating Custom ITCH Feeds:** While more involved, you could use this to construct sequences of ITCH messages for specialized scenarios.
400
+
401
+ **Example:**
402
+
403
+ ```python
404
+ from itch.messages import SystemEventMessage
405
+ import time
406
+
407
+ # 1. Create a SystemEventMessage instance.
408
+ # For direct packing, you need to provide all fields that are part of its `message_pack_format`.
409
+ # The `SystemEventMessage` constructor in `itch.messages` expects the raw bytes of the message body
410
+ # (excluding the common message type, stock_locate, tracking_number, and timestamp parts that are
411
+ # handled by its `__init__` if you were parsing).
412
+ # When creating from scratch for packing, it's often easier to instantiate and then set attributes.
413
+ # Let's assume SystemEventMessage can be instantiated with default or required values.
414
+ # (Note: The actual SystemEventMessage.__init__ takes raw message bytes, so direct instantiation
415
+ # for packing requires setting attributes manually if not using raw bytes for construction)
416
+
417
+ event_msg = SystemEventMessage.__new__(SystemEventMessage) # Create instance without calling __init__
418
+ event_msg.message_type = b'S' # Must be set for pack() to know its type
419
+ event_msg.stock_locate = 0 # Placeholder or actual value
420
+ event_msg.tracking_number = 0 # Placeholder or actual value
421
+ event_msg.event_code = b'O' # Example: Start of Messages
422
+
423
+ # 2. Set the timestamp.
424
+ # The `timestamp` attribute (nanoseconds since midnight) must be set.
425
+ # The `pack()` method will internally use `split_timestamp()` to get the parts.
426
+ current_nanoseconds = int(time.time() * 1e9) % (24 * 60 * 60 * int(1e9))
427
+ event_msg.timestamp = current_nanoseconds # Directly set the nanosecond timestamp
428
+
429
+ # 3. Pack the message into binary format.
430
+ # The pack() method prepends the message type and then packs stock_locate,
431
+ # tracking_number, the split timestamp, and then the message-specific fields.
432
+ packed_bytes = event_msg.pack()
433
+
434
+ # 4. The result is a bytes object
435
+ print(f"Packed {len(packed_bytes)} bytes: {packed_bytes.hex().upper()}")
436
+ print(f"Type of packed_bytes: {type(packed_bytes)}")
437
+
438
+ # Example Output (will vary based on actual timestamp and other values if not fixed):
439
+ # Packed 12 bytes: 53000000002F39580A004F
440
+ # Type of packed_bytes: <class 'bytes'>
441
+ ```
442
+ The `message_pack_format` attribute of each message class dictates how its fields are packed. Note that for messages read by the `MessageParser`, fields like `stock_locate` and `tracking_number` are prepended during parsing; when packing an object directly, ensure all fields defined in its `message_pack_format` are appropriately set.
443
+
444
+ ### Data Types in Parsed Messages
445
+
446
+ * **Strings:** Alpha fields (e.g., stock symbols, MPIDs) are initially parsed as `bytes`. The `decode()` method converts these to standard Python strings (ASCII) and typically removes any right-padding spaces used in the fixed-width ITCH fields.
447
+ * **Prices:** As mentioned under `decode_price()`, price fields are stored as raw integers in the initial message object. The `decode_price()` method or the comprehensive `decode()` method should be used to obtain correctly scaled floating-point values.
448
+ * **Timestamps:** Handled by `set_timestamp()` and `split_timestamp()` as described above, resulting in a nanosecond-precision integer for the `timestamp` attribute.
449
+ * **Decoded Objects:** The `message.decode()` method is the recommended way to get a fully processed, user-friendly representation of any message, with all fields converted to appropriate Python types (strings, floats, integers).
450
+
451
+ ## Error Handling
452
+
453
+ When parsing ITCH data, the `MessageParser` may encounter issues due to malformed data, incorrect file formats, or unexpected message types. These situations typically result in a `ValueError` being raised.
454
+
455
+ Common scenarios that can lead to a `ValueError` include:
456
+
457
+ * **Unexpected Byte:** When reading from a file or a raw byte stream, each ITCH message is expected to be prefixed by a `0x00` byte followed by a byte indicating the length of the upcoming message. If the parser encounters a byte other than `0x00` where this prefix is expected, it suggests data corruption, that the file is not a valid ITCH feed, or that the stream is out of sync.
458
+ * **Unknown Message Type:** After successfully reading the length-prefixed message, the first byte of the actual message content indicates its type (e.g., `S` for System Event, `A` for Add Order). If this byte does not correspond to one of the known ITCH 5.0 message types, the parser will raise an error.
459
+ * **Malformed Message Structure:** Even if the message type is known, errors can occur if the message's length does not match the expected length for that type, or if the internal structure cannot be unpacked correctly according to the defined format. This often points to data corruption or a non-standard message.
460
+
461
+ ### Handling Strategies
462
+
463
+ It's crucial to anticipate these errors in your application:
464
+
465
+ * **Use `try-except` Blocks:** Wrap your parsing calls (especially `read_message_from_file` or `read_message_from_bytes`) in `try-except ValueError as e:` blocks.
466
+ ```python
467
+ try:
468
+ # ... parsing operations ...
469
+ messages = parser.read_message_from_file(itch_file)
470
+ except ValueError as e:
471
+ print(f"An error occurred during parsing: {e}")
472
+ # Log the error, problematic data chunk, or take other actions
473
+ ```
474
+ * **Logging:** When an error is caught, log the exception details. If possible, log the problematic chunk of data that caused the error. This is invaluable for debugging and understanding the nature of the data issue.
475
+ * **Application-Specific Decisions:**
476
+ * **Skip and Continue:** For some applications, it might be acceptable to log the error, skip the problematic message or data chunk, and attempt to continue parsing the rest of the stream/file. This can be useful for robustly processing large datasets where a small amount of corrupted data is tolerable.
477
+ * **Halt Processing:** In other scenarios, particularly where data integrity is paramount, any parsing error might necessitate halting the entire process and flagging the data source as invalid.
478
+
479
+ Choosing the right strategy depends on the requirements of your application and the expected quality of your ITCH data sources.
480
+
481
+ ## Contributing
482
+
483
+ Contributions are welcome! If you find a bug, have a suggestion, or want to add a feature:
484
+
485
+ 1. **Check Issues:** See if an issue for your topic already exists.
486
+ 2. **Open an Issue:** If not, open a new issue describing the bug or feature request.
487
+ 3. **Fork and Branch:** Fork the repository and create a new branch for your changes.
488
+ 4. **Implement Changes:** Make your code changes, ensuring adherence to the ITCH 5.0 specification. Add tests if applicable.
489
+ 5. **Submit Pull Request:** Open a pull request from your branch to the main repository, referencing the relevant issue.
490
+
491
+ ## License
492
+
493
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
494
+
495
+ ## References
496
+ * **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.
@@ -0,0 +1,9 @@
1
+ itch/__init__.py,sha256=M9Jirj4-XXdaCoTcU2_g89z7JHK8mDtJflTFf9HnU-k,205
2
+ itch/indicators.py,sha256=-Ed2M8I60xGQ1bIPZCGCKGb8ayT87JAnIaosfiBimXI,6542
3
+ itch/messages.py,sha256=lm5pKQ00ETMbTij9HqaYVrN08JJdQe-mZKB_C7IAetU,63934
4
+ itch/parser.py,sha256=BOrkGsmRkcYnXSf5S9yqrwzP0jqtkH5mGCpWCeiWNTg,6155
5
+ itchfeed-1.0.4.dist-info/licenses/LICENSE,sha256=f2u79rUzh-UcYH0RN0Ph0VvVYHBkYlVxtguhKmrHqsw,1089
6
+ itchfeed-1.0.4.dist-info/METADATA,sha256=HYjteeevesrGUcrjvuNlW2P-0B9k8jtL0qdovoaLZT0,33793
7
+ itchfeed-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
8
+ itchfeed-1.0.4.dist-info/top_level.txt,sha256=xwsOYShvy3gc1rfyitCTgSxBZDGG1y6bfQxkdhIGmEM,5
9
+ itchfeed-1.0.4.dist-info/RECORD,,
@@ -1,5 +1,5 @@
1
1
  Wheel-Version: 1.0
2
- Generator: setuptools (80.3.1)
2
+ Generator: setuptools (80.9.0)
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
5
5
 
@@ -1,225 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: itchfeed
3
- Version: 1.0.2
4
- Summary: Simple parser for ITCH messages
5
- Home-page: https://github.com/bbalouki/itch
6
- Download-URL: https://pypi.org/project/itchfeed/
7
- Author: Bertin Balouki SIMYELI
8
- Author-email: <bertin@bbstrader.com>
9
- Maintainer: Bertin Balouki SIMYELI
10
- License: The MIT License (MIT)
11
- Project-URL: Source Code, https://github.com/bbalouki/itch
12
- Keywords: Finance,Financial,Quantitative,Equities,Totalview-ITCH,Totalview,Nasdaq-ITCH,Nasdaq,ITCH,Data,Feed,ETFs,Funds,Trading,Investing
13
- Classifier: Development Status :: 5 - Production/Stable
14
- Classifier: Intended Audience :: Developers
15
- Classifier: Intended Audience :: Financial and Insurance Industry
16
- Classifier: Topic :: Office/Business :: Financial :: Investment
17
- Classifier: Programming Language :: Python :: 3
18
- Classifier: Operating System :: OS Independent
19
- Description-Content-Type: text/markdown
20
- License-File: LICENSE
21
- Requires-Dist: pytest
22
- Dynamic: author
23
- Dynamic: author-email
24
- Dynamic: classifier
25
- Dynamic: description
26
- Dynamic: description-content-type
27
- Dynamic: download-url
28
- Dynamic: home-page
29
- Dynamic: keywords
30
- Dynamic: license
31
- Dynamic: license-file
32
- Dynamic: maintainer
33
- Dynamic: project-url
34
- Dynamic: requires-dist
35
- Dynamic: summary
36
-
37
- # Nasdaq TotalView-ITCH 5.0 Parser
38
- [![PYPI Version](https://img.shields.io/pypi/v/itchfeed)](https://pypi.org/project/itchfeed/)
39
- [![PyPi status](https://img.shields.io/pypi/status/itchfeed.svg?maxAge=60)](https://pypi.python.org/pypi/itchfeed)
40
- [![Supported Python Versions](https://img.shields.io/pypi/pyversions/itchfeed)](https://pypi.org/project/itchfeed/)
41
- [![PyPI Downloads](https://static.pepy.tech/badge/itchfeed)](https://pepy.tech/projects/itchfeed)
42
- [![CodeFactor](https://www.codefactor.io/repository/github/bbalouki/itch/badge)](https://www.codefactor.io/repository/github/bbalouki/itch)
43
- [![LinkedIn](https://img.shields.io/badge/LinkedIn-grey?logo=Linkedin&logoColor=white)](https://www.linkedin.com/in/bertin-balouki-simyeli-15b17a1a6/)
44
- [![PayPal Me](https://img.shields.io/badge/PayPal%20Me-blue?logo=paypal)](https://paypal.me/bertinbalouki?country.x=SN&locale.x=en_US)
45
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
46
-
47
- 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.
48
-
49
- ## Overview
50
-
51
- 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.
52
-
53
- ## Features
54
-
55
- * **Parses ITCH 5.0 Binary Data:** Accurately interprets the binary message structures defined in the official specification.
56
- * **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.).
57
- * **Object-Oriented Representation:** Each ITCH message type is represented by a dedicated Python class (`SystemEventMessage`, `AddOrderMessage`, etc.), inheriting from a common `MarketMessage` base class.
58
- * **Flexible Input:** Reads and parses messages from:
59
- * Binary files (`.gz` or similar).
60
- * Raw byte streams (e.g., from network sockets).
61
- * **Data Decoding:** Provides a `.decode()` method on each message object to convert it into a human-readable `dataclass` representation, handling:
62
- * Byte-to-string conversion (ASCII).
63
- * Stripping padding spaces.
64
- * Price decoding based on defined precision.
65
- * **Timestamp Handling:** Correctly reconstructs the 6-byte (48-bit) nanosecond timestamps.
66
- * **Price Handling:** Decodes fixed-point price fields into floating-point numbers based on the standard 4 or 8 decimal place precision.
67
- * **Pure Python:** Relies only on the Python standard library . No external dependencies required.
68
-
69
- ## Installation
70
-
71
- You can install this project using ``pip``
72
-
73
- 1. **Clone the repository (or download the source code):**
74
- ```bash
75
- pip install itchfeed
76
- ```
77
- 2. **Import the necessary modules** directly into your Python project:
78
- ```python
79
- from itch.parser import MessageParser
80
- from itch.messages import ModifyOrderMessage
81
- ```
82
-
83
- ## Usage
84
-
85
- ### Parsing from a Binary File
86
-
87
- This is useful for processing historical ITCH data stored in files. The `MessageParser` handles buffering efficiently.
88
-
89
- ```python
90
- from itch.parser import MessageParser
91
- from itch.messages import AddOrderMessage, TradeMessage
92
-
93
- # Initialize the parser. Optionally filter messages by type.
94
- # parser = MessageParser(message_type=b"AP") # Only parse AddOrder and NonCrossTrade messages
95
- parser = MessageParser()
96
-
97
- # Path to your ITCH 5.0 data file
98
- itch_file_path = 'path/to/your/data'
99
- # you can find sample data [here](https://emi.nasdaq.com/ITCH/Nasdaq%20ITCH/)
100
-
101
- try:
102
- with open(itch_file_path, 'rb') as itch_file:
103
- # read_message_from_file returns a list of parsed message objects
104
- parsed_messages = parser.read_message_from_file(itch_file)
105
-
106
- print(f"Parsed {len(parsed_messages)} messages.")
107
-
108
- # Process the messages
109
- for message in parsed_messages:
110
- # Access attributes directly
111
- print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
112
-
113
- if isinstance(message, AddOrderMessage):
114
- print(f" Add Order: Ref={message.order_reference_number}, "
115
- f"Side={message.buy_sell_indicator.decode()}, "
116
- f"Shares={message.shares}, Stock={message.stock.decode().strip()}, "
117
- f"Price={message.decode_price('price')}")
118
-
119
- elif isinstance(message, TradeMessage):
120
- print(f" Trade: Match={message.match_number}")
121
- # Access specific trade type attributes...
122
-
123
- # Get a human-readable dataclass representation
124
- decoded_msg = message.decode()
125
- print(f" Decoded: {decoded_msg}")
126
-
127
- except FileNotFoundError:
128
- print(f"Error: File not found at {itch_file_path}")
129
- except Exception as e:
130
- print(f"An error occurred: {e}")
131
-
132
- ```
133
-
134
- ### Parsing from Raw Bytes
135
-
136
- This is suitable for real-time processing, such as reading from a network stream.
137
-
138
- ```python
139
- from itch.parser import MessageParser
140
- from itch.messages import AddOrderMessage
141
- from queue import Queue
142
-
143
- # Initialize the parser
144
- parser = MessageParser()
145
-
146
- # Simulate receiving a chunk of binary data (e.g., from a network socket)
147
- # This chunk contains multiple ITCH messages, each prefixed with 0x00 and length byte
148
- # Example: \x00\x0bS...\x00\x25R...\x00\x27F...
149
- raw_binary_data: bytes = b"..." # Your raw ITCH 5.0 data chunk
150
-
151
- # read_message_from_bytes returns a queue of parsed message objects
152
- message_queue: Queue = parser.read_message_from_bytes(raw_binary_data)
153
-
154
- print(f"Parsed {message_queue.qsize()} messages from the byte chunk.")
155
-
156
- # Process messages from the queue
157
- while not message_queue.empty():
158
- message = message_queue.get()
159
-
160
- print(f"Type: {message.message_type.decode()}, Timestamp: {message.timestamp}")
161
-
162
- if isinstance(message, AddOrderMessage):
163
- print(f" Add Order: Ref={message.order_reference_number}, "
164
- f"Stock={message.stock.decode().strip()}, Price={message.decode_price('price')}")
165
-
166
- # Use the decoded representation
167
- decoded_msg = message.decode(prefix="Decoded")
168
- print(f" Decoded: {decoded_msg}")
169
-
170
- ```
171
-
172
- ## Supported Message Types
173
-
174
- 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.
175
-
176
- | Type (Byte) | Class Name | Description |
177
- | :---------- | :-------------------------------- | :----------------------------------------------- |
178
- | `S` | `SystemEventMessage` | System Event Message |
179
- | `R` | `StockDirectoryMessage` | Stock Directory Message |
180
- | `H` | `StockTradingActionMessage` | Stock Trading Action Message |
181
- | `Y` | `RegSHOMessage` | Reg SHO Short Sale Price Test Restricted Indicator |
182
- | `L` | `MarketParticipantPositionMessage`| Market Participant Position message |
183
- | `V` | `MWCBDeclineLeveMessage` | Market-Wide Circuit Breaker (MWCB) Decline Level |
184
- | `W` | `MWCBStatusMessage` | Market-Wide Circuit Breaker (MWCB) Status |
185
- | `K` | `IPOQuotingPeriodUpdateMessage` | IPO Quoting Period Update Message |
186
- | `J` | `LULDAuctionCollarMessage` | LULD Auction Collar Message |
187
- | `h` | `OperationalHaltMessage` | Operational Halt Message |
188
- | `A` | `AddOrderNoMPIAttributionMessage` | Add Order (No MPID Attribution) |
189
- | `F` | `AddOrderMPIDAttribution` | Add Order (MPID Attribution) |
190
- | `E` | `OrderExecutedMessage` | Order Executed Message |
191
- | `C` | `OrderExecutedWithPriceMessage` | Order Executed With Price Message |
192
- | `X` | `OrderCancelMessage` | Order Cancel Message |
193
- | `D` | `OrderDeleteMessage` | Order Delete Message |
194
- | `U` | `OrderReplaceMessage` | Order Replace Message |
195
- | `P` | `NonCrossTradeMessage` | Trade Message (Non-Cross) |
196
- | `Q` | `CrossTradeMessage` | Cross Trade Message |
197
- | `B` | `BrokenTradeMessage` | Broken Trade / Order Execution Message |
198
- | `I` | `NOIIMessage` | Net Order Imbalance Indicator (NOII) Message |
199
- | `N` | `RetailPriceImprovementIndicator` | Retail Price Improvement Indicator (RPII) |
200
- | `O` | `DLCRMessage` | Direct Listing with Capital Raise Message |
201
-
202
- ## Data Representation
203
-
204
- * **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`.
205
- * **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.
206
- * **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`).
207
- * **Strings:** Alpha fields are stored as `bytes`. The `.decode()` method converts these to ASCII strings and removes right-padding spaces.
208
- * **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).
209
-
210
- ## Contributing
211
-
212
- Contributions are welcome! If you find a bug, have a suggestion, or want to add a feature:
213
-
214
- 1. **Check Issues:** See if an issue for your topic already exists.
215
- 2. **Open an Issue:** If not, open a new issue describing the bug or feature request.
216
- 3. **Fork and Branch:** Fork the repository and create a new branch for your changes.
217
- 4. **Implement Changes:** Make your code changes, ensuring adherence to the ITCH 5.0 specification. Add tests if applicable.
218
- 5. **Submit Pull Request:** Open a pull request from your branch to the main repository, referencing the relevant issue.
219
-
220
- ## License
221
-
222
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
223
-
224
- ## References
225
- * **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.
@@ -1,9 +0,0 @@
1
- itch/__init__.py,sha256=m8ulOH0nET4yLoKcqWJA-VjOEZldGo932t95rHOZh4w,204
2
- itch/indicators.py,sha256=-Ed2M8I60xGQ1bIPZCGCKGb8ayT87JAnIaosfiBimXI,6542
3
- itch/messages.py,sha256=UHr4eBTtgiLg9vO53GpciAxiAO9AD9uCu8Xz3WnfadM,61927
4
- itch/parser.py,sha256=Hn7ixJsvflSGSwvDyK4IO8yCjEd7ctBz-JsBbK7Arl4,6126
5
- itchfeed-1.0.2.dist-info/licenses/LICENSE,sha256=f2u79rUzh-UcYH0RN0Ph0VvVYHBkYlVxtguhKmrHqsw,1089
6
- itchfeed-1.0.2.dist-info/METADATA,sha256=0IDg9F5c87rS3KCy-tHstJlYnre9BMNMkfD9004ntpY,12638
7
- itchfeed-1.0.2.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
8
- itchfeed-1.0.2.dist-info/top_level.txt,sha256=xwsOYShvy3gc1rfyitCTgSxBZDGG1y6bfQxkdhIGmEM,5
9
- itchfeed-1.0.2.dist-info/RECORD,,