ecos-reader 0.1.0__py3-none-any.whl

ecos/config.py

@@ -0,0 +1,148 @@
+"""
+ecos-reader 설정 관리
+
+API Key 및 기본 설정을 관리합니다.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .exceptions import EcosConfigError
+
+# dotenv 로드 상태(명시적으로만 로드)
+_dotenv_loaded: bool = False
+
+# 전역 API Key 저장소
+_api_key: str | None = None
+
+
+def load_env(*, dotenv_path: str | None = None, override: bool = False) -> bool:
+    """
+    .env 파일을 명시적으로 로드합니다.
+
+    Notes
+    -----
+    라이브러리 import 시점에 자동으로 .env를 로드하지 않습니다.
+    필요 시 사용자가 직접 호출하여 환경 변수를 로드할 수 있습니다.
+
+    Parameters
+    ----------
+    dotenv_path : str, optional
+        .env 파일 경로. 미지정 시 python-dotenv 기본 탐색 규칙을 따릅니다.
+    override : bool, optional
+        이미 설정된 환경 변수를 덮어쓸지 여부
+
+    Returns
+    -------
+    bool
+        .env 파일을 로드했으면 True, 아니면 False
+    """
+    global _dotenv_loaded
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        # python-dotenv가 설치되어 있지 않은 경우
+        _dotenv_loaded = False
+        return False
+
+    loaded = load_dotenv(dotenv_path=dotenv_path, override=override)
+    _dotenv_loaded = bool(loaded)
+    return _dotenv_loaded
+
+
+def set_api_key(api_key: str) -> None:
+    """
+    API Key를 설정합니다.
+
+    Parameters
+    ----------
+    api_key : str
+        한국은행에서 발급받은 ECOS Open API 인증키
+
+    Examples
+    --------
+    >>> import ecos
+    >>> ecos.set_api_key("your_api_key")
+    """
+    global _api_key
+    if not api_key or not isinstance(api_key, str):
+        raise EcosConfigError("API Key는 빈 문자열이 아닌 문자열이어야 합니다.")
+    _api_key = api_key
+
+
+def get_api_key() -> str:
+    """
+    현재 설정된 API Key를 반환합니다.
+
+    환경 변수 `ECOS_API_KEY`가 설정되어 있으면 해당 값을 사용합니다.
+    `set_api_key()`로 직접 설정한 값이 있으면 해당 값을 우선합니다.
+    `.env` 파일은 import 시점에 자동으로 로드되지 않습니다(필요 시 `load_env()` 호출).
+
+    Returns
+    -------
+    str
+        ECOS API 인증키
+
+    Raises
+    ------
+    EcosConfigError
+        API Key가 설정되지 않은 경우
+
+    Examples
+    --------
+    >>> import ecos
+    >>> ecos.set_api_key("your_api_key")
+    >>> ecos.get_api_key()
+    'your_api_key'
+    """
+    global _api_key
+
+    # 직접 설정한 값 우선
+    if _api_key is not None:
+        return _api_key
+
+    # 환경 변수에서 로드
+    env_key = os.environ.get("ECOS_API_KEY")
+    if env_key:
+        return env_key
+
+    raise EcosConfigError(
+        "API Key가 설정되지 않았습니다. "
+        "환경 변수 ECOS_API_KEY를 설정하거나, "
+        "ecos.load_env()로 .env 파일을 로드하거나, "
+        "ecos.set_api_key('your_api_key')를 호출하세요. "
+        "API Key는 https://ecos.bok.or.kr/api/ 에서 신청할 수 있습니다."
+    )
+
+
+def clear_api_key() -> None:
+    """
+    설정된 API Key를 초기화합니다.
+
+    주로 테스트 목적으로 사용됩니다.
+    """
+    global _api_key
+    _api_key = None
+
+
+# 기본 설정값
+class Settings:
+    """기본 설정값"""
+
+    # API 기본값
+    BASE_URL: str = "https://ecos.bok.or.kr/api/"
+    DEFAULT_FORMAT: str = "json"
+    DEFAULT_LANG: str = "kr"
+
+    # 요청 설정
+    DEFAULT_TIMEOUT: int = 30  # 초
+    MAX_RETRIES: int = 3
+    RETRY_BACKOFF_FACTOR: float = 1.0
+
+    # 캐시 설정
+    CACHE_TTL: int = 3600  # 1시간
+    CACHE_MAXSIZE: int = 100
+
+    # 페이지네이션
+    DEFAULT_PAGE_SIZE: int = 10000

ecos/constants.py

@@ -0,0 +1,155 @@
+"""
+ecos-reader 상수 정의
+
+ECOS API 통계코드 및 항목코드를 정의합니다.
+"""
+
+from __future__ import annotations
+
+# ============================================================================
+# 주기 코드
+# ============================================================================
+
+PERIOD_DAILY = "D"
+PERIOD_MONTHLY = "M"
+PERIOD_QUARTERLY = "Q"
+PERIOD_ANNUAL = "A"
+
+
+# ============================================================================
+# 금리 지표 (interest_rate)
+# ============================================================================
+
+# 한국은행 기준금리
+STAT_BASE_RATE = "722Y001"
+ITEM_BASE_RATE = "0101000"
+
+# 시장금리 (국고채, 회사채 등)
+STAT_MARKET_RATE = "817Y002"
+
+# 국고채 만기별 항목코드
+TREASURY_YIELD_ITEMS: dict[str, str] = {
+    "1Y": "010190000",  # 국고채 1년
+    "3Y": "010200000",  # 국고채 3년
+    "5Y": "010200001",  # 국고채 5년
+    "10Y": "010210000",  # 국고채 10년
+    "20Y": "010220000",  # 국고채 20년
+    "30Y": "010230000",  # 국고채 30년
+}
+
+
+# ============================================================================
+# 물가 지표 (prices)
+# ============================================================================
+
+# 소비자물가지수 (전년동월비)
+STAT_CPI = "901Y009"
+ITEM_CPI_TOTAL = "0"  # 총지수
+
+# 근원 소비자물가지수
+STAT_CORE_CPI = "901Y010"
+ITEM_CORE_CPI = "AA0000"  # 농산물및석유류제외
+
+# 생산자물가지수
+STAT_PPI = "404Y014"
+ITEM_PPI_TOTAL = "A00"  # 총지수
+
+
+# ============================================================================
+# 성장 지표 (growth)
+# ============================================================================
+
+# GDP (국내총생산)
+STAT_GDP_REAL = "200Y001"  # 실질 GDP
+STAT_GDP_NOMINAL = "200Y002"  # 명목 GDP
+ITEM_GDP = "10101"  # 국내총생산
+
+# GDP 디플레이터
+STAT_GDP_DEFLATOR = "200Y004"
+ITEM_GDP_DEFLATOR = "10101"
+
+
+# ============================================================================
+# 통화 지표 (money)
+# ============================================================================
+
+# 통화량
+STAT_MONEY_SUPPLY = "101Y018"
+
+# 통화량 항목코드
+MONEY_SUPPLY_ITEMS: dict[str, str] = {
+    "M1": "BBGA00",  # 협의통화(M1)
+    "M2": "BBGS00",  # 광의통화(M2)
+    "Lf": "BBLA00",  # 금융기관유동성(Lf)
+}
+
+# 은행 대출
+STAT_BANK_LENDING = "104Y016"
+
+# 대출 부문별 항목코드
+BANK_LENDING_ITEMS: dict[str, str] = {
+    "all": "BDCA",  # 총대출
+    "household": "BDCB",  # 가계대출
+    "corporate": "BDCC",  # 기업대출
+}
+
+
+# ============================================================================
+# 환율 지표 (forex) - Phase 3
+# ============================================================================
+
+STAT_EXCHANGE_RATE = "731Y003"
+
+# 통화별 항목코드
+EXCHANGE_RATE_ITEMS: dict[str, str] = {
+    "USD": "0000001",  # 원/달러
+    "JPY": "0000002",  # 원/100엔
+    "EUR": "0000003",  # 원/유로
+    "CNY": "0000053",  # 원/위안
+}
+
+# 실효환율
+STAT_EFFECTIVE_RATE = "731Y004"
+ITEM_NEER = "0000001"  # 명목실효환율
+ITEM_REER = "0000002"  # 실질실효환율
+
+
+# ============================================================================
+# 국제수지 지표 (bop) - Phase 3
+# ============================================================================
+
+STAT_BOP = "301Y017"
+ITEM_CURRENT_ACCOUNT = "CA"  # 경상수지
+ITEM_CAPITAL_ACCOUNT = "KA"  # 자본수지
+
+
+# ============================================================================
+# 실물 지표 (real_economy) - Phase 4
+# ============================================================================
+
+# 산업생산지수
+STAT_INDUSTRIAL_PRODUCTION = "901Y033"
+ITEM_INDUSTRIAL_PRODUCTION = "A00"
+
+# 설비투자지수
+STAT_FACILITY_INVESTMENT = "901Y049"
+ITEM_FACILITY_INVESTMENT = "I16A"
+
+# 소매판매지수
+STAT_RETAIL_SALES = "901Y037"
+ITEM_RETAIL_SALES = "*"
+
+
+# ============================================================================
+# 심리 지표 (sentiment) - Phase 4
+# ============================================================================
+
+# 기업경기실사지수 (BSI)
+STAT_BSI = "512Y014"
+ITEM_BSI_MANUFACTURING = "A001"
+ITEM_BSI_NON_MANUFACTURING = "B001"
+ITEM_BSI_ALL = "C001"
+
+# 소비자심리지수 (CSI)
+STAT_CSI = "511Y002"
+ITEM_CSI = "FME"

ecos/exceptions.py

@@ -0,0 +1,73 @@
+"""
+ecos-reader 예외 클래스 정의
+
+ECOS API 에러 및 라이브러리 예외를 처리합니다.
+"""
+
+from __future__ import annotations
+
+
+class EcosError(Exception):
+    """ecos-reader 기본 예외"""
+
+    pass
+
+
+class EcosAPIError(EcosError):
+    """ECOS API 호출 에러
+
+    Attributes
+    ----------
+    code : str
+        ECOS API 에러 코드
+    message : str
+        에러 메시지
+    """
+
+    def __init__(self, code: str, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")
+
+
+class EcosConfigError(EcosError):
+    """설정 관련 에러 (API Key 등)"""
+
+    pass
+
+
+class EcosNetworkError(EcosError):
+    """네트워크 연결 에러"""
+
+    pass
+
+
+class EcosRateLimitError(EcosError):
+    """Rate Limit 초과"""
+
+    def __init__(self, message: str, code: str = "602"):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")
+
+
+# ECOS 에러 코드 매핑
+ECOS_ERROR_CODES: dict[str, tuple[type[EcosError], str]] = {
+    # 정보 코드
+    "INFO_100": (EcosConfigError, "인증키가 유효하지 않습니다."),
+    "INFO_200": (EcosAPIError, "해당하는 데이터가 없습니다."),  # 빈 DataFrame 반환으로 처리
+    # 에러 코드
+    "ERROR_100": (EcosAPIError, "필수 값이 누락되어 있습니다."),
+    "ERROR_101": (EcosAPIError, "주기와 다른 형식의 날짜 형식입니다."),
+    "ERROR_200": (EcosAPIError, "파일타입 값이 누락 혹은 유효하지 않습니다."),
+    "ERROR_300": (EcosAPIError, "조회건수 값이 누락되어 있습니다."),
+    "ERROR_301": (EcosAPIError, "조회건수 값의 타입이 유효하지 않습니다."),
+    "ERROR_400": (EcosAPIError, "검색범위가 적정범위를 초과하여 TIMEOUT이 발생하였습니다."),
+    "ERROR_500": (EcosAPIError, "서버 오류입니다."),  # 재시도 대상
+    "ERROR_600": (EcosAPIError, "DB Connection 오류입니다."),  # 재시도 대상
+    "ERROR_601": (EcosAPIError, "SQL 오류입니다."),
+    "ERROR_602": (EcosRateLimitError, "과도한 OpenAPI 호출로 이용이 제한되었습니다."),
+}
+
+# 재시도 가능한 에러 코드 (ECOS API는 하이픈 형식 사용: ERROR-500)
+RETRYABLE_ERROR_CODES = {"ERROR-500", "ERROR-600", "ERROR-602"}

ecos/indicators/__init__.py

@@ -0,0 +1,29 @@
+"""
+ecos-reader 지표 모듈
+
+각종 거시경제 지표 조회 함수를 제공합니다.
+"""
+
+from __future__ import annotations
+
+from .growth import get_gdp, get_gdp_deflator
+from .interest_rate import get_base_rate, get_treasury_yield, get_yield_spread
+from .money import get_bank_lending, get_money_supply
+from .prices import get_core_cpi, get_cpi, get_ppi
+
+__all__ = [
+    # 금리 지표
+    "get_base_rate",
+    "get_treasury_yield",
+    "get_yield_spread",
+    # 물가 지표
+    "get_cpi",
+    "get_core_cpi",
+    "get_ppi",
+    # 성장 지표
+    "get_gdp",
+    "get_gdp_deflator",
+    # 통화 지표
+    "get_money_supply",
+    "get_bank_lending",
+]

ecos/indicators/growth.py

@@ -0,0 +1,186 @@
+"""
+성장 지표 모듈
+
+GDP(국내총생산), GDP 디플레이터 등 성장 관련 지표를 조회합니다.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+import pandas as pd
+
+from ..client import get_client
+from ..constants import (
+    ITEM_GDP,
+    ITEM_GDP_DEFLATOR,
+    PERIOD_ANNUAL,
+    PERIOD_QUARTERLY,
+    STAT_GDP_DEFLATOR,
+    STAT_GDP_NOMINAL,
+    STAT_GDP_REAL,
+)
+from ..parser import normalize_stat_result, parse_response
+
+
+def _get_default_dates_quarterly(years_back: int = 5) -> tuple[str, str]:
+    """기본 조회 기간을 반환합니다 (분기)."""
+    end_date = datetime.now()
+    start_year = end_date.year - years_back
+    current_quarter = (end_date.month - 1) // 3 + 1
+
+    start_str = f"{start_year}Q1"
+    end_str = f"{end_date.year}Q{current_quarter}"
+
+    return start_str, end_str
+
+
+def _get_default_dates_annual(years_back: int = 10) -> tuple[str, str]:
+    """기본 조회 기간을 반환합니다 (연간)."""
+    end_date = datetime.now()
+    start_year = end_date.year - years_back
+
+    return str(start_year), str(end_date.year)
+
+
+def get_gdp(
+    frequency: Literal["Q", "A"] = "Q",
+    basis: Literal["real", "nominal"] = "real",
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> pd.DataFrame:
+    """
+    국내총생산(GDP)을 조회합니다.
+
+    Parameters
+    ----------
+    frequency : str
+        조회 주기
+        - 'Q': 분기 (기본값)
+        - 'A': 연간
+    basis : str
+        GDP 기준
+        - 'real': 실질 GDP (기본값)
+        - 'nominal': 명목 GDP
+    start_date : str, optional
+        조회 시작일
+        - 분기: YYYYQN 형식 (예: 2020Q1)
+        - 연간: YYYY 형식 (예: 2020)
+    end_date : str, optional
+        조회 종료일
+
+    Returns
+    -------
+    pd.DataFrame
+        컬럼: date, value, unit
+        - date: 날짜 (datetime)
+        - value: GDP (조원)
+        - unit: 단위
+
+    Notes
+    -----
+    - 실질 GDP: 물가 변동을 제외한 실제 생산량 변화
+    - 명목 GDP: 당해 연도 가격 기준 GDP
+
+    Examples
+    --------
+    >>> import ecos
+    >>> df = ecos.get_gdp()  # 분기별 실질 GDP
+    >>> df.head()
+
+    >>> df = ecos.get_gdp(frequency="A", basis="nominal")  # 연간 명목 GDP
+    """
+    # 통계코드 선택
+    stat_code = STAT_GDP_REAL if basis == "real" else STAT_GDP_NOMINAL
+
+    # 주기 코드
+    period = PERIOD_QUARTERLY if frequency == "Q" else PERIOD_ANNUAL
+
+    # 기본 날짜 설정
+    if start_date is None or end_date is None:
+        if frequency == "Q":
+            default_start, default_end = _get_default_dates_quarterly(5)
+        else:
+            default_start, default_end = _get_default_dates_annual(10)
+        start_date = start_date or default_start
+        end_date = end_date or default_end
+
+    client = get_client()
+    response = client.get_statistic_search(
+        stat_code=stat_code,
+        period=period,
+        start_date=start_date,
+        end_date=end_date,
+        item_code1=ITEM_GDP,
+    )
+
+    df = parse_response(response)
+    return normalize_stat_result(df)
+
+
+def get_gdp_deflator(
+    frequency: Literal["Q", "A"] = "Q",
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> pd.DataFrame:
+    """
+    GDP 디플레이터를 조회합니다.
+
+    GDP 디플레이터는 명목 GDP와 실질 GDP의 비율로 계산되는
+    종합 물가지수입니다.
+
+    Parameters
+    ----------
+    frequency : str
+        조회 주기
+        - 'Q': 분기 (기본값)
+        - 'A': 연간
+    start_date : str, optional
+        조회 시작일
+    end_date : str, optional
+        조회 종료일
+
+    Returns
+    -------
+    pd.DataFrame
+        컬럼: date, value, unit
+        - date: 날짜 (datetime)
+        - value: GDP 디플레이터
+        - unit: 단위
+
+    Notes
+    -----
+    - GDP 디플레이터 = (명목 GDP / 실질 GDP) × 100
+    - CPI보다 포괄적인 물가 지표
+    - 국내에서 생산된 모든 재화와 서비스의 가격 변화 반영
+
+    Examples
+    --------
+    >>> import ecos
+    >>> df = ecos.get_gdp_deflator()
+    >>> df.head()
+    """
+    # 주기 코드
+    period = PERIOD_QUARTERLY if frequency == "Q" else PERIOD_ANNUAL
+
+    # 기본 날짜 설정
+    if start_date is None or end_date is None:
+        if frequency == "Q":
+            default_start, default_end = _get_default_dates_quarterly(5)
+        else:
+            default_start, default_end = _get_default_dates_annual(10)
+        start_date = start_date or default_start
+        end_date = end_date or default_end
+
+    client = get_client()
+    response = client.get_statistic_search(
+        stat_code=STAT_GDP_DEFLATOR,
+        period=period,
+        start_date=start_date,
+        end_date=end_date,
+        item_code1=ITEM_GDP_DEFLATOR,
+    )
+
+    df = parse_response(response)
+    return normalize_stat_result(df)