ecos-reader 0.1.0__tar.gz

ecos_reader-0.1.0/.gitignore

@@ -0,0 +1,152 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env*
+!.env.example
+!.env.sample
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# pyright
+.pyright/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.bak

ecos_reader-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests]

ecos_reader-0.1.0/API_SPEC.md

@@ -0,0 +1,69 @@
+
+## 상세주소
+
+* [https://ecos.bok.or.kr/api/](https://ecos.bok.or.kr/api/)
+
+---
+
+## 요청인자
+
+| 항목명(국문) | 필수여부 | 샘플데이터             | 항목설명                     |
+| ------- | ---- | ----------------- | ------------------------ |
+| 서비스명    | Y    | StatisticItemList | API 서비스명                 |
+| 인증키     | Y    | sample            | 한국은행에서 발급받은 오픈API 인증키    |
+| 요청유형    | Y    | xml               | 결과값의 파일 형식 - xml, json   |
+| 언어구분    | Y    | kr                | 결과값의 언어 - kr(국문), en(영문) |
+| 요청시작건수  | Y    | 1                 | 전체 결과값 중 시작 번호           |
+| 요청종료건수  | Y    | 10                | 전체 결과값 중 끝 번호            |
+| 통계표코드   | Y    | 601Y002           | 통계표코드                    |
+
+---
+
+## 출력값
+
+| 항목명(국문)  | 항목명(영문)     | 항목크기 | 샘플데이터                    | 항목설명     |
+| -------- | ----------- | ---- | ------------------------ | -------- |
+| 통계표코드    | STAT_CODE   | 8    | 601Y002                  | 통계표코드    |
+| 통계명      | STAT_NAME   | 200  | 7.5.2. 지역별 소비유형별 개인 신용카드 | 통계명      |
+| 항목그룹코드   | GRP_CODE    | 20   | Group1                   | 통계항목그룹코드 |
+| 항목그룹명    | GRP_NAME    | 60   | 지역코드                     | 통계항목그룹명  |
+| 통계항목코드   | ITEM_CODE   | 20   | A                        | 통계항목코드   |
+| 통계항목명    | ITEM_NAME   | 200  | 서울                       | 통계항목명    |
+| 상위통계항목코드 | P_ITEM_CODE | 8    | null                     | 상위통계항목코드 |
+| 상위통계항목명  | P_ITEM_NAME | 200  | null                     | 상위통계항목명  |
+| 주기       | CYCLE       | 2    | M                        | 주기(월)    |
+| 수록시작일자   | START_TIME  | 8    | 200912                   | 수록시작일자   |
+| 수록종료일자   | END_TIME    | 8    | 202112                   | 수록종료일자   |
+| 자료수      | DATA_CNT    | 22   | 145                      | 자료수      |
+| 단위       | UNIT_NAME   | 200  | 십억원                      | 단위       |
+| 가중치      | WEIGHT      | 22   | null                     | 가중치      |
+
+---
+
+## OpenAPI 테스트
+
+* **테스트 URL**
+
+  ```
+  https://ecos.bok.or.kr/api/StatisticItemList/sample/xml/kr/1/10/043Y070/
+  ```
+* `sample` 위치에 **인증키 값**을 입력
+
+---
+
+## OpenAPI 메세지
+
+| 타입 | 코드  | 설명                                                   |
+| -- | --- | ---------------------------------------------------- |
+| 정보 | 100 | 인증키가 유효하지 않습니다. 인증키를 확인하십시오! 인증키가 없는 경우 인증키를 신청하십시오! |
+| 정보 | 200 | 해당하는 데이터가 없습니다.                                      |
+| 에러 | 100 | 필수 값이 누락되어 있습니다. 필수 값을 확인하십시오!                       |
+| 에러 | 101 | 주기와 다른 형식의 날짜 형식입니다.                                 |
+| 에러 | 200 | 파일타입 값이 누락 혹은 유효하지 않습니다.                             |
+| 에러 | 300 | 조회건수 값이 누락되어 있습니다.                                   |
+| 에러 | 301 | 조회건수 값의 타입이 유효하지 않습니다. 정수를 입력하세요.                    |
+| 에러 | 400 | 검색범위가 적정범위를 초과하여 60초 TIMEOUT이 발생하였습니다.               |
+| 에러 | 500 | 서버 오류입니다. 해당 서비스를 찾을 수 없습니다.                         |
+| 에러 | 600 | DB Connection 오류입니다.                                 |
+| 에러 | 601 | SQL 오류입니다.                                           |
+| 에러 | 602 | 과도한 OpenAPI 호출로 이용이 제한되었습니다.                         |

ecos_reader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.

ecos_reader-0.1.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: ecos-reader
+Version: 0.1.0
+Summary: 한국은행 ECOS Open API Python 클라이언트
+Project-URL: Homepage, https://github.com/yeonguk/ecos-reader
+Project-URL: Documentation, https://github.com/yeonguk/ecos-reader#readme
+Project-URL: Repository, https://github.com/yeonguk/ecos-reader
+Project-URL: Issues, https://github.com/yeonguk/ecos-reader/issues
+Author: yeonguk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bok,economy,ecos,finance,korea,macro
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ecos-reader
+**한국은행 ECOS Open API Python 클라이언트**
+
+한국은행 ECOS Open API를 Python에서 쉽고 일관된 방식으로 사용할 수 있는 라이브러리입니다.
+
+
+## 설치
+
+```bash
+pip install ecos-reader
+```
+
+또는 개발 버전 설치:
+
+```bash
+git clone https://github.com/choo121600/ecos-reader.git
+cd ecos-reader
+pip install -e ".[dev]"
+```
+
+## API 키 설정
+
+ECOS API를 사용하려면 한국은행에서 발급받은 API 키가 필요합니다.
+
+[API 키 신청하기](https://ecos.bok.or.kr/api/)
+
+### 방법 1: 환경 변수 (권장)
+
+```bash
+export ECOS_API_KEY="your_api_key"
+```
+
+또는 `.env` 파일 생성:
+
+```
+ECOS_API_KEY=your_api_key
+```
+
+> 참고: v0.1.0부터는 라이브러리 import 시점에 `.env`를 자동으로 로드하지 않습니다.
+> `.env`를 사용하려면 아래처럼 `ecos.load_env()`를 한 번 호출하세요.
+
+```python
+import ecos
+
+ecos.load_env()  # .env 로드 (명시적)
+```
+
+### 방법 2: 코드에서 직접 설정
+
+```python
+import ecos
+
+ecos.set_api_key("your_api_key")
+```
+
+## 빠른 시작
+
+```python
+import ecos
+
+# 한국은행 기준금리 조회
+df = ecos.get_base_rate()
+print(df)
+#         date  value unit
+# 0 2024-01-01   3.50    %
+# 1 2024-02-01   3.50    %
+# ...
+
+# 소비자물가지수(CPI) 조회
+df = ecos.get_cpi(start_date="202301", end_date="202312")
+print(df)
+
+# 국고채 수익률 조회
+df = ecos.get_treasury_yield(maturity="10Y")
+print(df)
+
+# GDP 조회
+df = ecos.get_gdp(frequency="Q", basis="real")
+print(df)
+```
+
+## 지원 지표
+
+### 금리 지표
+
+| 함수 | 설명 |
+|-----|------|
+| `get_base_rate()` | 한국은행 기준금리 |
+| `get_treasury_yield(maturity)` | 국고채 수익률 (1Y, 3Y, 5Y, 10Y, 20Y, 30Y) |
+| `get_yield_spread()` | 장단기 금리차 |
+
+### 물가 지표
+
+| 함수 | 설명 |
+|-----|------|
+| `get_cpi()` | 소비자물가지수 전년동월비 |
+| `get_core_cpi()` | 근원 CPI (식료품·에너지 제외) |
+| `get_ppi()` | 생산자물가지수 전년동월비 |
+
+### 성장 지표
+
+| 함수 | 설명 |
+|-----|------|
+| `get_gdp(frequency, basis)` | GDP (분기/연간, 실질/명목) |
+| `get_gdp_deflator()` | GDP 디플레이터 |
+
+### 통화 지표
+
+| 함수 | 설명 |
+|-----|------|
+| `get_money_supply(indicator)` | 통화량 (M1, M2, Lf) |
+| `get_bank_lending(sector)` | 은행 대출 (가계/기업/전체) |
+
+## 상세 사용법
+
+### 기간 지정
+
+```python
+# 월간 데이터 (YYYYMM 형식)
+df = ecos.get_base_rate(start_date="202001", end_date="202312")
+
+# 일간 데이터 (YYYYMMDD 형식)
+df = ecos.get_treasury_yield(maturity="3Y", start_date="20240101", end_date="20241231")
+
+# 분기 데이터 (YYYYQN 형식)
+df = ecos.get_gdp(frequency="Q", start_date="2020Q1", end_date="2024Q4")
+
+# 연간 데이터 (YYYY 형식)
+df = ecos.get_gdp(frequency="A", start_date="2015", end_date="2024")
+```
+
+### 캐시 관리
+
+```python
+import ecos
+
+# 캐시 비활성화
+ecos.disable_cache()
+
+# 캐시 활성화
+ecos.enable_cache()
+
+# 캐시 초기화
+ecos.clear_cache()
+```
+
+### 에러 처리
+
+```python
+import ecos
+from ecos import EcosAPIError, EcosConfigError, EcosNetworkError
+
+try:
+    df = ecos.get_base_rate()
+except EcosConfigError as e:
+    print(f"API 키 설정 오류: {e}")
+except EcosNetworkError as e:
+    print(f"네트워크 오류: {e}")
+except EcosAPIError as e:
+    print(f"API 오류 [{e.code}]: {e.message}")
+```
+
+### 로깅 활성화(선택)
+
+라이브러리는 import 시점에 로깅 핸들러를 자동으로 구성하지 않습니다. 필요 시 아래처럼 활성화하세요.
+
+```python
+import logging
+import ecos
+
+ecos.setup_logging(logging.INFO)
+```
+
+### 직접 클라이언트 사용
+
+```python
+from ecos import EcosClient
+
+# 클라이언트 생성
+client = EcosClient(
+    api_key="your_api_key",
+    timeout=60,
+    max_retries=5,
+    use_cache=True,
+)
+
+# 통계 조회
+response = client.get_statistic_search(
+    stat_code="722Y001",
+    period="M",
+    start_date="202401",
+    end_date="202412",
+    item_code1="0101000",
+)
+```
+
+### 전역 기본 클라이언트 주입(선택)
+
+indicator 함수들이 사용할 “기본 클라이언트”를 교체하고 싶다면 아래처럼 설정할 수 있습니다.
+
+```python
+import ecos
+from ecos import EcosClient
+
+custom = EcosClient(timeout=60, max_retries=5, use_cache=True)
+ecos.set_client(custom)
+
+df = ecos.get_cpi()  # custom 클라이언트 사용
+```
+
+## 테스트
+
+```bash
+# 테스트 실행
+pytest
+
+# 커버리지 포함
+pytest --cov=src/ecos
+
+# 특정 테스트만 실행
+pytest tests/test_config.py -v
+```
+
+## 프로젝트 구조
+
+```
+ecos-reader/
+├── src/ecos/
+│   ├── __init__.py          # Public API
+│   ├── client.py            # API 클라이언트
+│   ├── config.py            # 설정 관리
+│   ├── cache.py             # 캐시 레이어
+│   ├── parser.py            # 응답 파서
+│   ├── exceptions.py        # 예외 클래스
+│   ├── constants.py         # 상수 정의
+│   └── indicators/          # 지표 모듈
+│       ├── interest_rate.py # 금리
+│       ├── prices.py        # 물가
+│       ├── growth.py        # 성장
+│       └── money.py         # 통화
+├── tests/                   # 테스트 코드
+├── examples/                # 예제 코드
+├── pyproject.toml
+└── README.md
+```
+
+# 라이센스
+MIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.