opendart-fss 0.1.0__py3-none-any.whl

opendart_fss/api/shareholder.py

@@ -0,0 +1,51 @@
+"""DS004 지분공시 종합정보 API."""
+
+from opendart_fss.api.base import BaseAPI
+from opendart_fss.models.shareholder import (
+    ExecutiveStock,
+    ExecutiveStockListResponse,
+    MajorStock,
+    MajorStockListResponse,
+)
+
+
+class ShareholderAPI(BaseAPI):
+    """지분공시 종합정보 API (DS004)."""
+
+    async def get_major_stock(
+        self,
+        corp_code: str,
+    ) -> list[MajorStock]:
+        """대량보유 상황보고 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+
+        Returns:
+            대량보유 상황보고 목록
+        """
+        response = await self._get(
+            "/api/majorstock.json",
+            MajorStockListResponse,
+            params={"corp_code": corp_code},
+        )
+        return response.items
+
+    async def get_executive_stock(
+        self,
+        corp_code: str,
+    ) -> list[ExecutiveStock]:
+        """임원/주요주주 소유보고 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+
+        Returns:
+            임원/주요주주 소유보고 목록
+        """
+        response = await self._get(
+            "/api/elestock.json",
+            ExecutiveStockListResponse,
+            params={"corp_code": corp_code},
+        )
+        return response.items

opendart_fss/client.py

