financechatbotkit 2.0.0__tar.gz → 3.1.0__tar.gz

financechatbotkit-3.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: financechatbotkit
+Version: 3.1.0
+Summary: FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dotenv<2,>=1
+Provides-Extra: orchestrator
+Requires-Dist: beautifulsoup4<5,>=4.12; extra == "orchestrator"
+Requires-Dist: finance-datareader==0.9.110; extra == "orchestrator"
+Requires-Dist: lxml>=5; extra == "orchestrator"
+Provides-Extra: firestore
+Requires-Dist: google-cloud-firestore>=2.16.0; extra == "firestore"
+Requires-Dist: google-api-core>=2.15.0; extra == "firestore"
+Requires-Dist: google-auth>=2.28.0; extra == "firestore"
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.0; extra == "excel"
+Provides-Extra: all
+Requires-Dist: financechatbotkit[excel,firestore,orchestrator]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+## FinanceChatbot
+
+`FinanceChatbot` bundles three installable code areas under `src/`:
+
+- `orchestrator`: finance data workflows
+- `utilitykit`: reusable utility helpers
+- `telebotkit`: Telegram / Firestore helpers
+
+The package name is `financechatbotkit`, and it currently requires Python 3.11+.
+
+## Orchestrator
+
+`orchestrator` is the main workflow library for:
+
+- `mapping`
+- `price`
+- `fnguide`
+- `bond`
+- `kind`
+
+### Public API
+
+```python
+from orchestrator import (
+    FnGuideWorkflow,
+    KindWorkflow,
+    MappingWorkflow,
+    MarketBondWorkflow,
+    PricePeriodWorkflow,
+)
+```
+
+Feature-level imports are also available:
+
+```python
+from orchestrator.mapping import MappingWorkflow
+from orchestrator.price import PricePeriodWorkflow
+from orchestrator.fnguide import FnGuideWorkflow
+from orchestrator.bond import MarketBondWorkflow
+from orchestrator.kind import KindWorkflow, parse_kind_html_to_json
+```
+
+Most workflow classes return a normalized payload shaped like:
+
+```python
+{
+    "input": {...},
+    "data": {...},
+}
+```
+
+`price` workflows support `price_fields="close"` (default), `price_fields="oclh"`, `price_fields="oclhv"`, `price_fields="oclhva"`, and comma-separated field lists such as `price_fields="volume,amount"` to control which price columns are returned. `PricePeriodWorkflow` also supports `price_source="krx"` when KRX `Amount` data is required for VWAP.
+
+### Workflow Classes
+
+The main usage pattern is class-based:
+
+- `MappingWorkflow`
+- `PricePeriodWorkflow`
+- `PriceSnapshotWorkflow`
+- `FnGuideWorkflow`
+- `MarketBondWorkflow`
+- `KindWorkflow`
+
+For example, `FnGuideWorkflow` is used like this:
+
+```python
+from orchestrator.fnguide import FnGuideWorkflow
+
+workflow = FnGuideWorkflow()
+result = workflow.run(stock_code="005930", statement_type="consolidated")
+```
+
+### KIND Workflow
+
+`kind` is slightly different from the other workflow modules because it supports both:
+
+- request payload construction and raw response download
+- HTML file parsing into structured JSON
+
+The recommended entry point is `KindWorkflow`.
+
+```python
+from pathlib import Path
+
+from orchestrator.kind import KindWorkflow
+from run import KIND_REQUEST_HEADERS
+
+workflow = KindWorkflow()
+result = workflow.run(
+    output_directory=Path("resources/kind_2012"),
+    request_headers=KIND_REQUEST_HEADERS,
+    start_date="2012-01-01",
+    end_date="2012-12-31",
+    start_page=1,
+    end_page=10,
+    disclosure_type_groups={"01": ["0119"]},
+    last_report_only=True,
+    save=True,
+)
+
+print(result["input_snapshot_path"])
+print(result["checkpoint_path"])
+```
+
+`KindWorkflow` stores normalized input state and, when `save=True`, writes:
+
+- raw `.body` files page by page
+- `kind_workflow.input.json`
+- `kind_workflow.checkpoint.json`
+
+This makes long-running downloads easier to inspect and recover.
+
+Lower-level helpers remain available when needed:
+
+```python
+from orchestrator.kind import (
+    build_kind_search_request_data,
+    parse_kind_file_to_json,
+    parse_kind_html_to_json,
+    save_kind_search_results,
+)
+```
+
+### Example Script
+
+`run.py` shows one concrete KIND pipeline:
+
+1. Download paged KIND responses through `KindWorkflow`
+2. Merge downloaded `.body` files into a single JSON file
+3. Convert the merged JSON into Excel using `utilitykit`
+
+## UtilityKit
+
+`utilitykit` is a shared utilities package for repo-wide helpers that do not belong to `orchestrator`.
+
+Current public utilities:
+
+- `utilitykit.excel.read_xlsx_sheet_as_json()`
+- `utilitykit.excel.write_json_to_xlsx()`
+- `utilitykit.excel.records_to_table()`
+- `utilitykit.excel.project_records_to_table()`
+- `utilitykit.excel.row_cell_records_to_table()`
+
+### Excel Examples
+
+Read an Excel sheet as `list[list]` using A1-start automatic bounds detection:
+
+```python
+from utilitykit import read_xlsx_sheet_as_json
+
+table = read_xlsx_sheet_as_json("sample.xlsx", sheet_name="Data")
+```
+
+Write row-oriented data:
+
+```python
+from utilitykit import write_json_to_xlsx
+
+write_json_to_xlsx(
+    [
+        {"company": "Samsung", "sales": 100},
+        {"company": "LG", "sales": 80},
+    ],
+    "rows.xlsx",
+    sheet_name="Rows",
+    axis="rows",
+    item_mode="dict",
+)
+```
+
+Write column-oriented data:
+
+```python
+from utilitykit import write_json_to_xlsx
+
+write_json_to_xlsx(
+    {"company": ["Samsung", "LG"], "sales": [100, 80]},
+    "columns.xlsx",
+    sheet_name="Columns",
+    axis="columns",
+    item_mode="dict",
+)
+```
+
+## TeleBotKit
+
+`TeleBotKit` is a shared helper package 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 fuller API documentation and examples.

