financechatbotkit 2.0.0__tar.gz

financechatbotkit-2.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: financechatbotkit
+Version: 2.0.0
+Summary: FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)
+Requires-Python: >=3.11
+Requires-Dist: finance-datareader==0.9.110
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: google-cloud-firestore>=2.16.0
+Requires-Dist: google-api-core>=2.15.0
+Requires-Dist: google-auth>=2.28.0
+Requires-Dist: openpyxl>=3.1.0

financechatbotkit-2.0.0/README.md

@@ -0,0 +1,52 @@
+## FinanceChatbot
+
+Unified finance workflow library (orchestrator) for:
+
+- `mapping`
+- `price`
+- `fnguide`
+- `bond`
+
+### Public API
+
+Each feature lives at the same level:
+
+```python
+from orchestrator.mapping import MappingWorkflow
+from orchestrator.price import PricePeriodWorkflow
+from orchestrator.fnguide import FnGuideWorkflow
+from orchestrator.bond import MarketBondWorkflow
+```
+
+All workflows return:
+
+```python
+{
+    "input": {...},
+    "data": {...},
+}
+```
+
+`price` workflows support `price_fields="close"` (default), `price_fields="oclh"`, and `price_fields="oclhv"` to control which price columns are returned.
+
+---
+
+## TeleBotKit
+
+`TeleBotKit` is a shared utility library that lives under `src/telebotkit` and is packaged together with this project.
+
+It provides helpers for:
+
+- Telegram bot command parsing, routing, MarkdownV2 escaping, and reply payload generation (`telebotkit.bot`)
+- Firestore client bootstrap, typed repositories, shared document access, and lease/lock helpers (`telebotkit.firestore`)
+- Excel row parsing and typed JSON payload generation for Firestore imports (`telebotkit.sheets`)
+
+### Example usage
+
+```python
+from telebotkit.bot import Reply, Router
+from telebotkit.firestore import DocumentStore, get_client
+from telebotkit.sheets import build_typed_rows_payload_from_xlsx
+```
+
+See `src/telebotkit/README.md` for full API documentation and examples.

financechatbotkit-2.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "financechatbotkit"
+version = "2.0.0"
+description = "FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)"
+requires-python = ">=3.11"
+dependencies = [
+    "finance-datareader==0.9.110",
+    "httpx>=0.27,<1",
+    "google-cloud-firestore>=2.16.0",
+    "google-api-core>=2.15.0",
+    "google-auth>=2.28.0",
+    "openpyxl>=3.1.0",
+]
+
+[project.scripts]
+orchestrator-update-corp-codes = "orchestrator.mapping.update_raw_data:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["orchestrator*", "telebotkit*"]
+
+[tool.setuptools.package-data]
+"orchestrator.mapping" = ["data/*.json"]

financechatbotkit-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: financechatbotkit
+Version: 2.0.0
+Summary: FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)
+Requires-Python: >=3.11
+Requires-Dist: finance-datareader==0.9.110
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: google-cloud-firestore>=2.16.0
+Requires-Dist: google-api-core>=2.15.0
+Requires-Dist: google-auth>=2.28.0
+Requires-Dist: openpyxl>=3.1.0

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/SOURCES.txt