@@ -0,0 +1,96 @@
+"""OpenDART API 클라이언트."""
+
+import os
+from types import TracebackType
+
+import httpx
+from dotenv import load_dotenv
+
+from opendart_fss.api.disclosure import DisclosureAPI
+from opendart_fss.api.financial import FinancialAPI
+from opendart_fss.api.major_event import MajorEventAPI
+from opendart_fss.api.registration import RegistrationAPI
+from opendart_fss.api.report import ReportAPI
+from opendart_fss.api.shareholder import ShareholderAPI
+
+load_dotenv()
+
+
+class OpenDartClient:
+    """OpenDART API 클라이언트.
+
+    Example:
+        ```python
+        async with OpenDartClient(api_key="YOUR_API_KEY") as client:
+            # 공시 검색
+            disclosures = await client.disclosure.search(
+                corp_code="00126380",
+                bgn_de="20240101",
+                end_de="20241231"
+            )
+
+            # 기업 개황
+            company = await client.disclosure.get_company("00126380")
+            print(f"회사명: {company.corp_name}")
+
+            # 재무제표 조회
+            financials = await client.financial.get_single_account(
+                corp_code="00126380",
+                bsns_year="2024",
+                reprt_code="11011"
+            )
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        timeout: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """클라이언트 초기화.
+
+        Args:
+            api_key: OpenDART API 키. 생략 시 OPENDART_API_KEY 환경변수 사용
+            timeout: HTTP 요청 타임아웃 (초)
+            http_client: 커스텀 httpx.AsyncClient (선택)
+
+        Raises:
+            ValueError: API 키가 제공되지 않고 환경변수도 설정되지 않은 경우
+        """
+        self.api_key = api_key or os.environ.get("OPENDART_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. "
+                "Provide api_key parameter or set OPENDART_API_KEY environment variable."
+            )
+        self._timeout = timeout
+        self._external_client = http_client is not None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        # API 모듈 초기화
+        self.disclosure = DisclosureAPI(self)
+        self.report = ReportAPI(self)
+        self.financial = FinancialAPI(self)
+        self.shareholder = ShareholderAPI(self)
+        self.major_event = MajorEventAPI(self)
+        self.registration = RegistrationAPI(self)
+
+    async def __aenter__(self) -> "OpenDartClient":
+        """컨텍스트 매니저 진입."""
+        return self
+
+    async def __aexit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        _exc_val: BaseException | None,
+        _exc_tb: TracebackType | None,
+    ) -> None:
+        """컨텍스트 매니저 종료."""
+        await self.close()
+
+    async def close(self) -> None:
+        """HTTP 클라이언트 종료."""
+        if not self._external_client:
+            await self._http.aclose()

opendart_fss/constants.py

@@ -0,0 +1,88 @@
+"""OpenDART API 상수 정의."""
+
+from enum import StrEnum
+
+BASE_URL = "https://opendart.fss.or.kr"
+
+
+class StatusCode(StrEnum):
+    """API 응답 상태 코드."""
+
+    SUCCESS = "000"
+    UNREGISTERED_KEY = "010"
+    INACTIVE_KEY = "011"
+    INVALID_KEY = "012"
+    USAGE_LIMIT_EXCEEDED = "013"
+    DAILY_LIMIT_EXCEEDED_FIELD = "014"
+    DAILY_LIMIT_EXCEEDED_REQUESTS = "015"
+    MONTHLY_LIMIT_EXCEEDED = "016"
+    INVALID_PARAMETER = "020"
+    MISSING_REQUIRED_PARAMETER = "021"
+    INVALID_REPORT_CODE = "022"
+    INVALID_DATE = "023"
+    NO_DATA = "100"
+    FILE_NOT_FOUND = "101"
+    SYSTEM_ERROR = "800"
+    MAINTENANCE = "900"
+    UNKNOWN = "999"
+
+
+STATUS_MESSAGES: dict[StatusCode, str] = {
+    StatusCode.SUCCESS: "정상",
+    StatusCode.UNREGISTERED_KEY: "등록되지 않은 키",
+    StatusCode.INACTIVE_KEY: "사용할 수 없는 키",
+    StatusCode.INVALID_KEY: "잘못된 키",
+    StatusCode.USAGE_LIMIT_EXCEEDED: "일시적 사용 제한",
+    StatusCode.DAILY_LIMIT_EXCEEDED_FIELD: "필드 일일 조회 한도 초과",
+    StatusCode.DAILY_LIMIT_EXCEEDED_REQUESTS: "요청 일일 한도 초과",
+    StatusCode.MONTHLY_LIMIT_EXCEEDED: "월간 조회 한도 초과",
+    StatusCode.INVALID_PARAMETER: "잘못된 파라미터",
+    StatusCode.MISSING_REQUIRED_PARAMETER: "필수 파라미터 누락",
+    StatusCode.INVALID_REPORT_CODE: "잘못된 보고서 코드",
+    StatusCode.INVALID_DATE: "잘못된 날짜",
+    StatusCode.NO_DATA: "조회된 데이터 없음",
+    StatusCode.FILE_NOT_FOUND: "파일 없음",
+    StatusCode.SYSTEM_ERROR: "시스템 오류",
+    StatusCode.MAINTENANCE: "시스템 점검",
+    StatusCode.UNKNOWN: "알 수 없는 오류",
+}
+
+
+class ReportCode(StrEnum):
+    """보고서 코드."""
+
+    Q1 = "11013"  # 1분기보고서
+    HALF = "11012"  # 반기보고서
+    Q3 = "11014"  # 3분기보고서
+    ANNUAL = "11011"  # 사업보고서
+
+
+class CorpClass(StrEnum):
+    """기업 분류 코드."""
+
+    KOSPI = "Y"  # 유가증권시장
+    KOSDAQ = "K"  # 코스닥시장
+    KONEX = "N"  # 코넥스시장
+    ETC = "E"  # 기타법인
+
+
+class DisclosureType(StrEnum):
+    """공시 유형 코드."""
+
+    A = "A"  # 정기공시
+    B = "B"  # 주요사항보고
+    C = "C"  # 발행공시
+    D = "D"  # 지분공시
+    E = "E"  # 기타공시
+    F = "F"  # 외부감사관련
+    G = "G"  # 펀드공시
+    H = "H"  # 자산유동화
+    I = "I"  # 거래소공시  # noqa: E741
+    J = "J"  # 공정위공시
+
+
+class FinancialStatementType(StrEnum):
+    """재무제표 구분 코드."""
+
+    CONSOLIDATED = "CFS"  # 연결재무제표
+    SEPARATE = "OFS"  # 개별재무제표

opendart_fss/exceptions.py

@@ -0,0 +1,90 @@
+"""OpenDART API 예외 클래스."""
+
+from opendart_fss.constants import STATUS_MESSAGES, StatusCode
+
+
+class OpenDartError(Exception):
+    """OpenDART API 기본 예외."""
+
+    def __init__(self, message: str, status: str | None = None):
+        self.status = status
+        self.message = message
+        super().__init__(message)
+
+
+class APIError(OpenDartError):
+    """API 응답 오류."""
+
+    def __init__(self, status: str, message: str | None = None):
+        try:
+            status_code = StatusCode(status)
+            default_message = STATUS_MESSAGES.get(status_code, "알 수 없는 오류")
+        except ValueError:
+            default_message = "알 수 없는 오류"
+        super().__init__(message or default_message, status)
+
+
+class AuthenticationError(APIError):
+    """인증 관련 오류 (010, 011, 012)."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """요청 제한 오류 (013, 014, 015, 016)."""
+
+    pass
+
+
+class ValidationError(APIError):
+    """파라미터 검증 오류 (020, 021, 022, 023)."""
+
+    pass
+
+
+class NotFoundError(APIError):
+    """데이터 없음 오류 (100, 101)."""
+
+    pass
+
+
+class ServerError(APIError):
+    """서버 오류 (800, 900)."""
+
+    pass
+
+
+def raise_for_status(status: str, message: str | None = None) -> None:
+    """상태 코드에 따른 예외 발생."""
+    if status == StatusCode.SUCCESS:
+        return
+
+    error_class: type[APIError]
+    if status in (
+        StatusCode.UNREGISTERED_KEY,
+        StatusCode.INACTIVE_KEY,
+        StatusCode.INVALID_KEY,
+    ):
+        error_class = AuthenticationError
+    elif status in (
+        StatusCode.USAGE_LIMIT_EXCEEDED,
+        StatusCode.DAILY_LIMIT_EXCEEDED_FIELD,
+        StatusCode.DAILY_LIMIT_EXCEEDED_REQUESTS,
+        StatusCode.MONTHLY_LIMIT_EXCEEDED,
+    ):
+        error_class = RateLimitError
+    elif status in (
+        StatusCode.INVALID_PARAMETER,
+        StatusCode.MISSING_REQUIRED_PARAMETER,
+        StatusCode.INVALID_REPORT_CODE,
+        StatusCode.INVALID_DATE,
+    ):
+        error_class = ValidationError
+    elif status in (StatusCode.NO_DATA, StatusCode.FILE_NOT_FOUND):
+        error_class = NotFoundError
+    elif status in (StatusCode.SYSTEM_ERROR, StatusCode.MAINTENANCE):
+        error_class = ServerError
+    else:
+        error_class = APIError
+
+    raise error_class(status, message)

opendart_fss/models/__init__.py

@@ -0,0 +1,124 @@
+"""OpenDART API 모델."""
+
+from opendart_fss.models.base import BaseResponse
+from opendart_fss.models.disclosure import (
+    Company,
+    CompanyResponse,
+    CorpCode,
+    Disclosure,
+    DisclosureListResponse,
+)
+from opendart_fss.models.financial import (
+    FinancialAccount,
+    FinancialAccountListResponse,
+    FinancialIndicator,
+    FinancialIndicatorListResponse,
+    XbrlTaxonomy,
+    XbrlTaxonomyListResponse,
+)
+from opendart_fss.models.major_event import (
+    BonusIssue,
+    BonusIssueListResponse,
+    CapitalChange,
+    CapitalChangeListResponse,
+    ConvertibleBond,
+    ConvertibleBondListResponse,
+    MergerDecision,
+    MergerDecisionListResponse,
+    SplitDecision,
+    SplitDecisionListResponse,
+)
+from opendart_fss.models.registration import (
+    DebtSecurities,
+    DebtSecuritiesListResponse,
+    EquitySecurities,
+    EquitySecuritiesListResponse,
+    MergerRegistration,
+    MergerRegistrationListResponse,
+    SplitRegistration,
+    SplitRegistrationListResponse,
+)
+from opendart_fss.models.report import (
+    DirectorCompensation,
+    DirectorCompensationListResponse,
+    DividendInfo,
+    DividendInfoListResponse,
+    Employee,
+    EmployeeListResponse,
+    Executive,
+    ExecutiveListResponse,
+    IndividualCompensation,
+    IndividualCompensationListResponse,
+    LargestShareholder,
+    LargestShareholderListResponse,
+    StockChange,
+    StockChangeListResponse,
+    TreasuryStock,
+    TreasuryStockListResponse,
+)
+from opendart_fss.models.shareholder import (
+    ExecutiveStock,
+    ExecutiveStockListResponse,
+    MajorStock,
+    MajorStockListResponse,
+)
+
+__all__ = [
+    # Base
+    "BaseResponse",
+    # Disclosure (DS001)
+    "Disclosure",
+    "DisclosureListResponse",
+    "Company",
+    "CompanyResponse",
+    "CorpCode",
+    # Report (DS002)
+    "StockChange",
+    "StockChangeListResponse",
+    "DividendInfo",
+    "DividendInfoListResponse",
+    "TreasuryStock",
+    "TreasuryStockListResponse",
+    "LargestShareholder",
+    "LargestShareholderListResponse",
+    "Executive",
+    "ExecutiveListResponse",
+    "Employee",
+    "EmployeeListResponse",
+    "IndividualCompensation",
+    "IndividualCompensationListResponse",
+    "DirectorCompensation",
+    "DirectorCompensationListResponse",
+    # Financial (DS003)
+    "FinancialAccount",
+    "FinancialAccountListResponse",
+    "FinancialIndicator",
+    "FinancialIndicatorListResponse",
+    "XbrlTaxonomy",
+    "XbrlTaxonomyListResponse",
+    # Shareholder (DS004)
+    "MajorStock",
+    "MajorStockListResponse",
+    "ExecutiveStock",
+    "ExecutiveStockListResponse",
+    # Major Event (DS005)
+    "CapitalChange",
+    "CapitalChangeListResponse",
+    "BonusIssue",
+    "BonusIssueListResponse",
+    "ConvertibleBond",
+    "ConvertibleBondListResponse",
+    "MergerDecision",
+    "MergerDecisionListResponse",
+    "SplitDecision",
+    "SplitDecisionListResponse",
+    # Registration (DS006)
+    "EquitySecurities",
+    "EquitySecuritiesListResponse",
+    "DebtSecurities",
+    "DebtSecuritiesListResponse",
+    "MergerRegistration",
+    "MergerRegistrationListResponse",
+    "SplitRegistration",
+    "SplitRegistrationListResponse",
+]

opendart_fss/models/base.py

@@ -0,0 +1,10 @@
+"""기본 응답 모델."""
+
+import msgspec
+
+
+class BaseResponse(msgspec.Struct, kw_only=True):
+    """API 기본 응답."""
+
+    status: str
+    message: str

opendart_fss/models/disclosure.py

@@ -0,0 +1,106 @@
+"""DS001 공시정보 모델."""
+
+import msgspec
+
+from opendart_fss.models.base import BaseResponse
+
+
+class Disclosure(msgspec.Struct, kw_only=True):
+    """공시 검색 결과."""
+
+    corp_code: str  # 고유번호
+    corp_name: str  # 회사명
+    stock_code: str | None = None  # 종목코드
+    corp_cls: str | None = None  # 법인구분 (Y/K/N/E)
+    report_nm: str | None = None  # 보고서명
+    rcept_no: str | None = None  # 접수번호
+    flr_nm: str | None = None  # 공시제출인명
+    rcept_dt: str | None = None  # 접수일자 (YYYYMMDD)
+    rm: str | None = None  # 비고
+
+
+class DisclosureListResponse(msgspec.Struct, kw_only=True):
+    """공시 검색 응답."""
+
+    status: str
+    message: str
+    page_no: int | None = None
+    page_count: int | None = None
+    total_count: int | None = None
+    total_page: int | None = None
+    items: list[Disclosure] = msgspec.field(default_factory=list, name="list")
+
+
+class Company(msgspec.Struct, kw_only=True):
+    """기업 개황 정보."""
+
+    corp_code: str  # 고유번호
+    corp_name: str  # 정식명칭
+    corp_name_eng: str | None = None  # 영문명칭
+    stock_name: str | None = None  # 종목명(상장사) 또는 약식명칭(기타법인)
+    stock_code: str | None = None  # 상장회사인 경우 주식의 종목코드
+    ceo_nm: str | None = None  # 대표자명
+    corp_cls: str | None = None  # 법인구분 (Y/K/N/E)
+    jurir_no: str | None = None  # 법인등록번호
+    bizr_no: str | None = None  # 사업자등록번호
+    adres: str | None = None  # 주소
+    hm_url: str | None = None  # 홈페이지
+    ir_url: str | None = None  # IR홈페이지
+    phn_no: str | None = None  # 전화번호
+    fax_no: str | None = None  # 팩스번호
+    induty_code: str | None = None  # 업종코드
+    est_dt: str | None = None  # 설립일 (YYYYMMDD)
+    acc_mt: str | None = None  # 결산월 (MM)
+
+
+class CompanyResponse(BaseResponse, kw_only=True):
+    """기업 개황 응답."""
+
+    corp_code: str  # 고유번호
+    corp_name: str  # 정식명칭
+    corp_name_eng: str | None = None  # 영문명칭
+    stock_name: str | None = None  # 종목명(상장사) 또는 약식명칭(기타법인)
+    stock_code: str | None = None  # 상장회사인 경우 주식의 종목코드
+    ceo_nm: str | None = None  # 대표자명
+    corp_cls: str | None = None  # 법인구분 (Y/K/N/E)
+    jurir_no: str | None = None  # 법인등록번호
+    bizr_no: str | None = None  # 사업자등록번호
+    adres: str | None = None  # 주소
+    hm_url: str | None = None  # 홈페이지
+    ir_url: str | None = None  # IR홈페이지
+    phn_no: str | None = None  # 전화번호
+    fax_no: str | None = None  # 팩스번호
+    induty_code: str | None = None  # 업종코드
+    est_dt: str | None = None  # 설립일 (YYYYMMDD)
+    acc_mt: str | None = None  # 결산월 (MM)
+
+    def to_company(self) -> Company:
+        """Company 객체로 변환."""
+        return Company(
+            corp_code=self.corp_code,
+            corp_name=self.corp_name,
+            corp_name_eng=self.corp_name_eng,
+            stock_name=self.stock_name,
+            stock_code=self.stock_code,
+            ceo_nm=self.ceo_nm,
+            corp_cls=self.corp_cls,
+            jurir_no=self.jurir_no,
+            bizr_no=self.bizr_no,
+            adres=self.adres,
+            hm_url=self.hm_url,
+            ir_url=self.ir_url,
+            phn_no=self.phn_no,
+            fax_no=self.fax_no,
+            induty_code=self.induty_code,
+            est_dt=self.est_dt,
+            acc_mt=self.acc_mt,
+        )
+
+
+class CorpCode(msgspec.Struct, kw_only=True):
+    """고유번호 정보."""
+
+    corp_code: str  # 고유번호
+    corp_name: str  # 정식명칭
+    stock_code: str | None = None  # 종목코드 (상장사만)
+    modify_date: str | None = None  # 최종변경일 (YYYYMMDD)

opendart_fss/models/financial.py

@@ -0,0 +1,85 @@
+"""DS003 정기보고서 재무정보 모델."""
+
+import msgspec
+
+
+class FinancialAccount(msgspec.Struct, kw_only=True):
+    """재무제표 주요계정."""
+
+    rcept_no: str  # 접수번호
+    reprt_code: str | None = None  # 보고서 코드
+    bsns_year: str | None = None  # 사업연도
+    corp_code: str | None = None  # 고유번호
+    stock_code: str | None = None  # 종목코드
+    fs_div: str | None = None  # 개별/연결구분 (CFS/OFS)
+    fs_nm: str | None = None  # 개별/연결명
+    sj_div: str | None = None  # 재무제표구분 (BS/IS/CIS/CF/SCE)
+    sj_nm: str | None = None  # 재무제표명
+    account_id: str | None = None  # 계정ID
+    account_nm: str | None = None  # 계정명
+    account_detail: str | None = None  # 계정상세
+    thstrm_nm: str | None = None  # 당기명
+    thstrm_amount: str | None = None  # 당기금액
+    thstrm_add_amount: str | None = None  # 당기누적금액
+    frmtrm_nm: str | None = None  # 전기명
+    frmtrm_amount: str | None = None  # 전기금액
+    frmtrm_q_nm: str | None = None  # 전기명(분/반기)
+    frmtrm_q_amount: str | None = None  # 전기금액(분/반기)
+    frmtrm_add_amount: str | None = None  # 전기누적금액
+    bfefrmtrm_nm: str | None = None  # 전전기명
+    bfefrmtrm_amount: str | None = None  # 전전기금액
+    ord: str | None = None  # 계정과목 정렬순서
+    currency: str | None = None  # 통화단위
+
+
+class FinancialAccountListResponse(msgspec.Struct, kw_only=True):
+    """재무제표 주요계정 응답."""
+
+    status: str
+    message: str
+    items: list[FinancialAccount] = msgspec.field(default_factory=list, name="list")
+
+
+class FinancialIndicator(msgspec.Struct, kw_only=True):
+    """재무지표."""
+
+    rcept_no: str | None = None  # 접수번호
+    bsns_year: str | None = None  # 사업연도
+    corp_code: str | None = None  # 고유번호
+    stock_code: str | None = None  # 종목코드
+    reprt_code: str | None = None  # 보고서 코드
+    stlm_dt: str | None = None  # 결산기준일
+    idx_cl_code: str | None = None  # 지표분류코드
+    idx_cl_nm: str | None = None  # 지표분류명
+    idx_code: str | None = None  # 지표코드
+    idx_nm: str | None = None  # 지표명
+    idx_val: str | None = None  # 지표값
+
+
+class FinancialIndicatorListResponse(msgspec.Struct, kw_only=True):
+    """재무지표 응답."""
+
+    status: str
+    message: str
+    items: list[FinancialIndicator] = msgspec.field(default_factory=list, name="list")
+
+
+class XbrlTaxonomy(msgspec.Struct, kw_only=True):
+    """XBRL 택사노미."""
+
+    sj_div: str  # 재무제표구분
+    account_id: str | None = None  # 계정ID
+    account_nm: str | None = None  # 계정명
+    bsns_de: str | None = None  # 개시일자
+    label_kor: str | None = None  # 한글라벨
+    label_eng: str | None = None  # 영문라벨
+    data_tp: str | None = None  # 데이터타입
+    ifrs_ref: str | None = None  # IFRS참조
+
+
+class XbrlTaxonomyListResponse(msgspec.Struct, kw_only=True):
+    """XBRL 택사노미 응답."""
+
+    status: str
+    message: str
+    items: list[XbrlTaxonomy] = msgspec.field(default_factory=list, name="list")