zoo-framework 0.5.4b0__py3-none-any.whl

zoo_framework/__init__.py

@@ -0,0 +1,72 @@
+"""Zoo Framework - A simple and quick multi-threaded Python framework with zoo metaphor.
+
+🎪 动物园框架 - 基于动物园隐喻的 Python 多线程框架
+
+核心概念：
+- 🦁 Worker: 动物，执行任务的基本单元
+- 🏠 Cage: 笼子，提供线程安全和生命周期管理
+- 👨‍🌾 Master: 园长，管理整个动物园
+- 🍎 Event: 食物，Worker 间通信的载体
+- 🥘 FIFO: 饲养员队列，管理事件的有序处理
+
+示例：
+    >>> from zoo_framework.core import Master
+    >>> from zoo_framework.workers import BaseWorker
+    >>>
+    >>> class MyWorker(BaseWorker):
+    ...     def _execute(self):
+    ...         print("Hello from MyWorker!")
+    >>>
+    >>> master = Master()
+    >>> master.run()
+
+版本: 0.1.0
+作者: XiangMeng
+许可证: Apache-2.0
+"""
+
+__version__ = "0.1.1-beta"
+__author__ = "XiangMeng"
+__email__ = "mengxiang931015@live.com"
+__license__ = "Apache-2.0"
+
+from dotenv import find_dotenv, load_dotenv
+
+# Replace wildcard imports with explicit package submodule imports to reduce linter noise
+# and avoid importing many symbols at package import time.
+from . import (
+    conf,
+    core,
+    fifo,
+    params,
+    reactor,
+    statemachine,
+    utils,
+    workers,
+)
+
+__all__ = [
+    "__version__",
+    "conf",
+    "core",
+    "fifo",
+    "params",
+    "reactor",
+    "statemachine",
+    "utils",
+    "workers",
+]
+
+
+def load_env() -> None:
+    """显式加载工程根目录下的 .env 文件（不在包导入时自动运行）。
+
+    调用示例：
+        from zoo_framework import load_env
+        load_env()
+    """
+    load_dotenv(find_dotenv())
+
+
+# NOTE: 原先代码在模块导入时会立即运行 `load_dotenv(find_dotenv())`，
+# 为了降低导入时的副作用（并减少 linter 噪声），已改为显式函数调用。

zoo_framework/__main__.py

@@ -0,0 +1,99 @@
+import json
+import os
+import sys
+
+import click
+from jinja2 import Template
+
+from zoo_framework.templates import main_template, worker_mod_insert_template, worker_template
+
+DEFAULT_CONF = {
+    "_exports": [],
+    "log": {"path": "./logs", "level": "debug"},
+    "worker": {"runPolicy": "simple", "pool": {"size": 5, "enabled": False}},
+}
+
+
+def create_func(object_name):
+    if os.path.exists(object_name):
+        return
+
+    os.mkdir(object_name)
+    src_dir = object_name + "/src"
+    conf_dir = src_dir + "/conf"
+    params_dir = src_dir + "/params"
+    main_file = src_dir + "/main.py"
+    events_dir = src_dir + "/events"
+    workers_dir = src_dir + "/workers"
+    config_file = object_name + "/config.json"
+
+    threads_init_file = workers_dir + "/__init__.py"
+    config_init_file = conf_dir + "/__init__.py"
+    events_init_file = events_dir + "/__init__.py"
+    params_init_file = params_dir + "/__init__.py"
+
+    os.mkdir(src_dir)
+    os.mkdir(conf_dir)
+    os.mkdir(workers_dir)
+    os.mkdir(params_dir)
+    os.mkdir(events_dir)
+    # os.mkdir(events_dir)
+    with open(config_file, "w") as fp:
+        json.dump(DEFAULT_CONF, fp)
+
+    with open(main_file, "w") as fp:
+        fp.write(main_template)
+
+    with open(threads_init_file, "w") as fp:
+        fp.write("")
+
+    with open(config_init_file, "w") as fp:
+        fp.write("")
+
+    with open(events_init_file, "w") as fp:
+        fp.write("")
+
+    with open(params_init_file, "w") as fp:
+        fp.write("")
+
+    # create main.py
+
+
+def worker_func(worker_name):
+    # 创建文件夹
+    src_dir = "./workers"
+    if sys.argv[0].endswith("/src"):
+        src_dir = "./src/workers"
+    file_path = src_dir + "/" + worker_name + "_worker.py"
+    workers_init_file = src_dir + "/__init__.py"
+    template = Template(worker_mod_insert_template)
+    content = template.render(worker_name=worker_name)
+
+    if not os.path.exists(src_dir):
+        os.mkdir(src_dir)
+        with open(workers_init_file, "w") as fp:
+            fp.write(content)
+    elif os.path.exists(workers_init_file):
+        with open(workers_init_file, "a") as fp:
+            fp.write(content)
+
+    template = Template(worker_template)
+    content = template.render(worker_name=worker_name)  # 渲染
+    with open(file_path, "w") as fp:
+        fp.write(content)
+
+
+@click.command()
+@click.option("--create", help="Input target object name and create it")
+@click.option("--worker", help="Input new worker name and create it")
+@click.option("--config", help="Input new config file name and create it")
+def zfc(create, worker, config):
+    if create is not None:
+        create_func(create)
+
+    if worker is not None:
+        worker_func(worker.lower())
+
+
+if __name__ == "__main__":
+    zfc()

