busline 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

busline/client/client.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from busline.event.event import Event
+
+
+class EventBusClient(ABC):
+
+    @abstractmethod
+    async def connect(self):
+        pass
+
+    @abstractmethod
+    async def disconnect(self):
+        pass
+
+    @abstractmethod
+    async def publish(self, topic: str, event: Event, **kwargs):
+        pass
+
+    @abstractmethod
+    async def subscribe(self, topic: str, **kwargs):
+        pass
+
+    @abstractmethod
+    async def unsubscribe(self, topic: Optional[str] = None, **kwargs):
+        pass

{eventbus_client → busline/client}/eventbus_connector.py

@@ -1,24 +1,19 @@
 from abc import ABC, abstractmethod
 from uuid import uuid4
+from typing import Optional
+from dataclasses import dataclass, field
 
 
+@dataclass(kw_only=True)
 class EventBusConnector(ABC):
     """
-    Abstract class which is used as base class to create a component which interacts with eventbus
+    Abstract class which provides methods to interact with eventbus
 
     Author: Nicola Ricciardi
     """
 
-    def __init__(self, connector_id: str = str(uuid4())):
-        self._id = connector_id
+    identifier: str = field(default=str(uuid4()))
 
-    @property
-    def id(self) -> str:
-        return self._id
-
-    @id.setter
-    def id(self, value):
-        self._id = value
 
     @abstractmethod
     async def connect(self):

busline/client/multiclient.py

@@ -0,0 +1,41 @@
+import asyncio
+from dataclasses import dataclass
+from typing import List, Optional, override
+
+from busline.client.client import EventBusClient
+from busline.event.event import Event
+
+
+@dataclass
+class EventBusMultiClient(EventBusClient):
+
+    clients: List[EventBusClient]
+
+    @classmethod
+    def from_client(cls, client: EventBusClient):
+        return cls([client])
+
+    @override
+    async def connect(self):
+        tasks = [client.connect() for client in self.clients]
+        await asyncio.gather(*tasks)
+
+    @override
+    async def disconnect(self):
+        tasks = [client.disconnect() for client in self.clients]
+        await asyncio.gather(*tasks)
+
+    @override
+    async def publish(self, topic: str, event: Event, **kwargs):
+        tasks = [client.publish(topic, event, **kwargs) for client in self.clients]
+        await asyncio.gather(*tasks)
+
+    @override
+    async def subscribe(self, topic: str, **kwargs):
+        tasks = [client.subscribe(topic, **kwargs) for client in self.clients]
+        await asyncio.gather(*tasks)
+
+    @override
+    async def unsubscribe(self, topic: Optional[str] = None, **kwargs):
+        tasks = [client.unsubscribe(topic, **kwargs) for client in self.clients]
+        await asyncio.gather(*tasks)

busline/client/publisher/publisher.py

@@ -0,0 +1,60 @@
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from busline.event.event import Event
+from busline.client.eventbus_connector import EventBusConnector
+
+
+@dataclass
+class Publisher(EventBusConnector, ABC):
+    """
+    Abstract class which can be implemented by your components which must be able to publish on eventbus
+
+    Author: Nicola Ricciardi
+    """
+
+    def __repr__(self) -> str:
+        return f"Publisher({self.identifier})"
+
+    @abstractmethod
+    async def _internal_publish(self, topic: str, event: Event, **kwargs):
+        """
+        Actual publish on topic the event
+
+        :param topic:
+        :param event:
+        :return:
+        """
+
+    async def publish(self, topic: str, event: Event, **kwargs):
+        """
+        Publish on topic the event
+
+        :param topic:
+        :param event:
+        :return:
+        """
+
+        logging.info(f"{self}: publish on {topic} -> {event}")
+        await self.on_publishing(topic, event, **kwargs)
+        await self._internal_publish(topic, event, **kwargs)
+        await self.on_published(topic, event, **kwargs)
+
+
+    async def on_publishing(self, topic: str, event: Event, **kwargs):
+        """
+        Callback called on publishing start
+
+        :param topic:
+        :param event:
+        :return:
+        """
+
+    async def on_published(self, topic: str, event: Event, **kwargs):
+        """
+        Callback called on publishing end
+
+        :param topic:
+        :param event:
+        :return:
+        """

busline/client/pubsub_client.py

