pyqqq-script 0.0.1__tar.gz → 0.0.2__tar.gz

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyqqq-script
-Version: 0.0.1
+Version: 0.0.2
 Summary: Pine Script-style trading library built on top of pyqqq
 License: MIT
 Author: PyQQQ team
@@ -23,27 +23,25 @@ Description-Content-Type: text/markdown
 **"우리는 누구나 자신의 투자 아이디어를 현실로 만들 수 있다고 믿습니다."**
 
 
-## 사전 준비
+## 환경설정
 
-먼저 PyQQQ 플랫폼에 회원가입 후 API Key를 발급받아야 합니다. 자세한 절차는 공식 가이드를 https://docs.pyqqq.net/getting_started/install.html 참고하세요.
-
-발급받은 API Key는 환경 변수로 설정해 사용합니다.
+### 1.1 설치
 
 ```bash
-export PYQQQ_API_KEY="발급받은_API_KEY"
+pip install pyqqq-script
 ```
 
+### 1.2 API Key 발급
 
-## 설치
+[PyQQQ](pyqqq.net)는 금융 데이터 분석과 자동화된 거래 전략을 제공하는 플랫폼입니다. 회원가입 후 API Key 를 발급받아 환경변수를 설정합니다. 보다 자세한 안내는 [공식 가이드](https://docs.pyqqq.net/getting_started/install.html) 문서를 참고하세요.
 
 ```bash
-pip install pyqqq-script
+export PYQQQ_API_KEY="발급받은_API_KEY"
 ```
 
-
 ## Quick Start
 
-아래는 PyQQQ Script의 기본 사용 흐름을 보여주는 간단한 예제입니다. `Strategy`를 상속받아 `next()`에서 매매 로직을 작성하고, `Backtest`로 실행한 뒤 결과를 출력하는 흐름입니다.
+몇 줄의 코드로 동작하는 백테스트 코드를 보여드리겠습니다.
 
 ```python
 from pyqqq3 import Backtest, Strategy, ta
@@ -51,6 +49,7 @@ 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)
@@ -65,11 +64,4 @@ bt = Backtest(strategy=Simple, symbol="005930", start="2026-04-01", end="2026-04
 print_result(bt.run())
 ```
 
-> 실제로 동작하는 전략들은 `examples/` 디렉터리를 참고하세요.
-
-실행:
-
-```bash
-python examples/mean_reversion_rsi_bb.py
-```
 

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/README.md

@@ -4,27 +4,25 @@
 **"우리는 누구나 자신의 투자 아이디어를 현실로 만들 수 있다고 믿습니다."**
 
 
-## 사전 준비
+## 환경설정
 
-먼저 PyQQQ 플랫폼에 회원가입 후 API Key를 발급받아야 합니다. 자세한 절차는 공식 가이드를 https://docs.pyqqq.net/getting_started/install.html 참고하세요.
-
-발급받은 API Key는 환경 변수로 설정해 사용합니다.
+### 1.1 설치
 
 ```bash
-export PYQQQ_API_KEY="발급받은_API_KEY"
+pip install pyqqq-script
 ```
 
+### 1.2 API Key 발급
 
-## 설치
+[PyQQQ](pyqqq.net)는 금융 데이터 분석과 자동화된 거래 전략을 제공하는 플랫폼입니다. 회원가입 후 API Key 를 발급받아 환경변수를 설정합니다. 보다 자세한 안내는 [공식 가이드](https://docs.pyqqq.net/getting_started/install.html) 문서를 참고하세요.
 
 ```bash
-pip install pyqqq-script
+export PYQQQ_API_KEY="발급받은_API_KEY"
 ```
 
-
 ## Quick Start
 
-아래는 PyQQQ Script의 기본 사용 흐름을 보여주는 간단한 예제입니다. `Strategy`를 상속받아 `next()`에서 매매 로직을 작성하고, `Backtest`로 실행한 뒤 결과를 출력하는 흐름입니다.
+몇 줄의 코드로 동작하는 백테스트 코드를 보여드리겠습니다.
 
 ```python
 from pyqqq3 import Backtest, Strategy, ta
@@ -32,6 +30,7 @@ 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)
@@ -46,10 +45,3 @@ bt = Backtest(strategy=Simple, symbol="005930", start="2026-04-01", end="2026-04
 print_result(bt.run())
 ```
 
-> 실제로 동작하는 전략들은 `examples/` 디렉터리를 참고하세요.
-
-실행:
-
-```bash
-python examples/mean_reversion_rsi_bb.py
-```

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pyqqq-script"
-version = "0.0.1"
+version = "0.0.2"
 description = "Pine Script-style trading library built on top of pyqqq"
 authors = ["PyQQQ team <pyqqq.cs@gmail.com>"]
 readme = "README.md"
@@ -22,6 +22,10 @@ ta = ">=0.11"
 ruff = ">=0.6"
 mongomock = ">=4.1"
 
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = ">=9.5"
+mkdocstrings = { version = ">=0.26", extras = ["python"] }
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/application/backtest.py

@@ -1,6 +1,6 @@
 """Backtest — 과거 데이터 시뮬레이션 파사드.
 
-HistoricalDataFeed + MockBroker + TradingEngine 을 조립한다.
+HistoricalDataFeed + MockBroker + TradingEngine 을 조립합니다.
 """
 
 from __future__ import annotations
@@ -29,7 +29,7 @@ if TYPE_CHECKING:
 
 
 class Backtest:
-    """과거 OHLCV DataFrame 으로 전략을 시뮬레이션한다.
+    """과거 OHLCV DataFrame 으로 전략을 시뮬레이션합니다.
 
     두 가지 모드:
     1. DataFrame 직접 제공 (테스트용):
@@ -39,10 +39,10 @@ class Backtest:
         bt = Backtest(strategy=RSI_BB, symbol="005930",
                       start="2025-01-01", end="2025-12-31", capital=10_000_000)
 
-    ``symbol`` 이 주어지면 ``symbol_repo`` 를 통해 즉시 메타데이터를 하이드레이트한다.
-    종목이 존재하지 않으면 ``SymbolNotFound`` 가 발생한다.
+    ``symbol`` 이 주어지면 ``symbol_repo`` 를 통해 즉시 메타데이터를 하이드레이트합니다.
+    종목이 존재하지 않으면 ``SymbolNotFound`` 가 발생합니다.
 
-    session_store 를 지정하면 운용 이력을 기록한다:
+    session_store 를 지정하면 운용 이력을 기록합니다:
         from pyqqq3.infra.store.file import FileStore
         bt = Backtest(..., session_store=FileStore())
     """
@@ -173,12 +173,12 @@ _FRAMEWORK_ATTRS = frozenset(
 
 
 def _extract_strategy_params(strategy: "Strategy") -> dict:
-    """전략 인스턴스에서 직렬화 가능한 파라미터를 추출한다.
+    """전략 인스턴스에서 직렬화 가능한 파라미터를 추출합니다.
 
     클래스 레벨 변수와 ``init()`` 안에서 ``self.X = ...`` 로 선언한 인스턴스 변수를
-    모두 포함한다. 같은 이름이 양쪽에 있으면 인스턴스 값이 우선한다 (Python 속성
+    모두 포함합니다. 같은 이름이 양쪽에 있으면 인스턴스 값이 우선합니다 (Python 속성
     lookup 과 동일). 엔진이 주입하는 framework 속성(open/high/low/close/volume,
-    bar_index, time, is_last_bar)과 underscore-prefixed 내부 속성은 제외한다.
+    bar_index, time, is_last_bar)과 underscore-prefixed 내부 속성은 제외합니다.
     """
     try:
         params: dict = {}

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/application/live.py

@@ -1,14 +1,14 @@
 """LiveTrading — 실시간 트레이딩 파사드.
 
-Backtest 와 동일한 조립 구조를 쓴다:
+Backtest 와 동일한 조립 구조를 씁니다:
     DataFeed + Broker + EventBus + Account + ExecutionJournal → TradingEngine
 
-차이는 Broker/DataFeed 의 구현체뿐이다 (KISDomesticBroker + RealtimeDataFeed).
-이 파일은 DI 배선과 lifecycle 만 담당한다.
+차이는 Broker/DataFeed 의 구현체뿐입니다 (KISDomesticBroker + RealtimeDataFeed).
+이 파일은 DI 배선과 lifecycle 만 담당합니다.
 
 session_store 가 주입되면 EventBus 에 streaming sink 를 붙여 이벤트가
-발생하는 즉시 store 로 흘려보낸다 — 프로세스가 중간에 죽어도 그 시점까지의
-체결 이력이 보존된다.
+발생하는 즉시 store 로 흘려보냅니다 — 프로세스가 중간에 죽어도 그 시점까지의
+체결 이력이 보존됩니다.
 """
 
 from __future__ import annotations
@@ -37,20 +37,20 @@ if TYPE_CHECKING:
 class LiveTrading:
     """실시간 트레이딩 파사드.
 
-    브로커와 데이터 피드는 호출자가 직접 주입한다. 브로커는 외부 거래소로부터
-    수신한 체결/거부 이벤트를 ``event_sink`` 로 발행해야 한다 (Broker 규약).
-    LiveTrading 은 EventBus 를 통해 이를 Journal + Account 로 fan-out 한다.
+    브로커와 데이터 피드는 호출자가 직접 주입합니다. 브로커는 외부 거래소로부터
+    수신한 체결/거부 이벤트를 ``event_sink`` 로 발행해야 합니다 (Broker 규약).
+    LiveTrading 은 EventBus 를 통해 이를 Journal + Account 로 fan-out 합니다.
 
-    종목은 진입 시점에 ``symbol_repo.require()`` 로 즉시 검증·하이드레이트한다.
-    존재하지 않는 종목 코드는 ``SymbolNotFound`` 로 거부된다.
+    종목은 진입 시점에 ``symbol_repo.require()`` 로 즉시 검증·하이드레이트합니다.
+    존재하지 않는 종목 코드는 ``SymbolNotFound`` 로 거부됩니다.
 
     Args:
         strategy: Strategy 서브클래스 타입.
         data_feed: 실시간 DataFeed 구현체.
         broker_factory: ``event_sink`` 를 받아 Broker 를 반환하는 팩토리.
-        symbol: 거래 종목 코드 (raw str). 즉시 ``Symbol`` 로 하이드레이트된다.
+        symbol: 거래 종목 코드 (raw str). 즉시 ``Symbol`` 로 하이드레이트됩니다.
         symbol_repo: 종목 메타데이터 조회용 Repository. 미주입 시
-            ``DomesticRepository`` 가 사용된다.
+            ``DomesticRepository`` 가 사용됩니다.
         session_store: 운용 이력 저장소 (선택).
     """
 
@@ -97,7 +97,7 @@ class LiveTrading:
 
         session_id = new_session_id()
         # broker 생성 시 CashDeposited 가 emit 되므로 session start 와 sink 구독은
-        # broker_factory 호출 *전*에 끝나야 한다.
+        # broker_factory 호출 *전*에 끝나야 합니다.
         session = Session(
             session_id=session_id,
             kind="live",

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/application/messaging/bus.py

@@ -1,7 +1,7 @@
 """EventBus — 동기 in-process fanout.
 
 브로커가 publish 한 ExecutionEvent 를 구독자(journal, Account 등)에게
-순차적으로 전달한다. Phase 1 단계에서는 단일 스레드, 동기 실행을 가정한다.
+순차적으로 전달합니다. Phase 1 단계에서는 단일 스레드, 동기 실행을 가정합니다.
 """
 
 from __future__ import annotations
@@ -16,8 +16,8 @@ EventHandler = Callable[[ExecutionEvent], None]
 class EventBus:
     """동기 이벤트 fanout.
 
-    한 번에 하나의 이벤트를 등록된 모든 핸들러에게 순차 전달한다.
-    구독자 등록 순서대로 실행되며, 한 핸들러 예외가 다음 핸들러 실행을 막는다
+    한 번에 하나의 이벤트를 등록된 모든 핸들러에게 순차 전달합니다.
+    구독자 등록 순서대로 실행되며, 한 핸들러 예외가 다음 핸들러 실행을 막습니다
     (journal / Account 의 일관성 확보를 위해 의도된 동작).
 
     Usage:

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/application/session.py

@@ -2,11 +2,11 @@
 
 도메인 라이프사이클 ``Strategy → Session → SessionReport`` 의 가운데 단계로,
 backtest/paper/live 를 아우르는 운용 인스턴스의 식별자·전략·심볼·기간·엔진설정을
-담는 경계 DTO 다. ``SessionStore`` 가 이 타입들을 키로 영속화한다.
+담는 경계 DTO 다. ``SessionStore`` 가 이 타입들을 키로 영속화합니다.
 
 심볼은 ``Symbol`` 객체로 보유하며, 영속화 어댑터(MongoStore/FileStore)는
 직렬화 시 ``str(symbol.code)`` 로 변환하고 역직렬화 시 ``SymbolRepository`` 로
-하이드레이트한다.
+하이드레이트합니다.
 """
 
 from __future__ import annotations

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/application/store.py

@@ -1,14 +1,14 @@
 """SessionStore — 운용 단위 저장/조회 인터페이스 (application 포트).
 
-저장은 stream API 로 통일되어 있다 — backtest 든 live 든 호출 패턴은 같다:
+저장은 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 인지 알 필요가 없다.
+EventBus 에 sink 를 붙여 이벤트마다(또는 배치 단위로) 호출합니다.
+구현체는 호출자가 backtest 인지 live 인지 알 필요가 없습니다.
 """
 
 from __future__ import annotations
@@ -29,7 +29,7 @@ class StoreLevel(Enum):
       FillExecuted, RiskTriggered) 를 그대로 저장.
     - FILLED: 체결 이벤트만 (FillExecuted, RiskTriggered) 저장. MVP 웹 뷰가
       필요로 하는 최소 페이로드. 초기 자본은 ``Session.engine_config.capital``
-      에 이미 들어 있어 별도 보존이 필요 없다.
+      에 이미 들어 있어 별도 보존이 필요 없습니다.
     """
 
     FULL = "full"
@@ -54,20 +54,20 @@ class SessionStore(Protocol):
     """운용 정의·통계·이벤트 로그를 저장하고 조회하는 인터페이스.
 
     write-only 싱크(파일)는 start/append_events/finalize 만 구현하고
-    load/list/delete 는 NotImplementedError 를 올린다.
+    load/list/delete 는 NotImplementedError 를 올립니다.
     """
 
     def start(self, session: Session) -> str:
         """session 을 시작 상태로 저장하고 session_id 반환. 동일 id 재호출 시
-        prior events 는 idempotent 하게 초기화된다."""
+        prior events 는 idempotent 하게 초기화됩니다."""
         ...
 
     def append_events(
         self, session_id: str, events: "list[ExecutionEvent]"
     ) -> None:
         """events 를 append. 빈 리스트는 no-op. 호출자는 임의 배치 크기로
-        여러 번 호출할 수 있다. 구현체는 ``StoreLevel`` 에 따라 내부적으로
-        필터링한다."""
+        여러 번 호출할 수 있습니다. 구현체는 ``StoreLevel`` 에 따라 내부적으로
+        필터링합니다."""
         ...
 
     def finalize(self, session_id: str, stats: dict[str, float]) -> None:

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/auth.py

@@ -1,7 +1,7 @@
 """API 키 노출 및 검증.
 
-pyqqq 의 키 해석 정책(메모리 → env → ~/.qred)을 그대로 따른다.
-사용자는 pyqqq import 없이 ``pyqqq3.set_api_key`` 만으로 키를 주입할 수 있다.
+pyqqq 의 키 해석 정책(메모리 → env → ~/.qred)을 그대로 따릅니다.
+사용자는 pyqqq import 없이 ``pyqqq3.set_api_key`` 만으로 키를 주입할 수 있습니다.
 """
 
 from __future__ import annotations
@@ -13,7 +13,7 @@ get_api_key = pyqqq.get_api_key
 
 
 def ensure_api_key() -> None:
-    """외부 pyqqq API 호출 직전 키가 해석 가능한지 확인한다.
+    """외부 pyqqq API 호출 직전 키가 해석 가능한지 확인합니다.
 
     Raises:
         RuntimeError: ``pyqqq.get_api_key()`` 가 None 인 경우.

{pyqqq_script-0.0.1 → pyqqq_script-0.0.2}/pyqqq3/infra/broker/kis.py

@@ -1,8 +1,8 @@
 """KISDomesticBroker — 한국투자증권 REST/Websocket 어댑터 (스켈레톤).
 
-실제 API 연동은 추후 작성한다. 이 파일은 Broker 계약 형태와
+실제 API 연동은 추후 작성합니다. 이 파일은 Broker 계약 형태와
 이벤트 발행 헬퍼만 제공해 LiveTrading 이 Backtest 와 동일한 구조로
-조립될 수 있음을 보여준다.
+조립될 수 있음을 보여줍니다.
 
 외부로 나가는 것 (이 어댑터의 책임):
     buy/sell/cancel → KIS REST 주문 API
@@ -55,7 +55,7 @@ class KISDomesticBroker:
     # ------------------------------------------------------------------ Broker interface
 
     def process(self, bar: Bar) -> None:
-        """실시간 모드에서는 no-op. 체결은 외부 이벤트로 들어온다."""
+        """실시간 모드에서는 no-op. 체결은 외부 이벤트로 들어옵니다."""
         # 향후: 봉 단위 리스크 체크가 필요하면 여기에. 단, 실제 손절/익절 주문은
         # 거래소에 미리 걸어두거나(OCO), websocket 에서 판단.