busline 0.3.0__tar.gz → 0.5.0__tar.gz

busline-0.5.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: busline
+Version: 0.5.0
+Summary: Agnostic eventbus for Python
+Author-email: Nicola Ricciardi <ricciardincl@gmail.com>
+Project-URL: Homepage, https://github.com/nricciardi/py-busline
+Project-URL: Issues, https://github.com/nricciardi/py-busline/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+from busline.local.subscriber.local_subscriber import LocalEventBusSubscriberfrom busline.local.eventbus.local_eventbus import LocalEventBus
+
+# Busline for Python
+
+Agnostic eventbus for Python.
+
+Official eventbus library for [Orbitalis](https://github.com/orbitalis-framework/py-orbitalis)
+
+## Get Start
+
+### Local EventBus
+
+#### Using Publisher/Subscriber
+
+```python
+local_eventbus_instance1 = LocalEventBus()       # singleton
+local_eventbus_instance2 = LocalEventBus()       # singleton
+
+subscriber = LocalEventBusSubscriber(
+    eventbus=local_eventbus_instance1,
+    fallback_event_handler=ClosureEventHandler(lambda t, e: ...)
+)
+publisher = LocalEventBusPublisher(eventbus=local_eventbus_instance2)
+
+await subscriber.connect()
+await publisher.connect()
+
+await subscriber.subscribe("topic-name")
+
+await publisher.publish("topic-name", Event())  # publish empty event
+
+# ...subscriber receives Event() thanks to singleton LocalEventBus()
+
+await subscriber.disconnect()
+await publisher.disconnect()
+```
+
+#### Using EventBusClient
+
+```python
+client = LocalPubSubClientBuilder()\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: both publisher and subscriber will use singleton local eventbus (default)
+
+await client.connect()
+
+await client.subscribe("topic-name")
+
+await client.publish("topic-name", Event())  # publish empty event
+
+# ...client receives Event()
+
+await client.disconnect()
+```
+
+#### MultiClient
+
+```python
+local_eventbus_instance1 = AsyncLocalEventBus()  # not singleton
+local_eventbus_instance2 = AsyncLocalEventBus()  # not singleton
+
+client1 = LocalPubSubClientBuilder(local_eventbus_instance1)\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: client1 pub/sub use `local_eventbus_instance1`
+
+client2 = LocalPubSubClientBuilder(local_eventbus_instance2)\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: client2 pub/sub use `local_eventbus_instance2`
+
+multi_client = EventBusMultiClient([
+    client1,
+    client2
+])
+
+await multi_client.connect()
+
+await multi_client.subscribe("topic-name", handler=ClosureEventHandler(lambda t, e: ...))
+
+await multi_client.publish("topic-name", Event())
+
+# ...both clients receive Event() and handle it using `on_event_callback`
+
+await multi_client.disconnect()
+```
+
+#### Specifying EventBus
+
+Local eventbuses use an internal implemented `EventBus`, this sort of architecture is not required in other scenarios such
+as MQTT, because the "eventbus" is the broken.
+
+Anyway, you may want to specify what `EventBus` instance your pub/sub components should use:
+
+```python
+local_eventbus_instance = AsyncLocalEventBus()
+
+subscriber = LocalEventBusClosureSubscriber(callback, eventbus_instance=local_eventbus_instance)
+publisher = LocalEventBusPublisher(eventbus_instance=local_eventbus_instance2)
+```
+
+### EventRegistry
+
+In order to help `event_type` management, a basic `EventRegistry` is provided to auto-build right inherited class of `Event`:
+
+```python
+class Event1(Event):
+    def my_value1(self) -> int:
+        return self.content
+    
+class Event2(Event):
+    def my_value2(self) -> int:
+        return self.content
+
+
+event_registry = EventRegistry()    # singleton
+
+event_registry.register("event1", Event1)
+event_registry.register("event2", Event2)
+
+generic_event1 = Event(content=1, event_type="event1")
+generic_event2 = Event(content=2, event_type="event2")
+generic_unknown_event = Event(content=2, event_type="unknown")
+
+# first approach
+event1_class = event_registry.retrive_class(generic_event1)
+event1_class: Type[Event1] = event1_class
+event1 = event1_class.from_event(generic_event1)
+
+# second approach
+event2: Event2 = event_registry.convert(generic_event2)
+```
+
+### Create Agnostic EventBus
+
+Implement business logic of your `Publisher` and `Subscriber` and... done. Nothing more.
+
+```python
+class YourEventBusPublisher(Publisher):
+
+    async def _internal_publish(self, topic_name: str, event: Event, **kwargs):
+        pass  # send events to your eventbus (maybe in cloud?)
+```
+
+```python
+class YourEventBusSubscriber(Subscriber):
+
+    async def on_event(self, topic_name: str, event: Event, **kwargs):
+        pass  # receive your events
+```
+
+You could create a client to allow components to use it instead of become a publisher or subscriber.
+
+```python
+subscriber = YourEventBusSubscriber(...)
+publisher = YourEventBusPublisher(...)
+
+client = PubSubClient(publisher, subscriber)
+```
+
+
+## Subscriber
+
+`Subscriber` is the component which receives events. It is a `EventHandler`, therefore it has `on_event` method in which 
+every event (and related topic) is passed.
+
+### TopicSubscriber
+
+`TopicSubscriber` is an enhanced subscriber which manages an handler for each topic. We can specify a _fallback handler_,
+which is run if no handler is spefied for a subscribed topic.
+
+If the subscriber is not subscribed to a topic, fallback handler is not called.
+
+A local implementation is already provided:
+
+```python
+subscriber = LocalEventBusSubscriber(fallback_event_handler=...)
+
+await subscriber.subscribe("t1")
+await subscriber.subscribe("t2", handler=...)
+```
+
+
+
+
+
+
+
+
+
+
+
+

busline-0.5.0/README.md

@@ -0,0 +1,200 @@
+from busline.local.subscriber.local_subscriber import LocalEventBusSubscriberfrom busline.local.eventbus.local_eventbus import LocalEventBus
+
+# Busline for Python
+
+Agnostic eventbus for Python.
+
+Official eventbus library for [Orbitalis](https://github.com/orbitalis-framework/py-orbitalis)
+
+## Get Start
+
+### Local EventBus
+
+#### Using Publisher/Subscriber
+
+```python
+local_eventbus_instance1 = LocalEventBus()       # singleton
+local_eventbus_instance2 = LocalEventBus()       # singleton
+
+subscriber = LocalEventBusSubscriber(
+    eventbus=local_eventbus_instance1,
+    fallback_event_handler=ClosureEventHandler(lambda t, e: ...)
+)
+publisher = LocalEventBusPublisher(eventbus=local_eventbus_instance2)
+
+await subscriber.connect()
+await publisher.connect()
+
+await subscriber.subscribe("topic-name")
+
+await publisher.publish("topic-name", Event())  # publish empty event
+
+# ...subscriber receives Event() thanks to singleton LocalEventBus()
+
+await subscriber.disconnect()
+await publisher.disconnect()
+```
+
+#### Using EventBusClient
+
+```python
+client = LocalPubSubClientBuilder()\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: both publisher and subscriber will use singleton local eventbus (default)
+
+await client.connect()
+
+await client.subscribe("topic-name")
+
+await client.publish("topic-name", Event())  # publish empty event
+
+# ...client receives Event()
+
+await client.disconnect()
+```
+
+#### MultiClient
+
+```python
+local_eventbus_instance1 = AsyncLocalEventBus()  # not singleton
+local_eventbus_instance2 = AsyncLocalEventBus()  # not singleton
+
+client1 = LocalPubSubClientBuilder(local_eventbus_instance1)\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: client1 pub/sub use `local_eventbus_instance1`
+
+client2 = LocalPubSubClientBuilder(local_eventbus_instance2)\
+                    .with_default_publisher()\
+                    .with_closure_subscriber(lambda t, e: ...)\
+                    .build()
+
+# NOTE: client2 pub/sub use `local_eventbus_instance2`
+
+multi_client = EventBusMultiClient([
+    client1,
+    client2
+])
+
+await multi_client.connect()
+
+await multi_client.subscribe("topic-name", handler=ClosureEventHandler(lambda t, e: ...))
+
+await multi_client.publish("topic-name", Event())
+
+# ...both clients receive Event() and handle it using `on_event_callback`
+
+await multi_client.disconnect()
+```
+
+#### Specifying EventBus
+
+Local eventbuses use an internal implemented `EventBus`, this sort of architecture is not required in other scenarios such
+as MQTT, because the "eventbus" is the broken.
+
+Anyway, you may want to specify what `EventBus` instance your pub/sub components should use:
+
+```python
+local_eventbus_instance = AsyncLocalEventBus()
+
+subscriber = LocalEventBusClosureSubscriber(callback, eventbus_instance=local_eventbus_instance)
+publisher = LocalEventBusPublisher(eventbus_instance=local_eventbus_instance2)
+```
+
+### EventRegistry
+
+In order to help `event_type` management, a basic `EventRegistry` is provided to auto-build right inherited class of `Event`:
+
+```python
+class Event1(Event):
+    def my_value1(self) -> int:
+        return self.content
+    
+class Event2(Event):
+    def my_value2(self) -> int:
+        return self.content
+
+
+event_registry = EventRegistry()    # singleton
+
+event_registry.register("event1", Event1)
+event_registry.register("event2", Event2)
+
+generic_event1 = Event(content=1, event_type="event1")
+generic_event2 = Event(content=2, event_type="event2")
+generic_unknown_event = Event(content=2, event_type="unknown")
+
+# first approach
+event1_class = event_registry.retrive_class(generic_event1)
+event1_class: Type[Event1] = event1_class
+event1 = event1_class.from_event(generic_event1)
+
+# second approach
+event2: Event2 = event_registry.convert(generic_event2)
+```
+
+### Create Agnostic EventBus
+
+Implement business logic of your `Publisher` and `Subscriber` and... done. Nothing more.
+
+```python
+class YourEventBusPublisher(Publisher):
+
+    async def _internal_publish(self, topic_name: str, event: Event, **kwargs):
+        pass  # send events to your eventbus (maybe in cloud?)
+```
+
+```python
+class YourEventBusSubscriber(Subscriber):
+
+    async def on_event(self, topic_name: str, event: Event, **kwargs):
+        pass  # receive your events
+```
+
+You could create a client to allow components to use it instead of become a publisher or subscriber.
+
+```python
+subscriber = YourEventBusSubscriber(...)
+publisher = YourEventBusPublisher(...)
+
+client = PubSubClient(publisher, subscriber)
+```
+
+
+## Subscriber
+
+`Subscriber` is the component which receives events. It is a `EventHandler`, therefore it has `on_event` method in which 
+every event (and related topic) is passed.
+
+### TopicSubscriber
+
+`TopicSubscriber` is an enhanced subscriber which manages an handler for each topic. We can specify a _fallback handler_,
+which is run if no handler is spefied for a subscribed topic.
+
+If the subscriber is not subscribed to a topic, fallback handler is not called.
+
+A local implementation is already provided:
+
+```python
+subscriber = LocalEventBusSubscriber(fallback_event_handler=...)
+
+await subscriber.subscribe("t1")
+await subscriber.subscribe("t2", handler=...)
+```
+
+
+
+
+
+
+
+
+
+
+
+

busline-0.5.0/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

{busline-0.3.0/src/eventbus_client → busline-0.5.0/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-0.5.0/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-0.5.0/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-0.5.0/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
+