target-weight pilot 날짜/달력 헬퍼 모듈 분리 (모놀리스 1차 축소)

13,500줄 모놀리스(target_weight_rotation_pilot.py)에서 순수 KRX 거래일·날짜 로직을
tools/pilot_calendar.py로 분리했다. 동작 변화 0 — _접두어 이름을 re-import해 하위
호환을 유지하고, KST/TARGET_WEIGHT_PILOT_TARGET_DAYS 상수도 거기서 가져온다.
모놀리스 13521 → 13458줄.

- pilot_calendar: split_symbols, date_range, load_kr_market_holidays,
  is_kr_market_business_day, pilot_valid_to, next_kr_market_business_day,
  coerce_kst_datetime, execution_day (+ _접두어 별칭).
- 분리 전 전용 테스트가 없던 헬퍼에 test_pilot_calendar.py 18개 추가(거래일·휴장일·
  KST 변환 경계 검증).
- 기존 테스트 2개가 twp._load_kr_market_holidays를 패치했는데, 의존성 조회 소스가
  pilot_calendar로 옮겨졌으므로 pc.load_kr_market_holidays 패치로 정합화.

검증: 전체 1344 테스트 통과. pilot --help 및 헬퍼 접근성 스모크 정상.

Author: easygap

tests/test_pilot_calendar.py

@@ -0,0 +1,104 @@
+"""tools/pilot_calendar.py — KRX 거래일·날짜 헬퍼 단위 테스트.
+
+모놀리스(target_weight_rotation_pilot.py)에서 분리한 순수 함수들. 분리 전에는 전용
+테스트가 없었으므로 이번에 커버리지를 추가한다. 휴장일은 주입해 결정론적으로 검증.
+"""
+from datetime import datetime
+
+import pytest
+
+from tools import pilot_calendar as pc
+
+
+class TestSplitSymbols:
+    def test_none_returns_none(self):
+        assert pc.split_symbols(None) is None
+
+    def test_comma_and_newline(self):
+        assert pc.split_symbols("005930, 000660\n035420") == ["005930", "000660", "035420"]
+
+    def test_empty_filtered(self):
+        assert pc.split_symbols("005930,,  ,000660") == ["005930", "000660"]
+
+
+class TestDateRange:
+    def test_weekdays_only(self):
+        # 2024-01-01(월)~01-07(일): 평일 5개(1,2,3,4,5)
+        out = pc.date_range("2024-01-01", "2024-01-07")
+        assert out == ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05"]
+
+    def test_end_before_start_raises(self):
+        with pytest.raises(ValueError):
+            pc.date_range("2024-01-10", "2024-01-01")
+
+    def test_only_weekend_raises(self):
+        # 2024-01-06(토)~01-07(일): 평일 없음
+        with pytest.raises(ValueError):
+            pc.date_range("2024-01-06", "2024-01-07")
+
+
+class TestBusinessDay:
+    def test_weekday_no_holiday(self):
+        from datetime import date
+        assert pc.is_kr_market_business_day(date(2024, 1, 2), set()) is True
+
+    def test_weekend_is_not_business_day(self):
+        from datetime import date
+        assert pc.is_kr_market_business_day(date(2024, 1, 6), set()) is False  # 토
+
+    def test_holiday_is_not_business_day(self):
+        from datetime import date
+        assert pc.is_kr_market_business_day(date(2024, 1, 2), {"2024-01-02"}) is False
+
+
+class TestPilotValidTo:
+    def test_counts_business_days(self, monkeypatch):
+        # 휴장일 없음 가정 → 2024-01-02(화)부터 5영업일째
+        monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: set())
+        # 1/2(1), 1/3(2), 1/4(3), 1/5(4), 주말, 1/8(5)
+        assert pc.pilot_valid_to("2024-01-02", 5) == "2024-01-08"
+
+    def test_skips_holiday(self, monkeypatch):
+        monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: {"2024-01-03"})
+        # 1/2(1), 1/3 휴장, 1/4(2), 1/5(3), 주말, 1/8(4), 1/9(5)
+        assert pc.pilot_valid_to("2024-01-02", 5) == "2024-01-09"
+
+    def test_non_positive_raises(self):
+        with pytest.raises(ValueError):
+            pc.pilot_valid_to("2024-01-02", 0)
+
+
+class TestNextBusinessDay:
+    def test_skips_weekend(self, monkeypatch):
+        monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: set())
+        # 금(1/5) 다음 영업일 = 월(1/8)
+        assert pc.next_kr_market_business_day("2024-01-05") == "2024-01-08"
+
+    def test_skips_holiday(self, monkeypatch):
+        monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: {"2024-01-03"})
+        # 화(1/2) 다음 = 수(1/3) 휴장 → 목(1/4)
+        assert pc.next_kr_market_business_day("2024-01-02") == "2024-01-04"
+
+
+class TestKstHelpers:
+    def test_coerce_naive_kept(self):
+        dt = datetime(2024, 1, 2, 10, 0, 0)
+        assert pc.coerce_kst_datetime(dt) == dt
+
+    def test_coerce_aware_converted_to_kst_naive(self):
+        from datetime import timezone as tz, timedelta
+        utc_dt = datetime(2024, 1, 2, 1, 0, 0, tzinfo=tz.utc)  # UTC 01:00 = KST 10:00
+        out = pc.coerce_kst_datetime(utc_dt)
+        assert out.tzinfo is None
+        assert out.hour == 10
+
+    def test_execution_day_format(self):
+        assert pc.execution_day(datetime(2024, 3, 5, 15, 30)) == "2024-03-05"
+
+
+def test_backcompat_aliases_exist():
+    """모놀리스가 쓰던 _접두어 별칭이 그대로 노출되는지."""
+    for name in ("_split_symbols", "_date_range", "_load_kr_market_holidays",
+                 "_is_kr_market_business_day", "_pilot_valid_to",
+                 "_next_kr_market_business_day", "_coerce_kst_datetime", "_execution_day"):
+        assert hasattr(pc, name)

