itchfeed 1.0.3__tar.gz → 1.0.4__tar.gz

{itchfeed-1.0.3/itchfeed.egg-info → itchfeed-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itchfeed
-Version: 1.0.3
+Version: 1.0.4
 Summary: Simple parser for ITCH messages
 Home-page: https://github.com/bbalouki/itch
 Download-URL: https://pypi.org/project/itchfeed/
@@ -52,6 +52,8 @@ Dynamic: summary
 *   [Usage](#usage)
     *   [Parsing from a Binary File](#parsing-from-a-binary-file)
     *   [Parsing from Raw Bytes](#parsing-from-raw-bytes)
+    *   [Creating Messages Programmatically](#creating-messages-programmatically)
+    *   [Example with Real-World Sample Data](#example-with-real-world-sample-data)
 *   [Interpreting Market Data (Conceptual Overview)](#interpreting-market-data-conceptual-overview)
 *   [Supported Message Types](#supported-message-types)
 *   [Data Representation](#data-representation)
@@ -211,6 +213,78 @@ while not message_queue.empty():
 
 ```
 
+### Creating Messages Programmatically
+
+In addition to parsing, `itch` provides a simple way to create ITCH message objects from scratch. This is particularly useful for:
+- **Testing:** Generating specific message sequences to test your own downstream applications.
+- **Simulation:** Building custom market simulators that produce ITCH-compliant data streams.
+- **Data Generation:** Creating custom datasets for analysis or backtesting.
+
+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.
+
+Here's a basic example of how to create a `SystemEventMessage` to signal the "Start of Messages":
+
+```python
+from itch.messages import create_message, SystemEventMessage
+
+# Define the attributes for the message
+event_attributes = {
+    "stock_locate": 1,
+    "tracking_number": 2,
+    "timestamp": 1651500000 * 1_000_000_000,
+    "event_code": b"O"
+}
+
+# Create the message object
+system_event_message = create_message(b"S", **event_attributes)
+
+# You can now work with this object just like one from the parser
+print(isinstance(system_event_message, SystemEventMessage))
+# Expected output: True
+
+print(system_event_message)
+# 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)
+```
+
+### Example with Real-World Sample Data
+
+You can also use the sample data provided in `tests/data.py` to create messages, simulating a more realistic scenario.
+
+```python
+from itch.messages import create_message, AddOrderNoMPIAttributionMessage
+from tests.data import TEST_DATA
+
+# Get the sample data for an "Add Order" message (type 'A')
+add_order_data = TEST_DATA[b"A"]
+
+# Create the message
+add_order_message = create_message(b"A", **add_order_data)
+
+# Verify the type
+print(isinstance(add_order_message, AddOrderNoMPIAttributionMessage))
+# Expected output: True
+
+# Access its attributes
+print(f"Stock: {add_order_message.stock.decode().strip()}")
+# Expected output: Stock: AAPL
+
+print(f"Price: {add_order_message.decode_price('price')}")
+# Expected output: Price: 150.1234
+
+# Test all message types in the sample data
+for message_type, sample_data in TEST_DATA.items():
+    print(f"Creating message of type {message_type}")
+    message = create_message(message_type, **sample_data)
+    print(f"Created message: {message}")
+    print(f"Packed message: {message.pack()}")
+    print(f"Message size: {message.message_size}")
+    print(f"Message Attributes: {message.get_attributes()}")
+    assert len(message.pack()) ==  message.message_size
+    print()
+```
+
+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.
+
 ## Interpreting Market Data (Conceptual Overview)
 
 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.

{itchfeed-1.0.3 → itchfeed-1.0.4}/README.md

@@ -16,6 +16,8 @@
 *   [Usage](#usage)
     *   [Parsing from a Binary File](#parsing-from-a-binary-file)
     *   [Parsing from Raw Bytes](#parsing-from-raw-bytes)
+    *   [Creating Messages Programmatically](#creating-messages-programmatically)
+    *   [Example with Real-World Sample Data](#example-with-real-world-sample-data)
 *   [Interpreting Market Data (Conceptual Overview)](#interpreting-market-data-conceptual-overview)
 *   [Supported Message Types](#supported-message-types)
 *   [Data Representation](#data-representation)
@@ -175,6 +177,78 @@ while not message_queue.empty():
 
 ```
 
+### Creating Messages Programmatically
+
+In addition to parsing, `itch` provides a simple way to create ITCH message objects from scratch. This is particularly useful for:
+- **Testing:** Generating specific message sequences to test your own downstream applications.
+- **Simulation:** Building custom market simulators that produce ITCH-compliant data streams.
+- **Data Generation:** Creating custom datasets for analysis or backtesting.
+
+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.
+
+Here's a basic example of how to create a `SystemEventMessage` to signal the "Start of Messages":
+
+```python
+from itch.messages import create_message, SystemEventMessage
+
+# Define the attributes for the message
+event_attributes = {
+    "stock_locate": 1,
+    "tracking_number": 2,
+    "timestamp": 1651500000 * 1_000_000_000,
+    "event_code": b"O"
+}
+
+# Create the message object
+system_event_message = create_message(b"S", **event_attributes)
+
+# You can now work with this object just like one from the parser
+print(isinstance(system_event_message, SystemEventMessage))
+# Expected output: True
+
+print(system_event_message)
+# 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)
+```
+
+### Example with Real-World Sample Data
+
+You can also use the sample data provided in `tests/data.py` to create messages, simulating a more realistic scenario.
+
+```python
+from itch.messages import create_message, AddOrderNoMPIAttributionMessage
+from tests.data import TEST_DATA
+
+# Get the sample data for an "Add Order" message (type 'A')
+add_order_data = TEST_DATA[b"A"]
+
+# Create the message
+add_order_message = create_message(b"A", **add_order_data)
+
+# Verify the type
+print(isinstance(add_order_message, AddOrderNoMPIAttributionMessage))
+# Expected output: True
+
+# Access its attributes
+print(f"Stock: {add_order_message.stock.decode().strip()}")
+# Expected output: Stock: AAPL
+
+print(f"Price: {add_order_message.decode_price('price')}")
+# Expected output: Price: 150.1234
+
+# Test all message types in the sample data
+for message_type, sample_data in TEST_DATA.items():
+    print(f"Creating message of type {message_type}")
+    message = create_message(message_type, **sample_data)
+    print(f"Created message: {message}")
+    print(f"Packed message: {message.pack()}")
+    print(f"Message size: {message.message_size}")
+    print(f"Message Attributes: {message.get_attributes()}")
+    assert len(message.pack()) ==  message.message_size
+    print()
+```
+
+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.
+
 ## Interpreting Market Data (Conceptual Overview)
 
 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.

{itchfeed-1.0.3 → itchfeed-1.0.4}/itch/__init__.py

@@ -6,5 +6,6 @@ __author__ = "Bertin Balouki SIMYELI"
 __copyright__ = "2025 Bertin Balouki SIMYELI"
 __email__ = "bertin@bbstrader.com"
 __license__ = "MIT"
-__version__ = "1.0.0"
+__version__ = "1.0.4"
+
 

{itchfeed-1.0.3 → itchfeed-1.0.4}/itch/messages.py

@@ -35,6 +35,13 @@ class MarketMessage(object):
     def __repr__(self):
         return repr(self.decode())
 
+    def pack(self) -> bytes:
+        """
+        Packs the message into bytes using the defined message_pack_format.
+        This method should be overridden by subclasses to include specific fields.
+        """
+        pass
+
     def set_timestamp(self, ts1: int, ts2: int):
         """
         Reconstructs a 6-byte timestamp (48 bits) from two 32-bit unsigned integers.
@@ -1598,3 +1605,51 @@ messages: Dict[bytes, Type[MarketMessage]] = {
     b"N": RetailPriceImprovementIndicator,
     b"O": DLCRMessage,
 }
+
+
+def create_message(message_type: bytes, **kwargs) -> Type[MarketMessage]:
+    """
+    Creates a new message of a given type with specified attributes.
+
+    This function simplifies the process of message creation by handling
+    the instantiation and attribute setting for any valid message type.
+    It's particularly useful for simulating trading environments or
+    generating test data without manually packing and unpacking bytes.
+
+    Args:
+        message_type (bytes):
+            A single-byte identifier for the message type (e.g., b'A'
+            for AddOrderNoMPIAttributionMessage).
+        **kwargs:
+            Keyword arguments representing the attributes of the message.
+            These must match the attributes expected by the message class
+            (e.g., `stock_locate`, `timestamp`, `price`).
+
+    Returns:
+        MarketMessage:
+            An instance of the corresponding message class, populated with
+            the provided attributes.
+
+    Raises:
+        ValueError:
+            If the `message_type` is not found in the registered messages.
+    """
+    message_class = messages.get(message_type)
+    if not message_class:
+        raise ValueError(f"Unknown message type: {message_type.decode()}")
+
+    # Create a new instance without calling __init__
+    # __init__ is for unpacking, not creating
+    instance = message_class.__new__(message_class)
+
+    # Set attributes from kwargs
+    for key, value in kwargs.items():
+        if key == 'timestamp':
+            # Timestamps are 48-bit, so we need to mask the original value
+            value &= ((1 << 48) - 1)
+        setattr(instance, key, value)
+
+    # Set the message_type attribute on the instance, as it's used by pack()
+    instance.message_type = message_type
+
+    return instance

{itchfeed-1.0.3 → itchfeed-1.0.4/itchfeed.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itchfeed
-Version: 1.0.3
+Version: 1.0.4
 Summary: Simple parser for ITCH messages
 Home-page: https://github.com/bbalouki/itch
 Download-URL: https://pypi.org/project/itchfeed/
@@ -52,6 +52,8 @@ Dynamic: summary
 *   [Usage](#usage)
     *   [Parsing from a Binary File](#parsing-from-a-binary-file)
     *   [Parsing from Raw Bytes](#parsing-from-raw-bytes)
+    *   [Creating Messages Programmatically](#creating-messages-programmatically)
+    *   [Example with Real-World Sample Data](#example-with-real-world-sample-data)
 *   [Interpreting Market Data (Conceptual Overview)](#interpreting-market-data-conceptual-overview)
 *   [Supported Message Types](#supported-message-types)
 *   [Data Representation](#data-representation)
@@ -211,6 +213,78 @@ while not message_queue.empty():
 
 ```
 
+### Creating Messages Programmatically
+
+In addition to parsing, `itch` provides a simple way to create ITCH message objects from scratch. This is particularly useful for:
+- **Testing:** Generating specific message sequences to test your own downstream applications.
+- **Simulation:** Building custom market simulators that produce ITCH-compliant data streams.
+- **Data Generation:** Creating custom datasets for analysis or backtesting.
+
+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.
+
+Here's a basic example of how to create a `SystemEventMessage` to signal the "Start of Messages":
+
+```python
+from itch.messages import create_message, SystemEventMessage
+
+# Define the attributes for the message
+event_attributes = {
+    "stock_locate": 1,
+    "tracking_number": 2,
+    "timestamp": 1651500000 * 1_000_000_000,
+    "event_code": b"O"
+}
+
+# Create the message object
+system_event_message = create_message(b"S", **event_attributes)
+
+# You can now work with this object just like one from the parser
+print(isinstance(system_event_message, SystemEventMessage))
+# Expected output: True
+
+print(system_event_message)
+# 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)
+```
+
+### Example with Real-World Sample Data
+
+You can also use the sample data provided in `tests/data.py` to create messages, simulating a more realistic scenario.
+
+```python
+from itch.messages import create_message, AddOrderNoMPIAttributionMessage
+from tests.data import TEST_DATA
+
+# Get the sample data for an "Add Order" message (type 'A')
+add_order_data = TEST_DATA[b"A"]
+
+# Create the message
+add_order_message = create_message(b"A", **add_order_data)
+
+# Verify the type
+print(isinstance(add_order_message, AddOrderNoMPIAttributionMessage))
+# Expected output: True
+
+# Access its attributes
+print(f"Stock: {add_order_message.stock.decode().strip()}")
+# Expected output: Stock: AAPL
+
+print(f"Price: {add_order_message.decode_price('price')}")
+# Expected output: Price: 150.1234
+
+# Test all message types in the sample data
+for message_type, sample_data in TEST_DATA.items():
+    print(f"Creating message of type {message_type}")
+    message = create_message(message_type, **sample_data)
+    print(f"Created message: {message}")
+    print(f"Packed message: {message.pack()}")
+    print(f"Message size: {message.message_size}")
+    print(f"Message Attributes: {message.get_attributes()}")
+    assert len(message.pack()) ==  message.message_size
+    print()
+```
+
+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.
+
 ## Interpreting Market Data (Conceptual Overview)
 
 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.

{itchfeed-1.0.3 → itchfeed-1.0.4}/itchfeed.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ itchfeed.egg-info/SOURCES.txt
 itchfeed.egg-info/dependency_links.txt
 itchfeed.egg-info/requires.txt
 itchfeed.egg-info/top_level.txt
+tests/test_create_message.py
 tests/test_messages.py

{itchfeed-1.0.3 → itchfeed-1.0.4}/setup.py

@@ -12,7 +12,7 @@ with io.open(path.join(here, "README.md"), encoding="utf-8") as f:
 with io.open(path.join(here, "requirements.txt"), encoding="utf-8") as f:
     REQUIREMENTS = [line.rstrip() for line in f]
 
-VERSION = "1.0.3"
+VERSION = "1.0.4"
 DESCRIPTION = "Simple parser for ITCH messages"
 
 KEYWORDS = [

itchfeed-1.0.4/tests/test_create_message.py

@@ -0,0 +1,28 @@
+import pytest
+from itch.messages import create_message, messages
+from .data import TEST_DATA
+
+@pytest.mark.parametrize("message_type, sample_data", TEST_DATA.items())
+def test_create_message_and_pack(message_type, sample_data):
+    """
+    Tests that create_message correctly creates a message that can be packed,
+    and that the packed message can be unpacked to match the original data.
+    """
+    # Create a message using the new function
+    created_message = create_message(message_type, **sample_data)
+
+    # Pack the created message
+    packed_message = created_message.pack()
+
+    # Unpack the message using the original class constructor
+    message_class = messages[message_type]
+    unpacked_message = message_class(packed_message)
+
+    # Verify that the attributes of the unpacked message match the original data
+    for key, expected_value in sample_data.items():
+        if key == 'timestamp':
+            # Timestamps are 48-bit, so we need to mask the original value
+            expected_value &= ((1 << 48) - 1)
+        assert getattr(unpacked_message, key) == expected_value, (
+            f"Attribute '{key}' mismatch for message type {message_type.decode()}"
+        )