Metadata-Version: 2.4
Name: candle-data-manager
Version: 0.2.0
Summary: Fetch, store, and manage OHLCV candle data from cryptocurrency exchanges (Binance, Upbit) with MySQL storage
Project-URL: Homepage, https://gatesplan-mathgate.com
Project-URL: Repository, https://github.com/gatesplan/candle-data-manager
Project-URL: Issues, https://github.com/gatesplan/candle-data-manager/issues
Author-email: fishfactory <gatesplan@gmail.com>
License: MIT License
        
        Copyright (c) 2026 fishfactory
        
        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
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
Requires-Python: >=3.10
Requires-Dist: binance-connector>=3.0.0
Requires-Dist: finance-datareader>=0.9.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pymysql>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyupbit>=0.2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Candle Data Manager

암호화폐 및 주식 시장의 OHLCV 캔들 데이터를 수집, 저장, 관리하는 패키지.
OHLCV candle data fetch, store, manage for cryptocurrency and stock markets.

## Installation

```bash
pip install candle-data-manager
```

## Requirements

- Python >= 3.10
- MySQL Server

### .env

인증이 필요한 거래소의 API 키를 설정한다.
API key is required for exchanges that need authentication.

```env
# Binance
BINANCE_API_KEY=your_binance_api_key
BINANCE_API_SECRET=your_binance_api_secret

# Upbit
UPBIT_API_KEY=your_upbit_api_key
UPBIT_API_SECRET=your_upbit_api_secret

# KRX OpenAPI (선택사항 / optional)
KRX_API_KEY=your_krx_api_key
```

**KRX**는 두 가지 provider를 지원한다:
**KRX** supports two providers:

- **KRXProvider** (primary): KRX OpenAPI (openapi.krx.co.kr) 사용. `KRX_API_KEY` 필요.
  Uses KRX OpenAPI. Requires `KRX_API_KEY`.
- **KRXFallbackProvider** (fallback): FinanceDataReader 사용. API 키 불필요.
  Uses FinanceDataReader. No API key required.

`KRX_API_KEY`가 설정되지 않으면 자동으로 FinanceDataReader로 전환된다.
If `KRX_API_KEY` is not set, automatically falls back to FinanceDataReader.

### KRX OpenAPI 설정 / KRX OpenAPI Setup

KRX OpenAPI는 활성화를 위해 **2단계 절차**가 필요하다.
KRX OpenAPI requires **two separate steps** to activate:

1. **API 키 발급**: [openapi.krx.co.kr](https://openapi.krx.co.kr/)에 회원가입 후 마이페이지에서 API 키를 신청한다.
   Sign up at [openapi.krx.co.kr](https://openapi.krx.co.kr/), go to My Page, request an API key.

2. **서비스별 개별 승인**: API 키를 받은 후, 사용할 데이터 서비스를 **각각 별도로 신청**해야 한다. "서비스 이용" 메뉴에서 원하는 서비스를 선택하고 하단의 "API 이용신청" 버튼을 클릭한다.
   After receiving the key, you must **individually apply** for each data service. Go to "Service Usage" menu, select the service, and click "API Usage Request" at the bottom.

필요한 서비스:
Required services:
- 유가증권 일별매매정보 / Securities Daily Trading Info (`sto/stk_bydd_trd`) - KOSPI
- 코스닥 일별매매정보 / KOSDAQ Daily Trading Info (`sto/ksq_bydd_trd`) - KOSDAQ

각 서비스는 관리자 승인이 필요하다 (보통 1일 이내). 키와 서비스 모두 승인될 때까지 API 호출 시 **401 Unauthorized**가 반환된다.
Each service requires admin approval (usually within 1 day). API calls will return **401 Unauthorized** until both the key and the service are approved.

NASDAQ, NYSE는 FinanceDataReader를 통해 제공된다. API 키 불필요.
NASDAQ, NYSE are provided via FinanceDataReader. No API key required.

## Quick Start

```python
from candle_data_manager import CandleDataAPI

api = CandleDataAPI()

# BTC/USDT 1d 캔들 수집 및 저장
# BTC/USDT 1d candle: fetch and store
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1d"
)

# DB에서 로드
# load from DB
markets = api.load(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1d"
)
print(markets[0].candles)  # pandas DataFrame (OHLCV)

api.close()
```

## API Reference

### CandleDataAPI(database_url=None)

```python
# 기본값 / default: mysql+pymysql://root@localhost/candle_data_manager
api = CandleDataAPI()

# 커스텀 / custom
api = CandleDataAPI(database_url="mysql+pymysql://user:pass@host/dbname")
```

초기화 시 DB와 테이블이 자동 생성된다.
DB and tables are auto-created on init.

---

### active_update(archetype, exchange, tradetype, base, quote, timeframe)

거래소 마켓 리스트에서 새 심볼을 등록하고 전체 과거 데이터를 수집한다.
Register new symbols from exchange market list and fetch all historical data.

```python
# 모든 Binance Spot 마켓, 모든 타임프레임
# all Binance Spot markets, all timeframes
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT"
)

# 필터: 특정 base/quote/timeframe
# filtered: specific base/quote/timeframe
result = api.active_update(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base=["BTC", "ETH"],
    quote="USDT",
    timeframe=["1h", "1d"]
)

# KRX 주식
# KRX stocks
result = api.active_update(
    archetype="STOCK",
    exchange="KRX",
    tradetype="SPOT",
    base="005930",
    timeframe="1d"
)
```

**Parameters:**
- `archetype` (str): "CRYPTO" 또는 "STOCK" / "CRYPTO" or "STOCK"
- `exchange` (str): "BINANCE", "UPBIT", "KRX", "NASDAQ", "NYSE"
- `tradetype` (str): "SPOT" 또는 "FUTURES" / "SPOT" or "FUTURES"
- `base` (str | list[str], optional): base 자산으로 필터 / filter by base asset
- `quote` (str | list[str], optional): quote 자산으로 필터 / filter by quote asset
- `timeframe` (str | list[str], optional): 타임프레임으로 필터. None = 지원하는 전체 / filter by timeframe. None = all supported

**Returns:** `UpdateResult(success_symbols, failed_symbols, total_rows)`

---

### passive_update(archetype, exchange, tradetype, base, quote, timeframe, buffer_size)

등록된 심볼의 증분 업데이트. 마지막 저장 시점부터 현재까지 수집한다.
Incremental update for registered symbols. Fetches from last stored timestamp (inclusive) to now.

```python
# 등록된 모든 Binance 심볼 업데이트
# update all registered Binance symbols
result = api.passive_update(
    exchange="BINANCE"
)

# 특정 조건으로 업데이트
# update specific conditions
result = api.passive_update(
    archetype="CRYPTO",
    exchange="UPBIT",
    tradetype="SPOT"
)
```

모든 파라미터는 선택사항. None = 필터 없음 (조건에 맞는 모든 등록 심볼 업데이트).
All parameters are optional. None = no filter (updates all registered symbols matching conditions).

**Returns:** `UpdateResult(success_symbols, failed_symbols, total_rows)`

---

### load(archetype, exchange, tradetype, base, quote, timeframe, start_at, end_at, limit)

DB에서 캔들 데이터를 Market 객체로 로드한다.
Load candle data from DB as Market objects.

```python
markets = api.load(
    archetype="CRYPTO",
    exchange="BINANCE",
    tradetype="SPOT",
    base="BTC",
    quote="USDT",
    timeframe="1h",
    start_at=1609459200,    # unix timestamp (sec)
    end_at=1609545600
)

for market in markets:
    print(market.symbol.to_string())  # "CRYPTO-BINANCE-SPOT-BTC-USDT-1h"
    print(market.candles)             # pandas DataFrame
    #    timestamp       open       high        low      close     volume
    # 0  1609459200  29000.50   29100.00   28900.00  29050.00   1234.56
```

모든 파라미터는 선택사항. `list[Market]`을 반환한다.
All parameters are optional. Returns `list[Market]`.

---

### get_symbol(symbol_str)

```python
symbol = api.get_symbol("CRYPTO-BINANCE-SPOT-BTC-USDT-1h")
# Symbol 객체 또는 None 반환
# Returns Symbol object or None
```

---

### close()

```python
api.close()
```

## Supported Providers

지원하는 Provider 목록.
List of supported providers.

| Provider | archetype | exchange | tradetype | timeframes |
|----------|-----------|----------|-----------|------------|
| Binance Spot | CRYPTO | BINANCE | SPOT | 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M |
| Binance Futures | CRYPTO | BINANCE | FUTURES | 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M |
| Upbit | CRYPTO | UPBIT | SPOT | 1m, 3m, 5m, 10m, 30m, 1h, 4h, 1d, 1w, 1M |
| KRX | STOCK | KRX | SPOT | 1d |
| NASDAQ | STOCK | NASDAQ | SPOT | 1d |
| NYSE | STOCK | NYSE | SPOT | 1d |

## Symbol Format

심볼 문자열 형식.
Symbol string format.

`ARCHETYPE-EXCHANGE-TRADETYPE-BASE-QUOTE-TIMEFRAME`

```
CRYPTO-BINANCE-SPOT-BTC-USDT-1h
CRYPTO-UPBIT-SPOT-BTC-KRW-1d
STOCK-KRX-SPOT-005930-KRW-1d
STOCK-NASDAQ-SPOT-AAPL-USD-1d
```

## License

MIT License
