pyqqq-script 0.0.1__py3-none-any.whl

pyqqq3/__init__.py

@@ -0,0 +1,15 @@
+"""pyqqq3 — Pine Script 스타일 트레이딩 라이브러리."""
+
+from pyqqq3.application.backtest import Backtest
+from pyqqq3.application.live import LiveTrading
+from pyqqq3.auth import get_api_key, set_api_key
+from pyqqq3.strategy import Strategy, ta
+
+__all__ = [
+    "Strategy",
+    "Backtest",
+    "LiveTrading",
+    "ta",
+    "set_api_key",
+    "get_api_key",
+]

pyqqq3/application/backtest.py

@@ -0,0 +1,213 @@
+"""Backtest — 과거 데이터 시뮬레이션 파사드.
+
+HistoricalDataFeed + MockBroker + TradingEngine 을 조립한다.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import inspect
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from pyqqq3.application.messaging import EventBus
+from pyqqq3.application.session import Session, new_session_id
+from pyqqq3.auth import ensure_api_key
+from pyqqq3.infra.broker.mock import MockBroker
+from pyqqq3.infra.data.historical import HistoricalDataFeed
+from pyqqq3.model.account import Account
+from pyqqq3.model.execution.journal import ExecutionJournal
+from pyqqq3.model.result import Result
+from pyqqq3.model.symbol import Symbol, SymbolCode
+from pyqqq3.trading.engine import TradingEngine
+
+if TYPE_CHECKING:
+    from pyqqq3.application.store import SessionStore
+    from pyqqq3.model.symbol_repository import SymbolRepository
+    from pyqqq3.strategy import Strategy
+
+
+class Backtest:
+    """과거 OHLCV DataFrame 으로 전략을 시뮬레이션한다.
+
+    두 가지 모드:
+    1. DataFrame 직접 제공 (테스트용):
+        bt = Backtest(strategy=RSI_BB, df=df, capital=10_000_000)
+
+    2. Symbol/Date 범위 (프로덕션용):
+        bt = Backtest(strategy=RSI_BB, symbol="005930",
+                      start="2025-01-01", end="2025-12-31", capital=10_000_000)
+
+    ``symbol`` 이 주어지면 ``symbol_repo`` 를 통해 즉시 메타데이터를 하이드레이트한다.
+    종목이 존재하지 않으면 ``SymbolNotFound`` 가 발생한다.
+
+    session_store 를 지정하면 운용 이력을 기록한다:
+        from pyqqq3.infra.store.file import FileStore
+        bt = Backtest(..., session_store=FileStore())
+    """
+
+    def __init__(
+        self,
+        strategy: type["Strategy"],
+        df: pd.DataFrame | None = None,
+        symbol: "str | Symbol | None" = None,
+        start: str | dt.date | None = None,
+        end: str | dt.date | None = None,
+        capital: int = 10_000_000,
+        commission: float = 0.00015,
+        slippage: float = 0.0,
+        session_store: "SessionStore | None" = None,
+        symbol_repo: "SymbolRepository | None" = None,
+    ) -> None:
+        if df is None and (symbol is None or start is None or end is None):
+            raise ValueError("Either df or (symbol, start, end) must be provided")
+
+        self.strategy = strategy
+        self.df = df
+        self.start = start
+        self.end = end
+        self.capital = capital
+        self.commission = commission
+        self.slippage = slippage
+        self.session_store = session_store
+
+        self._symbol: Symbol | None = None
+        if isinstance(symbol, Symbol):
+            self._symbol = symbol
+        elif symbol:
+            if symbol_repo is None:
+                from pyqqq3.infra.data.symbols import DomesticRepository
+
+                symbol_repo = DomesticRepository()
+            ensure_api_key()
+            self._symbol = symbol_repo.require(SymbolCode(symbol))
+
+    @property
+    def symbol(self) -> "Symbol | None":
+        return self._symbol
+
+    def run(self) -> "Result":
+        if self.df is not None:
+            data_feed = HistoricalDataFeed(df=self.df)
+        else:
+            assert self._symbol is not None  # __init__ 에서 검증됨
+            ensure_api_key()
+            data_feed = HistoricalDataFeed.from_symbol(
+                symbol=str(self._symbol.code), start=self.start, end=self.end
+            )
+
+        journal = ExecutionJournal()
+        account = Account()
+        bus = EventBus()
+        bus.subscribe(journal.append)
+        bus.subscribe(account.apply)
+        session_id = new_session_id()
+
+        broker = MockBroker(
+            capital=int(self.capital),
+            account=account,
+            commission=float(self.commission),
+            slippage=float(self.slippage),
+            symbol=self._symbol,
+            event_sink=bus.publish,
+        )
+        engine = TradingEngine(
+            strategy_class=self.strategy,
+            data_feed=data_feed,
+            broker=broker,
+            account=account,
+            journal=journal,
+        )
+        strategy_instance = engine.prepare()
+        strategy_params = _extract_strategy_params(strategy_instance)
+
+        equity_curve = engine.run()
+        self._account = account  # 테스트/디버깅용 노출 (dual-write 검증)
+
+        session = Session(
+            session_id=session_id,
+            kind="backtest",
+            created_at=dt.datetime.now(),
+            strategy_name=self.strategy.__name__,
+            strategy_params=strategy_params,
+            symbols=(self._symbol,) if self._symbol is not None else (),
+            start_date=_to_date(self.start),
+            end_date=_to_date(self.end),
+            engine_config={
+                "capital": int(self.capital),
+                "commission": float(self.commission),
+                "slippage": float(self.slippage),
+            },
+        )
+
+        trades = journal.trades(symbol=self._symbol) if self._symbol is not None else []
+        result = Result.from_equity_curve(
+            trades=trades,
+            equity_curve=equity_curve,
+            symbol=self._symbol,
+            session_id=session_id,
+            initial_capital=float(self.capital),
+        )
+
+        if self.session_store is not None:
+            sid = self.session_store.start(session)
+            self.session_store.append_events(sid, journal.events)
+            self.session_store.finalize(sid, stats=result.stats())
+
+        return result
+
+
+_FRAMEWORK_ATTRS = frozenset(
+    {
+        "open",
+        "high",
+        "low",
+        "close",
+        "volume",
+        "bar_index",
+        "time",
+        "is_last_bar",
+    }
+)
+
+
+def _extract_strategy_params(strategy: "Strategy") -> dict:
+    """전략 인스턴스에서 직렬화 가능한 파라미터를 추출한다.
+
+    클래스 레벨 변수와 ``init()`` 안에서 ``self.X = ...`` 로 선언한 인스턴스 변수를
+    모두 포함한다. 같은 이름이 양쪽에 있으면 인스턴스 값이 우선한다 (Python 속성
+    lookup 과 동일). 엔진이 주입하는 framework 속성(open/high/low/close/volume,
+    bar_index, time, is_last_bar)과 underscore-prefixed 내부 속성은 제외한다.
+    """
+    try:
+        params: dict = {}
+
+        for name, value in inspect.getmembers(type(strategy)):
+            if name.startswith("_") or name in _FRAMEWORK_ATTRS:
+                continue
+            if callable(value) or inspect.isclass(value):
+                continue
+            if isinstance(value, (int, float, str, bool)):
+                params[name] = value
+
+        for name, value in vars(strategy).items():
+            if name.startswith("_") or name in _FRAMEWORK_ATTRS:
+                continue
+            if isinstance(value, (int, float, str, bool)):
+                params[name] = value
+
+        return params
+    except Exception:
+        return {}
+
+
+def _to_date(value: "str | dt.date | None") -> "dt.date | None":
+    if value is None:
+        return None
+    if isinstance(value, dt.date):
+        return value
+    try:
+        return dt.date.fromisoformat(str(value)[:10])
+    except Exception:
+        return None

pyqqq3/application/live.py

@@ -0,0 +1,142 @@
+"""LiveTrading — 실시간 트레이딩 파사드.
+
+Backtest 와 동일한 조립 구조를 쓴다:
+    DataFeed + Broker + EventBus + Account + ExecutionJournal → TradingEngine
+
+차이는 Broker/DataFeed 의 구현체뿐이다 (KISDomesticBroker + RealtimeDataFeed).
+이 파일은 DI 배선과 lifecycle 만 담당한다.
+
+session_store 가 주입되면 EventBus 에 streaming sink 를 붙여 이벤트가
+발생하는 즉시 store 로 흘려보낸다 — 프로세스가 중간에 죽어도 그 시점까지의
+체결 이력이 보존된다.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
+
+from pyqqq3.application.backtest import _extract_strategy_params
+from pyqqq3.application.messaging import EventBus
+from pyqqq3.application.session import Session, new_session_id
+from pyqqq3.auth import ensure_api_key
+from pyqqq3.model.account import Account
+from pyqqq3.model.execution.journal import ExecutionJournal
+from pyqqq3.model.result import Result
+from pyqqq3.model.symbol import Symbol, SymbolCode
+from pyqqq3.trading.engine import TradingEngine
+
+if TYPE_CHECKING:
+    from pyqqq3.application.store import SessionStore
+    from pyqqq3.model.symbol_repository import SymbolRepository
+    from pyqqq3.strategy import Strategy
+    from pyqqq3.trading.broker import Broker
+    from pyqqq3.trading.feed import DataFeed
+
+
+class LiveTrading:
+    """실시간 트레이딩 파사드.
+
+    브로커와 데이터 피드는 호출자가 직접 주입한다. 브로커는 외부 거래소로부터
+    수신한 체결/거부 이벤트를 ``event_sink`` 로 발행해야 한다 (Broker 규약).
+    LiveTrading 은 EventBus 를 통해 이를 Journal + Account 로 fan-out 한다.
+
+    종목은 진입 시점에 ``symbol_repo.require()`` 로 즉시 검증·하이드레이트한다.
+    존재하지 않는 종목 코드는 ``SymbolNotFound`` 로 거부된다.
+
+    Args:
+        strategy: Strategy 서브클래스 타입.
+        data_feed: 실시간 DataFeed 구현체.
+        broker_factory: ``event_sink`` 를 받아 Broker 를 반환하는 팩토리.
+        symbol: 거래 종목 코드 (raw str). 즉시 ``Symbol`` 로 하이드레이트된다.
+        symbol_repo: 종목 메타데이터 조회용 Repository. 미주입 시
+            ``DomesticRepository`` 가 사용된다.
+        session_store: 운용 이력 저장소 (선택).
+    """
+
+    def __init__(
+        self,
+        strategy: type["Strategy"],
+        data_feed: "DataFeed",
+        broker_factory,
+        symbol: "str | Symbol",
+        symbol_repo: "SymbolRepository | None" = None,
+        session_store: "SessionStore | None" = None,
+    ) -> None:
+        if not symbol:
+            raise ValueError("LiveTrading 은 symbol 이 필수입니다")
+
+        self.strategy = strategy
+        self.data_feed = data_feed
+        self.broker_factory = broker_factory
+        self.session_store = session_store
+
+        if isinstance(symbol, Symbol):
+            self._symbol: Symbol = symbol
+        else:
+            if symbol_repo is None:
+                from pyqqq3.infra.data.symbols import DomesticRepository
+
+                symbol_repo = DomesticRepository()
+            ensure_api_key()
+            self._symbol = symbol_repo.require(SymbolCode(symbol))
+
+        self._account: Account | None = None
+        self._journal: ExecutionJournal | None = None
+
+    @property
+    def symbol(self) -> "Symbol":
+        return self._symbol
+
+    def run(self) -> Result:
+        journal = ExecutionJournal()
+        account = Account()
+        bus = EventBus()
+        bus.subscribe(journal.append)
+        bus.subscribe(account.apply)
+
+        session_id = new_session_id()
+        # broker 생성 시 CashDeposited 가 emit 되므로 session start 와 sink 구독은
+        # broker_factory 호출 *전*에 끝나야 한다.
+        session = Session(
+            session_id=session_id,
+            kind="live",
+            created_at=dt.datetime.now(),
+            strategy_name=self.strategy.__name__,
+            strategy_params=_extract_strategy_params(self.strategy()),
+            symbols=(self._symbol,),
+            start_date=None,
+            end_date=None,
+            engine_config={},
+        )
+        if self.session_store is not None:
+            store = self.session_store
+            store.start(session)
+            bus.subscribe(lambda e: store.append_events(session_id, [e]))
+
+        broker: "Broker" = self.broker_factory(bus.publish, account)
+
+        engine = TradingEngine(
+            strategy_class=self.strategy,
+            data_feed=self.data_feed,
+            broker=broker,
+            account=account,
+            journal=journal,
+        )
+        engine.prepare()
+        equity_curve = engine.run()
+
+        self._account = account
+        self._journal = journal
+
+        result = Result.from_equity_curve(
+            trades=journal.trades(symbol=self._symbol),
+            equity_curve=equity_curve,
+            symbol=self._symbol,
+            session_id=session_id,
+        )
+
+        if self.session_store is not None:
+            self.session_store.finalize(session_id, stats=result.stats())
+
+        return result

