cluefin-openapi 0.1.0__tar.gz

cluefin_openapi-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.so
+*.pyd
+
+# C extensions
+*.c
+*.cpp
+
+# Distribution / packaging
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+MANIFEST
+*.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/
+test-results/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VS Code
+.vscode/
+.code-workspace
+
+# PyCharm
+.idea/
+*.iml
+
+# macOS
+.DS_Store
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+# Lock files
+Pipfile.lock
+poetry.lock
+uv.lock
+
+# Project-specific
+packages/*/src/*/__pycache__/
+packages/*/src/*/*.py[cod]
+
+# Environment variables
+.env.*

cluefin_openapi-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: cluefin-openapi
+Version: 0.1.0
+Summary: OpenAPI Client for Cluefin
+Author-email: Hangoo Kang <kgcrom@hotmail.com>
+Requires-Python: >=3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: requests>=2.32.4
+Provides-Extra: kiwoom
+Description-Content-Type: text/markdown
+
+# cluefin-openapi
+
+> **cluefin-openapi**: A Python client for Kiwoom Securities investment REST API.
+
+---
+
+## Features
+- Account information retrieval
+- Domestic/foreign stock info
+- Chart data and analytics
+- ETF, sector, theme, and market condition support
+- Order management and real-time updates
+
+## Quickstart
+```bash
+$> pip install cluefin-openapi
+or
+$> pip install cluefin-openapi[kiwoom]
+```
+
+```python
+from cluefin_openapi.kiwoom._auth import Auth
+from cluefin_openapi.kiwoom._client import Client
+
+auth = Auth(
+    app_key=os.getenv("APP_KEY"),
+    secret_key=os.getenv("SECRET_KEY"),
+    env="dev",
+)
+
+token = auth.generate_token()
+client = Client(token=token.token, env="dev")
+
+response = client.account.get_daily_stock_realized_profit_loss_by_date("005930", "20250630")
+print(response.headers)
+print(response.body)
+```
+
+## Why cluefin-openapi?
+Easily access investment data and trading features from Kiwoom Securities, DART, KRX, and more—all through a unified Python interface.
+Save time integrating with multiple financial APIs and focus on building your investment tools.
+
+## Getting Started
+1. Install via pip
+2. Obtain your Kiwoom REST API credentials
+3. See [examples](./test/integration/kiwoom/) for more usage
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+---
+
+*Invest responsibly. This project is not affiliated with Kiwoom Securities.*

cluefin_openapi-0.1.0/README.md

@@ -0,0 +1,53 @@
+# cluefin-openapi
+
+> **cluefin-openapi**: A Python client for Kiwoom Securities investment REST API.
+
+---
+
+## Features
+- Account information retrieval
+- Domestic/foreign stock info
+- Chart data and analytics
+- ETF, sector, theme, and market condition support
+- Order management and real-time updates
+
+## Quickstart
+```bash
+$> pip install cluefin-openapi
+or
+$> pip install cluefin-openapi[kiwoom]
+```
+
+```python
+from cluefin_openapi.kiwoom._auth import Auth
+from cluefin_openapi.kiwoom._client import Client
+
+auth = Auth(
+    app_key=os.getenv("APP_KEY"),
+    secret_key=os.getenv("SECRET_KEY"),
+    env="dev",
+)
+
+token = auth.generate_token()
+client = Client(token=token.token, env="dev")
+
+response = client.account.get_daily_stock_realized_profit_loss_by_date("005930", "20250630")
+print(response.headers)
+print(response.body)
+```
+
+## Why cluefin-openapi?
+Easily access investment data and trading features from Kiwoom Securities, DART, KRX, and more—all through a unified Python interface.
+Save time integrating with multiple financial APIs and focus on building your investment tools.
+
+## Getting Started
+1. Install via pip
+2. Obtain your Kiwoom REST API credentials
+3. See [examples](./test/integration/kiwoom/) for more usage
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+---
+
+*Invest responsibly. This project is not affiliated with Kiwoom Securities.*

