kiwoompy 0.1.2__tar.gz

kiwoompy-0.1.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: kiwoompy
+Version: 0.1.2
+Summary: 키움증권 REST API Python 라이브러리
+Author: meonji-gogo
+Author-email: meonji-gogo <meonji-gogo@users.noreply.github.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: websockets>=16.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# kiwoompy
+
+키움증권 REST API를 Python에서 편하게 쓰기 위한 라이브러리입니다.
+
+[![PyPI](https://img.shields.io/pypi/v/kiwoompy)](https://pypi.org/project/kiwoompy/)
+[![Python](https://img.shields.io/pypi/pyversions/kiwoompy)](https://pypi.org/project/kiwoompy/)
+[![Docs](https://img.shields.io/badge/docs-meonji--gogo.github.io-blue)](https://meonji-gogo.github.io/kiwoompy/)
+[![License](https://img.shields.io/pypi/l/kiwoompy)](LICENSE)
+
+## 설치
+
+```bash
+pip install kiwoompy
+```
+
+uv 사용 시:
+
+```bash
+uv add kiwoompy
+```
+
+Python 3.12 이상이 필요합니다.
+
+## 사전 준비
+
+[키움증권 OpenAPI](https://openapi.kiwoom.com)에서 앱을 등록하고 **App Key** / **App Secret**을 발급받아야 합니다.
+
+> **주의** — App Key와 App Secret은 코드에 직접 넣지 마세요. 환경 변수나 시크릿 매니저로 관리하세요.
+
+## 빠른 시작
+
+```python
+from kiwoompy import KiwoomClient
+
+client = KiwoomClient(
+    env="demo",               # "demo"(모의투자) / "real"(실계좌)
+    appkey="YOUR_APP_KEY",
+    secretkey="YOUR_APP_SECRET",
+)
+
+# 계좌 잔고 조회
+balance = client.query.get_account_balance()
+print(balance.tot_evlt_amt)   # 총평가금액
+
+for item in balance.holdings:
+    print(item.stk_nm, item.evlt_amt)
+```
+
+```python
+# 시장가 매수
+result = client.order.buy("005930", quantity="1", trade_type="market")
+print(result.ord_no)
+
+# 지정가 매도
+client.order.sell("005930", quantity="1", trade_type="limit", price="75000")
+```
+
+context manager도 지원합니다.
+
+```python
+with KiwoomClient(env="demo", appkey="...", secretkey="...") as client:
+    deposit = client.query.get_deposit(query_type="normal")
+    print(deposit.entr)   # 예수금
+```
+
+## 기능
+
+- **OAuth2 인증** — 접근토큰 발급·만료 자동 관리
+- **환경 분리** — 모의투자 / 실계좌 한 줄로 전환
+- **유량 제어** — 모의 2건/초, 실전 20건/초 자동 적용
+- **자동 재시도** — 네트워크 오류·5xx 지수 백오프 재시도 (최대 3회)
+- **입력값 보완** — 계좌번호 상품코드 누락 시 자동 보완
+- **타입 힌트** — IDE 자동완성·정적 분석 지원
+
+## 에러 처리
+
+```python
+from kiwoompy import KiwoomAuthError, KiwoomApiError
+
+try:
+    client = KiwoomClient(env="demo", appkey="wrong", secretkey="wrong")
+except KiwoomAuthError as e:
+    print(f"인증 실패: {e}")
+except KiwoomApiError as e:
+    print(f"API 오류: {e}")
+```
+
+| 예외 | 발생 조건 |
+|------|-----------|
+| `KiwoomAuthError` | 잘못된 키, 토큰 미발급 상태에서 API 호출 |
+| `KiwoomApiError` | 네트워크 오류, 5xx 서버 오류, 응답 파싱 실패 |
+
+## 문서
+
+전체 사용법과 API 레퍼런스는 문서 사이트를 참고해 주세요.
+
+👉 **https://meonji-gogo.github.io/kiwoompy**
+
+## 키움증권 REST API 공지 알리미
+
+키움증권 REST API 공지사항·변경 사항을 텔레그램으로 받아볼 수 있습니다.
+
+👉 **https://t.me/+2do4kWIhBmg3OTM1**
+
+## 라이선스
+
+MIT

kiwoompy-0.1.2/README.md

@@ -0,0 +1,107 @@
+# kiwoompy
+
+키움증권 REST API를 Python에서 편하게 쓰기 위한 라이브러리입니다.
+
+[![PyPI](https://img.shields.io/pypi/v/kiwoompy)](https://pypi.org/project/kiwoompy/)
+[![Python](https://img.shields.io/pypi/pyversions/kiwoompy)](https://pypi.org/project/kiwoompy/)
+[![Docs](https://img.shields.io/badge/docs-meonji--gogo.github.io-blue)](https://meonji-gogo.github.io/kiwoompy/)
+[![License](https://img.shields.io/pypi/l/kiwoompy)](LICENSE)
+
+## 설치
+
+```bash
+pip install kiwoompy
+```
+
+uv 사용 시:
+
+```bash
+uv add kiwoompy
+```
+
+Python 3.12 이상이 필요합니다.
+
+## 사전 준비
+
+[키움증권 OpenAPI](https://openapi.kiwoom.com)에서 앱을 등록하고 **App Key** / **App Secret**을 발급받아야 합니다.
+
+> **주의** — App Key와 App Secret은 코드에 직접 넣지 마세요. 환경 변수나 시크릿 매니저로 관리하세요.
+
+## 빠른 시작
+
+```python
+from kiwoompy import KiwoomClient
+
+client = KiwoomClient(
+    env="demo",               # "demo"(모의투자) / "real"(실계좌)
+    appkey="YOUR_APP_KEY",
+    secretkey="YOUR_APP_SECRET",
+)
+
+# 계좌 잔고 조회
+balance = client.query.get_account_balance()
+print(balance.tot_evlt_amt)   # 총평가금액
+
+for item in balance.holdings:
+    print(item.stk_nm, item.evlt_amt)
+```
+
+```python
+# 시장가 매수
+result = client.order.buy("005930", quantity="1", trade_type="market")
+print(result.ord_no)
+
+# 지정가 매도
+client.order.sell("005930", quantity="1", trade_type="limit", price="75000")
+```
+
+context manager도 지원합니다.
+
+```python
+with KiwoomClient(env="demo", appkey="...", secretkey="...") as client:
+    deposit = client.query.get_deposit(query_type="normal")
+    print(deposit.entr)   # 예수금
+```
+
+## 기능
+
+- **OAuth2 인증** — 접근토큰 발급·만료 자동 관리
+- **환경 분리** — 모의투자 / 실계좌 한 줄로 전환
+- **유량 제어** — 모의 2건/초, 실전 20건/초 자동 적용
+- **자동 재시도** — 네트워크 오류·5xx 지수 백오프 재시도 (최대 3회)
+- **입력값 보완** — 계좌번호 상품코드 누락 시 자동 보완
+- **타입 힌트** — IDE 자동완성·정적 분석 지원
+
+## 에러 처리
+
+```python
+from kiwoompy import KiwoomAuthError, KiwoomApiError
+
+try:
+    client = KiwoomClient(env="demo", appkey="wrong", secretkey="wrong")
+except KiwoomAuthError as e:
+    print(f"인증 실패: {e}")
+except KiwoomApiError as e:
+    print(f"API 오류: {e}")
+```
+
+| 예외 | 발생 조건 |
+|------|-----------|
+| `KiwoomAuthError` | 잘못된 키, 토큰 미발급 상태에서 API 호출 |
+| `KiwoomApiError` | 네트워크 오류, 5xx 서버 오류, 응답 파싱 실패 |
+
+## 문서
+
+전체 사용법과 API 레퍼런스는 문서 사이트를 참고해 주세요.
+
+👉 **https://meonji-gogo.github.io/kiwoompy**
+
+## 키움증권 REST API 공지 알리미
+
+키움증권 REST API 공지사항·변경 사항을 텔레그램으로 받아볼 수 있습니다.
+
+👉 **https://t.me/+2do4kWIhBmg3OTM1**
+
+## 라이선스
+
+MIT

kiwoompy-0.1.2/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "kiwoompy"
+version = "0.1.2"
+description = "키움증권 REST API Python 라이브러리"
+readme = "README.md"
+authors = [
+    { name = "meonji-gogo", email = "meonji-gogo@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "tenacity>=9.1.4",
+    "websockets>=16.0",
+]
+
+[dependency-groups]
+docs = [
+    "mkdocs-material>=9.6,<10",
+    "mkdocs>=1.6,<2",
+    "mkdocstrings[python]>=0.29",
+]
+
+dev = [
+    "pytest-mock>=3.15.1",
+    "python-dotenv>=1.2.1",
+]
+
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--ignore=tests/e2e"
+markers = [
+    "mock: 단위 테스트, 외부 의존 없음 (CI 실행)",
+    "demo: 모의투자 환경 e2e 테스트 (로컬 전용)",
+    "real: 실계좌 환경 e2e 테스트 (로컬 전용, 실제 주문 발생 가능)",
+]