pyqqq3/application/messaging/__init__.py

@@ -0,0 +1,5 @@
+"""Application messaging — 이벤트 fanout 등 전달 메커니즘."""
+
+from pyqqq3.application.messaging.bus import EventBus, EventHandler
+
+__all__ = ["EventBus", "EventHandler"]

pyqqq3/application/messaging/bus.py

@@ -0,0 +1,38 @@
+"""EventBus — 동기 in-process fanout.
+
+브로커가 publish 한 ExecutionEvent 를 구독자(journal, Account 등)에게
+순차적으로 전달한다. Phase 1 단계에서는 단일 스레드, 동기 실행을 가정한다.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from pyqqq3.model.execution.events import ExecutionEvent
+
+EventHandler = Callable[[ExecutionEvent], None]
+
+
+class EventBus:
+    """동기 이벤트 fanout.
+
+    한 번에 하나의 이벤트를 등록된 모든 핸들러에게 순차 전달한다.
+    구독자 등록 순서대로 실행되며, 한 핸들러 예외가 다음 핸들러 실행을 막는다
+    (journal / Account 의 일관성 확보를 위해 의도된 동작).
+
+    Usage:
+        bus = EventBus()
+        bus.subscribe(journal.append)
+        bus.subscribe(account.apply)
+        broker = MockBroker(..., event_sink=bus.publish)
+    """
+
+    def __init__(self) -> None:
+        self._handlers: list[EventHandler] = []
+
+    def subscribe(self, handler: EventHandler) -> None:
+        self._handlers.append(handler)
+
+    def publish(self, event: ExecutionEvent) -> None:
+        for handler in self._handlers:
+            handler(event)

pyqqq3/application/session.py

@@ -0,0 +1,48 @@
+"""Session — application 레이어의 운용 단위 정의.
+
+도메인 라이프사이클 ``Strategy → Session → SessionReport`` 의 가운데 단계로,
+backtest/paper/live 를 아우르는 운용 인스턴스의 식별자·전략·심볼·기간·엔진설정을
+담는 경계 DTO 다. ``SessionStore`` 가 이 타입들을 키로 영속화한다.
+
+심볼은 ``Symbol`` 객체로 보유하며, 영속화 어댑터(MongoStore/FileStore)는
+직렬화 시 ``str(symbol.code)`` 로 변환하고 역직렬화 시 ``SymbolRepository`` 로
+하이드레이트한다.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pyqqq3.model.symbol import Symbol
+
+
+@dataclass(frozen=True)
+class Session:
+    session_id: str
+    kind: str  # "backtest" | "paper" | "live"
+    created_at: dt.datetime
+    strategy_name: str
+    strategy_params: dict[str, Any]
+    symbols: tuple["Symbol", ...]
+    start_date: dt.date | None
+    end_date: dt.date | None
+    engine_config: dict[str, Any]  # commission, slippage, capital
+
+
+@dataclass(frozen=True)
+class SessionReport:
+    session_id: str
+    created_at: dt.datetime
+    strategy_name: str
+    symbol: "Symbol | None"
+    total_return_pct: float
+    trade_count: int
+    kind: str
+
+
+def new_session_id() -> str:
+    return f"{dt.datetime.now().strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:6]}"

