PyEventEngine 0.3.2__py3-none-any.whl

PyEventEngine-0.3.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Bolun Han
+
+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.

PyEventEngine-0.3.2.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.1
+Name: PyEventEngine
+Version: 0.3.2
+Summary: Basic event engine
+Home-page: https://github.com/BolunHan/PyEventEngine.git
+Author: Bolun.Han
+Author-email: Bolun.Han@outlook.com
+License: MIT
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# PyEventEngine
+
+python native event engine
+
+# Install
+
+```shell
+pip install git+https://github.com/BolunHan/PyEventEngine.git
+```
+
+or
+
+```shell
+pip install PyEventEngine
+```
+
+# Use
+
+## basic usage
+
+```python
+# init event engine
+import time
+from event_engine import EventEngine, Topic
+
+EVENT_ENGINE = EventEngine()
+EVENT_ENGINE.start()
+
+
+# register handler
+def test_handler(msg, **kwargs):
+    print(msg)
+
+
+EVENT_ENGINE.register_handler(topic=Topic('SimpleTopic'), handler=test_handler)
+
+# publish message
+EVENT_ENGINE.put(topic=Topic('SimpleTopic'), msg='topic called')
+time.sleep(1)
+EVENT_ENGINE.stop()
+```
+
+## regular topic
+
+```python
+# init event engine
+import time
+from event_engine import EventEngine, Topic, RegularTopic
+
+EVENT_ENGINE = EventEngine()
+EVENT_ENGINE.start()
+
+
+# register handler
+def test_handler(msg, **kwargs):
+    print(msg)
+
+
+EVENT_ENGINE.register_handler(topic=RegularTopic('RegularTopic.*'), handler=test_handler)
+
+# publish message
+EVENT_ENGINE.put(topic=Topic('RegularTopic.ChildTopic0'), msg='topic called')
+time.sleep(1)
+EVENT_ENGINE.stop()
+```
+
+## timer topic
+
+```python
+# init event engine
+import time
+from event_engine import EventEngine, Topic, RegularTopic
+
+EVENT_ENGINE = EventEngine()
+EVENT_ENGINE.start()
+
+
+# register handler
+def test_handler(**kwargs):
+    print(kwargs)
+
+
+topic = EVENT_ENGINE.get_timer(interval=1)
+EVENT_ENGINE.register_handler(topic=topic, handler=test_handler)
+
+# publish message
+time.sleep(5)
+EVENT_ENGINE.stop()
+```
+
+See more advanced usage at .Demo

PyEventEngine-0.3.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+event_engine/__init__.py,sha256=0z5AJNA4EwsTqQFxSKYa8YefS1acGuKxlVLQPQk4Xzw,45
+event_engine/native/__init__.py,sha256=_HhWK3NYaS8e4JvGYVyC6MX5EKfNCRNZ3d0ItFj0Pis,3227
+event_engine/native/_event.py,sha256=w_k2znuX3newAnjUbFkYxh8_DFEr3WMkAyyzSc7QBhY,14346
+event_engine/native/_topic.py,sha256=fBcnKEsFoj0vmKZXq3MkEJJ_JyepvZLbDvnAzDjMNjI,4726
+event_engine/native/_topic_c.py,sha256=8CXsuHeRwbcxKqyfsIpp-QDKnk0vjOG4MT9nYoaUY2Y,2907
+PyEventEngine-0.3.2.dist-info/LICENSE,sha256=bTmmkRlafTj1JKDkDoGfnLHD8OiuIdXaXDa35W3Ii4g,1066
+PyEventEngine-0.3.2.dist-info/METADATA,sha256=EGiCnbUBokVgw4D-z5zh2VxLSyv2dGi8XvnB8eSuCzA,2107
+PyEventEngine-0.3.2.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+PyEventEngine-0.3.2.dist-info/top_level.txt,sha256=rIh2LcDfofRLIIqMSlulp5yAXTf1DNOmlofiyIHuylQ,13
+PyEventEngine-0.3.2.dist-info/RECORD,,

PyEventEngine-0.3.2.dist-info/WHEEL

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

PyEventEngine-0.3.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+event_engine

event_engine/__init__.py

@@ -0,0 +1,3 @@
+__version__ = '0.3.2'
+
+from .native import *

event_engine/native/__init__.py