@@ -0,0 +1,47 @@
+README.md
+pyproject.toml
+src/financechatbotkit.egg-info/PKG-INFO
+src/financechatbotkit.egg-info/SOURCES.txt
+src/financechatbotkit.egg-info/dependency_links.txt
+src/financechatbotkit.egg-info/entry_points.txt
+src/financechatbotkit.egg-info/requires.txt
+src/financechatbotkit.egg-info/top_level.txt
+src/orchestrator/__init__.py
+src/orchestrator/exceptions.py
+src/orchestrator/bond/__init__.py
+src/orchestrator/bond/base_reader.py
+src/orchestrator/bond/getBondBasiInfo.py
+src/orchestrator/bond/getBondWithOptiCallRede.py
+src/orchestrator/bond/getEarlExerOpti.py
+src/orchestrator/bond/getIssuIssuItemStat.py
+src/orchestrator/bond/getOptiExer.py
+src/orchestrator/bond/getOptiExerPricAdju.py
+src/orchestrator/bond/workflow.py
+src/orchestrator/fnguide/__init__.py
+src/orchestrator/fnguide/workflow.py
+src/orchestrator/mapping/__init__.py
+src/orchestrator/mapping/update_raw_data.py
+src/orchestrator/mapping/workflow.py
+src/orchestrator/mapping/data/__init__.py
+src/orchestrator/mapping/data/corp_codes_raw.json
+src/orchestrator/price/__init__.py
+src/orchestrator/price/workflow.py
+src/telebotkit/__init__.py
+src/telebotkit/sheets.py
+src/telebotkit/bot/__init__.py
+src/telebotkit/bot/client.py
+src/telebotkit/bot/reply.py
+src/telebotkit/bot/router.py
+src/telebotkit/bot/safety.py
+src/telebotkit/bot/telegram.py
+src/telebotkit/firestore/__init__.py
+src/telebotkit/firestore/client.py
+src/telebotkit/firestore/documents.py
+src/telebotkit/firestore/fetch.py
+src/telebotkit/firestore/locks.py
+src/telebotkit/firestore/upload.py
+tests/test_bond_workflow.py
+tests/test_fnguide_workflow.py
+tests/test_price_workflow.py
+tests/test_update_raw_data.py
+tests/test_workflow.py

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orchestrator-update-corp-codes = orchestrator.mapping.update_raw_data:main

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/requires.txt

@@ -0,0 +1,6 @@
+finance-datareader==0.9.110
+httpx<1,>=0.27
+google-cloud-firestore>=2.16.0
+google-api-core>=2.15.0
+google-auth>=2.28.0
+openpyxl>=3.1.0

financechatbotkit-2.0.0/src/financechatbotkit.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+orchestrator
+telebotkit

financechatbotkit-2.0.0/src/orchestrator/__init__.py

@@ -0,0 +1,29 @@
+"""FinanceChatbot workflow library."""
+
+from .bond import MarketBondWorkflow, run_market_bond_workflow
+from .exceptions import DownloadError, InvalidInputError, MappingWorkflowError, NotFoundError
+from .fnguide import FnGuideWorkflow, run_fnguide_workflow
+from .mapping import MappingWorkflow, run_mapping_workflow
+from .price import (
+    PricePeriodWorkflow,
+    PriceSnapshotWorkflow,
+    run_price_period_workflow,
+    run_price_snapshot_workflow,
+)
+
+__all__ = [
+    "DownloadError",
+    "FnGuideWorkflow",
+    "InvalidInputError",
+    "MappingWorkflow",
+    "MappingWorkflowError",
+    "MarketBondWorkflow",
+    "NotFoundError",
+    "PricePeriodWorkflow",
+    "PriceSnapshotWorkflow",
+    "run_fnguide_workflow",
+    "run_market_bond_workflow",
+    "run_mapping_workflow",
+    "run_price_period_workflow",
+    "run_price_snapshot_workflow",
+]

financechatbotkit-2.0.0/src/orchestrator/bond/__init__.py

@@ -0,0 +1,8 @@
+"""Bond workflows for FinanceChatbot."""
+
+from .workflow import MarketBondWorkflow, run_market_bond_workflow
+
+__all__ = [
+    "MarketBondWorkflow",
+    "run_market_bond_workflow",
+]

