programgarden-core 0.1.0__tar.gz

programgarden_core-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.3
+Name: programgarden-core
+Version: 0.1.0
+Summary: 자동화매매 클래스 상속, 로그, 환경 등의 핵심이되는 오픈소스
+Author: 프로그램동산
+Author-email: coding@programgarden.com
+Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+

programgarden_core-0.1.0/programgarden_core/__init__.py

@@ -0,0 +1,76 @@
+"""
+핵심 기능 모듈
+
+LS OpenAPI 클라이언트의 핵심 기능을 제공합니다.
+"""
+
+from .bases import (
+    SystemType, StrategyConditionType,
+    StrategyType, SystemSettingType,
+    DictConditionType,
+    SecuritiesAccountType,
+
+    ExecutionTimingType,
+    BaseCondition,
+
+    BaseBuyOverseasStock,
+    BaseSellOverseasStock,
+
+    BaseConditionResponseType,
+    BaseBuyOverseasStockResponseType,
+    BaseSellOverseasStockResponseType,
+
+    SymbolInfo,
+    HeldSymbol,
+    NonTradedSymbol,
+
+    NewBuyTradeType,
+    NewSellTradeType,
+    OrdersType,
+    OrderTimeType,
+    OrderCategoryType,
+)
+from .korea_alias import EnforceKoreanAliasMeta, require_korean_alias
+from . import logs, exceptions
+from .logs import pg_log_disable, pg_log_reset, pg_logger, pg_log
+
+
+__all__ = [
+    logs,
+    exceptions,
+
+    pg_logger,
+    pg_log,
+    pg_log_disable,
+    pg_log_reset,
+
+
+    require_korean_alias,
+    EnforceKoreanAliasMeta,
+
+    SecuritiesAccountType,
+    StrategyConditionType,
+    StrategyType,
+    DictConditionType,
+    SystemSettingType,
+    ExecutionTimingType,
+    SystemType,
+
+    BaseCondition,
+    BaseBuyOverseasStock,
+    BaseSellOverseasStock,
+
+    BaseConditionResponseType,
+    BaseBuyOverseasStockResponseType,
+    BaseSellOverseasStockResponseType,
+
+    SymbolInfo,
+    HeldSymbol,
+    NonTradedSymbol,
+
+    NewBuyTradeType,
+    NewSellTradeType,
+    OrdersType,
+    OrderTimeType,
+    OrderCategoryType,
+]

programgarden_core-0.1.0/programgarden_core/bases/__init__.py

@@ -0,0 +1,61 @@
+from .system import (
+    SystemType,
+    SystemSettingType,
+
+    StrategyType,
+    SecuritiesAccountType,
+    StrategyConditionType,
+    DictConditionType,
+
+    ExecutionTimingType,
+
+    NewBuyTradeType,
+    NewSellTradeType,
+    OrdersType,
+    OrderTimeType,
+)
+
+from .community import (
+    BaseCondition,
+    BaseBuyOverseasStock,
+    BaseSellOverseasStock,
+
+    BaseConditionResponseType,
+    BaseBuyOverseasStockResponseType,
+    BaseSellOverseasStockResponseType,
+
+    SymbolInfo,
+    HeldSymbol,
+    NonTradedSymbol,
+    OrderCategoryType,
+)
+
+
+__all__ = [
+    SystemType,
+    StrategyType,
+
+    BaseCondition,
+    BaseBuyOverseasStock,
+    BaseSellOverseasStock,
+
+    SecuritiesAccountType,
+    StrategyConditionType,
+    DictConditionType,
+    BaseConditionResponseType,
+    BaseBuyOverseasStockResponseType,
+    BaseSellOverseasStockResponseType,
+
+    SystemSettingType,
+    ExecutionTimingType,
+
+    SymbolInfo,
+    HeldSymbol,
+    NonTradedSymbol,
+
+    NewBuyTradeType,
+    NewSellTradeType,
+    OrderTimeType,
+    OrdersType,
+    OrderCategoryType,
+]

programgarden_core-0.1.0/programgarden_core/bases/community.py

