delegate-events 0.0.0__py3-none-any.whl

delegate/events/__init__.py

@@ -0,0 +1,13 @@
+from delegate.events.core.channel_closed_error import ChannelClosedError
+from delegate.events.core.channel import Channel
+from delegate.events.core.event import Event
+from delegate.events.core.handler_already_subscribed_error import HandlerAlreadySubscribedError
+from delegate.events.core.handler_not_subscribed_error import HandlerNotSubscribedError
+
+__all__ = (
+    'Channel',
+    'Event',
+    'ChannelClosedError',
+    'HandlerAlreadySubscribedError',
+    'HandlerNotSubscribedError',
+)

delegate/events/core/channel.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+from typing import Generic, TypeVar, MutableSequence, Callable, cast, overload
+from datetime import datetime, timedelta
+from threading import RLock
+from weakref import ref
+
+from delegate.events.core.channel_closed_error import ChannelClosedError
+from delegate.events.core.event import Event
+from delegate.events.core.queued_event import QueuedEvent
+from delegate.events.core.handler_already_subscribed_error import HandlerAlreadySubscribedError
+from delegate.events.core.handler_not_subscribed_error import HandlerNotSubscribedError
+
+T = TypeVar("T", bound=Event, contravariant=True)
+class Channel(Generic[T]):
+    __slots__ = [ "__publisher", "__subscribers", "__queue", "__queue_lock", "__weakref__", "__closed" ]
+
+    @overload
+    def __init__(self) -> None:
+        """
+        Creates a channel without a publisher. This is meant for testing purposes.
+        """
+        ...
+    @overload
+    def __init__(self, delegator: object) -> None:
+        """
+        Creates a delegate channel for specific publisher (delegator).
+        """
+        ...
+    def __init__(self, delegator: object | None = None):
+        self.__publisher = ref(delegator) if delegator is not None else None
+        self.__subscribers: MutableSequence[Callable[[object, T], None]] = []
+        self.__queue: MutableSequence[QueuedEvent] = []
+        self.__queue_lock = RLock()
+        self.__closed = False
+
+    def subscribe(self, handler: Callable[[object, T], None]) -> None:
+        """
+        Subscribes to the event channel.
+
+        Args:
+            handler (Callable[[object, T], None]): The event handler
+        """
+        if self.__closed:
+            raise ChannelClosedError
+
+        if handler in self.__subscribers:
+            raise HandlerAlreadySubscribedError
+
+        self.__subscribers.append(handler)
+
+        with self.__queue_lock:
+            for event in self.__queue:
+                if not event.expired:
+                    self.fire(cast(T, event.event))
+            self.__queue.clear()
+
+
+    def unsubscribe(self, handler: Callable[[object, T], None]) -> None:
+        """
+        Unsubscribes handler from event channel.
+
+        Args:
+            handler (Callable[[object, T], None]): The event handler
+        """
+        if self.__closed:
+            raise ChannelClosedError
+
+        if handler not in self.__subscribers:
+            raise HandlerNotSubscribedError
+
+        self.__subscribers.remove(handler)
+
+    def fire(self, event: T, *, ttl: float | None = 0) -> bool:
+        """
+        Fires the event, invoking all subscribed handlers
+
+        Args:
+            event (Event): The event
+            ttl (float, optional): The time (seconds) the event may live in the queue while awaiting subcriptions
+        Returns:
+            bool: Returns True when event was successfully sent to one or more subscribers.
+        """
+        if self.__closed:
+            raise ChannelClosedError
+
+        if not self.__subscribers:
+            if ttl:
+                with self.__queue_lock:
+                    self.__queue.append(QueuedEvent(event, datetime.now() + timedelta(seconds = ttl)))
+
+            return False
+
+        for subscriber in self.__subscribers:
+            subscriber(self.__publisher() if self.__publisher else None, event)
+
+        return True
+
+    def close(self) -> None:
+        """
+        Closes the channel.
+
+        Raises:
+            ChannelClosedError: _description_
+        """
+        if self.__closed:
+            raise ChannelClosedError
+
+        self.__closed = True
+        self.__subscribers.clear()
+        self.__queue.clear()
+
+    def __iadd__(self, handler: Callable[[object, T], None]) -> Channel[T]:
+        self.subscribe(handler)
+        return self
+
+    def __isub__(self, handler: Callable[[object, T], None]) -> Channel[T]:
+        self.unsubscribe(handler)
+        return self

