busline 0.3.0__py3-none-any.whl

busline-0.3.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: busline
+Version: 0.3.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
+
+# Busline for Python
+
+Agnostic eventbus for Python.
+
+Official eventbus library for [Orbitalis](https://github.com/nricciardi/orbitalis)
+
+## Local EventBus
+
+### Using Publisher/Subscriber
+
+```python
+from src.eventbus.async_local_eventbus import AsyncLocalEventBus
+from src.eventbus_client.publisher.local_eventbus_publisher import LocalEventBusPublisher
+from src.event.event import Event
+from src.eventbus_client.subscriber.local_eventbus_closure_subscriber import LocalEventBusClosureSubscriber
+
+
+local_eventbus_instance = AsyncLocalEventBus()       # singleton
+
+def callback(topic_name: str, event: Event):
+    print(event)
+
+subscriber = LocalEventBusClosureSubscriber(local_eventbus_instance, callback)
+publisher = LocalEventBusPublisher(local_eventbus_instance)
+
+await subscriber.subscribe("test-topic")
+
+await publisher.publish("test-topic", Event())      # publish empty event
+```
+
+### Using EventBusClient
+
+```python
+from src.event.event import Event
+from src.eventbus_client.local_eventbus_client import LocalEventBusClient
+
+def callback(topic_name: str, event: Event):
+    print(event)
+
+client = LocalEventBusClient(callback)
+
+await client.subscribe("test")
+
+await client.publish("test", Event())
+```
+
+
+## Create Agnostic EventBus
+
+Implement business logic of your `Publisher` and `Subscriber` and... done. Nothing more.
+
+```python
+from src.event.event import Event
+from src.eventbus_client.publisher.publisher import Publisher
+
+class YourEventBusPublisher(Publisher):
+
+    async def _internal_publish(self, topic_name: str, event: Event, **kwargs):
+        pass        # send events to your eventbus (maybe in cloud?)
+```
+
+```python
+from src.eventbus_client.subscriber.subscriber import Subscriber
+from src.event.event import Event
+
+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
+from src.eventbus_client.eventbus_client import EventBusClient
+from src.event.event import Event
+
+def client_callback(topic_name: str, e: Event):
+    print(e)
+
+subscriber = YourEventBusSubscriber(...)
+publisher = YourEventBusPublisher(...)
+
+client = EventBusClient(publisher, subscriber, ClosureEventListener(client_callback))
+```
+
+
+
+
+

busline-0.3.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+event/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+event/event.py,sha256=X5HSO6SDoxUFrxMJ9gzll2lr_M5li_09o2we5hMLbUI,587
+event/event_content.py,sha256=tPvltxfs66yRmUppHvdw5ThYR_K2WitvE5sLybg6vZE,341
+event/event_metadata.py,sha256=7aaSG4Z9uQzJKRe7Jz8zD6jo6WEo3PORNbJA_RElp8I,556
+eventbus/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eventbus/async_local_eventbus.py,sha256=cRAnUPfb22q9CzNS-48aGIdxhEgwg-nGHaAhvaeVIgI,764
+eventbus/eventbus.py,sha256=INT1DYL_rlyViLTGfEpPisDFp8JUuNJ55ZOuQUjh2E4,2981
+eventbus/exceptions.py,sha256=sjWa3Eyeqyci2yVWO9jSlnaZggM3SFDbTKzMtdBX1-E,40
+eventbus/queued_local_eventbus.py,sha256=7Gog7Xy6ytBTkXvUKXsSqXSkarZtiCvGg-qdiQPAQDo,1368
+eventbus/topic.py,sha256=rzbdYrv0YLbC6CDoFGhbc8dOVc19OHCQknkTP4fZHh4,950
+eventbus_client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eventbus_client/eventbus_client.py,sha256=1n53QBf-lvoe_lJhg7gttpOWnl3db9WoKRoJj7z7dBM,3079
+eventbus_client/eventbus_connector.py,sha256=zys73X8ul1UHyJHbIcmXBLucqCQhnLLVj9xDOVc1arU,702
+eventbus_client/exceptions.py,sha256=gm7oZsXHlymheYDZb209T4FqeZN9Saft0Xklk4rOg54,55
+eventbus_client/local_eventbus_client.py,sha256=gep5sO6Oek8y-wQEe-VMlbrboAlUI4QlrNihROY9A5E,867
+eventbus_client/publisher/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eventbus_client/publisher/local_eventbus_publisher.py,sha256=fizpHwZGEDuZJHMbBC76jzzcCzbvrp1oIXYKb7KsXi4,1107
+eventbus_client/publisher/publisher.py,sha256=QzaXlKwlURA4UXUgbkyKwUxaKWbayt5tYNGHy5TtI_Q,1536
+eventbus_client/subscriber/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eventbus_client/subscriber/closure_event_listener.py,sha256=1vou3bedIIeuDzdYRJeoEvdNMZtJP_SgnxLboTgFiEg,599
+eventbus_client/subscriber/event_listener.py,sha256=nBnPA-Jt5_L0qCV-IaTfmr1RTnKe_zMRF3Ce8ciX-4M,327
+eventbus_client/subscriber/local_eventbus_closure_subscriber.py,sha256=7KPlkMXqwKMBgPhp4U6xkca-oGErdO8ch3W7Ab0XpbI,748
+eventbus_client/subscriber/local_eventbus_subscriber.py,sha256=f7Vf4IpLeQ2IaMd9kwFUGT7hXrp1AeKHintyQONJ7YE,1331
+eventbus_client/subscriber/subscriber.py,sha256=MMw_iOVEflBTLiYuEbS--hZ_fOJ3Y82wk6N0BOJXNVA,2246
+busline-0.3.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+busline-0.3.0.dist-info/METADATA,sha256=EzrREZWnK4NQ3ycylqWGSeNPwlRDfaOiijgm_nxiSX8,2891
+busline-0.3.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+busline-0.3.0.dist-info/top_level.txt,sha256=tVHbqJlz1BKM3vq9VKiyjRf2irKCgXPV22iae_fcMss,40
+busline-0.3.0.dist-info/RECORD,,

busline-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

busline-0.3.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+__init__
+event
+eventbus
+eventbus_client

event/event.py

@@ -0,0 +1,25 @@
+import uuid
+from src.event.event_content import EventContent
+from src.event.event_metadata import EventMetadata
+
+
+class Event:
+
+    def __init__(self, content: EventContent = None, metadata: EventMetadata = EventMetadata()):
+
+        self._identifier = str(uuid.uuid4())
+        self._content = content
+        self._metadata = metadata
+
+
+    @property
+    def identifier(self) -> str:
+        return self._identifier
+
+    @property
+    def content(self) -> EventContent:
+        return self._content
+
+    @property
+    def metadata(self) -> EventMetadata:
+        return self._metadata

event/event_content.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+
+class EventContent:
+
+    def __init__(self, content: Any, content_type: str):
+
+        self.__content = content
+        self.__content_type = content_type
+
+
+    @property
+    def content(self) -> Any:
+        return self.__content
+
+    @property
+    def content_type(self) -> str:
+        return self.__content_type

event/event_metadata.py

@@ -0,0 +1,26 @@
+from datetime import timezone
+import datetime
+
+
+def utc_timestamp() -> float:
+    dt = datetime.datetime.now(timezone.utc)
+
+    utc_time = dt.replace(tzinfo=timezone.utc)
+    utc_timestamp = utc_time.timestamp()
+
+    return utc_timestamp
+
+
+class EventMetadata:
+
+    def __init__(self, timestamp: float = utc_timestamp(), **extra: dict):
+        self.__timestamp = timestamp
+        self.__extra = extra
+
+    @property
+    def timestamp(self) -> float:
+        return self.__timestamp
+
+    @property
+    def extra(self) -> dict:
+        return self.__extra

eventbus/async_local_eventbus.py

@@ -0,0 +1,32 @@
+import logging
+import asyncio
+
+from src.event.event import Event
+from src.eventbus.eventbus import EventBus
+
+
+class AsyncLocalEventBus(EventBus):
+    """
+    Async local eventbus (singleton)
+
+    Author: Nicola Ricciardi
+    """
+
+    async def put_event(self, topic_name: str, event: Event):
+
+        topic_subscriptions = self.subscriptions.get(topic_name, [])
+
+        logging.debug(f"new event {event} on topic {topic_name}, notify subscribers: {topic_subscriptions}")
+
+        if len(topic_subscriptions) == 0:
+            return
+
+        tasks = []
+
+        for subscriber in topic_subscriptions:
+            task = asyncio.create_task(subscriber.on_event(topic_name, event))
+            tasks.append(task)
+
+        await asyncio.gather(*tasks)
+
+            

eventbus/eventbus.py

@@ -0,0 +1,112 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List
+from src.eventbus.exceptions import TopicNotFound
+from src.eventbus_client.subscriber.subscriber import Subscriber
+from src.eventbus.topic import Topic
+from src.event.event import Event
+
+
+
+class EventBus(ABC):
+    """
+    Abstract class used as base for new eventbus implemented in local projects.
+
+    Eventbus are *singleton*
+
+    Author: Nicola Ricciardi
+    """
+
+    # === SINGLETON pattern ===
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+
+        return cls._instance
+
+    def __init__(self):
+
+        self.__subscriptions = None
+        self.__topics = None
+
+        self.reset_topics()
+
+    def reset_topics(self):
+        self.__topics: Dict[str, Topic] = {}
+        self.__subscriptions: Dict[str, List[Subscriber]] = {}
+
+    def add_topic(self, topic: Topic):
+        self.__topics[topic.name] = topic
+        self.__subscriptions[topic.name] = []
+
+    def remove_topic(self, topic_name: str):
+        """
+        Remove topic by name
+
+        :param topic_name:
+        :return:
+        """
+
+        del self.__topics[topic_name]
+        del self.__subscriptions[topic_name]
+
+    @property
+    def topics(self) -> Dict[str, Topic]:
+        return self.__topics
+
+    @property
+    def subscriptions(self) -> Dict[str, List[Subscriber]]:
+        return self.__subscriptions
+
+    def add_subscriber(self, topic_name: str, subscriber: Subscriber, raise_if_topic_missed: bool = False):
+        """
+        Add subscriber to topic
+
+        :param raise_if_topic_missed:
+        :param topic_name:
+        :param subscriber:
+        :return:
+        """
+
+        if topic_name not in self.__topics:
+            if raise_if_topic_missed:
+                raise TopicNotFound(f"topic '{topic_name}' not found")
+
+            else:
+                self.add_topic(Topic(topic_name))
+
+        self.__subscriptions[topic_name].append(subscriber)
+
+    def remove_subscriber(self, subscriber: Subscriber, topic_name: str = None, raise_if_topic_missed: bool = False):
+        """
+        Remove subscriber from topic selected or from all if topic is None
+
+        :param raise_if_topic_missed:
+        :param subscriber:
+        :param topic_name:
+        :return:
+        """
+
+        if raise_if_topic_missed and isinstance(topic_name, str) and topic_name not in self.__topics.keys():
+            raise TopicNotFound(f"topic '{topic_name}' not found")
+
+        for name in self.__topics.keys():
+
+            if topic_name is None or topic_name == name:
+                self.__subscriptions[name].remove(subscriber)
+
+
+    @abstractmethod
+    async def put_event(self, topic_name: str, event: Event):
+        """
+        Put a new event in the bus and notify subscribers of corresponding
+        event's topic
+
+        :param topic_name:
+        :param event:
+        :return:
+        """
+
+        raise NotImplemented()
+

eventbus/exceptions.py

@@ -0,0 +1,2 @@
+class TopicNotFound(Exception):
+    pass

eventbus/queued_local_eventbus.py

@@ -0,0 +1,50 @@
+import asyncio
+import logging
+from queue import Queue
+from concurrent.futures import ThreadPoolExecutor
+from src.event.event import Event
+from src.eventbus.eventbus import EventBus
+
+
+MAX_WORKERS = 3
+MAX_QUEUE_SIZE = 0
+
+
+class QueuedLocalEventBus(EventBus):
+    """
+    Queued local eventbus (singleton). It uses a queue to store and forward events.
+
+    Author: Nicola Ricciardi
+    """
+
+    def __init__(self, max_queue_size=MAX_QUEUE_SIZE, n_workers=MAX_WORKERS):
+
+        super().__init__()
+
+        self.__queue = Queue(maxsize=max_queue_size)
+        self.__n_workers = n_workers
+
+        self.__tpool = ThreadPoolExecutor(max_workers=self.__n_workers)
+
+        for i in range(self.__n_workers):
+            self.__tpool.submit(self.__elaborate_queue)
+
+    async def put_event(self, topic_name: str, event: Event):
+        self.__queue.put((topic_name, event))
+
+    def __elaborate_queue(self):
+
+        while True:
+
+            topic_name, event = self.__queue.get()
+
+            topic_subscriptions = self.subscriptions.get(topic_name, [])
+
+            logging.debug(
+                f"new event {event} on topic {topic_name}, notify subscribers: {topic_subscriptions}")
+
+            if len(topic_subscriptions) == 0:
+                return
+
+            for subscriber in topic_subscriptions:
+                asyncio.run(subscriber.on_event(topic_name, event))

eventbus/topic.py

@@ -0,0 +1,35 @@
+
+
+class Topic:
+    """
+    Topic of generic eventbus.
+
+    :param name: unique name of the topic
+    :param content_type: MIME type which describes content of the topic (e.g. "application/json")
+    :param description: simple topic description
+    :param priority: priority of message in topic related to other topics
+
+    Author: Nicola Ricciardi
+    """
+
+    def __init__(self, name: str, content_type: str | None = None, description: str | None = None, priority: int = 0):
+        self.__name = name
+        self.__description = description
+        self.__content_type = content_type
+        self.__priority = priority
+
+    @property
+    def name(self) -> str:
+        return self.__name
+
+    @property
+    def description(self) -> str | None:
+        return self.__description
+
+    @property
+    def content_type(self) -> str | None:
+        return self.__content_type
+
+    @property
+    def priority(self) -> int:
+        return self.__priority

eventbus_client/eventbus_client.py

@@ -0,0 +1,99 @@
+from uuid import uuid4
+from src.event.event import Event
+from src.eventbus_client.eventbus_connector import EventBusConnector
+from src.eventbus_client.publisher.publisher import Publisher
+from src.eventbus_client.subscriber.event_listener import EventListener
+from src.eventbus_client.subscriber.subscriber import Subscriber
+
+
+class EventBusClient(EventBusConnector):
+    """
+    Eventbus client which should used by components which wouldn't be a publisher/subscriber, but they need them
+
+    Author: Nicola Ricciardi
+    """
+
+    def __init__(self, publisher: Publisher, subscriber: Subscriber, event_listener: EventListener | None = None, client_id: str = str(uuid4())):
+        EventBusConnector.__init__(self, client_id)
+
+        self._id = client_id
+        self.__publisher: Publisher = None
+        self.__subscriber: Subscriber = None
+        self.__event_listener: EventListener = None
+
+        self.publisher = publisher
+        self.subscriber = subscriber
+        self.event_listener = event_listener
+
+    @property
+    def publisher(self) -> Publisher:
+        return self.__publisher
+
+    @publisher.setter
+    def publisher(self, publisher: Publisher):
+        self.__publisher = publisher
+
+    @property
+    def subscriber(self) -> Subscriber:
+        return self.__subscriber
+
+    @subscriber.setter
+    def subscriber(self, subscriber: Subscriber):
+
+        original_on_event = subscriber.on_event
+
+        async def on_event_wrapper(*args, **kwargs):        # wrap on_event method to call self.on_event
+            await original_on_event(*args, **kwargs)
+            await self.on_event(*args, **kwargs)
+
+        subscriber.on_event = on_event_wrapper
+        self.__subscriber = subscriber
+
+    @property
+    def event_listener(self) -> EventListener:
+        return self.__event_listener
+
+    @event_listener.setter
+    def event_listener(self, event_listener: EventListener):
+        self.__event_listener = event_listener
+
+    async def connect(self):
+        c1 = self.__publisher.connect()
+        c2 = self.__subscriber.connect()
+
+        await c1
+        await c2
+
+    async def disconnect(self):
+        d1 = self.__publisher.disconnect()
+        d2 = self.__subscriber.disconnect()
+
+        await d1
+        await d2
+
+    async def publish(self, topic_name: str, event: Event, **kwargs):
+        """
+        Alias of `client.publisher.publish(...)`
+        """
+
+        await self.__publisher.publish(topic_name, event, **kwargs)
+
+    async def subscribe(self, topic_name: str, **kwargs):
+        """
+        Alias of `client.subscriber.subscribe(...)`
+        """
+
+        await self.__subscriber.subscribe(topic_name, **kwargs)
+
+    async def unsubscribe(self, topic_name: str | None = None, **kwargs):
+        """
+        Alias of `client.subscriber.unsubscribe(...)`
+        """
+
+        await self.__subscriber.unsubscribe(topic_name, **kwargs)
+
+    async def on_event(self, topic_name: str, event: Event, **kwargs):
+        if self.__event_listener is not None:
+            await self.__event_listener.on_event(topic_name, event, **kwargs)
+
+

eventbus_client/eventbus_connector.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from uuid import uuid4
+
+
+class EventBusConnector(ABC):
+    """
+    Abstract class which is used as base class to create a component which interacts with eventbus
+
+    Author: Nicola Ricciardi
+    """
+
+    def __init__(self, connector_id: str = str(uuid4())):
+        self._id = connector_id
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @id.setter
+    def id(self, value):
+        self._id = value
+
+    @abstractmethod
+    async def connect(self):
+        """
+        Connect to eventbus
+
+        :return:
+        """
+
+    @abstractmethod
+    async def disconnect(self):
+        """
+        Disconnect to eventbus
+
+        :return:
+        """

eventbus_client/exceptions.py

@@ -0,0 +1,4 @@
+
+
+class EventBusClientNotConnected(Exception):
+    pass

eventbus_client/local_eventbus_client.py

@@ -0,0 +1,25 @@
+from typing import Callable
+from uuid import uuid4
+
+from src.event.event import Event
+from src.eventbus.async_local_eventbus import AsyncLocalEventBus
+from src.eventbus_client.eventbus_client import EventBusClient
+from src.eventbus_client.publisher.local_eventbus_publisher import LocalEventBusPublisher
+from src.eventbus_client.subscriber.local_eventbus_closure_subscriber import LocalEventBusClosureSubscriber
+
+
+class LocalEventBusClient(EventBusClient):
+
+    def __init__(self, on_event_callback: Callable[[str, Event], None], client_id: str = str(uuid4())):
+
+        eventbus_instance = AsyncLocalEventBus()
+
+        EventBusClient.__init__(
+            self,
+            publisher=LocalEventBusPublisher(eventbus_instance),
+            subscriber=LocalEventBusClosureSubscriber(eventbus_instance, on_event_callback),
+            client_id=client_id
+        )
+
+
+

eventbus_client/publisher/local_eventbus_publisher.py

@@ -0,0 +1,35 @@
+from src.event.event import Event
+from src.eventbus.eventbus import EventBus
+from src.eventbus_client.exceptions import EventBusClientNotConnected
+from src.eventbus_client.publisher.publisher import Publisher
+
+
+class LocalEventBusPublisher(Publisher):
+    """
+    Publisher which works with local eventbus, this class can be initialized and used stand-alone
+
+    Author: Nicola Ricciardi
+    """
+
+    def __init__(self, eventbus_instance: EventBus):
+        Publisher.__init__(self)
+
+        self._eventbus = eventbus_instance
+        self._connected = False
+
+    async def connect(self):
+        self._connected = True
+
+    async def disconnect(self):
+        self._connected = False
+
+    async def _internal_publish(self, topic_name: str, event: Event, raise_if_not_connected: bool = False, **kwargs):
+
+        if raise_if_not_connected and not self._connected:
+            raise EventBusClientNotConnected()
+        else:
+            await self.connect()
+
+        self.on_publishing(topic_name, event)
+        await self._eventbus.put_event(topic_name, event)
+        self.on_published(topic_name, event)