@@ -0,0 +1,99 @@
+import logging
+import sys
+import time
+
+__all__ = ['set_logger', 'LOG_LEVEL_EVENT', 'Topic', 'RegularTopic', 'PatternTopic', 'EventHook', 'EventEngine', 'LOGGER', 'use_cpp_override']
+LOGGER: logging.Logger | None = None
+DEBUG = False
+LOG_LEVEL = logging.INFO
+LOG_LEVEL_EVENT = LOG_LEVEL - 5
+
+
+class ColoredFormatter(logging.Formatter):
+    """Logging Formatter to add colors and count warning / errors"""
+
+    def __init__(self, fmt=None, datefmt=None, style='{', validate=True):
+        self.format_str = '[{asctime} {name} - {threadName} - {module}:{lineno} - {levelname}] {message}' if fmt is None else fmt
+        self.date_fmt = '%Y-%m-%d %H:%M:%S' if datefmt is None else datefmt
+        self.style = style
+
+        super().__init__(fmt=fmt, datefmt=datefmt, style=style, validate=validate)
+
+    def _get_format(self, level: int, select=False):
+        bold_red = f"\33[31;1;3;4{';7' if select else ''}m"
+        red = f"\33[31;1{';7' if select else ''}m"
+        green = f"\33[32;1{';7' if select else ''}m"
+        yellow = f"\33[33;1{';7' if select else ''}m"
+        blue = f"\33[34;1{';7' if select else ''}m"
+        reset = "\33[0m"
+
+        if level <= logging.NOTSET:
+            fmt = self.format_str
+        elif level <= logging.DEBUG:
+            fmt = blue + self.format_str + reset
+        elif level <= logging.INFO:
+            fmt = green + self.format_str + reset
+        elif level <= logging.WARNING:
+            fmt = yellow + self.format_str + reset
+        elif level <= logging.ERROR:
+            fmt = red + self.format_str + reset
+        else:
+            fmt = bold_red + self.format_str + reset
+
+        return fmt
+
+    def format(self, record):
+        log_fmt = self._get_format(level=record.levelno)
+        formatter = logging.Formatter(log_fmt, datefmt=self.date_fmt, style=self.style)
+        return formatter.format(record)
+
+
+def get_logger(**kwargs) -> logging.Logger:
+    level = kwargs.get('level', LOG_LEVEL)
+    stream_io = kwargs.get('stream_io', sys.stdout)
+    formatter = kwargs.get('formatter', ColoredFormatter())
+    global LOGGER
+
+    if LOGGER is not None:
+        return LOGGER
+
+    LOGGER = logging.getLogger('EventEngine')
+    LOGGER.setLevel(level)
+    logging.Formatter.converter = time.gmtime
+
+    if stream_io:
+        have_handler = False
+        for handler in LOGGER.handlers:
+            # noinspection PyUnresolvedReferences
+            if type(handler) == logging.StreamHandler and handler.stream == stream_io:
+                have_handler = True
+                break
+
+        if not have_handler:
+            logger_ch = logging.StreamHandler(stream=stream_io)
+            logger_ch.setLevel(level=level)
+            logger_ch.setFormatter(fmt=formatter)
+            LOGGER.addHandler(logger_ch)
+
+    return LOGGER
+
+
+def set_logger(logger: logging.Logger):
+    global LOGGER
+    LOGGER = logger
+
+    _event.LOGGER = LOGGER.getChild('Event')
+
+
+def use_cpp_override():
+    try:
+        from ._topic_c import Topic, RegularTopic, PatternTopic
+        from . import _topic as _Topic_native
+    except Exception as _:
+        LOGGER.warning(_)
+
+
+_ = get_logger()
+
+from ._topic import Topic, RegularTopic, PatternTopic
+from ._event import EventHook, EventEngine

event_engine/native/_event.py