@@ -0,0 +1,128 @@
+import asyncio
+from dataclasses import dataclass, field
+from typing import Optional, override, List, Self
+
+from busline.client.client import EventBusClient
+from busline.client.publisher.publisher import Publisher
+from busline.event.event import Event
+from busline.client.subscriber.subscriber import Subscriber
+
+
+@dataclass
+class PubSubClient(EventBusClient):
+    """
+    Eventbus client which should used by components which wouldn't be a publisher/subscriber, but they need them
+
+    Author: Nicola Ricciardi
+    """
+
+    publishers: List[Publisher]
+    subscribers: List[Subscriber]
+
+    @classmethod
+    def from_pubsub(cls, publisher: Optional[Publisher] = None, subscriber: Optional[Subscriber] = None) -> Self:
+
+        publishers = []
+        if publisher is not None:
+            publishers = [publisher]
+
+        subscribers = []
+        if subscriber is not None:
+            subscribers = [subscriber]
+
+        return cls(publishers, subscribers)
+
+    @classmethod
+    def from_pubsub_client(cls, client: 'PubSubClient') -> Self:
+        return cls(client.publishers.copy(), client.subscribers.copy())
+
+    @override
+    async def connect(self):
+        """
+        Connect all publishers and subscribers
+        """
+
+        tasks = [publisher.connect() for publisher in self.publishers]
+        tasks += [subscriber.connect() for subscriber in self.subscribers]
+
+        await asyncio.gather(*tasks)
+
+    @override
+    async def disconnect(self):
+        """
+        Disconnect all publishers and subscribers
+        """
+
+        tasks = [publisher.disconnect() for publisher in self.publishers]
+        tasks += [subscriber.disconnect() for subscriber in self.subscribers]
+
+        await asyncio.gather(*tasks)
+
+    @override
+    async def publish(self, topic: str, event: Event, **kwargs):
+        """
+        Publish event using all publishers
+        """
+
+        await asyncio.gather(*[
+            publisher.publish(topic, event, **kwargs) for publisher in self.publishers
+        ])
+
+    @override
+    async def subscribe(self, topic: str, **kwargs):
+        """
+        Subscribe all subscribers on topic
+        """
+
+        await asyncio.gather(*[
+            subscriber.subscribe(topic, **kwargs) for subscriber in self.subscribers
+        ])
+
+    @override
+    async def unsubscribe(self, topic: Optional[str] = None, **kwargs):
+        """
+        Alias of `client.subscriber.unsubscribe(...)`
+        """
+
+        await asyncio.gather(*[
+            subscriber.unsubscribe(topic, **kwargs) for subscriber in self.subscribers
+        ])
+
+
+@dataclass
+class PubSubClientBuilder:
+    """
+    Builder for a pub/sub client.
+
+    Author: Nicola Ricciardi
+    """
+
+    base_client: PubSubClient = field(
+        default_factory=lambda: PubSubClient([], []),
+        kw_only=True
+    )
+
+
+    def with_publisher(self, publisher: Publisher) -> Self:
+        self.base_client.publishers.append(publisher)
+
+        return self
+
+    def with_publishers(self, publishers: List[Publisher]) -> Self:
+        self.base_client.publishers.extend(publishers)
+
+        return self
+
+    def with_subscriber(self, subscriber: Subscriber) -> Self:
+        self.base_client.subscribers.append(subscriber)
+
+        return self
+
+    def with_subscribers(self, subscribers: List[Subscriber]) -> Self:
+        self.base_client.subscribers.extend(subscribers)
+
+        return self
+
+    def build(self) -> PubSubClient:
+        return self.base_client
+

busline/client/subscriber/event_handler/closure_event_handler.py

@@ -0,0 +1,18 @@
+from typing import Callable
+from dataclasses import dataclass
+from busline.event.event import Event
+from busline.client.subscriber.event_handler.event_handler import EventHandler
+
+
+@dataclass
+class ClosureEventHandler(EventHandler):
+    """
+    Event handler which use a pre-defined callback as `on_event`
+
+    Author: Nicola Ricciardi
+    """
+
+    on_event_callback: Callable[[str, Event], None]
+
+    async def handle(self, topic: str, event: Event):
+        self.on_event_callback(topic, event)

busline/client/subscriber/event_handler/event_handler.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from busline.event.event import Event
+
+
+class EventHandler(ABC):
+
+    @abstractmethod
+    async def handle(self, topic: str, event: Event):
+        """
+        Manage an event of a topic
+
+        :param topic:
+        :param event:
+        :return:
+        """

busline/client/subscriber/event_handler/multi_handler.py