delegate/events/core/channel_closed_error.py

@@ -0,0 +1,5 @@
+class ChannelClosedError(Exception):
+    """
+    The ChannelClosedError exception is raised when accessing functions etc. on a closed channel.
+    """
+    pass

delegate/events/core/event.py

@@ -0,0 +1,7 @@
+
+class Event:
+    __slots__ = [ ]
+
+
+
+

delegate/events/core/handler_already_subscribed_error.py

@@ -0,0 +1,6 @@
+
+class HandlerAlreadySubscribedError(Exception):
+    """
+    The HandlerAlreadySubscribedError exception is raised when an event handler is already subscribed to the channel.
+    """
+    pass

delegate/events/core/handler_not_subscribed_error.py

@@ -0,0 +1,6 @@
+
+class HandlerNotSubscribedError(Exception):
+    """
+    The HandlerNotSubscribedError exception is raised when an event handler is not subscribed to the channel.
+    """
+    pass

delegate/events/core/queued_event.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+
+from delegate.events.core.event import Event
+
+class QueuedEvent:
+    __slots__ = [ "__event", "__expires" ]
+
+    def __init__(self, event: Event, expires: datetime) -> None:
+        self.__event = event
+        self.__expires = expires
+
+    @property
+    def event(self) -> Event:
+        return self.__event
+
+    @property
+    def expired(self) -> bool:
+        return self.__expires < datetime.now()