@@ -0,0 +1,324 @@
+from abc import ABC, abstractmethod
+from typing import List, Literal, Optional, TypedDict, Any, Dict, TypeVar, Generic
+
+OrderCategoryType = Literal["submitted_new_buy", "submitted_new_sell",
+                            "filled_new_buy", "filled_new_sell",
+                            "cancel_request_buy", "cancel_request_sell",
+                            "modify_buy", "modify_sell", "cancel_complete_buy", "cancel_complete_sell",
+                            "reject_buy", "reject_sell"]
+"""
+- submitted_new_buy: 신규 매수 접수
+- submitted_new_sell: 신규 매도 접수
+- filled_new_buy: 신규 매수 체결
+- filled_new_sell: 신규 매도 체결
+- cancel_request_buy: 매수 취소 접수
+- cancel_request_sell: 매도 취소 접수
+- modify_buy: 매수 정정 접수
+- modify_sell: 매도 정정 접수
+- cancel_complete_buy: 매수 취소 완료
+- cancel_complete_sell: 매도 취소 완료
+- reject_buy: 매수 주문 거부
+- reject_sell: 매도 주문 거부
+"""
+
+
+class SymbolInfo(TypedDict):
+    """
+    종목 정보를 담기 위한 타입
+
+    Args
+    ----------
+    symbol: str
+        종목 코드
+    exchcd: Literal["81", "82"]
+        거래소 코드
+    """
+    symbol: str
+    """종목 코드"""
+    exchcd: Literal["81", "82"]
+    """
+    거래소 코드
+    82: NASDAQ
+    81: 뉴욕증권거래소
+    """
+    mcap: Optional[float] = None
+    """시가총액 (단위: 백만 달러)"""
+
+
+class HeldSymbol(TypedDict):
+    """
+    주문해서 보유중인 종목들
+    """
+    CrcyCode: str
+    """통화코드"""
+    ShtnIsuNo: str
+    """단축종목번호"""
+    AstkBalQty: float
+    """해외증권잔고수량"""
+    AstkSellAbleQty: float
+    """해외증권매도가능수량"""
+    PnlRat: float
+    """손익율"""
+    BaseXchrat: float
+    """기준환율"""
+    PchsAmt: float
+    """매입금액"""
+    FcurrMktCode: str
+    """외화시장코드"""
+
+
+class NonTradedSymbol(TypedDict):
+    """
+    미체결 종목
+    """
+    OrdTime: str
+    """주문시각"""
+    OrdNo: int
+    """주문번호"""
+    OrgOrdNo: int
+    """원주문번호"""
+    ShtnIsuNo: str
+    """단축종목번호"""
+    MrcAbleQty: int
+    """정정취소가능수량"""
+    OrdQty: int
+    """주문수량"""
+    OvrsOrdPrc: float
+    """해외주문가"""
+    OrdprcPtnCode: str
+    """호가유형코드"""
+    OrdPtnCode: str
+    """주문유형코드"""
+    MrcTpCode: str
+    """정정취소구분코드"""
+    OrdMktCode: str
+    """주문시장코드"""
+    UnercQty: int
+    """미체결수량"""
+    CnfQty: int
+    """확인수량"""
+    CrcyCode: str
+    """통화코드"""
+    RegMktCode: str
+    """등록시장코드"""
+    IsuNo: str
+    """종목번호"""
+    BnsTpCode: str
+    """매매구분코드"""
+
+
+class BaseCondition(ABC):
+    """
+    기본 전략의 조건 타입을 정의하는 추상 클래스입니다.
+    """
+
+    id: str
+    """전략의 고유 ID"""
+    description: str
+    """전략에 대한 설명"""
+    securities: List[str]
+    """사용 가능한 증권사/거래소들"""
+
+    @abstractmethod
+    def __init__(self, **kwargs):
+        self.symbol: Optional[SymbolInfo] = None
+
+    @abstractmethod
+    async def execute(self) -> 'BaseConditionResponseType':
+        """
+        전략을 실행하는 메서드입니다.
+        구체적인 전략 클래스에서 구현해야 합니다.
+        """
+        pass
+
+    def _set_system_id(self, system_id: Optional[str]) -> None:
+        """
+        시스템 고유 ID를 설정합니다.
+        """
+        self.system_id = system_id
+
+    def _set_symbol(self, symbol: SymbolInfo) -> None:
+        """
+        계산할 종목들을 선정합니다.
+        선정된 종목들 위주로 조건 충족 여부를 확인해서 반환해줍니다.
+        """
+        self.symbol = symbol
+
+
+class BaseConditionResponseType(TypedDict):
+    """기본 응답 데이터"""
+
+    condition_id: Optional[str]
+    """조건 ID"""
+    success: bool
+    """조건 통과한 종목이 1개라도 있으면 True로 처리합니다."""
+    symbol: str
+    """종목 코드"""
+    exchcd: str
+    """거래소 코드"""
+    data: Any
+    """조건 통과한 종목에 대한 추가 데이터"""
+    weight: Optional[int] = 0
+    """조건의 가중치는 0과 1사이의 값, 기본값은 0"""
+
+
+class BaseBuyOverseasStockResponseType(TypedDict):
+    """주문을 넣기 위한 반환값 데이터"""
+    success: bool
+    """전략 통과 성공 여부"""
+    ord_ptn_code: Literal["02"] = "02"
+    """주문유형코드 (02: 매수주문)"""
+    ord_mkt_code: Literal["81", "82"]
+    """주문시장코드 (81: 뉴욕거래소, 82: NASDAQ)"""
+    isu_no: str
+    """종목번호 (단축종목코드 ex.TSLA)"""
+    ord_qty: int
+    """주문수량"""
+    ovrs_ord_prc: float
+    """해외주문가"""
+    ordprc_ptn_code: Literal["00", "M1", "M2"]
+    """호가유형코드 (00: 지정가, M1: LOO, M2: LOC)"""
+
+
+class BaseSellOverseasStockResponseType(TypedDict):
+    """주문을 넣기 위한 반환값 데이터"""
+    success: bool
+    """전략 통과 성공 여부"""
+    ord_ptn_code: Literal["01"] = "01"
+    """주문유형코드 (01: 매도주문)"""
+    ord_mkt_code: Literal["81", "82"]
+    """주문시장코드 (81: 뉴욕거래소, 82: NASDAQ)"""
+    shtn_isu_no: str
+    """종목번호 (단축종목코드 ex.TSLA)"""
+    ord_qty: int
+    """주문수량"""
+    ovrs_ord_prc: float
+    """해외주문가"""
+    ordprc_ptn_code: Literal["00", "M1", "M2"]
+    """호가유형코드 (00: 지정가, M1: LOO, M2: LOC, 03@시장가, M3@MOO, M4@MOC)"""
+    crcy_code: Literal["USD"] = "USD"
+    """통화코드 (USD)"""
+    pnl_rat: float
+    """손익률"""
+    pchs_amt: float
+    """매입금액"""
+
+
+OrderResGenericT = TypeVar("OrderResGenericType", bound=Dict[str, Any])
+
+
+class BaseOrderOverseasStock(Generic[OrderResGenericT], ABC):
+    """
+    해외주식 매매 주문을 위한 기본 전략 클래스
+    """
+
+    id: str
+    """전략의 고유 ID"""
+    description: str
+    """전략에 대한 설명"""
+    securities: List[str]
+    """사용 가능한 증권사/거래소들"""
+
+    @abstractmethod
+    def __init__(
+        self,
+    ):
+        self.available_symbols = []
+
+    @abstractmethod
+    async def execute(self) -> 'List[OrderResGenericT]':
+        """
+        매수 전략을 실행하는 메서드입니다.
+        """
+        pass
+
+    def _set_system_id(self, system_id: Optional[str]) -> None:
+        """
+        시스템 고유 ID를 설정합니다.
+        """
+        self.system_id = system_id
+
+    def _set_available_symbols(self, symbols: List[SymbolInfo]) -> None:
+        """
+        매매 전략 계산에 사용하려는 종목들을 전달합니다.
+        """
+        self.available_symbols = symbols
+
+    def _set_held_symbols(self, symbols: List[HeldSymbol]) -> None:
+        """
+        현재 보유중인 종목들을 받습니다.
+        """
+        self.held_symbols = symbols
+
+    def _set_non_traded_symbols(self, symbols: List[NonTradedSymbol]) -> None:
+        """
+        현재 미체결 종목들을 받습니다.
+        """
+        self.non_traded_symbols = symbols
+
+    @abstractmethod
+    async def on_real_order_receive(self, order_type: OrderCategoryType, response: OrderResGenericT) -> None:
+        """
+        매매 주문 상태를 받습니다.
+        """
+        pass
+
+
+class BaseBuyOverseasStock(BaseOrderOverseasStock[BaseBuyOverseasStockResponseType]):
+    """
+    매수를 하기 위한 전략을 계산하고 매수를 위한 값을 던져줍니다.
+    """
+
+    @abstractmethod
+    def __init__(
+        self,
+    ):
+        super().__init__()
+
+        self.fcurr_dps = 0.0
+        self.fcurr_ord_able_amt = 0.0
+
+    def _set_available_balance(
+        self,
+        fcurr_dps: float,
+        fcurr_ord_able_amt: float
+    ) -> None:
+        """
+        사용 가능한 잔고를 설정합니다.
+
+        Args:
+            fcurr_dps (float): 외화 예금
+            fcurr_ord_able_amt (float): 외화 주문 가능 금액
+        """
+        self.fcurr_dps = fcurr_dps
+        self.fcurr_ord_able_amt = fcurr_ord_able_amt
+
+
+class BaseSellOverseasStock(BaseOrderOverseasStock[BaseSellOverseasStockResponseType]):
+    """
+    매도를 하기 위한 전략을 계산하고 매도를 위한 값을 던져줍니다.
+    """
+
+    id: str
+    """전략의 고유 ID"""
+    description: str
+    """전략에 대한 설명"""
+    securities_domains: List[str]
+    """사용 가능한 증권사/거래소들 주소"""
+
+    @abstractmethod
+    def __init__(
+        self,
+        **kwargs
+    ):
+        """
+        symbols: 종목 정보 리스트
+        """
+        self.symbols = []
+
+    @abstractmethod
+    async def on_real_order_receive(self, order_type: OrderCategoryType, response: Dict[str, Any]) -> None:
+        """
+        매매 주문 상태를 받습니다.
+        """
+        pass