@@ -0,0 +1,405 @@
+import datetime
+import enum
+import inspect
+import time
+import traceback
+from collections import deque
+from logging import Logger
+from threading import Thread, Semaphore
+from typing import Iterable, TypedDict, NotRequired, Callable
+
+from . import LOGGER, LOG_LEVEL_EVENT, Topic, DEBUG
+
+LOGGER = LOGGER.getChild('Event')
+
+
+class EventDict(TypedDict):
+    topic: str
+    args: NotRequired[tuple]
+    kwargs: NotRequired[dict]
+
+
+class EventHookBase(object):
+    """
+    Event object with
+    a string topic for event engine to distribute event,
+    and a list of handler to process data
+    """
+
+    def __init__(self, topic: Topic, logger: Logger = None, max_size: int = None):
+        self.topic = topic
+        self.logger = LOGGER.getChild(f'EventHook.{topic}') if logger is None else logger
+        self.handlers: deque[Callable] = deque(maxlen=max_size)
+
+    def __call__(self, *args, **kwargs):
+        self.trigger(topic=self.topic, args=args, kwargs=kwargs)
+
+    def __iadd__(self, handler: Callable):
+        self.add_handler(handler)
+        return self
+
+    def __isub__(self, handler: Callable):
+        self.remove_handler(handler)
+        return self
+
+    def trigger(self, topic: Topic, args: tuple = None, kwargs: dict = None):
+        if args is None:
+            args = ()
+
+        if kwargs is None:
+            kwargs = {}
+
+        for handler in self.handlers:
+            try:
+                try:
+                    handler(topic=topic, *args, **kwargs)
+                except TypeError as e:
+                    if e.__str__().endswith("unexpected keyword argument 'topic'"):
+                        handler(*args, **kwargs)
+                    else:
+                        raise e
+            except Exception as _:
+                self.logger.error(traceback.format_exc())
+
+    def add_handler(self, handler: Callable):
+        if handler in self.handlers:
+            LOGGER.warning(f'Handler {handler} already in {self}. This action might cause it to trigger twice.')
+        self.handlers.append(handler)
+
+    def remove_handler(self, handler: Callable):
+        try:
+            self.handlers.remove(handler)
+        except ValueError as e:
+            self.logger.error(f'Handler {handler} not found in {self}.')
+
+
+class EventHook(EventHookBase):
+    def __init__(self, topic: Topic, logger: Logger = None, max_size: int = None, handler: list[Callable] | Callable | None = None):
+        super().__init__(topic=topic, logger=logger, max_size=max_size)
+        self.with_topic: deque[bool] = deque()
+
+        if handler is None:
+            pass
+        elif callable(handler):
+            self.add_handler(handler)
+        elif isinstance(handler, Iterable):
+            for _handler in handler:
+                self.add_handler(handler=_handler)
+        else:
+            raise ValueError(f'Invalid handler {handler}, expect a Callable or a list of Callable.')
+
+    def trigger(self, topic: Topic, args: tuple = None, kwargs: dict = None):
+        ts = time.time()
+        if args is None:
+            args = ()
+
+        if kwargs is None:
+            kwargs = {}
+
+        for handler, with_topic in zip(self.handlers, self.with_topic):
+            try:
+                if with_topic:
+                    handler(topic=topic, *args, **kwargs)
+                else:
+                    handler(*args, **kwargs)
+            except Exception as _:
+                self.logger.error(traceback.format_exc())
+
+        if DEBUG:
+            self.logger.log(LOG_LEVEL_EVENT, f'EventHook {self.topic} tasks triggered {len(self.handlers):,} handlers, complete in {(time.time() - ts) * 1000:.3f}ms.')
+
+    def add_handler(self, handler: Callable, with_topic: bool = None):
+        sig = inspect.signature(handler)
+
+        if with_topic is None:
+            for param in sig.parameters.values():
+                if param.name == 'topic' or param.kind == param.VAR_KEYWORD:
+                    with_topic = True
+                    break
+
+        super().add_handler(handler=handler)
+        self.with_topic.append(with_topic)
+
+    def remove_handler(self, handler: Callable):
+        try:
+            idx = self.handlers.index(handler)
+            self.handlers.__delitem__(idx)
+            self.with_topic.__delitem__(idx)
+        except ValueError as e:
+            pass
+
+
+class EventEngineBase(object):
+    EventHook = EventHook
+
+    def __init__(self, logger: Logger = None, buffer_size: int = 0):
+        self.logger = LOGGER.getChild(f'EventEngine') if logger is None else logger
+        self._buffer_size = buffer_size
+        self._put_lock = Semaphore(self._buffer_size)
+        self._get_lock = Semaphore(0)
+        self._deque: deque[EventDict] = deque(maxlen=buffer_size if buffer_size else None)
+        self._active: bool = False
+        self._engine: Thread = None
+        self._event_hooks: dict[Topic, EventHook] = {}
+
+        if buffer_size and buffer_size < 8:
+            self.logger.info(f'buffer_size={buffer_size} too small. This might cause a dead lock.')
+
+    def _run(self) -> None:
+        """
+        Get event from queue and then process it.
+        """
+        while self._active:
+            self._get_lock.acquire(blocking=True, timeout=None)
+
+            try:
+                event_dict = self._deque.popleft()
+            except IndexError as e:
+                if not self._active:
+                    return
+                raise e
+
+            topic = event_dict['topic']
+            args = event_dict.get('args', ())
+            kwargs = event_dict.get('kwargs', {})
+            self._process(topic=topic, *args, **kwargs)
+
+            if self._buffer_size:
+                self._put_lock.release()
+
+    def _process(self, topic: str, *args, **kwargs) -> None:
+        """
+        distribute data to registered event hook in the order of registration
+        """
+        for event_topic, event_hook in self._event_hooks.items():
+            if matched_topic := event_topic.match(topic=topic):
+                event_hook.trigger(topic=matched_topic, args=args, kwargs=kwargs)
+
+    def start(self) -> None:
+        """
+        Start event engine to process events and generate timer events.
+        """
+        if self._active:
+            self.logger.warning(f'{self} already started!')
+            return
+
+        self._active = True
+        self._engine = Thread(target=self._run, name='EventEngine')
+        self._engine.start()
+
+    def stop(self) -> None:
+        """
+        Stop event engine.
+        """
+        if not self._active:
+            self.logger.warning('EventEngine already stopped!')
+            return
+
+        self._active = False
+        self._get_lock.release()
+        self._engine.join()
+
+    def clear(self) -> None:
+        if self._active:
+            self.logger.error('EventEngine must be stopped before cleared!')
+            return
+
+        self._event_hooks.clear()
+        self._deque.clear()
+
+        if self._buffer_size:
+            self._put_lock._value = self._buffer_size
+            self._get_lock._value = 0
+
+    def put(self, topic: str | Topic, block: bool = True, timeout: float = None, *args, **kwargs):
+        """
+        fast way to put an event, kwargs MUST NOT contain "topic", "block" and "timeout" keywords
+        :param topic: the topic to put into engine
+        :param block: block if necessary until a free slot is available
+        :param timeout: If 'timeout' is a non-negative number, it blocks at most 'timeout' seconds and raises the Full exception
+        :param args: args for handlers
+        :param kwargs: kwargs for handlers
+        :return: nothing
+        """
+        self.publish(topic=topic, block=block, timeout=timeout, args=args, kwargs=kwargs)
+
+    def publish(self, topic: str | Topic, block: bool = True, timeout: float = None, args=None, kwargs=None):
+        """
+        safe way to publish an event
+        :param topic: the topic to put into engine
+        :param block: block if necessary until a free slot is available
+        :param timeout: If 'timeout' is a non-negative number, it blocks at most 'timeout' seconds and raises the Full exception
+        :param args: a list / tuple, args for handlers
+        :param kwargs: a dict, kwargs for handlers
+        :return: nothing
+        """
+        if isinstance(topic, Topic):
+            topic = topic.value
+        elif not isinstance(topic, str):
+            raise ValueError(f'Invalid topic {topic}')
+
+        if self._buffer_size:
+            self._put_lock.acquire()
+
+        event_dict = {'topic': topic}
+
+        if args is not None:
+            event_dict['args'] = args
+
+        if kwargs is not None:
+            event_dict['kwargs'] = kwargs
+
+        self._deque.append(event_dict)
+
+        self._get_lock.release()
+
+    def register_hook(self, hook: EventHook) -> None:
+        """
+        register a hook event
+        """
+        if hook.topic in self._event_hooks:
+            for handler in hook.handlers:
+                self._event_hooks[hook.topic].add_handler(handler)
+        else:
+            self._event_hooks[hook.topic] = hook
+
+    def unregister_hook(self, topic: Topic) -> None:
+        """
+        Unregister an existing hook
+        """
+        if topic in self._event_hooks:
+            self._event_hooks.pop(topic)
+
+    def register_handler(self, topic: Topic, handler: Iterable[Callable] | Callable) -> None:
+        """
+        Register one or more handler for a specific topic
+        """
+
+        if not isinstance(topic, Topic):
+            raise TypeError(f'Invalid topic {topic}')
+
+        if topic not in self._event_hooks:
+            self._event_hooks[topic] = self.EventHook(topic=topic, handler=handler, logger=self.logger.getChild(topic.value))
+        else:
+            self._event_hooks[topic].add_handler(handler)
+
+    def unregister_handler(self, topic: Topic, handler: Callable) -> None:
+        """
+        Unregister an existing handler function.
+        """
+        if topic in self._event_hooks:
+            self._event_hooks[topic].remove_handler(handler=handler)
+
+    @property
+    def buffer_size(self):
+        return self._buffer_size
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+
+class EventEngine(EventEngineBase):
+    EventHook = EventHook
+
+    def __init__(self, buffer_size=0):
+        super().__init__(buffer_size=buffer_size)
+        self.timer: dict[float | str, Thread] = {}
+
+    def register_handler(self, topic: Topic | str | enum.Enum, handler: Callable):
+        topic = Topic.cast(topic)
+        super().register_handler(topic=topic, handler=handler)
+
+    def publish(self, topic, block: bool = True, timeout: float = None, args=None, kwargs=None):
+        topic = Topic.cast(topic)
+        super().publish(topic=topic, block=block, timeout=timeout, args=args, kwargs=kwargs)
+
+    def unregister_hook(self, topic) -> None:
+        topic = Topic.cast(topic)
+        super().unregister_hook(topic=topic)
+
+    def unregister_handler(self, topic, handler) -> None:
+        topic = Topic.cast(topic)
+
+        try:
+            super().unregister_handler(topic=topic, handler=handler)
+        except ValueError as _:
+            raise ValueError(f'unregister topic {topic} failed! handler {handler} not found!')
+
+    def get_timer(self, interval: datetime.timedelta | float | int, activate_time: datetime.datetime = None) -> Topic:
+        """
+        Start a timer, if not exist, and get topic of the timer event
+        :param interval: timer event interval in seconds
+        :param activate_time: UTC, timer event only start after active_time. This arg has no effect if timer already started.
+        :return: the topic of timer event hook
+        """
+        if isinstance(interval, datetime.timedelta):
+            interval = interval.total_seconds()
+
+        if interval == 1:
+            topic = Topic('EventEngine.Internal.Timer.Second')
+            timer = Thread(target=self._second_timer, kwargs={'topic': topic})
+        elif interval == 60:
+            topic = Topic('EventEngine.Internal.Timer.Minute')
+            timer = Thread(target=self._minute_timer, kwargs={'topic': topic})
+        else:
+            topic = Topic(f'EventEngine.Internal.Timer.{interval}')
+            timer = Thread(target=self._run_timer, kwargs={'interval': interval, 'topic': topic, 'activate_time': activate_time})
+
+        if interval not in self.timer:
+            self.timer[interval] = timer
+            timer.start()
+        else:
+            if activate_time is not None:
+                self.logger.debug(f'Timer thread with interval [{datetime.timedelta(seconds=interval)}] already initialized! Argument [activate_time] takes no effect!')
+
+        return topic
+
+    def _run_timer(self, interval: datetime.timedelta | float | int, topic: Topic, activate_time: datetime.datetime = None) -> None:
+        if isinstance(interval, datetime.timedelta):
+            interval = interval.total_seconds()
+
+        if activate_time is None:
+            scheduled_time = datetime.datetime.utcnow()
+        else:
+            scheduled_time = activate_time
+
+        while self._active:
+            sleep_time = (scheduled_time - datetime.datetime.utcnow()).total_seconds()
+
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+            self.put(topic=topic, interval=interval, trigger_time=scheduled_time)
+
+            while scheduled_time < datetime.datetime.utcnow():
+                scheduled_time += datetime.timedelta(seconds=interval)
+
+    def _minute_timer(self, topic: Topic):
+        while self._active:
+            t = time.time()
+            scheduled_time = t // 60 * 60
+            next_time = scheduled_time + 60
+            sleep_time = next_time - t
+            time.sleep(sleep_time)
+            self.put(topic=topic, interval=60., timestamp=scheduled_time)
+
+    def _second_timer(self, topic: Topic):
+        while self._active:
+            t = time.time()
+            scheduled_time = t // 1
+            next_time = scheduled_time + 1
+            sleep_time = next_time - t
+            time.sleep(sleep_time)
+            self.put(topic=topic, interval=1., timestamp=scheduled_time)
+
+    def stop(self) -> None:
+        super().stop()
+
+        for timer in self.timer.values():
+            timer.join()
+
+    def clear(self) -> None:
+        for t in self.timer.values():
+            t.join(timeout=0)
+
+        self.timer.clear()

