pyqqq-script 0.0.1__tar.gz

pyqqq_script-0.0.1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.1
+Name: pyqqq-script
+Version: 0.0.1
+Summary: Pine Script-style trading library built on top of pyqqq
+License: MIT
+Author: PyQQQ team
+Author-email: pyqqq.cs@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: numpy (>=1.24)
+Requires-Dist: pandas (>=2.0)
+Requires-Dist: pymongo (>=4.6)
+Requires-Dist: pyqqq (>=0.12.233)
+Project-URL: Documentation, https://docs.pyqqq.net
+Description-Content-Type: text/markdown
+
+
+# PyQQQ Script
+
+**"우리는 누구나 자신의 투자 아이디어를 현실로 만들 수 있다고 믿습니다."**
+
+
+## 사전 준비
+
+먼저 PyQQQ 플랫폼에 회원가입 후 API Key를 발급받아야 합니다. 자세한 절차는 공식 가이드를 https://docs.pyqqq.net/getting_started/install.html 참고하세요.
+
+발급받은 API Key는 환경 변수로 설정해 사용합니다.
+
+```bash
+export PYQQQ_API_KEY="발급받은_API_KEY"
+```
+
+
+## 설치
+
+```bash
+pip install pyqqq-script
+```
+
+
+## Quick Start
+
+아래는 PyQQQ Script의 기본 사용 흐름을 보여주는 간단한 예제입니다. `Strategy`를 상속받아 `next()`에서 매매 로직을 작성하고, `Backtest`로 실행한 뒤 결과를 출력하는 흐름입니다.
+
+```python
+from pyqqq3 import Backtest, Strategy, ta
+from pyqqq3.infra.presentation import print_result
+
+
+class Simple(Strategy):
+    def next(self):
+        sma5 = ta.sma(self.close, 5)
+        sma20 = ta.sma(self.close, 20)
+
+        if sma5 > sma20 and self.position.size == 0:
+            self.buy(amount=1_000_000)
+        elif sma5 < sma20 and self.position.size > 0:
+            self.sell()
+
+
+bt = Backtest(strategy=Simple, symbol="005930", start="2026-04-01", end="2026-04-07")
+print_result(bt.run())
+```
+
+> 실제로 동작하는 전략들은 `examples/` 디렉터리를 참고하세요.
+
+실행:
+
+```bash
+python examples/mean_reversion_rsi_bb.py
+```
+

pyqqq_script-0.0.1/README.md

@@ -0,0 +1,55 @@
+
+# PyQQQ Script
+
+**"우리는 누구나 자신의 투자 아이디어를 현실로 만들 수 있다고 믿습니다."**
+
+
+## 사전 준비
+
+먼저 PyQQQ 플랫폼에 회원가입 후 API Key를 발급받아야 합니다. 자세한 절차는 공식 가이드를 https://docs.pyqqq.net/getting_started/install.html 참고하세요.
+
+발급받은 API Key는 환경 변수로 설정해 사용합니다.
+
+```bash
+export PYQQQ_API_KEY="발급받은_API_KEY"
+```
+
+
+## 설치
+
+```bash
+pip install pyqqq-script
+```
+
+
+## Quick Start
+
+아래는 PyQQQ Script의 기본 사용 흐름을 보여주는 간단한 예제입니다. `Strategy`를 상속받아 `next()`에서 매매 로직을 작성하고, `Backtest`로 실행한 뒤 결과를 출력하는 흐름입니다.
+
+```python
+from pyqqq3 import Backtest, Strategy, ta
+from pyqqq3.infra.presentation import print_result
+
+
+class Simple(Strategy):
+    def next(self):
+        sma5 = ta.sma(self.close, 5)
+        sma20 = ta.sma(self.close, 20)
+
+        if sma5 > sma20 and self.position.size == 0:
+            self.buy(amount=1_000_000)
+        elif sma5 < sma20 and self.position.size > 0:
+            self.sell()
+
+
+bt = Backtest(strategy=Simple, symbol="005930", start="2026-04-01", end="2026-04-07")
+print_result(bt.run())
+```
+
+> 실제로 동작하는 전략들은 `examples/` 디렉터리를 참고하세요.
+
+실행:
+
+```bash
+python examples/mean_reversion_rsi_bb.py
+```

pyqqq_script-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[tool.poetry]
+name = "pyqqq-script"
+version = "0.0.1"
+description = "Pine Script-style trading library built on top of pyqqq"
+authors = ["PyQQQ team <pyqqq.cs@gmail.com>"]
+readme = "README.md"
+packages = [{include = "pyqqq3"}]
+license = "MIT"
+documentation = "https://docs.pyqqq.net"
+
+[tool.poetry.dependencies]
+python = ">=3.11,<4.0"
+pandas = ">=2.0"
+numpy = ">=1.24"
+pymongo = ">=4.6"
+pyqqq = ">=0.12.233"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+pytest-cov = ">=4.1"
+ta = ">=0.11"
+ruff = ">=0.6"
+mongomock = ">=4.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I"]
+ignore = ["E203"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["F401"]

pyqqq_script-0.0.1/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",
+]

pyqqq_script-0.0.1/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

pyqqq_script-0.0.1/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

pyqqq_script-0.0.1/pyqqq3/application/messaging/__init__.py

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

pyqqq_script-0.0.1/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)

pyqqq_script-0.0.1/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]}"