programgarden_core-0.1.0/programgarden_core/bases/system.py

@@ -0,0 +1,273 @@
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+from .community import BaseCondition, SymbolInfo, BaseBuyOverseasStock, BaseSellOverseasStock
+
+
+ExecutionTimingType = Literal["once", "interval", "cron"]
+"""
+전략 반복 실행 여부입니다.
+- "once": 한번만 실행
+- "interval": 주기적으로 실행
+- "cron": 크론 표현식에 따라 실행
+"""
+
+LogicType = Literal["all", "any", "not", "xor", "at_least", "at_most", "exactly", "if_then", "weighted"]
+"""
+다음 설명과 같습니다.
+- "all": 모든 조건 만족 (AND)
+- "any": 하나 이상 조건 만족 (OR)
+- "not": 조건이 만족되지 않아야 함 (NOT)
+- "xor": 정확히 하나만 만족 (XOR)
+- "at_least": 최소 N개 조건 만족
+- "at_most": 최대 N개 조건 만족
+- "exactly": 정확히 N개 조건 만족
+- "if_then": 조건부 논리 (if-then)
+- "weighted": 가중치 기반 조건 (점수 시스템)
+```
+"""
+
+
+class StrategyConditionType(TypedDict):
+    """
+    기본 전략 타입을 정의하는 TypedDict입니다.
+    """
+
+    id: str
+    """전략의 고유 ID"""
+    description: Optional[str] = None
+    """전략에 대한 설명"""
+    logic: LogicType
+    """전략의 논리 연산자"""
+    threshold: Optional[int] = None
+    """전략의 임계값"""
+    conditions: List[Union['StrategyConditionType', BaseCondition]]
+    """실행할 전략 리스트"""
+
+
+class MaxSymbolsLimitType(TypedDict):
+    order: Literal["random", "mcap"]
+    """
+    종목 선택 방식
+    - random: 랜덤 선택
+    - mcap: 시가총액 상위 선택
+    """
+    limit: int
+    """선택할 종목 수"""
+
+
+class StrategyType(TypedDict):
+    timing: ExecutionTimingType
+    """전략 실행 타이밍"""
+    schedule: Optional[str] = None
+    """
+### 필드 순서
+- 5-필드: 분 시 일(날짜) 월 요일 → 5-필드는 seconds-first 영향 없음
+- 6-필드: 초 분 시 일(날짜) 월 요일
+- 7-필드: 초 분 시 일(날짜) 월 요일 연도
+
+<br>
+
+### 허용 값/연산자
+- 초/분: 0–59, 시: 0–23, 일: 1–31 또는 l(마지막 날), 월: 1–12 또는 jan–dec, 요일: 0–6 또는 sun–sat(0 또는 7=일요일), 연도: 1970–2099
+- 와일드카드: *
+- 범위/목록: A-B, A,B,C
+- 간격: A/B 또는 A-B/S (예: */5)
+- 요일 n번째: 요일#n (예: 2#3=셋째 화요일)
+- 요일 마지막: lX (예: l5=마지막 금요일)
+- 일(날짜) l: 해당 달의 마지막 날
+- 일(날짜)과 요일을 함께 쓰면 OR
+
+<br>
+
+### 6-필드 예시 (초 분 시 일 월 요일)
+- 매초: * * * * * *
+- 5초마다: */5 * * * * *
+- 매분 0초: 0 * * * * *
+- 15분마다(0초): 0 */15 * * * *
+- 매시 정각: 0 0 * * * *
+- 매일 09:30:00: 0 30 9 * * *
+- 매월 1일 09:00:00: 0 0 9 1 * *
+- 매월 마지막 날 18:00:00: 0 0 18 l * *
+- 매주 월요일 10:00:00: 0 0 10 * * mon
+- 평일 10:00:00: 0 0 10 * * mon-fri
+- 1·4·7월 10:00:00: 0 0 10 * jan,apr,jul *
+- 매월 셋째 화요일 10:00:00: 0 0 10 * * 2#3
+- 매월 마지막 금요일 18:00:00: 0 0 18 * * l5
+- 평일 9–18시 매시 정각: 0 0 9-18 * * mon-fri
+- 평일 9–18시 10분 간격(0초): 0 0/10 9-18 * * mon-fri
+- 매 시각 15·30·45분의 10초: 10 15,30,45 * * * *
+- 일요일 09:00:00: 0 0 9 * * 0,7
+
+<br>
+
+### 7-필드 예시 (초 분 시 일 월 요일 연도)
+- 2025년 동안 매초: * * * * * * 2025
+- 2025–2026년 매월 1일 00:00:00: 0 0 0 1 * * 2025-2026
+- 2025년 평일 09:00:00: 0 0 9 * * mon-fri 2025
+- 2025년 매월 마지막 날 18:30:05: 5 30 18 l * * 2025
+- 2025년 매월 셋째 화요일 10:00:00: 0 0 10 * * 2#3 2025
+- 2025–2030년 격년 1/1 00:00:00: 0 0 0 1 jan * 2025-2030/2
+
+<br>
+
+### 5-필드 예시 (분 시 일 월 요일, 항상 0초)
+- 매분: * * * * *
+- 5분마다: */5 * * * *
+- 평일 09:00: 0 9 * * mon-fri
+- 매월 마지막 날 18:00: 0 18 l * *
+- 매월 셋째 화요일 10:00: 0 10 * * 2#3
+
+<br>
+
+### 팁/주의
+- 5-필드는 초 필드가 없고 항상 0초입니다.
+- 일(날짜)과 요일을 같이 쓰면 OR입니다.
+- 일요일은 0 또는 7, 요일/월 이름은 대소문자 무관입니다.
+    - 허용 형태:
+        - 요일: sun, mon, tue, wed, thu, fri, sat 또는 숫자 0–6
+        - 일요일은 0 권장. 7은 일부 설정/버전에서 거부될 수 있으니 사용하지 않는 게 안전합니다.
+        - 월: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec 또는 숫자 1–12
+    - 예시:
+        - 0 0 10 * * Mon-Fri → 평일 10:00:00
+        - 0 0 9 * Jan,Apr,Jul * → 1·4·7월 09:00:00
+        - 0 0 9 * * sun → 일요일 09:00:00
+        - 0 0 9 * * 0 → 일요일 09:00:00 (권장 숫자 표기)
+- 연도 제한은 7-필드에서만 가능합니다(1970–2099).
+- 시간대는 strategies.timezone을 따릅니다.
+    """
+    timezone: Optional[str] = "Asia/Seoul"
+    id: str
+    """전략의 고유 ID"""
+    description: Optional[str] = None
+    """전략에 대한 설명"""
+    symbols: Optional[List[SymbolInfo]] = None
+    """분석할 종목들, 빈값이면 전체 종목에서 분석한다."""
+    logic: LogicType
+    """전략의 논리 연산자"""
+    threshold: Optional[int] = None
+    """전략의 임계값"""
+    order_id: Optional[str] = None
+    """
+    buy 또는 sell 영역에서 주문으로 사용될 order_id들을 선택한다.
+    """
+    max_symbols: Optional[MaxSymbolsLimitType]
+    """
+    전체 종목중에 몇개까지만 확인할지 지정한다. None이면 전체 종목을 다 확인한다.
+    """
+    conditions: List[Union['StrategyConditionType', 'DictConditionType', BaseCondition]]
+    """실행할 전략 리스트"""
+
+
+class DictConditionType(TypedDict):
+    """
+    DictConditionType은 문자열로 표현된 조건 타입입니다.
+    이 타입은 BaseCondition의 문자열 표현을 사용하여 조건을 정의합니다.
+    """
+    condition_id: str
+    """전략의 고유 ID"""
+    params: Optional[Dict[str, Any]]
+    """조건에 필요한 매개변수들"""
+    weight: Optional[int] = 0
+    """조건의 가중치, 기본값은 0"""
+
+
+class SystemSettingType(TypedDict):
+    """시스템 설정 정보"""
+    name: str
+    """시스템 이름"""
+    description: str
+    """시스템 설명"""
+    version: str
+    """시스템 버전"""
+    author: str
+    """시스템 작성자"""
+    date: str
+    """시스템 생성일"""
+    debug: str
+    """
+    디버그 모드 여부
+    "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL" 단계로 설정
+    """
+
+
+class SecuritiesAccountType(TypedDict):
+    """계좌와 증권사 및 상품 정보"""
+    company: Literal["ls"]
+    """증권사 이름"""
+    product: Literal["overseas_stock", "overseas_future"]
+    """상품 이름"""
+    appkey: Optional[str]
+    """앱 키"""
+    appsecretkey: Optional[str]
+    """앱 시크릿 키"""
+
+
+class OrderTimeType(TypedDict, total=False):
+    start: str
+    """시작 시간, HH:MM:SS 형식"""
+    end: str
+    """종료 시간, HH:MM:SS 형식"""
+    days: List[Literal["mon", "tue", "wed", "thu", "fri", "sat", "sun"]]
+    """주문 실행 요일, 예: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']"""
+    timezone: Optional[str]
+    """시간대, 예: 'Asia/Seoul'"""
+    behavior: Optional[Literal["defer", "skip"]]
+    """
+    - defer: 전략이 윈도우 밖에서 트리거되면 다음 윈도우 시작 시 주문을 실행(대기). 윈도우 안에서 트리거되면 즉시 실행.
+    - skip: 윈도우 밖에서 트리거되면 주문을 실행하지 않음(스킵). 윈도우 안에서는 즉시 실행.
+    """
+    max_delay_seconds: Optional[int] = 86400
+    """최대 지연 시간(초), 기본값 86400초(24시간)"""
+
+
+class NewBuyTradeType(TypedDict):
+    order_id: str
+    """매수 거래의 고유 ID"""
+    description: Optional[str]
+    """매수 거래에 대한 설명"""
+    block_duplicate_trade: bool
+    """중복거래 방지 여부, True:방지, False:허용"""
+    available_balance: Optional[float] = None
+    """빈 값으로 두면, securities에서 지정된 증권사 예수금으로 대체된다."""
+    condition: Optional[Union[DictConditionType, BaseBuyOverseasStock]]
+    """ 매수 전략 정보"""
+    order_time: Optional[OrderTimeType] = None
+    """주문 실행 시간 설정"""
+
+
+class NewSellTradeType(TypedDict):
+    order_id: str
+    """매도 거래의 고유 ID"""
+    description: Optional[str]
+    """매도 거래에 대한 설명"""
+    condition: Optional[Union[DictConditionType, BaseSellOverseasStock]]
+    """ 매도 전략 정보"""
+    order_time: Optional[OrderTimeType] = None
+    """주문 실행 시간 설정"""
+
+
+class OrdersType(TypedDict):
+    """
+    매수 또는 매도용 전략, 빈값이면 전략만 확인하는 용도
+    주식 new_buys, new_sells만 지원합니다.
+
+    선물옵션("shortbuy", "shortsell", "longbuy", "longsell") 거래는 준비중입니다.
+    """
+    new_buys: List[NewBuyTradeType]
+    """신규매수"""
+    new_sells: List[NewSellTradeType]
+    """신규매도"""
+
+
+class SystemType(TypedDict):
+    """자동화 시스템 데이터 타입"""
+    id: str
+    """시스템의 고유 ID"""
+    settings: SystemSettingType
+    """시스템 설정 정보"""
+    securities: SecuritiesAccountType
+    """증권사 인증 정보"""
+    strategies: List[StrategyType]
+    """시스템 실행 바디"""
+    orders: OrdersType
+    """주문 정보"""