zoo_framework/conf/__init__.py

@@ -0,0 +1,3 @@
+from zoo_framework.conf.log_config import log_config, log_config_instance
+
+__all__ = ["log_config", "log_config_instance"]

zoo_framework/conf/log_config.py

@@ -0,0 +1,55 @@
+import logging
+import os
+
+from zoo_framework.core.aop import configure
+from zoo_framework.params import LogParams
+from zoo_framework.utils import DateTimeUtils, FileUtils
+
+level_relations = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "crit": logging.CRITICAL,
+}
+
+log_colors_config = {
+    # 终端输出日志颜色配置
+    "debug": "white",
+    "info": "cyan",
+    "warning": "yellow",
+    "error": "red",
+    "crit": "bold_red",
+}
+
+
+@configure(topic="log_config")
+def log_config(level: str = "info"):
+    logger = logging.getLogger()
+    log_config_instance(logger, level)
+
+
+def log_config_instance(logger, level: str = "info"):
+    if level_relations.get(LogParams.LOG_LEVEL) is None:
+        raise Exception(
+            "Config params \"log.level\"  only support to 'debug','info','warning','error','crit'"
+        )
+
+    logger.setLevel(level_relations[LogParams.LOG_LEVEL])
+
+    formatter = logging.Formatter(LogParams.LOG_BASIC_FORMAT, LogParams.LOG_DATE_FORMAT)
+
+    choler = logging.StreamHandler()  # 输出到控制台的handler
+    choler.setFormatter(formatter)
+    choler.setLevel(logging.INFO)  # 也可以不设置，不设置就默认用logger的level
+
+    log_dir_path = os.path.join(LogParams.LOG_BASE_PATH, DateTimeUtils.get_format_now("%Y-%m-%d"))
+
+    FileUtils.dir_exists_and_create(log_dir_path)
+
+    log_path = "{}/{}.log".format(log_dir_path, DateTimeUtils.get_format_now("%Y-%m-%d"))
+    filer = logging.FileHandler(log_path)  # 输出到文件的handler
+    filer.setFormatter(formatter)
+    logger.addHandler(choler)
+    logger.addHandler(filer)
+    return logger

zoo_framework/constant/__init__.py

@@ -0,0 +1,4 @@
+from .waiter_constant import WaiterConstant
+from .worker_constant import WorkerConstant
+
+__all__ = ["WaiterConstant", "WorkerConstant"]

zoo_framework/constant/waiter_constant.py

@@ -0,0 +1,5 @@
+class WaiterConstant:
+    WORKER_MODE_THREAD = "thread"
+    WORKER_MODE_THREAD_POOL = "thread_pool"
+    WORKER_MODE_PROCESS = "process"
+    WORKER_MODE_PROCESS_POOL = "process_pool"

zoo_framework/constant/worker_constant.py

@@ -0,0 +1,14 @@
+class WorkerConstant:
+    # worker 运行模式
+    RUN_MODE_THREAD = "thread"
+    RUN_MODE_PROCESS = "process"
+    RUN_MODE_COROUTINE = "coroutine"
+    # worker 运行模式（缩写）
+    RUN_MODE_THREAD_ABBREVIATE = "T"
+    RUN_MODE_PROCESS_ABBREVIATE = "P"
+    RUN_MODE_COROUTINE_ABBREVIATE = "C"
+
+    # 运行策略
+    RUN_POLICY_SAFE = "safe"
+    RUN_POLICY_SIMPLE = "simple"
+    RUN_POLICY_STABLE = "stable"

zoo_framework/core/__init__.py

@@ -0,0 +1,6 @@
+from zoo_framework.core.aop import cage, event, worker, worker_register
+from zoo_framework.core.master import Master
+from zoo_framework.core.params_factory import ParamsFactory
+from zoo_framework.core.params_path import ParamsPath
+
+__all__ = ["Master", "ParamsFactory", "ParamsPath", "cage", "event", "worker", "worker_register"]

zoo_framework/core/aop/__init__.py

