Metadata-Version: 2.3
Name: ecos-enhanced
Version: 0.1.0
Summary: Async Python client for Bank of Korea ECOS (Economic Statistics System) API
Project-URL: Homepage, https://github.com/dankang21/ecos-enhanced
Project-URL: Repository, https://github.com/dankang21/ecos-enhanced
Project-URL: Issues, https://github.com/dankang21/ecos-enhanced/issues
Author-email: Daniel Kang <dankang21@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Daniel Kang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: async,bank-of-korea,bok,cpi,economic-statistics,ecos,exchange-rate,gdp,interest-rate,korea
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Description-Content-Type: text/markdown

# ecos-enhanced

**Async Python client for Bank of Korea ECOS API**

한국은행 경제통계시스템(ECOS) API를 위한 비동기 Python 클라이언트. 기준금리, 환율, 국고채 금리, 소비자물가지수, GDP 등 주요 경제 지표를 간편하게 조회합니다.

[![PyPI](https://img.shields.io/pypi/v/ecos-enhanced)](https://pypi.org/project/ecos-enhanced/)
[![Python](https://img.shields.io/pypi/pyversions/ecos-enhanced)](https://pypi.org/project/ecos-enhanced/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Features

- **Async-first** — `httpx` 기반 비동기 HTTP 클라이언트
- **Built-in registry** — 12개 주요 통계코드 내장 (금리, 환율, 물가, GDP 등)
- **Convenience methods** — `get_base_rate()`, `get_exchange_rate()` 등 원라인 조회
- **Zero pandas dependency** — 순수 Python dataclass
- **Fully typed** — `py.typed` 마커, 모든 공개 API에 타입 힌트

## Installation

```bash
pip install ecos-enhanced
```

## Quick Start

```python
import asyncio
from ecos_enhanced import EcosClient

async def main():
    async with EcosClient(api_key="YOUR_ECOS_API_KEY") as client:
        # 원/달러 환율
        rates = await client.get_exchange_rate("usd", "20240101", "20241231")
        for r in rates:
            print(f"{r.time}: {r.value}원")

        # 한국은행 기준금리
        base = await client.get_base_rate("202401", "202412")
        print(f"현재 기준금리: {base[-1].value}%")

        # 소비자물가지수
        cpi = await client.get_cpi("202401", "202412")
        print(f"최근 CPI: {cpi[-1].value}")

asyncio.run(main())
```

### Error Handling

```python
from ecos_enhanced import EcosClient, EcosApiError

async with EcosClient() as client:
    try:
        data = await client.get_by_key("usd_krw", "20240101", "20241231")
    except EcosApiError as e:
        print(f"ECOS API 오류: {e} (code={e.code})")
```

## API Reference

### EcosClient

```python
client = EcosClient(api_key="...")  # 또는 환경변수 ECOS_API_KEY
```

| Method | Description |
|--------|-------------|
| `get_statistic(stat_code, cycle, start_date, end_date, item_code)` | 범용 통계 조회 |
| `get_by_key(key, start_date, end_date)` | 레지스트리 키로 간편 조회 |
| `get_base_rate(start_date, end_date)` | 한국은행 기준금리 |
| `get_exchange_rate(currency, start_date, end_date)` | 환율 (usd, jpy, eur, cny) |
| `get_cpi(start_date, end_date)` | 소비자물가지수 |
| `get_treasury_yield(maturity, start_date, end_date)` | 국고채 금리 (3y, 10y) |
| `get_gdp(start_date, end_date)` | 실질 GDP (분기) |
| `get_available_keys()` | 사용 가능한 레지스트리 키 목록 |
| `close()` | HTTP 클라이언트 종료 (context manager 사용 시 자동 호출) |

### EcosDataPoint

모든 조회 메서드의 반환 타입 (리스트):

| Field | Type | Description |
|-------|------|-------------|
| `stat_code` | `str` | 통계표 코드 |
| `stat_name` | `str` | 통계표 이름 |
| `item_name` | `str` | 통계항목 이름 |
| `time` | `str` | 시점 (YYYYMMDD 또는 YYYYMM) |
| `value` | `float` | 데이터 값 |
| `unit` | `str` | 단위 |

### Built-in Registry (STAT_CODES)

| Key | Name | Cycle | Unit |
|-----|------|:-----:|------|
| `base_rate` | 한국은행 기준금리 | M | 연% |
| `cd_rate` | CD(91일) 금리 | D | 연% |
| `treasury_3y` | 국고채(3년) 금리 | D | 연% |
| `treasury_10y` | 국고채(10년) 금리 | D | 연% |
| `usd_krw` | 원/달러 환율(종가) | D | 원 |
| `jpy_krw` | 원/100엔 환율(종가) | D | 원 |
| `eur_krw` | 원/유로 환율(종가) | D | 원 |
| `cny_krw` | 원/위안 환율(종가) | D | 원 |
| `cpi` | 소비자물가지수(총지수) | M | 2020=100 |
| `m2` | M2(광의통화) | M | 십억원 |
| `gdp` | 실질 국내총생산(GDP) | Q | 십억원 |

레지스트리에 없는 통계는 `get_statistic()`으로 직접 조회할 수 있습니다.

### Date Format

| Cycle | Format | Example |
|:-----:|--------|---------|
| D (일) | YYYYMMDD | `"20240315"` |
| M (월) | YYYYMM | `"202403"` |
| Q (분기) | YYYYQ | `"2024Q1"` |
| A (연) | YYYY | `"2024"` |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ECOS_API_KEY` | ECOS API 인증키 ([발급](https://ecos.bok.or.kr/api/)) |

## ECOS API Key

1. [ECOS API](https://ecos.bok.or.kr/api/) 접속
2. 회원가입 후 "인증키 신청"
3. 발급받은 키를 환경변수 `ECOS_API_KEY`로 설정하거나 `EcosClient(api_key="...")`에 전달

## Important Notes

### 비동기 전용

이 라이브러리는 `async/await` 전용입니다. 동기 코드에서 사용하려면:

```python
import asyncio
result = asyncio.run(main())
```

### 재무제표 파서 한계

- ECOS API는 통계표 코드 + 항목 코드 조합으로 데이터를 조회합니다.
- 내장 레지스트리(`STAT_CODES`)에 없는 통계는 [ECOS API 문서](https://ecos.bok.or.kr/api/)에서 코드를 확인한 후 `get_statistic()`으로 직접 조회하세요.

## Disclaimer

이 라이브러리는 한국은행 ECOS API 데이터 조회를 위한 기술적 도구이며, 투자 권유 또는 금융 서비스를 제공하지 않습니다. 데이터 활용 시 [ECOS API 이용약관](https://ecos.bok.or.kr/api/) 및 관련 법규를 준수할 책임은 사용자에게 있습니다.

This library is a technical tool for querying the Bank of Korea ECOS API and does not provide investment advice or financial services.

## License

MIT License. See [LICENSE](LICENSE).