@@ -0,0 +1,30 @@
+from typing import List
+import asyncio
+from dataclasses import dataclass
+from busline.event.event import Event
+from busline.client.subscriber.event_handler.event_handler import EventHandler
+
+
+@dataclass
+class MultiEventHandler(EventHandler):
+    """
+    Call a batch of pre-defined handlers.
+
+    Another parameter can be specified. If strict order is False, async capabilities can be exploited
+
+    Author: Nicola Ricciardi
+    """
+
+    handlers: List[EventHandler]
+    strict_order: bool = False
+
+
+    async def handle(self, topic: str, event: Event):
+        if self.strict_order:
+            for handler in self.handlers:
+                await handler.handle(topic, event)
+        else:
+            tasks = [handler.handle(topic, event) for handler in self.handlers]
+
+            await asyncio.gather(*tasks)
+            

busline/client/subscriber/subscriber.py

@@ -0,0 +1,109 @@
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from busline.client.eventbus_connector import EventBusConnector
+from busline.event.event import Event
+
+
+@dataclass
+class Subscriber(EventBusConnector, ABC):
+    """
+    Abstract class which can be implemented by your components which must be able to subscribe on eventbus
+
+    Author: Nicola Ricciardi
+    """
+
+    def __repr__(self) -> str:
+        return f"Subscriber({self.identifier})"
+
+    @abstractmethod
+    async def on_event(self, topic: str, event: Event):
+        """
+        Callback called when an event arrives from a topic
+        """
+
+    async def notify(self, topic: str, event: Event, **kwargs):
+        """
+        Notify subscriber
+        """
+
+        logging.info(f"{self}: incoming event on {topic} -> {event}")
+        await self.on_event(topic, event)
+
+    @abstractmethod
+    async def _internal_subscribe(self, topic: str, **kwargs):
+        """
+        Actual subscribe to topic
+
+        :param topic:
+        :return:
+        """
+
+    @abstractmethod
+    async def _internal_unsubscribe(self, topic: Optional[str] = None, **kwargs):
+        """
+        Actual unsubscribe to topic
+
+        :param topic:
+        :return:
+        """
+
+    async def subscribe(self, topic: str, **kwargs):
+        """
+        Subscribe to topic
+
+        :param topic:
+        :return:
+        """
+
+        logging.info(f"{self}: subscribe on topic {topic}")
+        await self._on_subscribing(topic, **kwargs)
+        await self._internal_subscribe(topic, **kwargs)
+        await self._on_subscribed(topic, **kwargs)
+
+    async def unsubscribe(self, topic: Optional[str] = None, **kwargs):
+        """
+        Unsubscribe to topic
+
+        :param topic:
+        :return:
+        """
+
+        logging.info(f"{self}: unsubscribe from topic {topic}")
+        await self._on_unsubscribing(topic, **kwargs)
+        await self._internal_unsubscribe(topic, **kwargs)
+        await self._on_unsubscribed(topic, **kwargs)
+
+    async def _on_subscribing(self, topic: str, **kwargs):
+        """
+        Callback called on subscribing
+
+        :param topic:
+        :return:
+        """
+
+    async def _on_subscribed(self, topic: str, **kwargs):
+        """
+        Callback called on subscribed
+
+        :param topic:
+        :return:
+        """
+
+    async def _on_unsubscribing(self, topic: Optional[str], **kwargs):
+        """
+        Callback called on unsubscribing
+
+        :param topic:
+        :return:
+        """
+
+    async def _on_unsubscribed(self, topic: Optional[str], **kwargs):
+        """
+        Callback called on unsubscribed
+
+        :param topic:
+        :return:
+        """

busline/client/subscriber/topic_subscriber.py

