vaitty-eventbus 0.0.1__tar.gz

vaitty_eventbus-0.0.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: vaitty_eventbus
+Version: 0.0.1
+Summary: A minimal, internal Python library for decoupled event communication using channels and wildcard-capable handlers.
+Home-page: https://bitbucket.org/rapihogar/event-bus
+Author: Tech Data AI
+Author-email: tech-data-ai@rapihogar.com
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

vaitty_eventbus-0.0.1/README.md

@@ -0,0 +1,90 @@
+# event-bus
+
+A minimal, internal Python library for decoupled event communication using channels and wildcard-capable handlers.
+
+---
+
+## 🚀 Features
+
+- 🔌 Pluggable event channels (console, file, or custom)
+- 🎯 Wildcard-matching event handlers (`user.*`, `*`)
+- 🔁 Emits and triggers events independently
+- 🧼 No third-party dependencies
+- 🧩 Fully configurable via Python dict or environment variables
+
+---
+
+## 📦 Installation
+
+To manually install the package, download the `vaitty_eventbus-X.X.X-py3-none-any.whl` file from the `dist` directory and run the following command:
+
+```bash
+pip install vaitty_eventbus-X.X.X-py3-none-any.whl
+```
+
+## 🛠 Configuration
+
+You can configure event-bus through a dictionary or environment variables:
+
+- **EVENTBUS_CHANNEL**: Determines the channel type to use: `console`, `file`, `http`, or a registered custom type. Default: `console`
+- **EVENTBUS_FILE**: For the `file` channel, the path to the log file. Default: `events.log`
+- **EVENTBUS_HTTP_ENDPOINT**: For the `http` channel, the target HTTP endpoint. Default: `http://example.com/events`
+
+### Example using environment variables:
+```bash
+export EVENTBUS_CHANNEL=file
+export EVENTBUS_FILE=/tmp/my-events.log
+```
+
+### Example using a configuration dictionary:
+```python
+import event-bus as events
+
+config = {
+    "EVENTBUS_CHANNEL": "http",
+    "EVENTBUS_HTTP_ENDPOINT": "http://api.my-events.com/ingest"
+}
+handler = events.EventHandlerFactory.from_config(config=config)
+```
+
+## 🌿 Usage
+
+Here's a simple example demonstrating basic usage of `event-bus`:
+
+```python
+import event-bus as events
+
+def handle_all(payload: Dict[str, Any]):
+    print(f"[*] Received: {payload}")
+
+def handle_user(payload: Dict[str, Any]):
+    print(f"[user.*] User event: {payload}")
+
+def handle_login(payload: Dict[str, Any]):
+    print(f"[user.login] Specific login: {payload['user_id']}")
+
+handler = events.EventHandlerFactory.from_config()
+
+# Register wildcard and specific listeners
+handler.on("*", handle_all)
+handler.on("user.*", handle_user)
+handler.on("user.login", handle_login)
+
+# Emit an event
+handler.emit("user.login", {"user_id": 42})
+
+# Trigger an event
+event = Event("user.login", {"user_id": 42})
+handler.trigger(event)
+
+```
+
+## 🔮 Extensibility
+
+The library is designed to be easily extended:
+
+1. Add new `EventChannel` subclasses.
+2. Register them with `EventHandlerFactory.register_channel`.
+3. Configure their behavior through the dictionary or environment variables.
+
+This makes it simple to integrate `event-bus` into diverse workflows and systems!

vaitty_eventbus-0.0.1/pyproject.toml

@@ -0,0 +1,3 @@
+   [build-system]
+   requires = ["setuptools", "wheel"]
+   build-backend = "setuptools.build_meta"

vaitty_eventbus-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vaitty_eventbus-0.0.1/setup.py