programgarden_core-0.1.0/programgarden_core/exceptions.py

@@ -0,0 +1,135 @@
+"""
+커스텀 예외 클래스들
+"""
+
+
+class BasicException(Exception):
+    """오픈소스의 기본 에러 클래스"""
+
+    def __init__(
+        self,
+        message: str = "알 수 없는 오류가 발생했습니다.",
+        code: str = "UNKNOWN_ERROR",
+    ):
+        super().__init__(message, code)
+
+
+class AppKeyException(BasicException):
+    """앱키가 존재하지 않음"""
+
+    def __init__(
+        self,
+        message: str = "appkey 또는 secretkey가 존재하지 않습니다.",
+        code: str = "APPKEY_NOT_FOUND",
+    ):
+        super().__init__(message, code)
+
+
+class LoginException(BasicException):
+    """로그인 실패"""
+
+    def __init__(
+        self,
+        message: str = "로그인에 실패했습니다.",
+        code: str = "LOGIN_ERROR",
+    ):
+        super().__init__(message, code)
+
+
+class TokenException(BasicException):
+    """토큰 발급 실패"""
+
+    def __init__(
+        self,
+        message: str = "토큰 발급 실패했습니다.",
+        code: str = "TOKEN_ERROR",
+    ):
+        super().__init__(message, code)
+
+
+class TokenNotFoundException(BasicException):
+    """토큰이 존재하지 않음"""
+
+    def __init__(
+        self,
+        message: str = "토큰이 존재하지 않습니다.",
+        code: str = "TOKEN_NOT_FOUND",
+    ):
+        super().__init__(message, code)
+
+
+class TrRequestDataNotFoundException(BasicException):
+    """TR 요청 데이터가 존재하지 않음"""
+
+    def __init__(
+        self,
+        message: str = "TR 요청 데이터가 존재하지 않습니다.",
+        code: str = "TR_REQUEST_DATA_NOT_FOUND",
+    ):
+        super().__init__(message, code)
+
+
+class SystemException(BasicException):
+    """시스템 오류"""
+
+    def __init__(
+        self,
+        message: str = "시스템 오류가 발생했습니다.",
+        code: str = "SYSTEM_ERROR",
+    ):
+        super().__init__(message, code)
+
+
+class NotExistSystemException(SystemException):
+    """존재하지 않는 시스템"""
+
+    def __init__(
+        self,
+        message: str = "존재하지 않는 시스템입니다.",
+        code: str = "NOT_EXIST_SYSTEM",
+    ):
+        super().__init__(message, code)
+
+
+class NotExistSystemKeyException(SystemException):
+    """존재하지 않는 키"""
+
+    def __init__(
+        self,
+        message: str = "존재하지 않는 키입니다.",
+        code: str = "NOT_EXIST_KEY",
+    ):
+        super().__init__(message, code)
+
+
+class NotExistConditionException(SystemException):
+    """존재하지 않는 조건"""
+
+    def __init__(
+        self,
+        message: str = "존재하지 않는 조건입니다.",
+        code: str = "NOT_EXIST_CONDITION",
+    ):
+        super().__init__(message, code)
+
+
+class OrderException(SystemException):
+    """주문 관련 오류"""
+
+    def __init__(
+        self,
+        message: str = "주문 처리 중 오류가 발생했습니다.",
+        code: str = "ORDER_ERROR",
+    ):
+        super().__init__(message, code)
+
+
+class NotExistCompanyException(SystemException):
+    """존재하지 않는 증권사"""
+
+    def __init__(
+        self,
+        message: str = "증권사가 존재하지 않습니다.",
+        code: str = "NOT_EXIST_COMPANY",
+    ):
+        super().__init__(message, code)