pyqqq3/application/store.py

@@ -0,0 +1,87 @@
+"""SessionStore — 운용 단위 저장/조회 인터페이스 (application 포트).
+
+저장은 stream API 로 통일되어 있다 — backtest 든 live 든 호출 패턴은 같다:
+
+    sid = store.start(session)
+    store.append_events(sid, events)   # 0회 이상, 임의 배치 크기
+    store.finalize(sid, stats)
+
+backtest 는 ``append_events`` 를 한 번에 모든 이벤트로 호출하고, live 는
+EventBus 에 sink 를 붙여 이벤트마다(또는 배치 단위로) 호출한다.
+구현체는 호출자가 backtest 인지 live 인지 알 필요가 없다.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Protocol
+
+from pyqqq3.application.session import Session, SessionReport
+
+if TYPE_CHECKING:
+    from pyqqq3.model.execution.events import ExecutionEvent
+
+
+class StoreLevel(Enum):
+    """저장 레벨 — 스토어가 events 를 얼마나 보존할지 결정.
+
+    - FULL: 모든 ExecutionEvent (CashDeposited, OrderSubmitted, OrderRejected,
+      FillExecuted, RiskTriggered) 를 그대로 저장.
+    - FILLED: 체결 이벤트만 (FillExecuted, RiskTriggered) 저장. MVP 웹 뷰가
+      필요로 하는 최소 페이로드. 초기 자본은 ``Session.engine_config.capital``
+      에 이미 들어 있어 별도 보존이 필요 없다.
+    """
+
+    FULL = "full"
+    FILLED = "filled"
+
+
+def filter_events(
+    events: "list[ExecutionEvent] | None",
+    level: StoreLevel,
+) -> "list[ExecutionEvent]":
+    """level 정책에 따라 events 를 필터링. None 은 빈 리스트로 정규화."""
+    from pyqqq3.model.execution.events import FillExecuted, RiskTriggered
+
+    if not events:
+        return []
+    if level is StoreLevel.FULL:
+        return list(events)
+    return [e for e in events if isinstance(e, (FillExecuted, RiskTriggered))]
+
+
+class SessionStore(Protocol):
+    """운용 정의·통계·이벤트 로그를 저장하고 조회하는 인터페이스.
+
+    write-only 싱크(파일)는 start/append_events/finalize 만 구현하고
+    load/list/delete 는 NotImplementedError 를 올린다.
+    """
+
+    def start(self, session: Session) -> str:
+        """session 을 시작 상태로 저장하고 session_id 반환. 동일 id 재호출 시
+        prior events 는 idempotent 하게 초기화된다."""
+        ...
+
+    def append_events(
+        self, session_id: str, events: "list[ExecutionEvent]"
+    ) -> None:
+        """events 를 append. 빈 리스트는 no-op. 호출자는 임의 배치 크기로
+        여러 번 호출할 수 있다. 구현체는 ``StoreLevel`` 에 따라 내부적으로
+        필터링한다."""
+        ...
+
+    def finalize(self, session_id: str, stats: dict[str, float]) -> None:
+        """stats 를 갱신해 session 을 종료 상태로 마감."""
+        ...
+
+    def load(self, session_id: str) -> tuple[Session, dict[str, float]]:
+        """session_id 로 (session, stats) 튜플 반환."""
+        ...
+
+    def list(self, limit: int = 100) -> list[SessionReport]:
+        """최근 session 목록 반환."""
+        ...
+
+    def delete(self, session_id: str) -> None:
+        """session 삭제."""
+        ...

pyqqq3/auth.py

@@ -0,0 +1,28 @@
+"""API 키 노출 및 검증.
+
+pyqqq 의 키 해석 정책(메모리 → env → ~/.qred)을 그대로 따른다.
+사용자는 pyqqq import 없이 ``pyqqq3.set_api_key`` 만으로 키를 주입할 수 있다.
+"""
+
+from __future__ import annotations
+
+import pyqqq
+
+set_api_key = pyqqq.set_api_key
+get_api_key = pyqqq.get_api_key
+
+
+def ensure_api_key() -> None:
+    """외부 pyqqq API 호출 직전 키가 해석 가능한지 확인한다.
+
+    Raises:
+        RuntimeError: ``pyqqq.get_api_key()`` 가 None 인 경우.
+    """
+    if pyqqq.get_api_key() is None:
+        raise RuntimeError(
+            "PYQQQ_API_KEY 가 설정되지 않았습니다. 다음 중 하나를 사용하세요:\n"
+            "  1) 프로젝트 루트의 .env 파일에 PYQQQ_API_KEY=... 작성\n"
+            "  2) 환경변수 PYQQQ_API_KEY 설정\n"
+            "  3) pyqqq3.set_api_key('...') 호출\n"
+            "  4) ~/.qred 파일에 키 저장"
+        )