@@ -0,0 +1,79 @@
+import asyncio
+import logging
+from abc import ABC
+from typing import Dict, List, Callable, Optional, override
+from dataclasses import dataclass, field
+from busline.client.subscriber.event_handler.event_handler import EventHandler
+from busline.client.subscriber.subscriber import Subscriber
+from busline.event.event import Event
+from busline.exceptions import EventHandlerNotFound
+
+
+@dataclass(kw_only=True)
+class TopicSubscriber(Subscriber, ABC):
+    """
+    Handles different topic events using ad hoc handlers defined by user,
+    else it uses fallback handler if provided (otherwise throws an exception)
+
+    Attributes:
+        fallback_event_handler: event handler used for a topic if no event handler is specified for that topic
+        handlers: event handler for each topic (i.e. key); notice that key can also be a string with wildcards
+        topic_names_matcher: function used to check match between two topic name (with wildcards); default "t1 == t2"
+        event_handler_always_required: raise an exception if no handlers are found for a topic
+
+    Author: Nicola Ricciardi
+    """
+
+    fallback_event_handler: Optional[EventHandler] = field(default=None)
+    handlers: Dict[str, EventHandler] = field(default_factory=dict)
+    topic_names_matcher: Callable[[str, str], bool] = field(repr=False, default=lambda t1, t2: t1 == t2)
+    event_handler_always_required: bool = field(default=False)
+
+    @override
+    async def _on_subscribing(self, topic: str, handler: Optional[EventHandler] = None, **kwargs):
+
+        if self.fallback_event_handler is None:
+            if self.event_handler_always_required:
+                raise EventHandlerNotFound()
+            else:
+                logging.warning(f"{self}: event handler for topic '{topic}' not found")
+
+    @override
+    async def _on_subscribed(self, topic: str, handler: Optional[EventHandler] = None, **kwargs):
+
+        self.handlers[topic] = handler
+
+    @override
+    async def _on_unsubscribed(self, topic: str | None, **kwargs):
+
+        if topic is None:
+            self.handlers = {}
+        else:
+            del self.handlers[topic]
+
+    def __get_handlers_of_topic(self, topic: str) -> List[EventHandler]:
+
+        handlers = []
+        for t, h in self.handlers.items():
+            if self.topic_names_matcher(topic, t):
+                if h is not None:
+                    handlers.append(h)
+                else:
+                    if self.fallback_event_handler is not None:
+                        handlers.append(self.fallback_event_handler)
+                    else:
+                        if self.event_handler_always_required:
+                            raise EventHandlerNotFound()
+                        else:
+                            logging.warning(f"{self}: event handler for topic '{topic}' not found")
+
+        return handlers
+
+    @override
+    async def on_event(self, topic: str, event: Event):
+
+        handlers_of_topic: List[EventHandler] = self.__get_handlers_of_topic(topic)
+
+        if len(handlers_of_topic) > 0:
+            tasks = [handler.handle(topic, event) for handler in handlers_of_topic]
+            await asyncio.gather(*tasks)

busline/event/event.py

@@ -0,0 +1,47 @@
+import json
+import uuid
+from typing import Any, Self
+import datetime
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Event:
+    """
+    Event publishable in an eventbus
+
+    Author: Nicola Ricciardi
+    """
+
+    identifier: str = field(default=str(uuid.uuid4()))
+    content: Any = field(default=None)
+    content_type: Optional[str] = field(default=None)
+    event_type: Optional[str] = field(default=None)
+    timestamp: float = field(default_factory=lambda: datetime.datetime.now(datetime.timezone.utc).timestamp())
+    metadata: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """
+        Build event object from JSON string
+        """
+
+        return cls(**json.loads(json_str))
+
+    @classmethod
+    def from_event(cls, event: 'Event') -> Self:
+        """
+        Build event object based on Event (base) class.
+
+        This method can be useful when Event class is inherited and an event registry is used.
+        """
+
+        return cls(
+            identifier=event.identifier,
+            content=event.content,
+            content_type=event.content_type,
+            event_type=event.event_type,
+            timestamp=event.timestamp,
+            metadata=event.metadata
+        )

busline/event/registry.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass, field
+from typing import Dict, Type
+
+from busline.event.event import Event
+
+class _Singleton(type):
+    _instances = {}
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super().__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+
+@dataclass
+class EventRegistry(metaclass=_Singleton):
+    """
+    Registry to manage different event types
+
+    Author: Nicola Ricciardi
+    """
+
+    associations: Dict[str, Type[Event]] = field(default_factory=dict)
+
+    def unregister(self, event_type: str):
+        """
+        Remove an event type association
+        """
+
+        self.associations.pop(event_type)
+
+    def register(self, event_type: str, event_class: Type[Event]):
+        """
+        Add a new association between an event type and an event class
+        """
+
+        self.associations[event_type] = event_class
+
+    def retrive_class(self, event) -> Type[Event]:
+        """
+        Retrive event class of event input based on saved associations and given event type
+
+        KeyError is raised if no association is found
+        """
+
+        return self.associations[event.event_type]
+
+    def convert(self, event: Event, raise_on_miss: bool = True) -> Event:
+        """
+        Convert a generic event, auto-building the right event class based on event type.
+
+        If raise_on_miss=True, a KeyError exception is raised. Otherwise, input is returned in output.
+        """
+
+        if event.event_type not in self.associations and not raise_on_miss:
+            return event
+
+        event_class: Type[Event] = self.retrive_class(event)
+
+        return event_class.from_event(event)
+
+
+
+
+
+
+