@@ -0,0 +1,21 @@
+from .cage import cage
+from .configure import config_funcs, configure
+from .event import event
+from .logger import logger
+from .params import params
+from .stopwatch import stopwatch
+from .validation import validation
+from .worker import worker, worker_register
+
+__all__ = [
+    "cage",
+    "config_funcs",
+    "configure",
+    "event",
+    "logger",
+    "params",
+    "stopwatch",
+    "validation",
+    "worker",
+    "worker_register",
+]

zoo_framework/core/aop/cage.py

@@ -0,0 +1,14 @@
+from zoo_framework.utils.thread_safe_dict import ThreadSafeDict
+
+# 单例对象注册器
+cage_register_map = ThreadSafeDict()
+
+
+def cage(cls):
+    def _cage():
+        """用于单例模式的装饰器."""
+        if cage_register_map.get(cls.__name__) is None:
+            cage_register_map[cls.__name__] = cls()
+        return cage_register_map[cls.__name__]
+
+    return _cage

zoo_framework/core/aop/configure.py

@@ -0,0 +1,22 @@
+from zoo_framework.utils.thread_safe_dict import ThreadSafeDict
+
+# 创建一个线程安全的字典，用于存储配置函数
+config_funcs = ThreadSafeDict()
+
+
+def configure(topic: str):
+    """装饰器工厂函数，用于将函数注册到指定的主题下。
+
+    参数:
+        topic (str): 主题名称，用于标识配置函数的分类或用途。
+
+    返回:
+        function: 返回一个装饰器函数，该装饰器将传入的函数注册到 config_funcs 字典中。
+    """
+
+    def inner(func):
+        # 将传入的函数以主题为键存储到线程安全字典中
+        config_funcs[topic] = func
+        return func
+
+    return inner

zoo_framework/core/aop/event.py

@@ -0,0 +1,44 @@
+import time
+
+from zoo_framework.event.event_channel_manager import EventChannelManager
+from zoo_framework.reactor import EventReactor
+from zoo_framework.reactor.event_retry_strategy import EventRetryStrategy
+
+
+# 自定义事件装饰器，用于注册事件
+# 参数说明：
+#   topic: 事件的主题，用于标识事件类型
+#   channel: 事件通道名称，默认为"default"
+#   timeout: 事件超时时间，默认为当前时间加1000秒
+#   retry_time: 重试次数，默认为1次
+#   retry_strategy: 重试策略，默认为RetryOnce（仅重试一次）
+#   done_callback: 事件完成后的回调函数，默认为None
+#   error_callback: 事件出错时的回调函数，默认为None
+#   success_callback: 事件成功时的回调函数，默认为None
+# 返回值：返回一个装饰器函数，用于包装目标函数
+def event(
+    topic: str,
+    channel: str = "default",
+    timeout: int = time.time() + 1000,
+    retry_time: int = 1,
+    retry_strategy=EventRetryStrategy.RetryOnce,
+    done_callback=None,
+    error_callback=None,
+    success_callback=None,
+):
+    # 内部装饰器函数，接收被装饰的目标函数
+    def _event(func: callable):
+        # 创建一个事件反应器实例，并设置相关属性
+        reactor = EventReactor(func.__name__)
+        reactor.set_event_callback(func)  # 设置事件回调函数为目标函数
+        reactor.set_event_timeout(timeout)  # 设置事件超时时间
+        reactor.set_retry_strategy(retry_strategy, retry_time)  # 设置重试策略和重试次数
+        reactor.set_error_callback(error_callback)  # 设置错误回调函数
+        reactor.set_success_callback(success_callback)  # 设置成功回调函数
+        reactor.set_done_callback(done_callback)  # 设置完成回调函数
+
+        # 检查并刷新事件通道，将当前反应器与指定主题和通道关联
+        EventChannelManager().refresh_channel(channel, topic, reactor)
+        return func  # 返回原始函数，保持装饰器透明性
+
+    return _event  # 返回内部装饰器函数

zoo_framework/core/aop/logger.py

@@ -0,0 +1,61 @@
+import logging
+
+from zoo_framework.utils import LogUtils
+
+log_utils = LogUtils()
+
+
+def logger(cls):
+    """为类添加日志记录功能的装饰器。
+
+    该装饰器会为传入的类创建一个日志记录器，并将其赋值给类的 `_logger` 属性。
+
+    参数:
+        cls (class): 需要添加日志功能的类。
+
+    返回:
+        class: 添加了日志功能的类。
+    """
+    from zoo_framework.conf.log_config import log_config_instance
+
+    # 创建类的日志记录器
+    _logger = logging.getLogger(cls.__name__)
+
+    _logger = log_config_instance(_logger)
+
+    # 将日志记录器赋值给类的 _logger 属性
+    cls._logger = _logger
+
+    # 定义装饰器函数，用于添加日志记录功能
+    def decorator(func):
+        """为函数添加日志记录功能的装饰器。
+
+        在函数调用前后分别记录调试日志，包括函数名和返回值。
+
+        参数:
+            func (function): 需要添加日志功能的函数。
+
+        返回:
+            function: 添加了日志功能的函数。
+        """
+
+        def wrapper(*args, **kwargs):
+            # 记录方法调用前的日志
+            cls._logger.debug(f"Calling {func.__name__}")
+
+            # 执行原始方法
+            result = func(*args, **kwargs)
+
+            # 记录方法调用后的日志
+            cls._logger.debug(f"{func.__name__} returned: {result}")
+
+            return result
+
+        return wrapper
+
+    # 遍历类中的方法，并应用装饰器
+    for name, method in cls.__dict__.items():
+        if callable(method):
+            setattr(cls, name, decorator(method))
+
+    return cls

