# KV 저장소 활용하기

PyQQQ SDK의 `KVStore` 모듈은 간단한 키-값 저장소 기능을 제공합니다. 이 모듈을 통해 다양한 데이터 타입을 저장하고 불러올 수 있으며 데이터의 지속성을 보장합니다.


## 기본 사용법

### 키-값 저장과 조회

`set` 과 `get` 메서드는 데이터를 저장하고 읽는데 가장 기본적이며 핵심적인 역할을 합니다. 다양한 데이터 타입을 저장하고 읽어보면서 배워봅시다.


```python
from pyqqq.utils.kvstore import KVStore

# KVStore 인스턴스 생성
store = KVStore()

# 1. 문자열 (str) 타입 저장 및 조회
store.set("greeting_message", "Hello, World!")
print(store.get("greeting_message"))  # 출력: Hello, World!

# 2. 부울 (bool) 타입 저장 및 조회
store.set("is_user_active", True)
store.set("has_access", False)
print(store.get("is_user_active"))  # 출력: True
print(store.get("has_access"))  # 출력: False

# 3. 정수 (int) 타입 저장 및 조회
store.set("total_users", 42)
print(store.get("total_users"))  # 출력: 42

# 4. 실수 (float) 타입 저장 및 조회
store.set("pi_value", 3.14159)
print(store.get("pi_value"))  # 출력: 3.14159

# 5. 딕셔너리 (dict) 타입 저장 및 조회
store.set("user_profile", {"name": "Alice", "age": 30})
print(store.get("user_profile"))  # 출력: {'name': 'Alice', 'age': 30}

# 6. 리스트 (list) 타입 저장 및 조회
store.set("prime_numbers", [2, 3, 5, 7, 11])
print(store.get("prime_numbers"))  # 출력: [2, 3, 5, 7, 11]

# 7. None 타입 저장 및 조회
store.set("optional_field", None)
print(store.get("optional_field"))  # 출력: None

# 추가 예제: 복합 데이터 구조
store.set("dashboard_stats", {
    "total_sales": 1500.75,
    "is_goal_met": True,
    "daily_visits": [120, 95, 130, 110],
    "metadata": {"region": "North America", "manager": "Bob"}
})
print(store.get("dashboard_stats"))
# 출력: {'total_sales': 1500.75, 'is_goal_met': True, 'daily_visits': [120, 95, 130, 110], 'metadata': {'region': 'North America', 'manager': 'Bob'}}

```

### 데이터 삭제

더 이상 사용하지 않는 데이터는 `delete` 메소드로 삭제할 수 있습니다.

```python
from pyqqq.utils.kvstore import KVStore

# KVStore 인스턴스 생성
store = KVStore()

# 1. 키-값 저장
store.set("username", "john_doe")
store.set("is_logged_in", True)
store.set("user_profile", {"name": "Alice", "age": 30})

# 2. 데이터 조회
print(store.get("username"))  # 출력: john_doe
print(store.get("is_logged_in"))  # 출력: True
print(store.get("user_profile"))  # 출력: {'name': 'Alice', 'age': 30}

# 3. 데이터 삭제
store.delete("username")  # 'username' 키 삭제
store.delete("non_existing_key")  # 존재하지 않는 키 삭제 시도 (에러 없음)

# 4. 삭제 후 데이터 확인
print(store.get("username"))  # 출력: None (삭제됨)
print(store.get("is_logged_in"))  # 출력: True (삭제되지 않음)
print(store.get("user_profile"))  # 출력: {'name': 'Alice', 'age': 30} (삭제되지 않음)

# 5. 여러 키 삭제
store.set("temp_key1", "temp_value1")
store.set("temp_key2", "temp_value2")
store.clear()  # 여러 키 삭제
print(store.get("temp_key1"))  # 출력: None
print(store.get("temp_key2"))  # 출력: None

```

```{important}
`clear` 메소드는 해당 KVStore 인스턴스의 모든 키를 삭제합니다.
```


### 컨텍스트를 이용한 데이터 분리

`KVStore`의 컨텍스트 개념을 통해 저장소를 논리적으로 분리시켜 사용할 수 있습니다. 주로, 저장하고자 하는 데이터 성격(유형)에 맞춰 저장소를 구분하여 사용합니다. 코스피 거래 데이터를 `KVStore("kospi")`에 저장하고, 코스닥 거래 데이터는 `KVStore("kosdaq")`로 구분하여 각각 독립적으로 운용할 수 있습니다.

```python
from pyqqq.utils.kvstore import KVStore

# 1. 기본 KVStore 생성 (컨텍스트 없이)
global_store = KVStore()
global_store.set("app_name", "MyApp")
print(global_store.get("app_name"))  # 출력: MyApp

# 2. context_name을 이용한 KVStore 생성
user_store = KVStore(context_name="user_data")
admin_store = KVStore(context_name="admin_data")

# 3. 각 컨텍스트에 데이터 저장
user_store.set("username", "john_doe")
user_store.set("email", "john.doe@example.com")

admin_store.set("username", "admin_user")
admin_store.set("permissions", ["read", "write", "delete"])

# 4. 컨텍스트별 데이터 조회
print(user_store.get("username"))  # 출력: john_doe
print(user_store.get("email"))     # 출력: john.doe@example.com

print(admin_store.get("username"))    # 출력: admin_user
print(admin_store.get("permissions"))  # 출력: ['read', 'write', 'delete']

# 5. 다른 컨텍스트 간 데이터 격리 확인
print(global_store.get("username"))  # 출력: None (다른 컨텍스트의 데이터)
print(user_store.get("permissions")) # 출력: None (admin_data 컨텍스트 데이터)

# 6. 데이터 삭제 (특정 컨텍스트)
user_store.delete("email")
print(user_store.get("email"))  # 출력: None (삭제됨)
print(admin_store.get("username"))  # 출력: admin_user (영향 없음)

# 7. 컨텍스트 활용 예제: 사용자별 설정 관리
alice_store = KVStore(context_name="user:alice")
bob_store = KVStore(context_name="user:bob")

alice_store.set("theme", "dark")
bob_store.set("theme", "light")

print(alice_store.get("theme"))  # 출력: dark
print(bob_store.get("theme"))    # 출력: light

```

## 활용 사례

### KVStore를 사용하여 환경변수 대체하기

```python
import os
import dotenv
from pyqqq.utils.kvstore import KVStore

dotenv.load_dotenv()
store = KVStore("misc")

# 1. 환경변수 읽기
bot_token = os.getenv("TELEGRAM_API_TOKEN")
print(bot_token)

# 2. 환경변수를 KVStore에 저장
if store.get("TELEGRAM_API_TOKEN") === None:
    store.set("TELEGRAM_API_TOKEN", bot_token)

# 3. 앞으로 bot_token 읽기
bot_token = store.get("TELEGRAM_API_TOKEN") or os.getenv("TELEGRAM_API_TOKEN")
print(bot_token)

```