@@ -0,0 +1,16 @@
+from setuptools import setup
+
+setup(
+    name="vaitty_eventbus",
+    version="0.0.1",
+    description="A minimal, internal Python library for decoupled event communication using channels and wildcard-capable handlers.",
+    author="Tech Data AI",
+    author_email="tech-data-ai@rapihogar.com",
+    url="https://bitbucket.org/rapihogar/event-bus",
+    packages=["vaitty_eventbus"],
+    package_dir={"": "src"},
+    install_requires=[
+        'requests>=2.0.0',
+    ],
+    python_requires='>=3.7',
+)

vaitty_eventbus-0.0.1/src/vaitty_eventbus/__init__.py

@@ -0,0 +1,14 @@
+from .channels import ConsoleEventChannel, FileEventChannel, HttpEventChannel
+from .core import Event, EventHandler, EventChannel, EventBusError
+from .factory import EventHandlerFactory
+
+__all__ = [
+    "Event",
+    "EventBusError",
+    "EventHandler",
+    "EventChannel",
+    "EventHandlerFactory",
+    "ConsoleEventChannel",
+    "FileEventChannel",
+    "HttpEventChannel"
+]

vaitty_eventbus-0.0.1/src/vaitty_eventbus/channels.py

@@ -0,0 +1,98 @@
+from typing import Dict
+
+import requests
+
+from .core import EventChannel, Event, EventBusError
+
+
+class ConsoleEventChannel(EventChannel):
+    """
+    Provides a channel for sending events to the console.
+
+    This class is a specific implementation of the EventChannel base class
+    and is designed to handle events by outputting them to the standard
+    console. It is useful for debugging or simple event logging where
+    persistent storage or advanced handling of events is not required.
+    """
+
+    @classmethod
+    def from_config(cls, config: Dict[str, str]):
+        return cls()
+
+    def send(self, event: Event) -> None:
+        print(f"[ConsoleChannel] Event sent: {event}")
+
+
+class FileEventChannel(EventChannel):
+    """
+    Handles event logging to a specified file.
+
+    This class inherits from EventChannel and is used to log events to a
+    file. It appends the event data to the specified file in text format.
+    Useful for persistent logging or debugging purposes.
+
+    :ivar filename: Path to the file where events are logged.
+    :type filename: str
+    """
+
+    def __init__(self, filename: str = "events.log"):
+        self.filename = filename
+
+    @classmethod
+    def from_config(cls, config: Dict[str, str]):
+        filename = config.get("EVENTBUS_FILE", "events.log")
+        return cls(filename)
+
+    def send(self, event: Event) -> None:
+        with open(self.filename, 'a') as f:
+            f.write(f"{event}\n")
+
+
+class HttpEventChannel(EventChannel):
+    """
+    Implements an HTTP-based event channel.
+
+    Sends events as HTTP POST requests to a configured endpoint. This class
+    is useful when working with systems that accept event ingestion via HTTP
+    APIs.
+
+    :ivar endpoint: The HTTP endpoint URI to send events to.
+    :type endpoint: str
+    :ivar headers: Optional HTTP headers to send with the requests.
+    :type headers: dict
+    """
+
+    def __init__(self, endpoint: str, headers: dict = None):
+        """
+        Initializes the HTTP event channel.
+
+        :param endpoint: The target URL endpoint for event ingestion.
+        :type endpoint: str
+        :param headers: Additional HTTP headers to include in the request.
+        :type headers: dict, optional
+        """
+        self.endpoint = endpoint
+        self.headers = headers or {}
+
+    @classmethod
+    def from_config(cls, config: Dict[str, str]):
+        endpoint = config.get("EVENTBUS_HTTP_ENDPOINT", "http://example.com/events")
+        return cls(endpoint=endpoint, headers={})
+
+    def send(self, event: Event) -> None:
+        """
+        Sends an event as an HTTP POST request.
+
+        :param event: The event to send.
+        :type event: Event
+        :raises EventBusError: If the request fails.
+        """
+        try:
+            response = requests.post(
+                self.endpoint,
+                json=event.to_dict(),
+                headers=self.headers
+            )
+            response.raise_for_status()
+        except Exception as error:
+            raise EventBusError(f"Failed to send event: {error}")