event_engine/native/_topic.py

@@ -0,0 +1,156 @@
+import re
+from enum import Enum
+from string import Formatter
+from typing import Self, Type
+
+
+class Topic(dict):
+    """
+    topic for event hook. e.g. "TickData.002410.SZ.Realtime"
+    """
+
+    class Error(Exception):
+        def __init__(self, msg):
+            super().__init__(msg)
+
+    def __init__(self, topic: str, *args, **kwargs):
+        self._value = topic
+        super().__init__(*args, **kwargs)
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__}>({self._value}){super().__repr__()}'
+
+    def __str__(self):
+        return self.value
+
+    def __bool__(self):
+        return True
+
+    def __hash__(self):
+        return self.value.__hash__()
+
+    def match(self, topic: str) -> Self | None:
+        if self._value == topic:
+            # return self.__class__(topic=topic)
+            return self
+        else:
+            return None
+
+    @classmethod
+    def cast(cls, topic: Self | str | Enum, dtype: Type[Self] = None) -> Self:
+        if isinstance(topic, cls):
+            return topic
+        elif isinstance(topic, Enum):
+            t = topic.value
+            return cls.cast(t)
+        elif isinstance(topic, str):
+            if dtype is None:
+                if re.search(r'{(.+?)}', topic):
+                    t = PatternTopic(pattern=topic)
+                elif '*' in topic or '+' in topic or '|' in topic:
+                    re.compile(pattern=topic)
+                    t = RegularTopic(pattern=topic)
+                else:
+                    t = Topic(topic=topic)
+            else:
+                t = dtype(topic)
+        else:
+            raise NotImplementedError(f'Can not cast {topic} into {cls}.')
+
+        return t
+
+    @property
+    def value(self) -> str:
+        return self._value
+
+
+class RegularTopic(Topic):
+    """
+    topic in regular expression. e.g. "TickData.(.+).((SZ)|(SH)).((Realtime)|(History))"
+    """
+
+    def __init__(self, pattern: str):
+        super().__init__(topic=pattern)
+
+    def match(self, topic: str) -> Topic | None:
+        if re.match(self._value, topic):
+            match = Topic(topic=topic)
+            match['pattern'] = self._value
+            return match
+        else:
+            return None
+
+
+class PatternTopic(Topic):
+    """
+    topic for event hook. e.g. "TickData.{symbol}.{market}.{flag}"
+    """
+
+    class NotMatchError(Topic.Error):
+        pass
+
+    def __init__(self, pattern: str):
+        super().__init__(topic=pattern)
+
+    def __call__(self, **kwargs):
+        return self.format_map(kwargs)
+
+    # @classmethod
+    # def extract_mapping(cls, target: str, pattern: str):
+    #     pattern = re.escape(pattern)
+    #     regex = re.sub(r'\\{(.+?)\\}', r'(?P<_\1>.+)', pattern)
+    #     match = re.match(regex, target)
+    #     if match:
+    #         values = list(match.groups())
+    #         keys = re.findall(r'\\{(.+?)\\}', pattern)
+    #         m = dict(zip(keys, values))
+    #         return m
+    #     else:
+    #         raise Topic.Error(f'pattern {pattern} not in string {target} found!')
+
+    @classmethod
+    def extract_mapping(cls, target: str, pattern: str) -> dict[str, str]:
+        dictionary = {}
+
+        result_parts = target.split('.')
+        pattern_parts = pattern.split('.')
+
+        # Check if the number of parts in result and pattern are the same
+        if len(result_parts) < len(pattern_parts):
+            raise cls.NotMatchError(f'Target {target} not match with pattern {pattern}.')
+
+        # Generate the mapping dictionary
+        for result_part, pattern_part in zip(result_parts, pattern_parts):
+            if pattern_part[0] == '{' and pattern_part[-1] == '}':
+                content: str = pattern_part[1:-1]
+                dictionary[content] = result_part
+            else:
+                if result_part != pattern_part:
+                    dictionary.clear()
+                    raise cls.NotMatchError(f'Target {target} not match with pattern {pattern}.')
+
+        return dictionary
+
+    def format_map(self, mapping: dict) -> Topic:
+        for key in self.keys():
+            if key not in mapping:
+                mapping[key] = f'{{{key}}}'
+
+        return Topic.cast(self._value.format_map(mapping))
+
+    def keys(self):
+        keys = [i[1] for i in Formatter().parse(self._value) if i[1] is not None]
+        return keys
+
+    def match(self, topic: str) -> Topic | None:
+        try:
+            keyword_dict = self.extract_mapping(target=topic, pattern=self._value)
+            match = Topic(topic=topic)
+            match.update(keyword_dict)
+            return match
+        except self.NotMatchError as _:
+            return None
+
+    @property
+    def value(self) -> str:
+        return self._value.format_map({_: '*' for _ in self.keys()})

