pysmq 1.0.7__tar.gz

pysmq-1.0.7/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: pysmq
+Version: 1.0.7
+Summary: Python client for SuhaibMessageQueue
+Author-email: Suhaib MessageQueue <example@example.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: protobuf>=4.21.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.50.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+
+# PySMQ: Python Client for SuhaibMessageQueue
+
+This package provides a Python client for interacting with [SuhaibMessageQueue](https://github.com/Suhaibinator/SuhaibMessageQueue), a simple and efficient message queue service.
+
+## Installation
+
+```bash
+# From PyPI (once published)
+pip install pysmq
+
+# From source
+git clone https://github.com/Suhaibinator/SuhaibMessageQueue.git
+cd SuhaibMessageQueue
+pip install -e ./pysmq
+```
+
+## Dependencies
+
+- Python 3.7+
+- grpcio
+- protobuf
+
+## Quick Start
+
+### Creating a client and publishing messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Create a topic
+    client.create_topic("my-topic")
+    
+    # Publish a message
+    offset = client.produce("my-topic", b"Hello, SMQ!")
+    print(f"Message published at offset {offset}")
+```
+
+### Consuming messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Consume the latest message
+    message, offset = client.consume_latest("my-topic")
+    print(f"Latest message: {message.decode('utf-8')}, offset: {offset}")
+    
+    # Consume the earliest message
+    message, offset = client.consume_earliest("my-topic")
+    print(f"Earliest message: {message.decode('utf-8')}, offset: {offset}")
+    
+    # Consume a specific message
+    message, offset = client.consume("my-topic", 5)  # offset 5
+    print(f"Message at offset 5: {message.decode('utf-8')}")
+```
+
+### Streaming messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Stream produce messages
+    messages = [b"Message 1", b"Message 2", b"Message 3"]
+    last_offset = client.stream_produce("my-topic", messages)
+    print(f"Last message published at offset {last_offset}")
+    
+    # Stream consume messages (continuous)
+    for message, offset in client.stream_consume("my-topic", 0):
+        print(f"Received message: {message.decode('utf-8')}, offset: {offset}")
+        # Break the loop when needed
+        if offset >= 10:
+            break
+```
+
+### Secure Connection (mTLS)
+
+```python
+from pysmq.client import Client
+from pysmq.config import ClientTLSConfig
+
+# Create TLS configuration
+tls_config = ClientTLSConfig(
+    cert_file="/path/to/client.crt",
+    key_file="/path/to/client.key",
+    ca_file="/path/to/ca.crt"
+)
+
+# Create a secure client
+with Client(host="localhost", port=8097, tls_config=tls_config) as client:
+    # Use the client as normal
+    client.create_topic("secure-topic")
+    offset = client.produce("secure-topic", b"Secure message")
+    print(f"Secure message published at offset {offset}")
+```
+
+## API Overview
+
+### Client
+
+The `Client` class provides methods for interacting with the SMQ server.
+
+```python
+# Constructor
+client = Client(
+    host="localhost",
+    port=8097,
+    tls_config=None,  # Optional: ClientTLSConfig for secure connections
+    max_send_message_size_mb=1024,  # Optional: Maximum size of messages to send
+    max_receive_message_size_mb=1024  # Optional: Maximum size of messages to receive
+)
+```
+
+### Topic Management
+
+```python
+# Create a topic
+client.create_topic(topic)
+```
+
+### Message Production
+
+```python
+# Produce a single message
+offset = client.produce(topic, message_bytes)
+
+# Produce a stream of messages
+last_offset = client.stream_produce(topic, messages_iterable)
+```
+
+### Message Consumption
+
+```python
+# Consume a single message at a specific offset
+message, offset = client.consume(topic, offset)
+
+# Consume the earliest available message
+message, offset = client.consume_earliest(topic)
+
+# Consume the latest message
+message, offset = client.consume_latest(topic)
+
+# Stream consume messages (returns an iterator)
+for message, offset in client.stream_consume(topic, start_offset):
+    # Process each message
+    pass
+```
+
+### Offset Management
+
+```python
+# Get the latest offset for a topic
+latest_offset = client.get_latest_offset(topic)
+
+# Get the earliest available offset for a topic
+earliest_offset = client.get_earliest_offset(topic)
+
+# Delete all messages up to and including the specified offset
+client.delete_until_offset(topic, offset)
+```
+
+### Bulk Operations
+
+```python
+# Retrieve a batch of messages
+response = client.bulk_retrieve(topic, start_offset, limit)
+for message in response.messages:
+    # Process each message
+    message_bytes = message.message
+    message_offset = message.offset
+```
+
+### Connection Management
+
+```python
+# Connect to the server (optional, happens automatically on first operation)
+client.connect()
+
+# Close the connection (or use 'with' statement)
+client.close()
+```
+
+## Exception Handling
+
+The client throws specific exceptions for different types of errors:
+
+```python
+from pysmq.exceptions import (
+    SMQException,              # Base exception for all SMQ errors
+    SMQConnectionError,        # Connection issues
+    SMQAuthenticationError,    # TLS/authentication issues
+    SMQProduceError,           # Issues with producing messages
+    SMQConsumeError,           # Issues with consuming messages
+    SMQTopicCreationError,     # Issues with creating topics
+    SMQOffsetError,            # Issues with offsets
+    SMQTimeoutError,           # Timeout errors
+)
+
+try:
+    client.produce("my-topic", b"Hello")
+except SMQProduceError as e:
+    print(f"Failed to produce message: {e}")
+    # Access the original error if needed
+    original_error = e.original_error
+```
+
+## Configuration
+
+The client supports various configuration options:
+
+```python
+from pysmq.config import ClientTLSConfig, ClientConfig
+
+# Default timeout values can be accessed or modified
+ClientConfig.DEFAULT_TIMEOUT = 60.0  # Default timeout for most operations
+ClientConfig.DEFAULT_TOPIC_TIMEOUT = 2.0  # Default timeout for topic creation
+ClientConfig.DEFAULT_DELETE_TIMEOUT = 2.0  # Default timeout for deletion operations
+```
+
+## Examples
+
+For more detailed examples, see the [examples](examples/) directory:
+
+- [Basic Publishing](examples/publish_example.py)
+- [Message Consumption](examples/subscribe_example.py)
+- [Secure Connection](examples/secure_connection_example.py)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

pysmq-1.0.7/README.md

@@ -0,0 +1,234 @@
+# PySMQ: Python Client for SuhaibMessageQueue
+
+This package provides a Python client for interacting with [SuhaibMessageQueue](https://github.com/Suhaibinator/SuhaibMessageQueue), a simple and efficient message queue service.
+
+## Installation
+
+```bash
+# From PyPI (once published)
+pip install pysmq
+
+# From source
+git clone https://github.com/Suhaibinator/SuhaibMessageQueue.git
+cd SuhaibMessageQueue
+pip install -e ./pysmq
+```
+
+## Dependencies
+
+- Python 3.7+
+- grpcio
+- protobuf
+
+## Quick Start
+
+### Creating a client and publishing messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Create a topic
+    client.create_topic("my-topic")
+    
+    # Publish a message
+    offset = client.produce("my-topic", b"Hello, SMQ!")
+    print(f"Message published at offset {offset}")
+```
+
+### Consuming messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Consume the latest message
+    message, offset = client.consume_latest("my-topic")
+    print(f"Latest message: {message.decode('utf-8')}, offset: {offset}")
+    
+    # Consume the earliest message
+    message, offset = client.consume_earliest("my-topic")
+    print(f"Earliest message: {message.decode('utf-8')}, offset: {offset}")
+    
+    # Consume a specific message
+    message, offset = client.consume("my-topic", 5)  # offset 5
+    print(f"Message at offset 5: {message.decode('utf-8')}")
+```
+
+### Streaming messages
+
+```python
+from pysmq.client import Client
+
+# Create a client
+with Client(host="localhost", port=8097) as client:
+    # Stream produce messages
+    messages = [b"Message 1", b"Message 2", b"Message 3"]
+    last_offset = client.stream_produce("my-topic", messages)
+    print(f"Last message published at offset {last_offset}")
+    
+    # Stream consume messages (continuous)
+    for message, offset in client.stream_consume("my-topic", 0):
+        print(f"Received message: {message.decode('utf-8')}, offset: {offset}")
+        # Break the loop when needed
+        if offset >= 10:
+            break
+```
+
+### Secure Connection (mTLS)
+
+```python
+from pysmq.client import Client
+from pysmq.config import ClientTLSConfig
+
+# Create TLS configuration
+tls_config = ClientTLSConfig(
+    cert_file="/path/to/client.crt",
+    key_file="/path/to/client.key",
+    ca_file="/path/to/ca.crt"
+)
+
+# Create a secure client
+with Client(host="localhost", port=8097, tls_config=tls_config) as client:
+    # Use the client as normal
+    client.create_topic("secure-topic")
+    offset = client.produce("secure-topic", b"Secure message")
+    print(f"Secure message published at offset {offset}")
+```
+
+## API Overview
+
+### Client
+
+The `Client` class provides methods for interacting with the SMQ server.
+
+```python
+# Constructor
+client = Client(
+    host="localhost",
+    port=8097,
+    tls_config=None,  # Optional: ClientTLSConfig for secure connections
+    max_send_message_size_mb=1024,  # Optional: Maximum size of messages to send
+    max_receive_message_size_mb=1024  # Optional: Maximum size of messages to receive
+)
+```
+
+### Topic Management
+
+```python
+# Create a topic
+client.create_topic(topic)
+```
+
+### Message Production
+
+```python
+# Produce a single message
+offset = client.produce(topic, message_bytes)
+
+# Produce a stream of messages
+last_offset = client.stream_produce(topic, messages_iterable)
+```
+
+### Message Consumption
+
+```python
+# Consume a single message at a specific offset
+message, offset = client.consume(topic, offset)
+
+# Consume the earliest available message
+message, offset = client.consume_earliest(topic)
+
+# Consume the latest message
+message, offset = client.consume_latest(topic)
+
+# Stream consume messages (returns an iterator)
+for message, offset in client.stream_consume(topic, start_offset):
+    # Process each message
+    pass
+```
+
+### Offset Management
+
+```python
+# Get the latest offset for a topic
+latest_offset = client.get_latest_offset(topic)
+
+# Get the earliest available offset for a topic
+earliest_offset = client.get_earliest_offset(topic)
+
+# Delete all messages up to and including the specified offset
+client.delete_until_offset(topic, offset)
+```
+
+### Bulk Operations
+
+```python
+# Retrieve a batch of messages
+response = client.bulk_retrieve(topic, start_offset, limit)
+for message in response.messages:
+    # Process each message
+    message_bytes = message.message
+    message_offset = message.offset
+```
+
+### Connection Management
+
+```python
+# Connect to the server (optional, happens automatically on first operation)
+client.connect()
+
+# Close the connection (or use 'with' statement)
+client.close()
+```
+
+## Exception Handling
+
+The client throws specific exceptions for different types of errors:
+
+```python
+from pysmq.exceptions import (
+    SMQException,              # Base exception for all SMQ errors
+    SMQConnectionError,        # Connection issues
+    SMQAuthenticationError,    # TLS/authentication issues
+    SMQProduceError,           # Issues with producing messages
+    SMQConsumeError,           # Issues with consuming messages
+    SMQTopicCreationError,     # Issues with creating topics
+    SMQOffsetError,            # Issues with offsets
+    SMQTimeoutError,           # Timeout errors
+)
+
+try:
+    client.produce("my-topic", b"Hello")
+except SMQProduceError as e:
+    print(f"Failed to produce message: {e}")
+    # Access the original error if needed
+    original_error = e.original_error
+```
+
+## Configuration
+
+The client supports various configuration options:
+
+```python
+from pysmq.config import ClientTLSConfig, ClientConfig
+
+# Default timeout values can be accessed or modified
+ClientConfig.DEFAULT_TIMEOUT = 60.0  # Default timeout for most operations
+ClientConfig.DEFAULT_TOPIC_TIMEOUT = 2.0  # Default timeout for topic creation
+ClientConfig.DEFAULT_DELETE_TIMEOUT = 2.0  # Default timeout for deletion operations
+```
+
+## Examples
+
+For more detailed examples, see the [examples](examples/) directory:
+
+- [Basic Publishing](examples/publish_example.py)
+- [Message Consumption](examples/subscribe_example.py)
+- [Secure Connection](examples/secure_connection_example.py)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

pysmq-1.0.7/examples/publish_example.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Example showing how to publish messages to SMQ using the Python client.
+"""
+import time
+import json
+
+from pysmq.client import Client
+from pysmq.config import ClientTLSConfig
+
+
+def main():
+    # Replace with actual server details
+    host = "localhost"
+    port = 8097
+    
+    # Create a client with default settings (insecure connection)
+    with Client(host=host, port=port) as client:
+        # Connect to the server (this is optional but a good test)
+        print("Connecting to SMQ server...")
+        client.connect()
+        print("Connected!")
+        
+        # Create a topic if it doesn't exist
+        topic = "example-topic"
+        try:
+            print(f"Creating topic '{topic}'...")
+            client.create_topic(topic)
+            print(f"Topic '{topic}' created successfully!")
+        except Exception as e:
+            # Topic may already exist, which is okay
+            print(f"Note: {e}")
+        
+        # Publish a few messages
+        for i in range(5):
+            # Create a sample message (convert to bytes)
+            message = {
+                "id": i,
+                "timestamp": time.time(),
+                "content": f"Message #{i}",
+            }
+            message_bytes = json.dumps(message).encode('utf-8')
+            
+            # Publish the message
+            print(f"Publishing message {i}...")
+            offset = client.produce(topic, message_bytes)
+            print(f"Message published at offset {offset}")
+            
+            # Small delay between messages for demonstration
+            time.sleep(0.5)
+        
+        print("All messages published successfully!")
+
+
+if __name__ == "__main__":
+    main()

pysmq-1.0.7/examples/secure_connection_example.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Example showing how to establish a secure connection to the SMQ server using mTLS.
+"""
+import json
+import time
+import os
+
+from pysmq.client import Client
+from pysmq.config import ClientTLSConfig
+from pysmq.exceptions import SMQAuthenticationError, SMQConnectionError
+
+
+def main():
+    # Replace with actual server details
+    host = "localhost"
+    port = 8097
+    
+    # Replace with actual paths to your TLS certificate files
+    # These paths should point to your client certificate, client key, 
+    # and CA certificate that signed the server's certificate
+    cert_file = os.environ.get("CLIENT_CERT", "/path/to/client.crt")
+    key_file = os.environ.get("CLIENT_KEY", "/path/to/client.key")
+    ca_file = os.environ.get("CA_CERT", "/path/to/ca.crt")
+    
+    # Check if the certificate files exist
+    for file_path, file_name in [
+        (cert_file, "Client certificate"),
+        (key_file, "Client key"),
+        (ca_file, "CA certificate")
+    ]:
+        if not os.path.exists(file_path):
+            print(f"Warning: {file_name} file not found at {file_path}")
+            print("This example requires valid TLS certificates to work.")
+            print("You can set the paths via environment variables:")
+            print("  CLIENT_CERT: Path to client certificate file")
+            print("  CLIENT_KEY: Path to client key file")
+            print("  CA_CERT: Path to CA certificate file")
+            return
+    
+    # Create the TLS configuration
+    tls_config = ClientTLSConfig(
+        cert_file=cert_file,
+        key_file=key_file,
+        ca_file=ca_file,
+    )
+    
+    try:
+        print("Creating secure client with mTLS...")
+        # Create a client with mTLS configuration
+        with Client(host=host, port=port, tls_config=tls_config) as client:
+            # Connect to the server
+            print("Connecting to SMQ server securely...")
+            client.connect()
+            print("Connected securely!")
+            
+            # Example: Create a topic
+            topic = "secure-example-topic"
+            try:
+                print(f"Creating topic '{topic}'...")
+                client.create_topic(topic)
+                print(f"Topic '{topic}' created successfully!")
+            except Exception as e:
+                # Topic may already exist, which is okay
+                print(f"Note: {e}")
+            
+            # Example: Publish a message
+            message = {
+                "id": 1,
+                "timestamp": time.time(),
+                "content": "Secure message",
+                "secure": True,
+            }
+            message_bytes = json.dumps(message).encode('utf-8')
+            
+            print("Publishing a secure message...")
+            offset = client.produce(topic, message_bytes)
+            print(f"Message published securely at offset {offset}")
+            
+            # Example: Consume the message
+            print("Consuming the message...")
+            received_bytes, received_offset = client.consume(topic, offset)
+            
+            # Decode and print the message
+            received_message = json.loads(received_bytes.decode('utf-8'))
+            print(f"Received secure message at offset {received_offset}:")
+            print(f"  ID: {received_message.get('id')}")
+            print(f"  Timestamp: {received_message.get('timestamp')}")
+            print(f"  Content: {received_message.get('content')}")
+            print(f"  Secure: {received_message.get('secure')}")
+            
+            print("Secure connection example completed successfully!")
+    
+    except SMQAuthenticationError as e:
+        print(f"TLS Authentication Error: {e}")
+        print("Make sure your certificates are correctly configured and valid.")
+    except SMQConnectionError as e:
+        print(f"Connection Error: {e}")
+        print("Make sure the server is running and configured for mTLS.")
+    except Exception as e:
+        print(f"Unexpected Error: {e}")
+
+
+if __name__ == "__main__":
+    main()