delegate_events-0.0.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: delegate-events
+Version: 0.0.0
+Summary: Python implementation of the Event Pattern
+Author-email: Anders Madsen <anders.madsen@alphavue.com>
+License: MIT
+Project-URL: repository, https://github.com/apmadsen/delegate-events
+Keywords: windows,linux,delegates,events
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 6 - Mature
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: delegate-pattern==0.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-cov>=6.1; extra == "test"
+Dynamic: license-file
+
+[![Test](https://github.com/apmadsen/delegate-events/actions/workflows/python-test.yml/badge.svg)](https://github.com/apmadsen/delegate-events/actions/workflows/python-test.yml)
+[![Coverage](https://github.com/apmadsen/delegate-events/actions/workflows/python-test-coverage.yml/badge.svg)](https://github.com/apmadsen/delegate-events/actions/workflows/python-test-coverage.yml)
+[![Stable Version](https://img.shields.io/pypi/v/delegate-events?label=stable&sort=semver&color=blue)](https://github.com/apmadsen/delegate-events/releases)
+![Pre-release Version](https://img.shields.io/github/v/release/apmadsen/delegate-events?label=pre-release&include_prereleases&sort=semver&color=blue)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/delegate-events)
+[![PyPI Downloads](https://static.pepy.tech/badge/delegate-events/week)](https://pepy.tech/projects/delegate-events)
+
+# delegate-events: Python implementation of the Event Pattern.
+
+delegate-events provides a basic implementation of the well-known Event or Pub/Sub Pattern, and is built on top of the `delegate-pattern` package which handles the delegation part.
+
+## Example
+
+```python
+from delegate.pattern import delegate
+from delegate.events import Channel, Event
+
+class OnSomethingEvent(Event):
+    def __init__(self, what: str, why: str):
+        self.what = what
+        self.why = why
+
+    def __str__(self):
+        return f"{self.what} happened because of {self.why}"
+
+class Class1:
+    on_something = delegate(Channel[OnSomethingEvent])
+
+inst = Class1()
+msg_queue: list[Event] = []
+
+def fn(publisher, event: OnSomethingEvent):
+    msg_queue.append(event)
+
+inst.on_something.subscribe(fn)
+inst.on_something.fire(OnSomethingEvent("Something", "some other thing"))
+
+str(msg_queue[0]) # => "Something happened because of some other thing"
+```
+
+# API
+
+## Event class
+The `Event` class is the base class of all events. Events are the classes holding the event information, when an event is fired, thus, when subclassed, should contain properties/fields of the event information.
+
+#### Example
+```python
+from delegate.events import Event
+
+class OnSomething(Event):
+    def __init__(self, what: str, why: str):
+        self.what = what
+        self.why = why
+
+    def __str__(self):
+        return f"{self.what} happened because of {self.why}"
+
+```
+
+## Channel class
+The `Channel` class is the event channel returned by the delegate, and its jobs are handling subscriptions and firing of events.
+
+### Channel.subscribe(handler: _Callable[[object, T\<Event>], None]_)
+
+The `subscribe` function subscribes a handler function to the channel. The function takes 1 argument:
+- handler: `Callable[[object, Event], None]`
+
+#### Example
+```python
+from delegate.events import Channel
+
+channel = Channel[OnSomethingEvent]()
+
+def handler(sender: object, args: OnSomethingEvent) -> None:
+    pass
+
+channel.subscribe(handler)
+```
+
+
+### Channel.unsubscribe(handler: _Callable[[object, T\<Event>], None]_)
+The `unsubscribe` function unsubscribes a handler function from the channel. The function takes 1 argument:
+- handler: `Callable[[object, Event], None]`
+
+```python
+from delegate.events import Channel
+
+channel = Channel[OnSomethingEvent]()
+
+def handler(sender: object, args: OnSomethingEvent) -> None:
+    pass
+
+channel.subscribe(handler)
+channel.unsubscribe(handler)
+```
+
+### Channel.fire(event: _T\<Event>_, *, ttl: _float | None = 0_) -> _bool_ function
+The `fire` function fires the event, invoking all subscribed handlers. The function returns True if event was successfully sent and takes 1 argument:
+- event: `Event`
+
+and 1 optional keyword argument:
+- ttl: `float | None` the time-to-live (seconds) of the event.
+
+```python
+from delegate.events import Channel
+
+channel = Channel[OnSomethingEvent]()
+
+msg_queue: list[Event] = []
+
+def handler(sender: object, event: OnSomethingEvent) -> None:
+    msg_queue.append(event)
+
+channel.fire(OnSomethingEvent("Something", "some other thing")) # => False
+channel.fire(OnSomethingEvent("Something", "some other thing"), ttl=10) # => False - event stays in queue and will be sent if subcrribed to within 10 seconds though
+
+channel.subscribe(handler)
+
+channel.fire(OnSomethingEvent("Something", "some other thing")) # => True
+
+len(msg_queue) # => 2
+```

delegate_events-0.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+delegate/events/__init__.py,sha256=p9T6xaF__aQ5iZEd-E7AGqRjd9mb-JRlNxSFk48EnY4,489
+delegate/events/core/channel.py,sha256=zXfs-dw8U91TQUeyimutRj5Jnb21WUEXVkZw--yudsE,3886
+delegate/events/core/channel_closed_error.py,sha256=wKs0nZvCY6iKba93S4cEEjAPggmmA6HQk6LhlbEVvlM,159
+delegate/events/core/event.py,sha256=5v53F15GvHN7bjz0dFoYS8s6gcO2FQJ7cylpA-pNilc,38
+delegate/events/core/handler_already_subscribed_error.py,sha256=M-abPb0GfOOdRdN2Wfrfn8dim3JZp-oaEeeUfTH4Uqc,191
+delegate/events/core/handler_not_subscribed_error.py,sha256=_qTOxqklHYnVpjQ1txw2n4hvef2_6i7h1O6E5z7mEj4,179
+delegate/events/core/queued_event.py,sha256=sA41t0ODtLu8Sdn0Ty_dCi72luOcqPo6jydB4O_gH64,432
+delegate_events-0.0.0.dist-info/licenses/LICENSE,sha256=arWCq6_BrCqO8UFdTrMBI356o9Qyqsp_RPvpthW5Yfk,1066
+delegate_events-0.0.0.dist-info/METADATA,sha256=V77cfjTaBClQ-HIDZTdRUv9qKRyY969N9Hsz3Fir_kU,5600
+delegate_events-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+delegate_events-0.0.0.dist-info/top_level.txt,sha256=l_igR_YcbGXNRiMQ2yVnuPO7HyGXHvVWrifyAAg3uX8,9
+delegate_events-0.0.0.dist-info/RECORD,,

delegate_events-0.0.0.dist-info/WHEEL

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

delegate_events-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Dagrofa BI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

delegate_events-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+delegate