programgarden_core-0.1.0/programgarden_core/korea_alias.py

@@ -0,0 +1,81 @@
+"""
+한글 별칭을 강제하기 위한 데코레이터와 메타클래스
+
+이 모듈은 함수에 한글 별칭이 필요한 경우 이를 강제하기 위한
+데코레이터와 메타클래스를 제공합니다.
+이 기능은 함수가 한글 별칭을 갖도록 보장하며, 이를 통해
+프로그램의 일관성을 유지합니다.
+
+사용방법은
+1. 함수에 `@require_korean_alias` 데코레이터를 적용합니다.
+2. 클래스에 `EnforceKoreanAliasMeta` 메타클래스를 적용합니다.
+이렇게 하면 해당 클래스의 모든 메서드가 한글 별칭을 갖도록 강제됩니다.
+
+예시:
+```python
+from programgarden_core.korean_alias import require_korean_alias, EnforceKoreanAliasMeta
+
+class OverseasStock(metaclass=EnforceKoreanAliasMeta):
+
+    @require_korean_alias
+    def accno(self) -> Accno:
+        return Accno()
+
+    계좌 = accno
+    계좌.__doc__ = "계좌 정보를 조회합니다."
+
+    ```
+
+이렇게 하면 `accno`는 한글 별칭을 반드시 가져야 합니다.
+만약 한글 별칭이 정의되지 않으면 `ValueError`가 발생합니다.
+"""
+
+from functools import wraps
+import inspect
+
+
+def require_korean_alias(func):
+    """한글 별칭이 필요한 함수임을 표시하는 데코레이터"""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    wrapper._requires_korean_alias = True
+    return wrapper
+
+
+class EnforceKoreanAliasMeta(type):
+    """한글 별칭 강제를 위한 메타클래스"""
+    def __new__(cls, name, bases, attrs):
+        korean_aliases = set()
+        # 한글 별칭 수집
+        for key, value in attrs.items():
+            if key.startswith('__') or not key.encode().isalnum() or key.isascii():
+                continue
+            korean_aliases.add(value.__name__ if callable(value) else key)
+
+        # @require_korean_alias가 붙은 메서드만 검사
+        for key, value in attrs.items():
+            if not inspect.isfunction(value) or key.startswith('__'):
+                continue
+
+            # 데코레이터가 붙은 경우에만 한글 별칭 검사
+            if getattr(value, '_requires_korean_alias', False):
+
+                has_korean_alias = False
+                for alias_key, alias_value in attrs.items():
+                    if (
+                        not alias_key.startswith('__')
+                        and not alias_key.isascii()
+                        and callable(alias_value)
+                        and alias_value.__name__ == value.__name__
+                    ):
+                        has_korean_alias = True
+                        break
+
+                if not has_korean_alias:
+                    raise ValueError(
+                        f"메서드 '{key}'는 @require_korean_alias 데코레이터가 적용되었으나 "
+                        "한글 별칭이 정의되지 않았습니다."
+                    )
+
+        return super().__new__(cls, name, bases, attrs)

