echoss-timeseries 1.0.0__py3-none-any.whl

echoss_timeseries/__init__.py

@@ -0,0 +1,110 @@
+"""
+12cm. inc timeseries package for  data analysis and modeling on time-base values
+- TSData class
+- TSModel class
+
+이름을 실제로 쓸 때 해당 모듈을 적재한다 (PEP 562 module __getattr__).
+전량 eager re-export 는 쓰지 않는다 — `import echoss_timeseries` 만으로 bokeh,
+matplotlib, statsmodels, holidays 가 전부 올라오면 진단 함수 하나 쓰는 비용이 과하고,
+엔진별 optional extras 가 성립하지 않는다 (docs/design/engine-abstraction.md 4절).
+"""
+from importlib import import_module
+
+# Package-level variables
+__version__ = '1.0.0'
+__author__ = 'ckkim@12cm.co.kr'
+
+from echoss_fileformat import get_logger, use_logger
+
+# Use package module level variable to store the singleton logger instance.
+# This check ensures the logger is created only once.
+try:
+    # Attempt to use an existing logger.
+    _logger = use_logger('echoss_timeseries')
+except RuntimeError:
+    # If it doesn't exist, create it.
+    _logger = get_logger('echoss_timeseries', backup_count=7)
+
+# Expose the logger to other modules in the package.
+# This makes it easily accessible via 'from . import logger'.
+# 지연 적재 대상이 아니다 — 하위 모듈이 import 시점에 `from . import logger` 로 가져간다.
+logger = _logger
+
+# export 이름 -> 이를 정의한 모듈. 지연 적재의 유일한 근거 자료다.
+_EXPORTS = {
+    "TSData": "echoss_tsdata",
+    "TSModel": "echoss_tsmodel",
+    "EventDayFeatures": "event_day_features",
+    **{name: "autoregressive_features" for name in (
+        "add_lag_features", "add_rolling_features",
+        "add_seasonal_rolling_features", "add_ewma_features",
+    )},
+    **{name: "decomposition" for name in (
+        "BaseDecomposition", "MultiSeasonalDecomposition",
+        "FourierDecomposition", "DecomposeResult",
+    )},
+    **{name: "temporal_features" for name in (
+        "add_temporal_features", "add_fourier_features", "bulk_add_fourier_features",
+    )},
+    **{name: "outlier" for name in (
+        "detect_outlier_sd", "detect_outlier_iqr", "detect_outlier_isolation_forest",
+    )},
+    **{name: "echoss_plot_bokeh" for name in (
+        "plot_lines", "plot_lines_grid", "plot_datetime", "plot_interactive_datetime",
+        "format_plot", "plot_forecast", "plot_train_test_forecast",
+    )},
+    "plot_sales_intensity_heatmap": "echoss_plot_matplot",
+    **{name: "engines.model_base" for name in ("ModelEngine", "DataShape")},
+    "StatsmodelsArimaEngine": "engines.statsmodels_arima",
+    "SklearnTabularEngine": "engines.sklearn_tabular",
+    "DartsSeriesEngine": "engines.darts_series",
+    "HoldoutComparison": "engines.holdout_comparison",
+    "EngineRegistry": "engines.registry",
+    **{name: "engines.ensemble_base" for name in ("Ensemble", "WeightedEnsemble")},
+    **{name: "engines.screener_base" for name in ("Screener", "Candidate")},
+    **{name: "tsdiag" for name in (
+        "ensure_month_start_col", "validate_month_ms", "ensure_datetime_freq",
+        "seasonal_strength", "is_constant_series", "stationarity_tests",
+        "lag_diagnostics", "try_autoreg", "naive_cv_scores", "analyze_series",
+    )},
+}
+
+# 기본 설치에 포함되지 않는 모듈 -> 필요한 extras 이름.
+# 여기 없는 모듈은 기본 의존성만으로 적재된다.
+_EXTRAS = {
+    "echoss_plot_bokeh": "plot",
+    "echoss_plot_matplot": "plot",
+    "engines.darts_series": "forecast",
+}
+
+__all__ = ["logger", *sorted(_EXPORTS)]
+
+
+def __getattr__(name: str):
+    """이름을 처음 쓸 때 해당 모듈을 적재한다 (PEP 562)."""
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    try:
+        module = import_module(f".{module_name}", __name__)
+    except ModuleNotFoundError as e:
+        # 무엇을 설치해야 하는지 알려준다. 맨 ModuleNotFoundError 로 끝내면
+        # 사용자가 extras 의 존재를 알 방법이 없다.
+        extras = _EXTRAS.get(module_name)
+        if extras is None:
+            raise
+        raise ModuleNotFoundError(
+            f"{name!r} 을 쓰려면 '{extras}' extras 가 필요하다 "
+            f"(빠진 의존성: {e.name}). "
+            f"설치: pip install 'echoss-timeseries[{extras}]'"
+        ) from e
+
+    value = getattr(module, name)
+    # 전역에 넣어두면 다음 접근부터는 __getattr__ 를 타지 않는다.
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted([*globals(), *_EXPORTS])