opendart-fss 0.1.0__py3-none-any.whl

opendart_fss/models/shareholder.py

@@ -0,0 +1,54 @@
+"""DS004 지분공시 종합정보 모델."""
+
+import msgspec
+
+
+class MajorStock(msgspec.Struct, kw_only=True):
+    """대량보유 상황보고."""
+
+    rcept_no: str  # 접수번호
+    rcept_dt: str | None = None  # 접수일자
+    corp_code: str | None = None  # 고유번호
+    corp_name: str | None = None  # 회사명
+    report_tp: str | None = None  # 보고구분
+    repror: str | None = None  # 보고자
+    stkqy: str | None = None  # 보유주식등의수
+    stkqy_irds: str | None = None  # 보유주식등의수증감
+    stkrt: str | None = None  # 보유비율
+    stkrt_irds: str | None = None  # 보유비율증감
+    ctr_stkqy: str | None = None  # 주요체결등의수
+    ctr_stkrt: str | None = None  # 주요체결등비율
+    report_resn: str | None = None  # 보고사유
+
+
+class MajorStockListResponse(msgspec.Struct, kw_only=True):
+    """대량보유 상황보고 응답."""
+
+    status: str
+    message: str
+    items: list[MajorStock] = msgspec.field(default_factory=list, name="list")
+
+
+class ExecutiveStock(msgspec.Struct, kw_only=True):
+    """임원/주요주주 소유보고."""
+
+    rcept_no: str  # 접수번호
+    rcept_dt: str | None = None  # 접수일자
+    corp_code: str | None = None  # 고유번호
+    corp_name: str | None = None  # 회사명
+    repror: str | None = None  # 보고자
+    isu_exctv_rgist_at: str | None = None  # 발행회사관계(임원등기여부)
+    isu_exctv_ofcps: str | None = None  # 발행회사관계(직위)
+    isu_main_shrholdr: str | None = None  # 발행회사관계(주요주주)
+    sp_stock_lmp_cnt: str | None = None  # 특정증권등소유수(주권)
+    sp_stock_lmp_irds_cnt: str | None = None  # 특정증권등소유수증감(주권)
+    sp_stock_lmp_rate: str | None = None  # 특정증권등소유비율(주권)
+    sp_stock_lmp_irds_rate: str | None = None  # 특정증권등소유비율증감(주권)
+
+
+class ExecutiveStockListResponse(msgspec.Struct, kw_only=True):
+    """임원/주요주주 소유보고 응답."""
+
+    status: str
+    message: str
+    items: list[ExecutiveStock] = msgspec.field(default_factory=list, name="list")

opendart_fss/verification/__init__.py

@@ -0,0 +1,50 @@
+"""OpenDART API 엔드포인트 검증 모듈.
+
+이 모듈은 OpenDART API의 모든 엔드포인트를 실제 호출하여 검증합니다.
+
+Example:
+    ```python
+    import asyncio
+    from opendart_fss.verification import EndpointVerifier, generate_report
+
+    async def main():
+        verifier = EndpointVerifier()
+        results = await verifier.verify_all()
+        report = generate_report(results, format="console")
+        print(report)
+
+    asyncio.run(main())
+    ```
+"""
+
+from opendart_fss.verification.config import (
+    DEFAULT_TEST_DATA,
+    ENDPOINT_CONFIGS,
+    FALLBACK_CORP_CODES,
+    EndpointConfig,
+    VerificationResult,
+    VerificationStatus,
+)
+from opendart_fss.verification.rate_limiter import AdaptiveRateLimiter
+from opendart_fss.verification.reporter import (
+    VerificationReport,
+    generate_report,
+)
+from opendart_fss.verification.runner import EndpointVerifier
+
+__all__ = [
+    # Config
+    "EndpointConfig",
+    "VerificationResult",
+    "VerificationStatus",
+    "ENDPOINT_CONFIGS",
+    "DEFAULT_TEST_DATA",
+    "FALLBACK_CORP_CODES",
+    # Rate Limiter
+    "AdaptiveRateLimiter",
+    # Runner
+    "EndpointVerifier",
+    # Reporter
+    "VerificationReport",
+    "generate_report",
+]