zoo_framework/core/aop/params.py

@@ -0,0 +1,23 @@
+from ..params_factory import ParamsFactory
+from ..params_path import ParamsPath
+
+config_params = {}
+
+
+def params(cls):
+    def inner():
+        if config_params.get(cls.__name__) is not None:
+            return config_params[cls.__name__]
+        params_list = dir(cls)
+        for param in params_list:
+            params_path = getattr(cls, param)
+            if not isinstance(params_path, ParamsPath):
+                continue
+            param_value = params_path.get_value()
+            default_value = params_path.get_default()
+            value = ParamsFactory().get_params(param_value, default_value=default_value)
+            setattr(cls, param, value)
+        config_params[cls.__name__] = cls
+        return cls
+
+    return inner()

zoo_framework/core/aop/stopwatch.py

@@ -0,0 +1,16 @@
+def stopwatch(func):
+    """Decorator for measuring time of function execution.
+    :param func: function to be measured
+    :return: function result.
+    """
+    from functools import wraps
+    from time import time
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time()
+        result = func(*args, **kwargs)
+        print(f"Function {func.__name__} took {time() - start} seconds")
+        return result
+
+    return wrapper

zoo_framework/core/aop/validation.py

@@ -0,0 +1,54 @@
+# 全局字典，用于存储参数验证规则
+params_validate_map = {}
+
+
+def validation(params_key="") -> object:
+    """返回一个装饰器函数，用于将参数插入到指定键的验证列表中。
+
+    参数:
+        params_key (str): 用于标识参数验证规则的键，默认为空字符串。
+
+    返回:
+        function: 内部函数，接受一个参数并将其插入到对应键的验证列表中。
+    """
+
+    def inner(params):
+        # 如果指定键在验证映射中不存在，则初始化为空列表
+        if params_validate_map.get(params_key) is None:
+            params_validate_map[params_key] = []
+
+        # 将参数插入到对应键的验证列表中
+        params_validate_map[params_key].append(params)
+        return params
+
+    return inner
+
+
+def validation_params(params_key, value):
+    """验证给定值是否存在于指定键的验证列表中。
+
+    参数:
+        params_key (str): 用于查找验证列表的键。
+        value (any): 需要验证的值。
+
+    返回:
+        bool or None:
+            - 如果值存在于验证列表中，返回True；
+            - 如果验证列表不存在或类型不正确，返回False；
+            - 如果值不在验证列表中，返回None。
+    """
+    # 获取指定键对应的验证列表
+    valid_values = params_validate_map.get(params_key)
+
+    # 如果验证列表不存在，直接返回False
+    if valid_values is None:
+        return False
+
+    # 如果验证列表不是列表类型，返回False
+    if not isinstance(valid_values, list):
+        return False
+
+    # 检查值是否在验证列表中
+    if value in valid_values:
+        return True
+    return None

zoo_framework/core/aop/worker.py

@@ -0,0 +1,38 @@
+# TODO: 使用 register 的方式来注册 worker
+from zoo_framework.workers import WorkerRegister
+
+worker_register: WorkerRegister = WorkerRegister()
+
+
+def worker(count: int = 1):
+    """装饰器函数，用于注册指定数量的 worker 实例。
+
+    参数:
+        count (int): 需要注册的 worker 实例数量，默认为 1。
+
+    返回:
+        function: 返回一个内部装饰器函数，用于处理被装饰的类。
+    """
+
+    def inner(cls):
+        """内部装饰器函数，负责实际的 worker 注册逻辑。
+
+        参数:
+            cls (class): 被装饰的类，表示 worker 的类型。
+
+        返回:
+            class: 返回原始类，保持装饰器的透明性。
+        """
+        # 如果只需要注册一个实例，则直接注册该类的实例
+        if count == 1:
+            worker_register.register(cls.__name__, cls())
+            return cls
+
+        # 如果需要注册多个实例，则为每个实例分配编号并分别注册
+        for i in range(1, count + 1):
+            instance = cls()
+            instance.num = i
+            worker_register.register(f"{cls.__name__}_{i}", instance)
+        return cls
+
+    return inner