financechatbotkit-2.0.0/src/orchestrator/bond/base_reader.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from typing import Any
+
+import re
+import httpx
+
+
+def get_datagokr_data(
+    serviceUrl: str, params: dict[str, Any], timeout_seconds: float = 60.0
+) -> Any | None:
+    """ Datagokr API를 호출해서 응답 JSON을 반환한다. """
+    baseUrl = "http://apis.data.go.kr"
+    url = f"{baseUrl}/{serviceUrl}"
+    try:
+        resp = httpx.get(url, params=params, timeout=timeout_seconds)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception:
+        return None
+
+def get_datagokr_document(
+    serviceUrl: str, params: dict[str, Any], timeout_seconds: float = 60.0,
+    numOfRows: int = 100, resultType: str = "json",
+) -> Any | None:
+    """
+    Datagokr API를 반복 호출해서 응답 JSON을 반환한다.
+    1. `pageNo = 1`부터 `pageNo = totalCount / numOfRows` 페이지까지 반복 호출한다.
+    2. 각 페이지의 items를 모두 모아서 반환한다. 
+        반환 형식은 기본 형식과 동일하며, items는 {"item": [...]} 구조와 단순 리스트 구조를 모두 지원한다. 
+    ```json
+    {
+      "response": {
+        "body": {
+          "pageNo": 1,
+          "numOfRows": 100,
+          "totalCount": ...,
+          "items": # contents
+        }
+      }
+    }
+    ```
+    """
+    # 공통 파라미터 설정 (기본값이 있으면 덮어쓰지 않음)
+    base_params: dict[str, Any] = dict(params)
+    base_params.setdefault("numOfRows", numOfRows)
+    base_params.setdefault("resultType", resultType)
+
+    # 1페이지 호출
+    first_params = dict(base_params)
+    first_params["pageNo"] = 1
+    first_doc = get_datagokr_data(serviceUrl, first_params, timeout_seconds)
+    if first_doc is None:
+        return None
+    try:
+        body = first_doc["response"]["body"]
+    except Exception:
+        return first_doc
+
+    # 전체 개수 확인
+    total_count_raw = body.get("totalCount", 0)
+    try:
+        total_count = int(total_count_raw)
+    except Exception:
+        total_count = 0
+    if total_count <= 0:
+        return first_doc
+
+    # items 추출
+    def extract_items(items_obj: Any) -> list[Any]:
+        # 1) items가 None인 경우 -> []
+        if items_obj is None:
+            return []
+        # 2) "items": {"item": [...]} OR "items": {"item": {...}} 인 경우
+        #    - inner가 리스트면 그대로 리스트 반환
+        #    - inner가 단일 객체면 리스트로 감싸서 반환
+        if isinstance(items_obj, dict) and "item" in items_obj:
+            inner = items_obj.get("item")
+            if inner is None:
+                return []
+            if isinstance(inner, list):
+                return inner
+            return [inner]
+        # 3) "items": [...] 인 경우 -> 그대로 리스트 반환
+        if isinstance(items_obj, list):
+            return items_obj
+        # 4) 그 외에는 리스트로 감싸서 반환
+        return [items_obj]
+
+    items_obj = body.get("items")
+    all_items: list[Any] = extract_items(items_obj)
+
+    # 총 페이지 수 계산
+    total_pages = (total_count + numOfRows - 1) // numOfRows
+
+    # 2페이지부터 마지막 페이지까지 반복 호출
+    for page_no in range(2, total_pages + 1):
+        page_params = dict(base_params)
+        page_params["pageNo"] = page_no
+        page_doc = get_datagokr_data(serviceUrl, page_params, timeout_seconds)
+        if page_doc is None:
+            break
+        try:
+            page_body = page_doc["response"]["body"]
+            page_items_obj = page_body.get("items")
+        except Exception:
+            break
+        all_items.extend(extract_items(page_items_obj))
+
+    # 첫 응답 객체에 모든 items를 합쳐서 세팅
+    if isinstance(items_obj, dict) and "item" in items_obj:
+        items_obj["item"] = all_items
+        body["items"] = items_obj
+    else:
+        body["items"] = all_items
+
+    # 메타 정보 정리 (pageNo는 1, numOfRows는 입력값, totalCount는 실제 아이템 개수)
+    body["pageNo"] = 1
+    body["numOfRows"] = numOfRows
+    body["totalCount"] = len(all_items)
+
+    return first_doc
+
+
+def normalize_name(name: str) -> str:
+    name_no_space = name.replace(" ", "")
+    name_no_space = re.sub(r"[A-Za-z]+", lambda m: m.group(0).lower(), name_no_space)
+    paren_index = name_no_space.find("(")
+    if paren_index != -1:
+        return name_no_space[:paren_index]
+    return name_no_space
+
+def issuer_name_from_bond_name(bond_name: str) -> str:
+    """ 채권명에서 발행사명을 추출. (숫자를 기준으로 절삭) """
+    normalized = normalize_name(bond_name)
+    m = re.search(r"\d", normalized)
+    if not m:
+        return normalized
+    return normalized[: m.start()]  