financechatbotkit-3.1.0/README.md

@@ -0,0 +1,204 @@
+## FinanceChatbot
+
+`FinanceChatbot` bundles three installable code areas under `src/`:
+
+- `orchestrator`: finance data workflows
+- `utilitykit`: reusable utility helpers
+- `telebotkit`: Telegram / Firestore helpers
+
+The package name is `financechatbotkit`, and it currently requires Python 3.11+.
+
+## Orchestrator
+
+`orchestrator` is the main workflow library for:
+
+- `mapping`
+- `price`
+- `fnguide`
+- `bond`
+- `kind`
+
+### Public API
+
+```python
+from orchestrator import (
+    FnGuideWorkflow,
+    KindWorkflow,
+    MappingWorkflow,
+    MarketBondWorkflow,
+    PricePeriodWorkflow,
+)
+```
+
+Feature-level imports are also available:
+
+```python
+from orchestrator.mapping import MappingWorkflow
+from orchestrator.price import PricePeriodWorkflow
+from orchestrator.fnguide import FnGuideWorkflow
+from orchestrator.bond import MarketBondWorkflow
+from orchestrator.kind import KindWorkflow, parse_kind_html_to_json
+```
+
+Most workflow classes return a normalized payload shaped like:
+
+```python
+{
+    "input": {...},
+    "data": {...},
+}
+```
+
+`price` workflows support `price_fields="close"` (default), `price_fields="oclh"`, `price_fields="oclhv"`, `price_fields="oclhva"`, and comma-separated field lists such as `price_fields="volume,amount"` to control which price columns are returned. `PricePeriodWorkflow` also supports `price_source="krx"` when KRX `Amount` data is required for VWAP.
+
+### Workflow Classes
+
+The main usage pattern is class-based:
+
+- `MappingWorkflow`
+- `PricePeriodWorkflow`
+- `PriceSnapshotWorkflow`
+- `FnGuideWorkflow`
+- `MarketBondWorkflow`
+- `KindWorkflow`
+
+For example, `FnGuideWorkflow` is used like this:
+
+```python
+from orchestrator.fnguide import FnGuideWorkflow
+
+workflow = FnGuideWorkflow()
+result = workflow.run(stock_code="005930", statement_type="consolidated")
+```
+
+### KIND Workflow
+
+`kind` is slightly different from the other workflow modules because it supports both:
+
+- request payload construction and raw response download
+- HTML file parsing into structured JSON
+
+The recommended entry point is `KindWorkflow`.
+
+```python
+from pathlib import Path
+
+from orchestrator.kind import KindWorkflow
+from run import KIND_REQUEST_HEADERS
+
+workflow = KindWorkflow()
+result = workflow.run(
+    output_directory=Path("resources/kind_2012"),
+    request_headers=KIND_REQUEST_HEADERS,
+    start_date="2012-01-01",
+    end_date="2012-12-31",
+    start_page=1,
+    end_page=10,
+    disclosure_type_groups={"01": ["0119"]},
+    last_report_only=True,
+    save=True,
+)
+
+print(result["input_snapshot_path"])
+print(result["checkpoint_path"])
+```
+
+`KindWorkflow` stores normalized input state and, when `save=True`, writes:
+
+- raw `.body` files page by page
+- `kind_workflow.input.json`
+- `kind_workflow.checkpoint.json`
+
+This makes long-running downloads easier to inspect and recover.
+
+Lower-level helpers remain available when needed:
+
+```python
+from orchestrator.kind import (
+    build_kind_search_request_data,
+    parse_kind_file_to_json,
+    parse_kind_html_to_json,
+    save_kind_search_results,
+)
+```
+
+### Example Script
+
+`run.py` shows one concrete KIND pipeline:
+
+1. Download paged KIND responses through `KindWorkflow`
+2. Merge downloaded `.body` files into a single JSON file
+3. Convert the merged JSON into Excel using `utilitykit`
+
+## UtilityKit
+
+`utilitykit` is a shared utilities package for repo-wide helpers that do not belong to `orchestrator`.
+
+Current public utilities:
+
+- `utilitykit.excel.read_xlsx_sheet_as_json()`
+- `utilitykit.excel.write_json_to_xlsx()`
+- `utilitykit.excel.records_to_table()`
+- `utilitykit.excel.project_records_to_table()`
+- `utilitykit.excel.row_cell_records_to_table()`
+
+### Excel Examples
+
+Read an Excel sheet as `list[list]` using A1-start automatic bounds detection:
+
+```python
+from utilitykit import read_xlsx_sheet_as_json
+
+table = read_xlsx_sheet_as_json("sample.xlsx", sheet_name="Data")
+```
+
+Write row-oriented data:
+
+```python
+from utilitykit import write_json_to_xlsx
+
+write_json_to_xlsx(
+    [
+        {"company": "Samsung", "sales": 100},
+        {"company": "LG", "sales": 80},
+    ],
+    "rows.xlsx",
+    sheet_name="Rows",
+    axis="rows",
+    item_mode="dict",
+)
+```
+
+Write column-oriented data:
+
+```python
+from utilitykit import write_json_to_xlsx
+
+write_json_to_xlsx(
+    {"company": ["Samsung", "LG"], "sales": [100, 80]},
+    "columns.xlsx",
+    sheet_name="Columns",
+    axis="columns",
+    item_mode="dict",
+)
+```
+
+## TeleBotKit
+
+`TeleBotKit` is a shared helper package 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 fuller API documentation and examples.