vaitty_eventbus-0.0.1/src/vaitty_eventbus/core.py

@@ -0,0 +1,163 @@
+import fnmatch
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Callable, List
+
+
+class EventBusError(Exception):
+    pass
+
+
+class Event:
+    """
+    Represents an event with a topic and associated payload.
+
+    This class is designed to encapsulate an event, typically used in event-driven
+    systems or messaging patterns. The class ensures that the topic is a string and
+    the payload is a dictionary. It provides a representation method for easy
+    inspection of event instances.
+
+    :ivar topic: The topic of the event.
+    :type topic: str
+    :ivar payload: The payload of the event, containing related data.
+    :type payload: Dict[str, Any]
+    """
+
+    def __init__(self, topic: str, payload: Dict[str, Any]):
+        if not isinstance(topic, str):
+            raise TypeError("Event topic must be a string.")
+        if not isinstance(payload, dict):
+            raise TypeError("Event payload must be a dictionary.")
+        self.topic = topic
+        self.payload = payload
+
+    def __repr__(self):
+        return f"Event(topic={self.topic!r}, payload={self.payload!r})"
+
+    def __str__(self):
+        return f"Event(topic={self.topic!r}, payload={self.payload!r})"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Converts the event instance to a dictionary representation.
+
+        :return: A dictionary containing the topic and payload of the event.
+        """
+        return {
+            'topic': self.topic,
+            'payload': self.payload,
+        }
+
+
+class EventChannel(ABC):
+    """
+    Defines an abstract base class for an event channel.
+
+    The purpose of this class is to serve as a blueprint for creating
+    concrete event channels that can send events. It ensures that
+    all subclasses implement the `send` method to handle the process
+    of dispatching events.
+    """
+
+    @abstractmethod
+    def send(self, event: Event) -> None:
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_config(cls, config: Dict[str, str]) -> 'EventChannel':
+        """
+        Creates an instance of the class based on the provided configuration.
+
+        :param config: A dictionary containing configuration properties.
+        :return: An initialized instance of the class.
+        """
+        pass
+
+    @classmethod
+    def validate_config(cls, config: Dict[str, str], required_keys: List[str]) -> None:
+        """
+        Validates that all required keys are present in the provided configuration.
+
+        :param config: A dictionary containing configuration properties.
+        :param required_keys: A list of keys that must be present.
+        :raises ValueError: If any of the required keys are missing.
+        """
+        missing = [key for key in required_keys if key not in config]
+        if missing:
+            raise ValueError(f"Missing required configuration keys: {missing}")
+
+
+class EventHandler:
+    """
+    Handles event-based communication within a system.
+
+    This class is responsible for managing subscription to event topics, emitting events to a channel,
+    and triggering callbacks registered for specific topics. Its primary purpose is to provide a
+    centralized mechanism for event-driven programming, where subscribers can listen and respond
+    to specific topics without direct coupling between components.
+
+    :ivar channel: The communication channel through which events are sent.
+    :type channel: EventChannel
+    :ivar _handlers: A mapping of topic patterns to lists of callback functions subscribed to the
+        respective patterns.
+    :type _handlers: Dict[str, List[Callable[[Dict[str, Any]], None]]]
+    """
+
+    def __init__(self, channel: EventChannel):
+        self.channel = channel
+        self._handlers: Dict[str, List[Callable[[Dict[str, Any]], None]]] = {}
+
+    def emit(self, topic: str, payload: Dict[str, Any]) -> None:
+        """
+        Emit an event using the specified topic and payload values.
+
+        Creates an event with the given topic and payload, and sends it
+        through the associated channel instance.
+
+        :param topic: The topic to associate with the event.
+        :param payload: A dictionary containing the event payload data.
+        :return: None
+        """
+        event = Event(topic, payload)
+        self.channel.send(event)
+
+    def on(self, topic: str, callback: Callable[[Dict[str, Any]], None]) -> None:
+        """
+        Registers a callback function for a specific topic. If the topic does not already
+        exist in the handlers, it initializes a new list for the topic and appends the
+        callback to it.
+
+        The callback will be triggered when the associated topic is processed.
+
+        :param topic: The name of the topic to register the callback for.
+        :type topic: str
+        :param callback: A callable function that will handle messages with the given
+            topic. The callable must accept a dictionary containing message data.
+        :type callback: Callable[[Dict[str, Any]], None]
+        :return: None
+        """
+        if topic not in self._handlers:
+            self._handlers[topic] = []
+        self._handlers[topic].append(callback)
+
+    def trigger(self, event: Event) -> None:
+        """
+        Triggers the execution of all callbacks that are associated with patterns
+        matching the topic of the given event. It iterates through all registered
+        patterns and checks if the event's topic matches any pattern. If a match
+        is found, all associated callbacks for the matching pattern are executed
+        with the event payload as an argument. This allows for dynamic and flexible
+        event handling based on topic patterns.
+
+        :param event: The event object containing a topic and payload.
+        :type event: Event
+        :return: None
+        """
+        matched = set()
+
+        for pattern, callbacks in self._handlers.items():
+            if fnmatch.fnmatch(event.topic, pattern):
+                matched.update(callbacks)
+
+        for callback in matched:
+            callback(event.payload)

vaitty_eventbus-0.0.1/src/vaitty_eventbus/factory.py

@@ -0,0 +1,44 @@
+from typing import Dict, Type, Optional
+
+from .channels import ConsoleEventChannel, FileEventChannel, HttpEventChannel, EventChannel
+from .core import EventHandler
+
+
+class EventHandlerFactory:
+    _registered_channels: Dict[str, Type[EventChannel]] = {
+        "console": ConsoleEventChannel,
+        "file": FileEventChannel,
+        "http": HttpEventChannel,
+    }
+
+    @classmethod
+    def register_channel(cls, channel_type: str, channel_class: Type[EventChannel]) -> None:
+        """
+        Registers a custom channel type to the channel registry.
+
+        :param channel_type: The unique string identifier for the custom channel.
+        :param channel_class: The class implementing the EventChannel for this type.
+        """
+        if not issubclass(channel_class, EventChannel):
+            raise TypeError("channel_class must be a subclass of EventChannel")
+        cls._registered_channels[channel_type.lower()] = channel_class
+
+    @staticmethod
+    def from_config(config: Optional[Dict[str, str]] = None) -> EventHandler:
+        """
+        Creates an EventHandler instance based on the provided configuration.
+
+        :param config: A dictionary containing configuration properties.
+        :return: An EventHandler instance configured with the appropriate channel.
+        """
+        if config is None:
+            config = {}
+
+        channel_type = config.get("EVENTBUS_CHANNEL", "console").lower()
+        channel_class = EventHandlerFactory._registered_channels.get(channel_type)
+
+        if channel_class is None:
+            raise ValueError(f"Unsupported channel type: {channel_type}")
+
+        channel = channel_class.from_config(config)
+        return EventHandler(channel)

vaitty_eventbus-0.0.1/src/vaitty_eventbus.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: vaitty_eventbus
+Version: 0.0.1
+Summary: A minimal, internal Python library for decoupled event communication using channels and wildcard-capable handlers.
+Home-page: https://bitbucket.org/rapihogar/event-bus
+Author: Tech Data AI
+Author-email: tech-data-ai@rapihogar.com
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

vaitty_eventbus-0.0.1/src/vaitty_eventbus.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+setup.py
+src/vaitty_eventbus/__init__.py
+src/vaitty_eventbus/channels.py
+src/vaitty_eventbus/core.py
+src/vaitty_eventbus/factory.py
+src/vaitty_eventbus.egg-info/PKG-INFO
+src/vaitty_eventbus.egg-info/SOURCES.txt
+src/vaitty_eventbus.egg-info/dependency_links.txt
+src/vaitty_eventbus.egg-info/requires.txt
+src/vaitty_eventbus.egg-info/top_level.txt
+tests/test_channels.py
+tests/test_core.py
+tests/test_factory.py

vaitty_eventbus-0.0.1/src/vaitty_eventbus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vaitty_eventbus-0.0.1/src/vaitty_eventbus.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.0.0

vaitty_eventbus-0.0.1/src/vaitty_eventbus.egg-info/top_level.txt

@@ -0,0 +1 @@
+vaitty_eventbus

vaitty_eventbus-0.0.1/tests/test_channels.py

@@ -0,0 +1,55 @@
+import unittest
+from unittest.mock import patch, mock_open, MagicMock
+
+from src.vaitty_eventbus import ConsoleEventChannel, Event, FileEventChannel, HttpEventChannel, EventBusError
+
+
+class TestChannels(unittest.TestCase):
+    def test_console_event_channel(self):
+        channel = ConsoleEventChannel()
+        with patch('builtins.print') as mocked_print:
+            event = Event("test.topic", {"key": "value"})
+            channel.send(event)
+            mocked_print.assert_called_once_with(
+                "[ConsoleChannel] Event sent: Event(topic='test.topic', payload={'key': 'value'})")
+
+    def test_file_event_channel(self):
+        channel = FileEventChannel("test.log")
+        event = Event("test.topic", {"key": "value"})
+        with patch("builtins.open", mock_open()) as mocked_file:
+            channel.send(event)
+            mocked_file.assert_called_once_with("test.log", "a")
+            mocked_file().write.assert_called_once_with("Event(topic='test.topic', payload={'key': 'value'})\n")
+
+    def test_http_event_channel(self):
+        channel = HttpEventChannel("http://example.com/events")
+        event = Event("test.topic", {"key": "value"})
+
+        with patch('requests.post') as mocked_post:
+            # Simulate a successful response
+            mocked_response = MagicMock()
+            mocked_response.raise_for_status.return_value = None
+            mocked_post.return_value = mocked_response
+
+            channel.send(event)
+
+            mocked_post.assert_called_once_with(
+                "http://example.com/events",
+                json={"topic": "test.topic", "payload": {"key": "value"}},
+                headers={}
+            )
+
+            mocked_response.raise_for_status.assert_called_once()
+
+    def test_http_event_channel_failure(self):
+        channel = HttpEventChannel("http://example.com/events")
+        event = Event("test.topic", {"key": "value"})
+
+        with patch('requests.post') as mocked_post:
+            # Simulate a failed response
+            mocked_post.side_effect = Exception("Failed to send request")
+
+            try:
+                channel.send(event)
+            except EventBusError as e:
+                self.assertEqual(str(e), "Failed to send event: Failed to send request")

vaitty_eventbus-0.0.1/tests/test_core.py

@@ -0,0 +1,73 @@
+import unittest
+from unittest.mock import MagicMock
+
+from src.vaitty_eventbus import Event, EventChannel, EventHandler
+
+
+class TestCore(unittest.TestCase):
+    def test_event_initialization(self):
+        event = Event("test.topic", {"key": "value"})
+        self.assertEqual(event.topic, "test.topic")
+        self.assertEqual(event.payload, {"key": "value"})
+
+    def test_event_repr(self):
+        event = Event("test.topic", {"key": "value"})
+        self.assertEqual(repr(event), "Event(topic='test.topic', payload={'key': 'value'})")
+
+    def test_event_invalid_topic_type(self):
+        with self.assertRaises(TypeError) as context:
+            Event(123, {"key": "value"})
+        self.assertEqual(str(context.exception), "Event topic must be a string.")
+
+    def test_event_invalid_payload_type(self):
+        with self.assertRaises(TypeError) as context:
+            Event("test.topic", ["invalid_payload"])
+        self.assertEqual(str(context.exception), "Event payload must be a dictionary.")
+
+    def test_event_handler_emit(self):
+        channel = MagicMock(spec=EventChannel)
+        handler = EventHandler(channel)
+        event_topic = "test.topic"
+        event_payload = {"key": "value"}
+
+        handler.emit(event_topic, event_payload)
+        channel.send.assert_called_once()
+        sent_event = channel.send.call_args[0][0]
+        self.assertEqual(sent_event.topic, event_topic)
+        self.assertEqual(sent_event.payload, event_payload)
+
+    def test_event_handler_on_and_trigger(self):
+        channel = MagicMock(spec=EventChannel)
+        handler = EventHandler(channel)
+
+        mock_callback = MagicMock()
+        handler.on("test.topic", mock_callback)
+
+        event = Event("test.topic", {"key": "value"})
+        handler.trigger(event)
+
+        mock_callback.assert_called_once_with({"key": "value"})
+
+    def test_event_handler_trigger_with_wildcard(self):
+        channel = MagicMock(spec=EventChannel)
+        handler = EventHandler(channel)
+
+        mock_callback = MagicMock()
+        handler.on("test.*", mock_callback)
+
+        event = Event("test.topic", {"key": "value"})
+        handler.trigger(event)
+
+        mock_callback.assert_called_once_with({"key": "value"})
+
+    def test_event_handler_trigger_no_match(self):
+        channel = MagicMock(spec=EventChannel)
+        handler = EventHandler(channel)
+
+        mock_callback = MagicMock()
+        handler.on("other.topic", mock_callback)
+
+        event = Event("test.topic", {"key": "value"})
+        handler.trigger(event)
+
+        mock_callback.assert_not_called()

vaitty_eventbus-0.0.1/tests/test_factory.py

@@ -0,0 +1,43 @@
+import unittest
+from typing import Dict
+
+from src.vaitty_eventbus import EventHandlerFactory, EventChannel, Event, ConsoleEventChannel, FileEventChannel, \
+    HttpEventChannel
+
+
+class TestFactory(unittest.TestCase):
+    def test_factory_from_config_console(self):
+        handler = EventHandlerFactory.from_config()
+        self.assertIsInstance(handler.channel, ConsoleEventChannel)
+
+    def test_factory_from_config_file(self):
+        config = {"EVENTBUS_CHANNEL": "file", "EVENTBUS_FILE": "test.log"}
+        handler = EventHandlerFactory.from_config(config=config)
+        self.assertIsInstance(handler.channel, FileEventChannel)
+        self.assertEqual(handler.channel.filename, "test.log")
+
+    def test_factory_from_config_http(self):
+        config = {"EVENTBUS_CHANNEL": "http", "EVENTBUS_HTTP_ENDPOINT": "http://example.com/events"}
+        handler = EventHandlerFactory.from_config(config=config)
+        self.assertIsInstance(handler.channel, HttpEventChannel)
+        self.assertEqual(handler.channel.endpoint, "http://example.com/events")
+
+    def test_factory_invalid_channel(self):
+        invalid_config = {"EVENTBUS_CHANNEL": "unsupported"}
+        with self.assertRaises(ValueError) as context:
+            EventHandlerFactory.from_config(invalid_config)
+        self.assertEqual(str(context.exception), "Unsupported channel type: unsupported")
+
+    def test_factory_custom_channel(self):
+        class CustomEventChannel(EventChannel):
+            @classmethod
+            def from_config(cls, config: Dict[str, str]):
+                return cls()
+
+            def send(self, event: Event) -> None:
+                pass
+
+        EventHandlerFactory.register_channel("custom", CustomEventChannel)
+        config = {"EVENTBUS_CHANNEL": "custom"}
+        handler = EventHandlerFactory.from_config(config=config)
+        self.assertIsInstance(handler.channel, CustomEventChannel)