event_engine/native/_topic_c.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import ctypes
+import pathlib
+import platform
+import re
+
+from ._topic import Topic, RegularTopic as RegularTopicBase, PatternTopic as PatternTopicBase
+
+__all__ = ['Topic', 'RegularTopic', 'PatternTopic']
+
+topic_lib = None
+
+if platform.system() == 'Windows':
+    package_name = 'topic_api.(.*).pyd'
+elif platform.system() == 'Darwin':
+    package_name = '^topic_api(.*).so$'
+else:
+    package_name = '^topic_api(.*).so$'
+
+ROOT_DIR = pathlib.Path(__file__).parent.parent
+ENCODING = 'utf-8'
+
+for _ in ROOT_DIR.iterdir():
+    if lib_path := re.search(package_name, _.name):
+        topic_lib = ctypes.CDLL(str(_))
+        break
+
+# Load the shared library
+if topic_lib is None:
+    raise ImportError(f'EventEngine.Topic c extension {package_name} not found in {ROOT_DIR}! Fallback to native lib!')
+
+# Function prototypes
+# topic_lib.delete_vector.restype = [ctypes.POINTER]
+topic_lib.get_vector_value.restype = ctypes.c_char_p
+topic_lib.is_regular_match.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+topic_lib.is_regular_match.restype = ctypes.c_int
+
+
+# Define the RegularTopic class in Python
+class RegularTopic(RegularTopicBase):
+    """
+    topic in regular expression. e.g. "TickData.(.+).((SZ)|(SH)).((Realtime)|(History))"
+    """
+
+    def match(self, topic: str):
+        match = topic_lib.is_regular_match(topic.encode(ENCODING), self._value.encode(ENCODING))
+
+        if match:
+            return Topic(topic=topic, pattern=self.value)
+        else:
+            return None
+
+
+# Define the PatternTopic class in Python
+class PatternTopic(PatternTopicBase):
+    """
+    topic for event hook. e.g. "TickData.{symbol}.{market}.{flag}"
+    """
+
+    def match(self, topic: str):
+        mapping = self.extract_mapping(target=topic, pattern=self._value, encoding=ENCODING)
+
+        if mapping:
+            return Topic(topic, pattern=self._value, **mapping)
+        else:
+            return None
+
+    @classmethod
+    def extract_mapping(cls, target: str, pattern: str, encoding: str = ENCODING) -> dict[str, str]:
+        # noinspection PyArgumentList
+        keys_ptr, values_ptr = ctypes.POINTER(ctypes.c_void_p)(), ctypes.POINTER(ctypes.c_void_p)()
+        mapping = {}
+
+        topic_lib.extract_mapping(
+            target.encode(encoding),
+            pattern.encode(encoding),
+            ctypes.byref(keys_ptr),
+            ctypes.byref(values_ptr)
+        )
+
+        for i in range(topic_lib.vector_size(ctypes.byref(keys_ptr))):
+            key = topic_lib.get_vector_value(ctypes.byref(keys_ptr), i)
+            value = topic_lib.get_vector_value(ctypes.byref(values_ptr), i)
+            # print(key, value)
+            mapping[key.decode(encoding)] = value.decode(encoding)
+
+        # topic_lib.delete_vector(ctypes.byref(keys_ptr))
+        # topic_lib.delete_vector(ctypes.byref(values_ptr))
+
+        del keys_ptr
+        del values_ptr
+
+        return mapping