owl-imdl 0.0.1__tar.gz

owl_imdl-0.0.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 kwen
+
+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.

owl_imdl-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: owl-imdl
+Version: 0.0.1
+Summary: IMDL template engine
+Author-email: kwen <aikwen@outlook.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: rich>=13.4.0
+Requires-Dist: python-statemachine>=3.0.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: prettytable>=3.17.0
+Requires-Dist: grpcio>=1.80.0
+Requires-Dist: protobuf>=6.31.1
+Dynamic: license-file
+
+# owl-imdl
+![Python Version](https://img.shields.io/badge/python->=3.10-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation (TestPyPI)
+
+Currently, this package is available on **TestPyPI**. You can install it using the following command:
+
+```bash
+pip install -i https://test.pypi.org/simple/ owl-imdl
+```
+
+## Manual Dependencies
+
+To keep the package lightweight and flexible, this project does not enforce deep learning framework dependencies (to avoid version conflicts).
+
+Please manually install the following dependencies according to your environment before use:
+
+1. **PyTorch**: Visit [pytorch](https://pytorch.org/get-started/locally/) to get the command for your CUDA version.
+2. Other Essentials:
+```bash
+pip install numpy Pillow albumentations
+```
+
+## Quick Start
+
+### Initialize a Project
+
+Run the following command in any directory to generate a training script (e.g., `my_project.py`):
+
+```bash
+owl init
+```
+
+The generated template uses `example/` as a placeholder dataset directory. Replace it with your own dataset path in actual use.
+
+## Dataset Structure
+
+```text
+my_dataset/
+├── gt/                 # Ground Truth images
+├── tp/                 # Tampered/Target images
+└── my_dataset.json     # Index file (MUST match the folder name!)
+```
+
+JSON Format (my_dataset.json):
+
+```json
+[
+  {
+    "tp": "tampered_image_01.jpg",
+    "gt": "mask_01.png"
+  },
+  {
+    "tp": "tampered_image_02.jpg",
+    "gt": "mask_02.png"
+  }
+]
+```

owl_imdl-0.0.1/README.md

@@ -0,0 +1,59 @@
+# owl-imdl
+![Python Version](https://img.shields.io/badge/python->=3.10-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation (TestPyPI)
+
+Currently, this package is available on **TestPyPI**. You can install it using the following command:
+
+```bash
+pip install -i https://test.pypi.org/simple/ owl-imdl
+```
+
+## Manual Dependencies
+
+To keep the package lightweight and flexible, this project does not enforce deep learning framework dependencies (to avoid version conflicts).
+
+Please manually install the following dependencies according to your environment before use:
+
+1. **PyTorch**: Visit [pytorch](https://pytorch.org/get-started/locally/) to get the command for your CUDA version.
+2. Other Essentials:
+```bash
+pip install numpy Pillow albumentations
+```
+
+## Quick Start
+
+### Initialize a Project
+
+Run the following command in any directory to generate a training script (e.g., `my_project.py`):
+
+```bash
+owl init
+```
+
+The generated template uses `example/` as a placeholder dataset directory. Replace it with your own dataset path in actual use.
+
+## Dataset Structure
+
+```text
+my_dataset/
+├── gt/                 # Ground Truth images
+├── tp/                 # Tampered/Target images
+└── my_dataset.json     # Index file (MUST match the folder name!)
+```
+
+JSON Format (my_dataset.json):
+
+```json
+[
+  {
+    "tp": "tampered_image_01.jpg",
+    "gt": "mask_01.png"
+  },
+  {
+    "tp": "tampered_image_02.jpg",
+    "gt": "mask_02.png"
+  }
+]
+```

owl_imdl-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "owl-imdl"
+version = "0.0.1"
+description = "IMDL template engine"
+readme = "README.md"
+authors = [
+  {name = "kwen", email = "aikwen@outlook.com"},
+]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "loguru>=0.7.3",
+    "rich>=13.4.0",
+    "python-statemachine>=3.0.0",
+    "questionary>=2.1.1",
+    "prettytable>=3.17.0",
+    "grpcio>=1.80.0",
+    "protobuf>=6.31.1",
+]
+
+[project.scripts]
+owl = "owl.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

owl_imdl-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

owl_imdl-0.0.1/src/owl/__init__.py

@@ -0,0 +1,40 @@
+from typing import TYPE_CHECKING
+
+from ._internal.lazy import attach_lazy_modules
+from .toolkits.common.seed import seed_everything
+
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("owl-imdl")
+    except PackageNotFoundError:
+        __version__ = "unknown"
+except ImportError:
+    __version__ = "unknown"
+
+
+seed = seed_everything
+
+
+# IDE 提示
+if TYPE_CHECKING:
+    from . import engine
+    from . import toolkits
+
+
+__all__ = attach_lazy_modules(
+    target_globals=globals(),
+    package=__package__,
+    delayed_modules={
+        "engine": ".engine",
+        "toolkits": ".toolkits",
+    },
+)
+
+__all__.extend([
+    "__version__",
+    "seed",
+    "seed_everything",
+])

owl_imdl-0.0.1/src/owl/_internal/fmt.py

@@ -0,0 +1,50 @@
+from prettytable import PrettyTable
+
+
+def format_metrics_table(all_metrics: dict[str, dict[str, float]], current_epoch: int) -> str:
+    """使用 PrettyTable 生成纯 ASCII 指标表格，确保日志文件无乱码。"""
+    if not all_metrics:
+        return ""
+
+    table = PrettyTable()
+
+    # 获取指标名称 (例如: AUC, F1)
+    first_ds = list(all_metrics.keys())[0]
+    metric_keys = list(all_metrics[first_ds].keys())
+
+    # 设置表头列名
+    table.field_names = ["DATASET"] + [k.upper() for k in metric_keys]
+
+    for ds_name, metrics in all_metrics.items():
+        row_values = [ds_name]
+        for k in metric_keys:
+            val = metrics.get(k, 0.0)
+            # 保持 4 位小数格式化
+            row_values.append(f"{val:.4f}" if isinstance(val, float) else str(val))
+        table.add_row(row_values)
+
+    table.align = "c"
+
+    lines = [
+        f"\nEpoch [{current_epoch}] Summary",
+        table.get_string(),
+        ""
+    ]
+
+    return "\n".join(lines) + "\n"
+
+def format_zero_pad(value: int, max_val: int) -> str:
+    """
+    对数字进行前导补 0 格式化。
+    对齐宽度由 max_val 的位数决定。
+
+    Args:
+        value (int): 当前值。
+        max_val (int): 允许达到的最大值, 用于确定宽度。
+
+    Returns:
+        str: 格式化后的字符串。例如：value=1, max_val=100 -> "001"
+    """
+    # 计算最大值的位数作为宽度
+    width = len(str(max_val))
+    return f"{value:0{width}d}"

owl_imdl-0.0.1/src/owl/_internal/lazy.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+from typing import Mapping
+
+
+def attach_lazy_modules(
+    target_globals: dict,
+    package: str | None,
+    delayed_modules: Mapping[str, str],
+) -> list[str]:
+    """
+    给当前包挂载子模块懒加载能力。
+
+    当用户第一次访问包下的某个子模块时，才真正导入该模块。
+    例如访问 ``common.fs`` 时，才导入 ``owl.toolkits.common.fs``。
+    Args:
+        target_globals (dict): 调用方模块的 globals()。
+        package (str | None): 调用方模块的 __package__。
+        delayed_modules (Mapping[str, str]): 子模块懒加载映射表。
+
+    Returns:
+        list[str]: 建议写入 __all__ 的模块名列表。
+    """
+
+    if package is None:
+        package = target_globals.get("__name__", "")
+
+    def __getattr__(name: str) -> ModuleType:
+        if name in delayed_modules:
+            module = importlib.import_module(delayed_modules[name], package=package)
+
+            # 缓存，避免下次再次触发 __getattr__
+            target_globals[name] = module
+
+            return module
+
+        current_module_name = target_globals.get("__name__", package)
+        raise AttributeError(f"module {current_module_name!r} has no attribute {name!r}")
+
+    target_globals["__getattr__"] = __getattr__
+    return list(delayed_modules.keys())

owl_imdl-0.0.1/src/owl/_internal/logger.py

@@ -0,0 +1,102 @@
+import sys
+import pathlib
+from loguru import logger as _logger
+
+LOGO_TEXT = r"""
+                 __
+  ____ _      __/ /
+ / __ \ | /| / / /
+/ /_/ / |/ |/ / /
+\____/|__/|__/_/ owl(v{})
+"""
+
+class OwlLogger:
+    """全局日志管理器"""
+    # 单例
+    _initialized = False
+
+    @classmethod
+    def setup(cls, work_dir: str | pathlib.Path):
+        """
+        初始化日志
+        """
+        if cls._initialized:
+            return
+
+        work_dir = pathlib.Path(work_dir)
+        work_dir.mkdir(parents=True, exist_ok=True)
+
+        # 移除 loguru 默认的终端输出
+        _logger.remove()
+
+        # ==========================================
+        # 终端控制台输出 (Console)
+        # ==========================================
+        _logger.add(
+            sys.stdout,
+            format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> - <level>{message}</level>",
+            level="INFO",   # 只打印 INFO 及以上级别的日志
+            colorize=True,  # 开启颜色
+            filter=lambda record: "mode" not in record["extra"],
+            enqueue=True    # 开启异步/多线程安全
+        )
+
+        # ==========================================
+        # 训练日志文件 (train.log)
+        # ==========================================
+        train_log_path = work_dir.joinpath("train.log")
+        _logger.add(
+            str(train_log_path),
+            # 纯文本 format
+            format="{time:YYYY-MM-DD HH:mm:ss} - {message}",
+            level="INFO",
+            filter=lambda record: record["extra"].get("mode", "train") == "train",  # 默认接收 train 模式的日志
+            rotation="100 MB",  # 文件超过 100MB 自动打包
+            retention="30 days",  # 日志保留 30 天
+            enqueue=True
+        )
+
+        # ==========================================
+        # 验证日志文件 (validate.log)
+        # ==========================================
+        val_log_path = work_dir.joinpath("validate.log")
+        _logger.add(
+            str(val_log_path),
+            format="{time:YYYY-MM-DD HH:mm:ss} - {message}",
+            level="INFO",
+            filter=lambda record: record["extra"].get("mode") == "val",  # 只有被标记为 val 的日志才会存到这里
+            rotation="100 MB",
+            retention="30 days",
+            enqueue=True
+        )
+
+        # 标记为已初始化
+        cls._initialized = True
+        _logger.info(f"日志目录: {work_dir}")
+
+    @classmethod
+    def welcome(cls):
+        """打印欢迎词与 Logo"""
+        try:
+            from .. import __version__
+        except ImportError:
+            __version__ = "unknown"
+
+        logo = LOGO_TEXT.format(__version__)
+
+        _logger.opt(raw=True, colors=True).info(f"<cyan>{logo}</cyan>\n")
+        _logger.opt(colors=True).info("<cyan>owl engine</cyan> is starting...")
+
+    @classmethod
+    def stop(cls):
+        """打印结束语"""
+        if not cls._initialized:
+            return
+
+        _logger.opt(colors=True).info("<cyan>owl engine</cyan> is stopped!")
+        _logger.complete()
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        return cls._initialized
+logger = _logger

owl_imdl-0.0.1/src/owl/_internal/registry.py

@@ -0,0 +1,66 @@
+import inspect
+from typing import Callable, Generic, TypeVar
+
+# 定义一个泛型类型 T
+T = TypeVar('T')
+
+class Registry(Generic[T]):
+    """泛型组件注册器。
+
+    支持直接注册类（Class），也支持注册构建函数（Factory Function）。
+    """
+
+    def __init__(self, name: str):
+        self._name = name
+        # 存储名称到可调用对象（类或函数）的映射
+        self._obj_map: dict[str, Callable[..., T]] = {}
+
+    def register(self, name: str|None = None) -> Callable[[Callable[..., T]], Callable[..., T]]:
+        """装饰器：将类或构建函数注册到工厂中。
+
+        把类或者函数放到 map 里面
+        """
+
+        def _register(obj: Callable[..., T]) -> Callable[..., T]:
+            key = name if name is not None else obj.__name__
+            if key in self._obj_map:
+                raise ValueError(f"组件 '{key}' 已经在注册器 '{self._name}' 中被注册过了！")
+
+            self._obj_map[key] = obj
+            return obj
+
+        return _register
+
+    def get(self, name: str) -> Callable[..., T]:
+        """获取已注册的类或构建函数"""
+        if name not in self._obj_map:
+            valid_list = list(self._obj_map.keys())
+            raise ValueError(f"未知的组件类型: '{name}'。在 '{self._name}' 中的支持列表: {valid_list}")
+        return self._obj_map[name]
+
+    def build(self, obj_type: str, **kwargs) -> T:
+        """组件构建
+
+        Args:
+            obj_type (str): 注册的组件名称（例如 "poly" 或 "adamw"）。
+            **kwargs: 目标类或函数所需的任意参数。
+
+        Returns:
+            T: 实例化后的具体对象。
+        """
+        # 获取已注册的类或工厂函数
+        build_func = self.get(obj_type)
+
+        # kwargs 解包
+        try:
+            inspect.signature(build_func).bind(**kwargs)
+        except TypeError as e:
+            raise ValueError(f"构建组件 '{obj_type}' 失败，参数不匹配: {e}") from e
+
+        return build_func(**kwargs)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._obj_map
+
+    def __repr__(self) -> str:
+        return f"Registry(name={self._name}, items={list(self._obj_map.keys())})"

owl_imdl-0.0.1/src/owl/_internal/signature.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def check_required_params(
+    func: Callable[..., Any],
+    required_params: tuple[str, ...],
+) -> None:
+    """检查函数签名是否包含指定的最小参数名集合。
+
+    该函数只检查参数名，不检查类型注解。
+
+    规则:
+        1. 如果函数显式声明了 required_params 中的所有参数，则通过。
+        2. 如果函数包含 **kwargs，则认为可以接收任意参数，也通过。
+        3. 否则抛出 ValueError。
+
+    Args:
+        func: 被检查的函数或可调用对象。
+        required_params: 必须包含的参数名集合。
+
+    Raises:
+        ValueError: 当函数签名缺少 required_params 中的参数时抛出。
+    """
+    sig = inspect.signature(func)
+
+    has_var_kwargs = any(
+        param.kind == inspect.Parameter.VAR_KEYWORD
+        for param in sig.parameters.values()
+    )
+
+    if has_var_kwargs:
+        return
+
+    missing_params = [
+        name for name in required_params
+        if name not in sig.parameters
+    ]
+
+    if missing_params:
+        raise ValueError(
+            f"函数签名缺少必要参数: {missing_params}. "
+            f"required={list(required_params)}, "
+            f"signature={func.__name__}{sig}"
+        )
+
+
+def _has_var_kwargs(sig: inspect.Signature) -> bool:
+    """判断函数签名中是否包含 **kwargs。"""
+    return any(
+        param.kind == inspect.Parameter.VAR_KEYWORD
+        for param in sig.parameters.values()
+    )
+
+
+def _required_param_names_from_base(
+    base_sig: inspect.Signature,
+) -> tuple[str, ...]:
+    """从基类方法签名中提取需要子类显式兼容的参数名。
+
+    这里只提取普通参数名，不包含 self，也不包含 *args / **kwargs。
+    """
+    names: list[str] = []
+
+    for name, param in base_sig.parameters.items():
+        if name == "self":
+            continue
+
+        if param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+
+        names.append(name)
+
+    return tuple(names)
+
+
+def check_method_contract(
+    child_cls: type,
+    base_cls: type,
+    method_name: str,
+    *,
+    require_var_kwargs: bool = True,
+    check_return_annotation: bool = False,
+) -> None:
+    """检查子类方法是否满足基类方法的最小签名契约。
+
+    该函数只检查参数名，不检查类型注解。
+
+    规则:
+        1. 子类必须具有 method_name 方法。
+        2. 子类方法必须显式包含基类方法中的必要参数名。
+        3. 默认要求子类方法保留 **kwargs，以兼容 Owl 后续扩展。
+        4. 可选检查子类方法是否声明返回值注解。
+
+    注意:
+        **kwargs 只用于接收未来扩展参数，不用于替代当前核心参数。
+        例如基类 forward 要求 batch_data/current_epoch/current_step，
+        那么子类也应该显式声明这些参数。
+
+    Args:
+        child_cls: 用户实现的子类，例如 MyModel。
+        base_cls: Owl 基类，例如 OwlModel。
+        method_name: 需要检查的方法名，例如 "forward"。
+        require_var_kwargs: 是否要求子类方法包含 **kwargs。
+        check_return_annotation: 是否要求子类方法声明返回值注解。
+
+    Raises:
+        TypeError: 当子类方法签名不满足基类契约时抛出。
+    """
+    if not hasattr(base_cls, method_name):
+        raise TypeError(
+            f"基类 {base_cls.__name__} 不存在方法: {method_name}"
+        )
+
+    if not hasattr(child_cls, method_name):
+        raise TypeError(
+            f"子类 {child_cls.__name__} 不存在方法: {method_name}"
+        )
+
+    base_method = getattr(base_cls, method_name)
+    child_method = getattr(child_cls, method_name)
+
+    base_sig = inspect.signature(base_method)
+    child_sig = inspect.signature(child_method)
+
+    base_required_params = _required_param_names_from_base(base_sig)
+    child_has_var_kwargs = _has_var_kwargs(child_sig)
+
+    missing_params = [
+        name for name in base_required_params
+        if name not in child_sig.parameters
+    ]
+
+    if missing_params:
+        raise TypeError(
+            f"{child_cls.__name__}.{method_name} 签名不满足 "
+            f"{base_cls.__name__}.{method_name} 契约。"
+            f"缺少参数: {missing_params}. "
+            f"required={list(base_required_params)}, "
+            f"signature={child_cls.__name__}.{method_name}{child_sig}"
+        )
+
+    if require_var_kwargs and not child_has_var_kwargs:
+        raise TypeError(
+            f"{child_cls.__name__}.{method_name} 缺少 **kwargs。"
+            f"Owl 组件方法建议保留 **kwargs，以兼容未来框架注入的扩展上下文参数。"
+            f"signature={child_cls.__name__}.{method_name}{child_sig}"
+        )
+
+    if check_return_annotation:
+        if child_sig.return_annotation is inspect.Signature.empty:
+            raise TypeError(
+                f"{child_cls.__name__}.{method_name} 缺少返回值类型注解。"
+                f"建议与 {base_cls.__name__}.{method_name} 保持一致。"
+            )