opendart_fss/verification/config.py

@@ -0,0 +1,450 @@
+"""엔드포인트 검증 설정."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class VerificationStatus(StrEnum):
+    """검증 상태."""
+
+    SUCCESS = "SUCCESS"
+    NO_DATA = "NO_DATA"
+    FAILED = "FAILED"
+    SKIPPED = "SKIPPED"
+
+
+@dataclass
+class VerificationResult:
+    """검증 결과."""
+
+    endpoint_id: str
+    endpoint_name: str
+    category: str
+    status: VerificationStatus
+    response_time_ms: float = 0.0
+    error_message: str | None = None
+    response_data: Any = None
+
+
+@dataclass
+class EndpointConfig:
+    """엔드포인트 설정."""
+
+    id: str
+    name: str
+    category: str
+    service: str
+    method: str
+    params: dict[str, str] = field(default_factory=dict)
+    requires_rcept_no: bool = False
+    description: str = ""
+
+
+# 기본 테스트 데이터
+DEFAULT_TEST_DATA = {
+    "corp_code": "00126380",  # 삼성전자
+    "bsns_year": "2023",
+    "reprt_code": "11011",  # 사업보고서
+    "bgn_de": "20230101",
+    "end_de": "20231231",
+    "fs_div": "CFS",  # 연결재무제표
+    "sj_div": "BS",  # 재무상태표
+}
+
+# 대체 기업 코드 (삼성전자에 데이터가 없을 경우)
+FALLBACK_CORP_CODES = [
+    "00164779",  # SK하이닉스
+    "00401731",  # 현대자동차
+    "00155246",  # LG전자
+]
+
+# 모든 엔드포인트 설정 (28개)
+ENDPOINT_CONFIGS: list[EndpointConfig] = [
+    # DS001 - 공시정보 (4개)
+    EndpointConfig(
+        id="DS001-01",
+        name="disclosure.search",
+        category="DS001",
+        service="disclosure",
+        method="search",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="공시검색",
+    ),
+    EndpointConfig(
+        id="DS001-02",
+        name="disclosure.get_company",
+        category="DS001",
+        service="disclosure",
+        method="get_company",
+        params={"corp_code": "{corp_code}"},
+        description="기업개황 조회",
+    ),
+    EndpointConfig(
+        id="DS001-03",
+        name="disclosure.download_document",
+        category="DS001",
+        service="disclosure",
+        method="download_document",
+        params={"rcept_no": "{rcept_no}"},
+        requires_rcept_no=True,
+        description="공시서류 원본 다운로드",
+    ),
+    EndpointConfig(
+        id="DS001-04",
+        name="disclosure.download_corp_codes",
+        category="DS001",
+        service="disclosure",
+        method="download_corp_codes",
+        params={},
+        description="고유번호 전체 다운로드",
+    ),
+    # DS002 - 정기보고서 주요정보 (8개)
+    EndpointConfig(
+        id="DS002-01",
+        name="report.get_stock_changes",
+        category="DS002",
+        service="report",
+        method="get_stock_changes",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="증자(감자) 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-02",
+        name="report.get_dividends",
+        category="DS002",
+        service="report",
+        method="get_dividends",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="배당에 관한 사항 조회",
+    ),
+    EndpointConfig(
+        id="DS002-03",
+        name="report.get_treasury_stock",
+        category="DS002",
+        service="report",
+        method="get_treasury_stock",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="자기주식 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-04",
+        name="report.get_largest_shareholders",
+        category="DS002",
+        service="report",
+        method="get_largest_shareholders",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="최대주주 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-05",
+        name="report.get_executives",
+        category="DS002",
+        service="report",
+        method="get_executives",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="임원 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-06",
+        name="report.get_employees",
+        category="DS002",
+        service="report",
+        method="get_employees",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="직원 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-07",
+        name="report.get_individual_compensation",
+        category="DS002",
+        service="report",
+        method="get_individual_compensation",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="개인별 보수 현황 조회",
+    ),
+    EndpointConfig(
+        id="DS002-08",
+        name="report.get_director_compensation",
+        category="DS002",
+        service="report",
+        method="get_director_compensation",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="이사/감사 보수 현황 조회",
+    ),
+    # DS003 - 정기보고서 재무정보 (6개)
+    EndpointConfig(
+        id="DS003-01",
+        name="financial.get_single_account",
+        category="DS003",
+        service="financial",
+        method="get_single_account",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+            "fs_div": "{fs_div}",
+        },
+        description="단일회사 주요계정 조회",
+    ),
+    EndpointConfig(
+        id="DS003-02",
+        name="financial.get_multi_account",
+        category="DS003",
+        service="financial",
+        method="get_multi_account",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+            "fs_div": "{fs_div}",
+        },
+        description="다중회사 주요계정 조회",
+    ),
+    EndpointConfig(
+        id="DS003-03",
+        name="financial.get_full_statements",
+        category="DS003",
+        service="financial",
+        method="get_full_statements",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+            "fs_div": "{fs_div}",
+        },
+        description="단일회사 전체 재무제표 조회",
+    ),
+    EndpointConfig(
+        id="DS003-04",
+        name="financial.download_xbrl",
+        category="DS003",
+        service="financial",
+        method="download_xbrl",
+        params={
+            "rcept_no": "{rcept_no}",
+            "reprt_code": "{reprt_code}",
+        },
+        requires_rcept_no=True,
+        description="XBRL 원본파일 다운로드",
+    ),
+    EndpointConfig(
+        id="DS003-05",
+        name="financial.get_xbrl_taxonomy",
+        category="DS003",
+        service="financial",
+        method="get_xbrl_taxonomy",
+        params={"sj_div": "{sj_div}"},
+        description="XBRL 택사노미 조회",
+    ),
+    EndpointConfig(
+        id="DS003-06",
+        name="financial.get_indicators",
+        category="DS003",
+        service="financial",
+        method="get_indicators",
+        params={
+            "corp_code": "{corp_code}",
+            "bsns_year": "{bsns_year}",
+            "reprt_code": "{reprt_code}",
+        },
+        description="재무지표 조회",
+    ),
+    # DS004 - 지분공시 종합정보 (2개)
+    EndpointConfig(
+        id="DS004-01",
+        name="shareholder.get_major_stock",
+        category="DS004",
+        service="shareholder",
+        method="get_major_stock",
+        params={"corp_code": "{corp_code}"},
+        description="대량보유 상황보고 조회",
+    ),
+    EndpointConfig(
+        id="DS004-02",
+        name="shareholder.get_executive_stock",
+        category="DS004",
+        service="shareholder",
+        method="get_executive_stock",
+        params={"corp_code": "{corp_code}"},
+        description="임원/주요주주 소유보고 조회",
+    ),
+    # DS005 - 주요사항보고서 주요정보 (6개)
+    EndpointConfig(
+        id="DS005-01",
+        name="major_event.get_paid_capital_increase",
+        category="DS005",
+        service="major_event",
+        method="get_paid_capital_increase",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="유상증자 결정 조회",
+    ),
+    EndpointConfig(
+        id="DS005-02",
+        name="major_event.get_bonus_issue",
+        category="DS005",
+        service="major_event",
+        method="get_bonus_issue",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="무상증자 결정 조회",
+    ),
+    EndpointConfig(
+        id="DS005-03",
+        name="major_event.get_capital_reduction",
+        category="DS005",
+        service="major_event",
+        method="get_capital_reduction",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="감자 결정 조회",
+    ),
+    EndpointConfig(
+        id="DS005-04",
+        name="major_event.get_convertible_bond",
+        category="DS005",
+        service="major_event",
+        method="get_convertible_bond",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="전환사채권 발행결정 조회",
+    ),
+    EndpointConfig(
+        id="DS005-05",
+        name="major_event.get_merger_decision",
+        category="DS005",
+        service="major_event",
+        method="get_merger_decision",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="합병 결정 조회",
+    ),
+    EndpointConfig(
+        id="DS005-06",
+        name="major_event.get_split_decision",
+        category="DS005",
+        service="major_event",
+        method="get_split_decision",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="분할 결정 조회",
+    ),
+    # DS006 - 증권신고서 주요정보 (4개)
+    EndpointConfig(
+        id="DS006-01",
+        name="registration.get_equity_securities",
+        category="DS006",
+        service="registration",
+        method="get_equity_securities",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="지분증권 발행 조회",
+    ),
+    EndpointConfig(
+        id="DS006-02",
+        name="registration.get_debt_securities",
+        category="DS006",
+        service="registration",
+        method="get_debt_securities",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="채무증권 발행 조회",
+    ),
+    EndpointConfig(
+        id="DS006-03",
+        name="registration.get_merger_registration",
+        category="DS006",
+        service="registration",
+        method="get_merger_registration",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="합병 신고 조회",
+    ),
+    EndpointConfig(
+        id="DS006-04",
+        name="registration.get_split_registration",
+        category="DS006",
+        service="registration",
+        method="get_split_registration",
+        params={
+            "corp_code": "{corp_code}",
+            "bgn_de": "{bgn_de}",
+            "end_de": "{end_de}",
+        },
+        description="분할 신고 조회",
+    ),
+]
+
+# 카테고리 설명
+CATEGORY_DESCRIPTIONS = {
+    "DS001": "공시정보",
+    "DS002": "정기보고서 주요정보",
+    "DS003": "정기보고서 재무정보",
+    "DS004": "지분공시 종합정보",
+    "DS005": "주요사항보고서 주요정보",
+    "DS006": "증권신고서 주요정보",
+}

opendart_fss/verification/rate_limiter.py

@@ -0,0 +1,92 @@
+"""적응형 Rate Limiter."""
+
+import asyncio
+import time
+
+
+class AdaptiveRateLimiter:
+    """지수 백오프를 사용하는 적응형 Rate Limiter.
+
+    Rate limit 오류 발생 시 지수적으로 대기 시간을 증가시키고,
+    성공 시 점진적으로 감소시킵니다.
+
+    Example:
+        ```python
+        limiter = AdaptiveRateLimiter()
+
+        async def make_request():
+            await limiter.wait()
+            try:
+                result = await api_call()
+                limiter.on_success()
+                return result
+            except RateLimitError:
+                limiter.on_rate_limit()
+                raise
+        ```
+    """
+
+    def __init__(
+        self,
+        min_delay: float = 0.5,
+        max_delay: float = 16.0,
+        backoff_factor: float = 2.0,
+        recovery_factor: float = 0.9,
+    ) -> None:
+        """Rate Limiter 초기화.
+
+        Args:
+            min_delay: 최소 요청 간격 (초)
+            max_delay: 최대 요청 간격 (초)
+            backoff_factor: Rate limit 시 지연 증가 배수
+            recovery_factor: 성공 시 지연 감소 배수
+        """
+        self.min_delay = min_delay
+        self.max_delay = max_delay
+        self.backoff_factor = backoff_factor
+        self.recovery_factor = recovery_factor
+
+        self._current_delay = min_delay
+        self._last_request_time: float = 0.0
+        self._rate_limit_count = 0
+
+    @property
+    def current_delay(self) -> float:
+        """현재 요청 간격."""
+        return self._current_delay
+
+    @property
+    def rate_limit_count(self) -> int:
+        """Rate limit 발생 횟수."""
+        return self._rate_limit_count
+
+    async def wait(self) -> None:
+        """다음 요청 전 필요한 시간만큼 대기."""
+        now = time.monotonic()
+        elapsed = now - self._last_request_time
+
+        if elapsed < self._current_delay:
+            await asyncio.sleep(self._current_delay - elapsed)
+
+        self._last_request_time = time.monotonic()
+
+    def on_success(self) -> None:
+        """요청 성공 시 호출. 대기 시간 점진적 감소."""
+        self._current_delay = max(
+            self.min_delay,
+            self._current_delay * self.recovery_factor,
+        )
+
+    def on_rate_limit(self) -> None:
+        """Rate limit 발생 시 호출. 대기 시간 지수적 증가."""
+        self._rate_limit_count += 1
+        self._current_delay = min(
+            self.max_delay,
+            self._current_delay * self.backoff_factor,
+        )
+
+    def reset(self) -> None:
+        """Rate limiter 상태 초기화."""
+        self._current_delay = self.min_delay
+        self._last_request_time = 0.0
+        self._rate_limit_count = 0