cluefin_openapi-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "cluefin-openapi"
+version = "0.1.0"
+description = "OpenAPI Client for Cluefin"
+readme = "README.md"
+authors = [
+    { name = "Hangoo Kang", email = "kgcrom@hotmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "loguru>=0.7.3",
+    "pydantic>=2.11.7",
+    "requests>=2.32.4",
+]
+
+[project.optional-dependencies]
+kiwoom = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cluefin_openapi"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+include = ["src/**", "tests/**"]

cluefin_openapi-0.1.0/src/cluefin_openapi/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from cluefin-openapi!")

cluefin_openapi-0.1.0/src/cluefin_openapi/kiwoom/__init__.py

@@ -0,0 +1,31 @@
+"""Cluefin Kiwoom API Client Package."""
+
+from ._auth import Auth
+from ._client import Client
+from ._exceptions import (
+    KiwoomAPIError,
+    KiwoomAuthenticationError,
+    KiwoomAuthorizationError,
+    KiwoomNetworkError,
+    KiwoomRateLimitError,
+    KiwoomServerError,
+    KiwoomTimeoutError,
+    KiwoomValidationError,
+)
+
+__all__ = [
+    "Auth",
+    "Client",
+    "KiwoomAPIError",
+    "KiwoomAuthenticationError",
+    "KiwoomAuthorizationError",
+    "KiwoomNetworkError",
+    "KiwoomRateLimitError",
+    "KiwoomServerError",
+    "KiwoomTimeoutError",
+    "KiwoomValidationError",
+]
+
+
+def hello() -> str:
+    return "Hello from cluefin-kiwoom!"

cluefin_openapi-0.1.0/src/cluefin_openapi/kiwoom/_auth.py

@@ -0,0 +1,96 @@
+"""Authentication module for Kiwoom API.
+
+This module provides functionality for generating and revoking API tokens
+using client credentials authentication flow.
+"""
+
+from typing import Literal
+
+import requests
+
+from ._auth_types import TokenResponse
+
+
+class Auth:
+    """Initialize the Auth client.
+
+    Args:
+        app_key: The application key provided by Kiwoom.
+        secret_key: The secret key provided by Kiwoom.
+        env: The environment to use. Either "dev" or "prod".
+            Defaults to "dev".
+
+    Raises:
+        ValueError: If an invalid environment is provided.
+    """
+
+    def __init__(self, app_key: str, secret_key: str, env: Literal["dev", "prod"] = "dev") -> None:
+        self.app_key = app_key
+        self.secret_key = secret_key
+
+        if env == "dev":
+            self.url = "https://mockapi.kiwoom.com"
+        elif env == "prod":
+            self.url = "https://api.kiwoom.com"
+        else:
+            raise ValueError("Invalid environment. Must be either 'dev' or 'prod'.")
+
+    @property
+    def token(self) -> TokenResponse:
+        """Get the current token data.
+
+        Returns:
+            TokenResponse: The current token data.
+
+        Raises:
+            AttributeError: If no token has been generated yet.
+        """
+        return self._token_data
+
+    def generate_token(self) -> TokenResponse:
+        """Generate a new access token.
+
+        Calls the Kiwoom OAuth2 token endpoint to generate a new access token
+        using the client credentials flow.
+
+        Returns:
+            TokenResponse: The generated token data including access token
+                and expiration.
+
+        Raises:
+            requests.exceptions.HTTPError: If the API request fails.
+        """
+        headers = {
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+        data = {"grant_type": "client_credentials", "appkey": self.app_key, "secretkey": self.secret_key}
+
+        response = requests.post(f"{self.url}/oauth2/token", headers=headers, json=data)
+        response.raise_for_status()
+
+        token_data = TokenResponse(**response.json())
+        self._token_data = token_data
+
+        return self._token_data
+
+    def revoke_token(self, token: str) -> bool:
+        """Revoke an access token.
+
+        Args:
+            token: The token to revoke.
+        Returns:
+            bool: True if the token was successfully revoked.
+
+        Raises:
+            requests.exceptions.HTTPError: If the API request fails.
+        """
+        headers = {
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        data = {"appkey": self.app_key, "secretkey": self.secret_key, "token": token}
+
+        response = requests.post(f"{self.url}/oauth2/revoke", headers=headers, json=data)
+        response.raise_for_status()
+
+        return True

cluefin_openapi-0.1.0/src/cluefin_openapi/kiwoom/_auth_types.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+
+from pydantic import BaseModel, field_validator
+
+
+class TokenResponse(BaseModel):
+    expires_dt: datetime
+    token_type: str
+    token: str
+
+    @field_validator("expires_dt", mode="before")
+    def parse_expires_dt(cls, v):
+        if isinstance(v, str):
+            try:
+                return datetime.strptime(v, "%Y%m%d%H%M%S")
+            except ValueError:
+                pass  # 다른 형식도 추가 가능
+        return v

cluefin_openapi-0.1.0/src/cluefin_openapi/kiwoom/_cache.py

@@ -0,0 +1,130 @@
+"""Caching utilities for Kiwoom API client."""
+
+import hashlib
+import time
+from typing import Any, Dict, Optional
+
+
+class SimpleCache:
+    """Simple in-memory cache with TTL support."""
+
+    def __init__(self, default_ttl: int = 300):
+        """
+        Initialize cache.
+
+        Args:
+            default_ttl: Default time-to-live in seconds (default: 5 minutes)
+        """
+        self.default_ttl = default_ttl
+        self._cache: Dict[str, Dict[str, Any]] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        if key in self._cache:
+            entry = self._cache[key]
+            if time.time() < entry["expires_at"]:
+                return entry["value"]
+            else:
+                # Remove expired entry
+                del self._cache[key]
+        return None
+
+    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """
+        Set value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (uses default if None)
+        """
+        if ttl is None:
+            ttl = self.default_ttl
+
+        self._cache[key] = {
+            "value": value,
+            "expires_at": time.time() + ttl,
+            "created_at": time.time(),
+        }
+
+    def delete(self, key: str) -> bool:
+        """
+        Delete key from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if key was deleted, False if not found
+        """
+        if key in self._cache:
+            del self._cache[key]
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()
+
+    def cleanup_expired(self) -> int:
+        """
+        Remove expired entries from cache.
+
+        Returns:
+            Number of entries removed
+        """
+        current_time = time.time()
+        expired_keys = [key for key, entry in self._cache.items() if current_time >= entry["expires_at"]]
+
+        for key in expired_keys:
+            del self._cache[key]
+
+        return len(expired_keys)
+
+    def cache_info(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        current_time = time.time()
+        valid_entries = sum(1 for entry in self._cache.values() if current_time < entry["expires_at"])
+
+        return {
+            "total_entries": len(self._cache),
+            "valid_entries": valid_entries,
+            "expired_entries": len(self._cache) - valid_entries,
+        }
+
+
+def create_cache_key(url: str, headers: Dict[str, str], body: Dict[str, Any]) -> str:
+    """
+    Create a cache key from request parameters.
+
+    Args:
+        url: Request URL
+        headers: Request headers (excluding auth and dynamic headers)
+        body: Request body
+
+    Returns:
+        Cache key string
+    """
+    # Filter out dynamic headers that shouldn't affect caching
+    cacheable_headers = {
+        k: v for k, v in headers.items() if k.lower() not in ["authorization", "user-agent", "content-length"]
+    }
+
+    # Create a deterministic string representation
+    cache_data = {
+        "url": url,
+        "headers": sorted(cacheable_headers.items()),
+        "body": sorted(body.items()) if isinstance(body, dict) else body,
+    }
+
+    # Create hash of the cache data
+    cache_string = str(cache_data)
+    return hashlib.sha256(cache_string.encode()).hexdigest()[:16]  # First 16 chars for brevity