{financechatbotkit-2.0.0 → financechatbotkit-3.1.0}/pyproject.toml

@@ -4,27 +4,47 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "financechatbotkit"
-version = "2.0.0"
+version = "3.1.0"
 description = "FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)"
 requires-python = ">=3.11"
+readme = "README.md"
+
 dependencies = [
-    "finance-datareader==0.9.110",
     "httpx>=0.27,<1",
+    "python-dotenv>=1,<2",
+]
+
+[project.optional-dependencies]
+orchestrator = [
+    "beautifulsoup4>=4.12,<5",
+    "finance-datareader==0.9.110",
+    "lxml>=5",
+]
+firestore = [
     "google-cloud-firestore>=2.16.0",
     "google-api-core>=2.15.0",
     "google-auth>=2.28.0",
+]
+excel = [
     "openpyxl>=3.1.0",
 ]
+all = [
+    "financechatbotkit[orchestrator,firestore,excel]"
+]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
 
 [project.scripts]
-orchestrator-update-corp-codes = "orchestrator.mapping.update_raw_data:main"
+orchestrator-update-corp-codes = "financechatbotkit.orchestrator.mapping.update_raw_data:main"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
-include = ["orchestrator*", "telebotkit*"]
+include = ["financechatbotkit*"]
 
 [tool.setuptools.package-data]
-"orchestrator.mapping" = ["data/*.json"]
+"financechatbotkit.orchestrator.mapping" = ["data/*.json"]

financechatbotkit-3.1.0/src/financechatbotkit/orchestrator/__init__.py