tests/test_target_weight_paper_adapter.py

@@ -8398,8 +8398,10 @@ def test_pilot_plan_validation_uses_net_exposure_increase_for_existing_positions
 
 def test_pilot_valid_to_counts_inclusive_krx_business_days(monkeypatch):
     import tools.target_weight_rotation_pilot as twp
+    import tools.pilot_calendar as pc
 
-    monkeypatch.setattr(twp, "_load_kr_market_holidays", lambda: {"2026-04-14"})
+    # 날짜 헬퍼는 tools/pilot_calendar로 분리됨 — 휴장일 로더는 그 모듈에서 조회한다.
+    monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: {"2026-04-14"})
 
     assert twp._pilot_valid_to("2026-04-10", target_pilot_days=3) == "2026-04-15"
 
@@ -9416,7 +9418,9 @@ def test_build_target_weight_daily_ops_summary_marks_today_recorded(tmp_path, mo
         write_target_weight_daily_ops_summary,
     )
 
-    monkeypatch.setattr(twp, "_load_kr_market_holidays", lambda: {"2026-04-13"})
+    import tools.pilot_calendar as pc
+    # 날짜 헬퍼는 tools/pilot_calendar로 분리됨 — 휴장일 로더는 그 모듈에서 조회한다.
+    monkeypatch.setattr(pc, "load_kr_market_holidays", lambda: {"2026-04-13"})
     plan = _adapter_plan()
     cap_recommendation = recommend_pilot_caps(plan)
     pass_check = {

tools/pilot_calendar.py

@@ -0,0 +1,114 @@
+"""target-weight pilot의 KRX 거래일·날짜 계산 헬퍼.
+
+target_weight_rotation_pilot.py(13,500줄 모놀리스)에서 순수 날짜/달력 로직만 분리한
+모듈이다. 외부 상태에 의존하지 않고(휴장일은 core.trading_hours에서 lazy load) stdlib만
+쓰므로 단독 테스트가 쉽다. 기존 동작과 100% 동일하며, 모놀리스는 이 모듈을 re-import해
+하위 호환을 유지한다.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+from loguru import logger
+
+# 한국 표준시(KST). pilot 실행일·세션ID 계산 기준.
+KST = timezone(timedelta(hours=9))
+
+# pilot 윈도우 기본 길이(영업일). _pilot_valid_to 기본값.
+TARGET_WEIGHT_PILOT_TARGET_DAYS = 60
+
+
+def split_symbols(raw: str | None) -> list[str] | None:
+    """쉼표/개행 구분 종목 문자열을 리스트로. None이면 None."""
+    if raw is None:
+        return None
+    symbols = [part.strip() for part in raw.replace("\n", ",").split(",")]
+    return [symbol for symbol in symbols if symbol]
+
+
+def date_range(start_date: str, end_date: str) -> list[str]:
+    """start~end(포함) 사이의 평일(월~금) 날짜 문자열 리스트."""
+    start = datetime.strptime(start_date, "%Y-%m-%d").date()
+    end = datetime.strptime(end_date, "%Y-%m-%d").date()
+    if end < start:
+        raise ValueError("shadow end date must be on or after start date")
+
+    dates: list[str] = []
+    day = start
+    while day <= end:
+        if day.weekday() < 5:
+            dates.append(day.strftime("%Y-%m-%d"))
+        day += timedelta(days=1)
+    if not dates:
+        raise ValueError("shadow date range contains no weekdays")
+    return dates
+
+
+def load_kr_market_holidays() -> set[str]:
+    """KRX 휴장일 집합(ISO 날짜 문자열). 조회 실패 시 빈 집합."""
+    try:
+        from core.trading_hours import _load_holidays
+
+        return {str(day).strip() for day in _load_holidays() if str(day).strip()}
+    except Exception as exc:
+        logger.debug("KRX holiday lookup skipped for pilot window calculation: {}", exc)
+        return set()
+
+
+def is_kr_market_business_day(day: date, holidays: set[str]) -> bool:
+    """평일이면서 휴장일이 아니면 True."""
+    return day.weekday() < 5 and day.isoformat() not in holidays
+
+
+def pilot_valid_to(
+    valid_from: str,
+    target_pilot_days: int = TARGET_WEIGHT_PILOT_TARGET_DAYS,
+) -> str:
+    """valid_from부터 target_pilot_days 영업일째 되는 날(포함)을 ISO로 반환."""
+    if target_pilot_days <= 0:
+        raise ValueError("target_pilot_days must be positive")
+
+    current = datetime.strptime(valid_from, "%Y-%m-%d").date()
+    holidays = load_kr_market_holidays()
+    counted_days = 0
+    while True:
+        if is_kr_market_business_day(current, holidays):
+            counted_days += 1
+            if counted_days >= target_pilot_days:
+                return current.isoformat()
+        current += timedelta(days=1)
+
+
+def next_kr_market_business_day(day: str) -> str:
+    """주어진 날의 다음 KRX 영업일을 ISO로 반환."""
+    current = datetime.strptime(day, "%Y-%m-%d").date() + timedelta(days=1)
+    holidays = load_kr_market_holidays()
+    while not is_kr_market_business_day(current, holidays):
+        current += timedelta(days=1)
+    return current.isoformat()
+
+
+def coerce_kst_datetime(now: datetime | None = None) -> datetime:
+    """now를 KST naive datetime으로 정규화(미지정 시 현재 KST)."""
+    current = now or datetime.now(KST)
+    if current.tzinfo is not None:
+        current = current.astimezone(KST).replace(tzinfo=None)
+    return current
+
+
+def execution_day(now: datetime | None = None) -> str:
+    """KST 기준 실행일(YYYY-MM-DD)."""
+    current = coerce_kst_datetime(now)
+    return current.date().strftime("%Y-%m-%d")
+
+
+# ── 하위 호환: 모놀리스가 쓰던 _접두어 이름을 별칭으로 노출 ──
+_split_symbols = split_symbols
+_date_range = date_range
+_load_kr_market_holidays = load_kr_market_holidays
+_is_kr_market_business_day = is_kr_market_business_day
+_pilot_valid_to = pilot_valid_to
+_next_kr_market_business_day = next_kr_market_business_day
+_coerce_kst_datetime = coerce_kst_datetime
+_execution_day = execution_day

tools/target_weight_rotation_pilot.py

@@ -36,6 +36,21 @@
     validate_plan_against_pilot,
 )
 
+# KRX 거래일·날짜 헬퍼는 tools/pilot_calendar.py로 분리(모놀리스 축소). 하위 호환 위해
+# _접두어 이름 그대로 re-import한다. KST / TARGET_WEIGHT_PILOT_TARGET_DAYS 도 여기서 온다.
+from tools.pilot_calendar import (
+    KST,
+    TARGET_WEIGHT_PILOT_TARGET_DAYS,
+    _split_symbols,
+    _date_range,
+    _load_kr_market_holidays,
+    _is_kr_market_business_day,
+    _pilot_valid_to,
+    _next_kr_market_business_day,
+    _coerce_kst_datetime,
+    _execution_day,
+)
+
 DEFAULT_OUTPUT_DIR = Path("reports/paper_runtime")
 DEFAULT_PILOT_PREVIEW_CAPS = {
     "max_orders_per_day": 2,
@@ -48,10 +63,9 @@
 DEFAULT_SHADOW_SCAN_MULTIPLIER = 5
 DEFAULT_LIQUIDITY_LOOKBACK_DAYS = 20
 DEFAULT_MAX_ORDER_ADV_PCT = 5.0
-TARGET_WEIGHT_PILOT_TARGET_DAYS = 60
+# TARGET_WEIGHT_PILOT_TARGET_DAYS, KST 는 tools/pilot_calendar.py에서 import (위 import 블록).
 AUTHORIZATION_SNAPSHOT_SCHEMA_VERSION = 1
 AUTHORIZATION_SNAPSHOT_TYPE = "target_weight_plan_authorization"
-KST = timezone(timedelta(hours=9))
 NO_ORDER_OPERATION_ERRORS = (ValueError, DataCollectionError)
 REPAIRABLE_TARGET_WEIGHT_EVIDENCE_REASONS = {
     "target_weight_benchmark_status_not_final",
@@ -88,83 +102,6 @@ def _stable_manifest_hash(payload: dict[str, Any]) -> str:
     return hashlib.sha256(encoded).hexdigest()
 
 
-def _split_symbols(raw: str | None) -> list[str] | None:
-    if raw is None:
-        return None
-    symbols = [part.strip() for part in raw.replace("\n", ",").split(",")]
-    return [symbol for symbol in symbols if symbol]
-
-
-def _date_range(start_date: str, end_date: str) -> list[str]:
-    start = datetime.strptime(start_date, "%Y-%m-%d").date()
-    end = datetime.strptime(end_date, "%Y-%m-%d").date()
-    if end < start:
-        raise ValueError("shadow end date must be on or after start date")
-
-    dates: list[str] = []
-    day = start
-    while day <= end:
-        if day.weekday() < 5:
-            dates.append(day.strftime("%Y-%m-%d"))
-        day += timedelta(days=1)
-    if not dates:
-        raise ValueError("shadow date range contains no weekdays")
-    return dates
-
-
-def _load_kr_market_holidays() -> set[str]:
-    try:
-        from core.trading_hours import _load_holidays
-
-        return {str(day).strip() for day in _load_holidays() if str(day).strip()}
-    except Exception as exc:
-        logger.debug("KRX holiday lookup skipped for pilot window calculation: {}", exc)
-        return set()
-
-
-def _is_kr_market_business_day(day: date, holidays: set[str]) -> bool:
-    return day.weekday() < 5 and day.isoformat() not in holidays
-
-
-def _pilot_valid_to(
-    valid_from: str,
-    target_pilot_days: int = TARGET_WEIGHT_PILOT_TARGET_DAYS,
-) -> str:
-    """Return an inclusive KRX business-day pilot window end date."""
-    if target_pilot_days <= 0:
-        raise ValueError("target_pilot_days must be positive")
-
-    current = datetime.strptime(valid_from, "%Y-%m-%d").date()
-    holidays = _load_kr_market_holidays()
-    counted_days = 0
-    while True:
-        if _is_kr_market_business_day(current, holidays):
-            counted_days += 1
-            if counted_days >= target_pilot_days:
-                return current.isoformat()
-        current += timedelta(days=1)
-
-
-def _next_kr_market_business_day(day: str) -> str:
-    current = datetime.strptime(day, "%Y-%m-%d").date() + timedelta(days=1)
-    holidays = _load_kr_market_holidays()
-    while not _is_kr_market_business_day(current, holidays):
-        current += timedelta(days=1)
-    return current.isoformat()
-
-
-def _coerce_kst_datetime(now: datetime | None = None) -> datetime:
-    current = now or datetime.now(KST)
-    if current.tzinfo is not None:
-        current = current.astimezone(KST).replace(tzinfo=None)
-    return current
-
-
-def _execution_day(now: datetime | None = None) -> str:
-    current = _coerce_kst_datetime(now)
-    return current.date().strftime("%Y-%m-%d")
-
-
 def _require_not_future_as_of_date(
     as_of_date: str | None,
     *,