programgarden_core-0.1.0/programgarden_core/logs.py

@@ -0,0 +1,88 @@
+import logging
+
+# ANSI 색상 코드
+LOG_COLORS = {
+    "INFO": "\033[92m",  # 초록색
+    "WARNING": "\033[93m",  # 노란색
+    "ERROR": "\033[91m",  # 빨간색
+    "CRITICAL": "\033[41m",  # 배경 빨간색
+    "RESET": "\033[0m",  # 색상 초기화
+}
+
+pg_logger = logging.getLogger("pg")
+
+
+class _ColoredFormatter(logging.Formatter):
+    """메시지를 제외한 모든 항목에 로그 레벨별 색상을 입히는 포매터"""
+
+    def format_time(self, record, datefmt=None):
+        # 원본 levelname을 사용 (format()에서 _orig_levelname에 저장)
+        orig_level = getattr(record, "_orig_levelname", record.levelname)
+        log_color = LOG_COLORS.get(orig_level, LOG_COLORS["RESET"])
+        t = super().formatTime(record, datefmt or "%Y-%m-%d %H:%M:%S")
+        return f"{log_color}{t}{LOG_COLORS['RESET']}"
+
+    def format(self, record):
+        # record의 원본 levelname을 저장 (나중에 formatTime에서 사용)
+        orig_levelname = record.levelname
+        record._orig_levelname = orig_levelname
+
+        # 원본 levelname을 바탕으로 색상 결정
+        color = LOG_COLORS.get(orig_levelname, LOG_COLORS["RESET"])
+        record.levelname = f"{color}{orig_levelname}{LOG_COLORS['RESET']}"
+        record.name = f"{color}{record.name}{LOG_COLORS['RESET']}"
+        record.filename = f"{color}{record.pathname}{LOG_COLORS['RESET']}"
+
+        # 숫자형 필드를 변경하지 않고, 새 필드에 색상 적용
+        record.colored_lineno = f"{color}{record.lineno}{LOG_COLORS['RESET']}"
+
+        return super().format(record)
+
+
+def pg_log(level=logging.DEBUG):
+    """
+    로그 레벨을 설정합니다.
+    설정된 레벨부터 표시됩니다.
+
+    .. code-block:: python
+        logger.debug("디버그 메시지")
+        logger.info("정보 메시지")
+        logger.warning("경고 메시지")
+        logger.error("에러 메시지")
+        logger.critical("치명적인 메시지")
+    """
+
+    handler = logging.StreamHandler()
+    pg_logger.setLevel(level)
+    formatter = _ColoredFormatter(
+        "%(name)s | %(asctime)s | %(levelname)s | %(filename)s:%(colored_lineno)s\n %(message)s"  # noqa: E501
+    )
+    handler.setFormatter(formatter)
+    pg_logger.addHandler(handler)
+
+    # 루트 로거에 영향을 주지 않도록 설정
+    pg_logger.propagate = False  # 루트 로거로 전파 방지
+
+
+def pg_log_disable():
+    """로그를 완전히 비활성화합니다."""
+    pg_logger.handlers.clear()
+    pg_logger.setLevel(logging.CRITICAL + 1)  # 모든 로그 차단
+
+
+def pg_log_reset():
+    """로그 설정을 초기화합니다."""
+    pg_logger.handlers.clear()
+    pg_logger.setLevel(logging.NOTSET)
+
+
+# 테스트 코드
+if __name__ == "__main__":
+    # 자동 실행 제거 - 명시적으로 호출해야 함
+    # pg_log(level=logging.DEBUG)  # 이 줄 제거
+    pg_log()
+    pg_logger.debug("디버그 메시지")
+    pg_logger.info("정보 메시지")
+    pg_logger.warning("경고 메시지")
+    pg_logger.error("에러 메시지")
+    pg_logger.critical("치명적인 메시지")

programgarden_core-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+authors = [
+    {"name" = "프로그램동산","email" = "coding@programgarden.com"}
+]
+homepage = "https://programgarden.com"
+requires-python = ">=3.9"
+name = "programgarden-core"
+version = "0.1.0"
+description = "자동화매매 클래스 상속, 로그, 환경 등의 핵심이되는 오픈소스"
+readme = "README.md"
+
+[tool.poetry]
+packages = [
+  { include = "programgarden_core" }
+]
+
+[tool.poetry.dependencies]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"