@@ -0,0 +1,90 @@
+"""FinanceChatbot workflow library."""
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .bond import MarketBondWorkflow, run_market_bond_workflow
+    from .exceptions import DownloadError, InvalidInputError, MappingWorkflowError, NotFoundError
+    from .fnguide import FnGuideWorkflow, run_fnguide_workflow
+    from .kind import (
+        KindSavedFileCallback,
+        KindWorkflowCheckpoint,
+        KindWorkflow,
+        KindWorkflowInput,
+        ParseMode,
+        build_kind_search_request_data,
+        parse_kind_file_to_json,
+        parse_kind_html_to_json,
+        save_kind_search_results,
+    )
+    from .mapping import MappingWorkflow, run_mapping_workflow
+    from .price import (
+        PricePeriodWorkflow,
+        PriceSnapshotWorkflow,
+        run_price_period_workflow,
+        run_price_snapshot_workflow,
+    )
+
+def __getattr__(name):
+    module_mapping = {
+        "MarketBondWorkflow": "bond",
+        "run_market_bond_workflow": "bond",
+        "DownloadError": "exceptions",
+        "InvalidInputError": "exceptions",
+        "MappingWorkflowError": "exceptions",
+        "NotFoundError": "exceptions",
+        "FnGuideWorkflow": "fnguide",
+        "run_fnguide_workflow": "fnguide",
+        "KindSavedFileCallback": "kind",
+        "KindWorkflowCheckpoint": "kind",
+        "KindWorkflow": "kind",
+        "KindWorkflowInput": "kind",
+        "ParseMode": "kind",
+        "build_kind_search_request_data": "kind",
+        "parse_kind_file_to_json": "kind",
+        "parse_kind_html_to_json": "kind",
+        "save_kind_search_results": "kind",
+        "MappingWorkflow": "mapping",
+        "run_mapping_workflow": "mapping",
+        "PricePeriodWorkflow": "price",
+        "PriceSnapshotWorkflow": "price",
+        "run_price_period_workflow": "price",
+        "run_price_snapshot_workflow": "price",
+    }
+    
+    if name in module_mapping:
+        module_name = module_mapping[name]
+        module = importlib.import_module(f".{module_name}", package=__name__)
+        return getattr(module, name)
+        
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+def __dir__():
+    return __all__
+
+__all__ = [
+    "DownloadError",
+    "FnGuideWorkflow",
+    "InvalidInputError",
+    "KindSavedFileCallback",
+    "KindWorkflowCheckpoint",
+    "KindWorkflow",
+    "KindWorkflowInput",
+    "MappingWorkflow",
+    "MappingWorkflowError",
+    "MarketBondWorkflow",
+    "NotFoundError",
+    "ParseMode",
+    "PricePeriodWorkflow",
+    "PriceSnapshotWorkflow",
+    "build_kind_search_request_data",
+    "parse_kind_file_to_json",
+    "parse_kind_html_to_json",
+    "run_fnguide_workflow",
+    "run_market_bond_workflow",
+    "run_mapping_workflow",
+    "run_price_period_workflow",
+    "run_price_snapshot_workflow",
+    "save_kind_search_results",
+]

financechatbotkit-3.1.0/src/financechatbotkit/orchestrator/dart/__init__.py

@@ -0,0 +1,21 @@
+"""Open DART 공시 API 클라이언트. 아직 미완성."""
+
+from .zip_extractor import extract_dart_zip
+from .api_client import DART_OPEN_API_BASE, fetch_dart_json, fetch_dart_bytes, fetch_dart
+from .xml_to_dict import xml_markup_to_json, xml_to_soup
+from .xml_to_tree import parse_dart_xml
+from .tree_to_outline import build_outline_nested, iter_outline_from_structure, render_outline_lines
+
+__all__ = [
+    "DART_OPEN_API_BASE",
+    "extract_dart_zip",
+    "fetch_dart",
+    "fetch_dart_bytes",
+    "fetch_dart_json",
+    "xml_markup_to_json",
+    "xml_to_soup",
+    "parse_dart_xml",
+    "build_outline_nested",
+    "iter_outline_from_structure",
+    "render_outline_lines",
+]

financechatbotkit-3.1.0/src/financechatbotkit/orchestrator/dart/api_client.py

@@ -0,0 +1,66 @@
+"""Open DART (금융감독원 전자공시) API — 기본 httpx 동기 요청."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from ..exceptions import DownloadError
+
+logger = logging.getLogger(__name__)
+
+DART_OPEN_API_BASE = "https://opendart.fss.or.kr/api"
+
+
+def fetch_dart(
+    *,
+    path: str,
+    api_key: str,
+    params: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> httpx.Response:
+    """Open DART API에 GET 요청 후 응답 객체를 반환한다."""
+    url = f"{DART_OPEN_API_BASE}/{path.lstrip('/')}"
+    query: dict[str, Any] = {"crtfc_key": api_key}
+    if params:
+        query.update(params)
+
+    try:
+        response = httpx.get(
+            url,
+            params=query,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        logger.warning("DART request failed for %s: %s", url, exc)
+        raise DownloadError(f"Failed to fetch DART API: {url}") from exc
+
+    return response
+
+
+def fetch_dart_json(
+    *,
+    path: str,
+    api_key: str,
+    params: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    """Open DART API에 GET 요청 후 JSON을 파싱해 반환한다."""
+    response = fetch_dart(path=path, api_key=api_key, params=params, timeout=timeout)
+    return response.json()
+
+
+def fetch_dart_bytes(
+    *,
+    path: str,
+    api_key: str,
+    params: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> bytes:
+    """Open DART API에 GET 요청 후 바이너리(Bytes)를 반환한다."""
+    response = fetch_dart(path=path, api_key=api_key, params=params, timeout=timeout)
+    return response.content