financechatbotkit-2.0.0/src/orchestrator/bond/getBondBasiInfo.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base_reader import get_datagokr_document
+
+"""
+Read https://www.data.go.kr/data/15059592/openapi.do
+"""
+
+def get_BondBasiInfo(
+    serviceKey: str,
+    basDt: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> Any | None:
+    """ 채권 기초정보 다운로드. """
+    if not basDt or not isinCd:
+        return None
+
+    service_url = "1160100/service/GetBondIssuInfoService/getBondBasiInfo"
+    params: dict[str, Any] = {
+        "serviceKey": serviceKey,
+        "basDt": basDt,
+        "isinCd": isinCd,
+    }
+
+    return get_datagokr_document(
+        serviceUrl=service_url,
+        params=params,
+        timeout_seconds=timeout_seconds
+    )
+
+
+def parse_bond_basi_info(
+    serviceKey: str,
+    basDt: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> list[dict[str, Any]] | None:
+    """ Parse get_BondBasiInfo results. """
+    raw = get_BondBasiInfo(
+        serviceKey=serviceKey,
+        basDt=basDt,
+        isinCd=isinCd,
+        timeout_seconds=timeout_seconds,
+    )
+    if raw is None:
+        return None
+
+    try:
+        body = raw["response"]["body"]
+        items_obj = body.get("items")
+    except Exception:
+        return None
+
+    def extract_items(items: Any) -> list[dict[str, Any]]:
+        if items is None:
+            return []
+        if isinstance(items, dict) and "item" in items:
+            inner = items.get("item")
+            if inner is None:
+                return []
+            if isinstance(inner, list):
+                return [i for i in inner if isinstance(i, dict)]
+            return [inner] if isinstance(inner, dict) else []
+        if isinstance(items, list):
+            return [i for i in items if isinstance(i, dict)]
+        return [items] if isinstance(items, dict) else []
+
+    items = extract_items(items_obj)
+    if not items:
+        return []
+
+    out: list[dict[str, Any]] = []
+    for it in items:
+        out.append(
+            {
+                "발행잔액": it.get("bondBal", ""),
+            }
+        )
+
+    return out
+

financechatbotkit-2.0.0/src/orchestrator/bond/getBondWithOptiCallRede.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base_reader import get_datagokr_document
+
+"""
+Read https://www.data.go.kr/data/15059595/openapi.do
+"""
+
+def get_BondWithOptiCallRede(
+    serviceKey: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> Any | None:
+    """ 옵션 행사내역 다운로드. """
+    if not isinCd:
+        return None
+
+    service_url = "1160100/service/GetBondRedeInfoService/getBondWithOptiCallRede"
+    params: dict[str, Any] = {
+        "serviceKey": serviceKey,
+        "isinCd": isinCd,
+    }
+
+    return get_datagokr_document(
+        serviceUrl=service_url,
+        params=params,
+        timeout_seconds=timeout_seconds
+    )
+
+
+def parse_bond_with_opti_call_rede(
+    serviceKey: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> list[dict[str, Any]] | None:
+    """ Parse get_BondWithOptiCallRede results. """
+    raw = get_BondWithOptiCallRede(
+        serviceKey=serviceKey,
+        isinCd=isinCd,
+        timeout_seconds=timeout_seconds,
+    )
+    if raw is None:
+        return None
+
+    try:
+        body = raw["response"]["body"]
+        items_obj = body.get("items")
+    except Exception:
+        return None
+
+    def extract_items(items: Any) -> list[dict[str, Any]]:
+        if items is None:
+            return []
+        if isinstance(items, dict) and "item" in items:
+            inner = items.get("item")
+            if inner is None:
+                return []
+            if isinstance(inner, list):
+                return [i for i in inner if isinstance(i, dict)]
+            return [inner] if isinstance(inner, dict) else []
+        if isinstance(items, list):
+            return [i for i in items if isinstance(i, dict)]
+        return [items] if isinstance(items, dict) else []
+
+    items = extract_items(items_obj)
+    if not items:
+        return []
+
+    out: list[dict[str, Any]] = []
+    for it in items:
+        out.append(
+            {
+                "옵션분류": it.get("optnTcdNm", ""),
+                "행사일자": it.get("opbdClrdDt", ""),
+                "행사원금": it.get("opbdPamtPayAmt", ""),
+                "행사이자": it.get("opbdIntPayAmt", ""),
+            }
+        )
+
+    return out
+

financechatbotkit-2.0.0/src/orchestrator/bond/getEarlExerOpti.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+from typing import Any
+from .base_reader import get_datagokr_document
+
+
+"""
+Read https://www.data.go.kr/data/15059595/openapi.do
+"""
+
+
+def get_EarlExerOpti(
+    serviceKey: str,
+    basDt: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> Any | None:
+    """ 
+    옵션 행사 일정 다운로드. 콜옵션은 대부분의 경우 누락되니 주의.
+    basDt가 없는 경우 수만 개에 달하기 때문에 사실상 사용 불가능.
+    """
+    if not basDt or not isinCd:
+        return None
+
+    service_url = "1160100/service/GetBondRedeInfoService/getEarlExerOpti"
+    params: dict[str, Any] = {
+        "serviceKey": serviceKey,
+        "basDt": basDt,
+        "isinCd": isinCd,
+    }
+    return get_datagokr_document(
+        serviceUrl=service_url,
+        params=params,
+        timeout_seconds=timeout_seconds
+    )
+
+
+def parse_earl_exer_opti(
+    serviceKey: str,
+    basDt: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> list[dict[str, Any]] | None:
+    """ Parse get_EarlExerOpti results. """
+    raw = get_EarlExerOpti(
+        serviceKey=serviceKey,
+        basDt=basDt,
+        isinCd=isinCd,
+        timeout_seconds=timeout_seconds
+    )
+    if raw is None:
+        return None
+
+    try:
+        body = raw["response"]["body"]
+        items_obj = body.get("items")
+    except Exception:
+        return None
+
+    def extract_items(items: Any) -> list[dict[str, Any]]:
+        if items is None:
+            return []
+        if isinstance(items, dict) and "item" in items:
+            inner = items.get("item")
+            if inner is None:
+                return []
+            if isinstance(inner, list):
+                return [i for i in inner if isinstance(i, dict)]
+            return [inner] if isinstance(inner, dict) else []
+        if isinstance(items, list):
+            return [i for i in items if isinstance(i, dict)]
+        return [items] if isinstance(items, dict) else []
+
+    items = extract_items(items_obj)
+    if not items:
+        return []
+
+    out: list[dict[str, Any]] = []
+    for it in items:
+        out.append(
+            {
+                "옵션분류": it.get("optnTcdNm", ""),
+                "행사일정": [
+                    it.get("옵션청구시작일", ""),
+                    it.get("옵션청구종료일", ""),
+                    it.get("지급일", ""),
+                ],
+            }
+        )
+
+    return out