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

busline-0.5.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,36 @@
+busline/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/exceptions.py,sha256=T83gWMYpQor7DQZsg-UinsxJ9Xe2PldOYeA7mBjAMDw,144
+busline/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/client/client.py,sha256=4IGMJXp_46cPOXJaMeix45rUkxRNlSFJXch2hLy0C70,553
+busline/client/eventbus_connector.py,sha256=V3D5f4bddlQW1oiZzjvNTsVa0yIHAjYHG03YV3zwz5c,596
+busline/client/multiclient.py,sha256=QnKK8ShrwbuS1fnsXVhRgMnBzIbPgnDkBPGjswDilR8,1251
+busline/client/pubsub_client.py,sha256=QzzJf_Uap9d1Y18PB_rZwU4fNOtSnG3MmFUykxCGt2g,3449
+busline/client/publisher/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/client/publisher/publisher.py,sha256=FUht2eeV25lrQzgHxB0OjijEGUiTSan8AEjb-IqYjX8,1521
+busline/client/subscriber/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/client/subscriber/subscriber.py,sha256=QHMEi6PbzoiY6SywVGPjOBUL86PD3OYRVH6fCTeZPfw,2713
+busline/client/subscriber/topic_subscriber.py,sha256=uUdgmwkGSn0A1aM81CxuitmKLxNL3QMxAlO0AkD1xE4,3157
+busline/client/subscriber/event_handler/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/client/subscriber/event_handler/closure_event_handler.py,sha256=YvgHEDgsWkW5shZ4r11pPSXnPotcXcr56xQQJDnkmxg,497
+busline/client/subscriber/event_handler/event_handler.py,sha256=az-zyJpZykowWN9M0x7PzO1qsUUOgVcEqi15crX8txc,296
+busline/client/subscriber/event_handler/multi_handler.py,sha256=bU2bEfIlOcSm6vGf_3ewDQMja6lZFsfRJ_7pOq159Qk,825
+busline/event/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/event/event.py,sha256=a1-COH-0hOwFQnbFpwWWJHpr0GqwsyV0JUgqPiI4iRs,1308
+busline/event/registry.py,sha256=2Yr-UE7rOuJGEawsybfKiK1HZUNxyDovlaXJh0tdct8,1709
+busline/event/test.py,sha256=SkPH0IB3x5WbJCv6dr_wP_dP8_-mQRz9MRWnipHzBDY,1361
+busline/local/__init__.py,sha256=th_6FPU7d8l4CQ_Rp21FM7NCLMFBWkt0Cyy6mCMJeUY,125
+busline/local/local_pubsub_client.py,sha256=F8IK83PgmRUV1pBqCv6BhF0YQn_B9nn18DmSVTFdwnk,1698
+busline/local/test.py,sha256=HxJBNWBqY-0L7salT_XzILF2i6WMCitnGO8LwQx6D8o,4438
+busline/local/eventbus/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/local/eventbus/async_local_eventbus.py,sha256=aettYF1W7G3agKVneGMU6kBr_-Gy2M10Lx40vQ2k66M,649
+busline/local/eventbus/eventbus.py,sha256=BH2zzoEeeqveqcgfrNXSsuE5kBGSL2LJcjOwuEtPEmI,2437
+busline/local/eventbus/local_eventbus.py,sha256=2wK2NMlWXm_9CTYR39y7Z40C8yOQ8RdViAQOnYS5g7M,611
+busline/local/publisher/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/local/publisher/local_publisher.py,sha256=FngthjSMZyswYK2Ka1LHrTqFkZ6yvGUjn0COGEzI0hI,1076
+busline/local/subscriber/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+busline/local/subscriber/local_subscriber.py,sha256=tWQ5YCRH78wiFlwO6I_dSAvCyhkQLox0GhoeVPKWxro,1237
+busline-0.5.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+busline-0.5.0.dist-info/METADATA,sha256=_8Cwu2T1kNnYJK_nV9fVMPScbxnzHB8hPNboQKawSUE,5904
+busline-0.5.0.dist-info/WHEEL,sha256=DnLRTWE75wApRYVsjgc6wsVswC54sMSJhAEd4xhDpBk,91
+busline-0.5.0.dist-info/top_level.txt,sha256=bZY0fK2wgNEI5igR7DBF3CyXHGkzujGvmoqdSzG6Zp0,8
+busline-0.5.0.dist-info/RECORD,,

{busline-0.3.1.dist-info → busline-0.5.0.dist-info}/WHEEL

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

busline/event/event_content.py

@@ -1,18 +0,0 @@
-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

busline/event/event_metadata.py

@@ -1,26 +0,0 @@
-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

busline/eventbus/async_local_eventbus.py

@@ -1,32 +0,0 @@
-import logging
-import asyncio
-
-from busline.event.event import Event
-from busline.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)
-
-            

busline/eventbus/eventbus.py

@@ -1,112 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Dict, List
-from busline.eventbus.exceptions import TopicNotFound
-from busline.eventbus_client.subscriber.subscriber import Subscriber
-from busline.eventbus.topic import Topic
-from busline.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()
-

busline/eventbus/exceptions.py

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

busline/eventbus/queued_local_eventbus.py

@@ -1,50 +0,0 @@
-import asyncio
-import logging
-from queue import Queue
-from concurrent.futures import ThreadPoolExecutor
-from busline.event.event import Event
-from busline.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))

busline/eventbus/topic.py

@@ -1,35 +0,0 @@
-
-
-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

busline/eventbus_client/eventbus_client.py

@@ -1,99 +0,0 @@
-from uuid import uuid4
-from busline.event.event import Event
-from busline.eventbus_client.eventbus_connector import EventBusConnector
-from busline.eventbus_client.publisher.publisher import Publisher
-from busline.eventbus_client.subscriber.event_listener import EventListener
-from busline.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)
-
-

busline/eventbus_client/exceptions.py

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

busline/eventbus_client/local_eventbus_client.py

@@ -1,25 +0,0 @@
-from typing import Callable
-from uuid import uuid4
-
-from busline.event.event import Event
-from busline.eventbus.async_local_eventbus import AsyncLocalEventBus
-from busline.eventbus_client.eventbus_client import EventBusClient
-from busline.eventbus_client.publisher.local_eventbus_publisher import LocalEventBusPublisher
-from busline.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
-        )
-
-
-