opendart-fss 0.1.0__py3-none-any.whl

opendart_fss/__init__.py

@@ -0,0 +1,77 @@
+"""OpenDART FSS Python SDK.
+
+금융감독원 전자공시시스템 OpenDART API를 위한 Python SDK입니다.
+
+Example:
+    ```python
+    import asyncio
+    from opendart_fss import OpenDartClient
+
+    async def main():
+        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}")
+            print(f"대표자: {company.ceo_nm}")
+
+            # 재무제표 조회
+            financials = await client.financial.get_single_account(
+                corp_code="00126380",
+                bsns_year="2024",
+                reprt_code="11011"  # 사업보고서
+            )
+
+            for item in financials:
+                print(f"{item.account_nm}: {item.thstrm_amount}")
+
+    asyncio.run(main())
+    ```
+"""
+
+from opendart_fss.client import OpenDartClient
+from opendart_fss.constants import (
+    CorpClass,
+    DisclosureType,
+    FinancialStatementType,
+    ReportCode,
+    StatusCode,
+)
+from opendart_fss.exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    OpenDartError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+try:
+    from opendart_fss._version import __version__
+except ImportError:
+    __version__ = "0.0.0"  # fallback for editable installs without build
+__all__ = [
+    # Client
+    "OpenDartClient",
+    # Constants
+    "StatusCode",
+    "ReportCode",
+    "CorpClass",
+    "DisclosureType",
+    "FinancialStatementType",
+    # Exceptions
+    "OpenDartError",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+]

opendart_fss/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

opendart_fss/api/__init__.py

@@ -0,0 +1,19 @@
+"""OpenDART API 클래스."""
+
+from opendart_fss.api.base import BaseAPI
+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
+
+__all__ = [
+    "BaseAPI",
+    "DisclosureAPI",
+    "ReportAPI",
+    "FinancialAPI",
+    "ShareholderAPI",
+    "MajorEventAPI",
+    "RegistrationAPI",
+]

opendart_fss/api/base.py

@@ -0,0 +1,72 @@
+"""API 기본 클래스."""
+
+from typing import TYPE_CHECKING
+
+import httpx
+import msgspec
+
+from opendart_fss.constants import BASE_URL
+from opendart_fss.exceptions import raise_for_status
+
+if TYPE_CHECKING:
+    from opendart_fss.client import OpenDartClient
+
+
+class BaseAPI:
+    """API 기본 클래스."""
+
+    def __init__(self, client: "OpenDartClient") -> None:
+        self._client = client
+
+    @property
+    def _http(self) -> httpx.AsyncClient:
+        return self._client._http
+
+    @property
+    def _api_key(self) -> str:
+        return self._client.api_key
+
+    async def _request[T: msgspec.Struct](
+        self,
+        method: str,
+        endpoint: str,
+        response_type: type[T],
+        *,
+        params: dict | None = None,
+    ) -> T:
+        """API 요청 수행."""
+        url = f"{BASE_URL}{endpoint}"
+        request_params = {"crtfc_key": self._api_key}
+        if params:
+            request_params.update({k: v for k, v in params.items() if v is not None})
+
+        response = await self._http.request(method, url, params=request_params)
+        response.raise_for_status()
+
+        result = msgspec.json.decode(response.content, type=response_type)
+
+        if hasattr(result, "status"):
+            raise_for_status(result.status, getattr(result, "message", None))
+
+        return result
+
+    async def _get[T: msgspec.Struct](
+        self,
+        endpoint: str,
+        response_type: type[T],
+        *,
+        params: dict | None = None,
+    ) -> T:
+        """GET 요청."""
+        return await self._request("GET", endpoint, response_type, params=params)
+
+    async def _download(self, endpoint: str, *, params: dict | None = None) -> bytes:
+        """파일 다운로드 (ZIP, XML 등)."""
+        url = f"{BASE_URL}{endpoint}"
+        request_params = {"crtfc_key": self._api_key}
+        if params:
+            request_params.update({k: v for k, v in params.items() if v is not None})
+
+        response = await self._http.get(url, params=request_params)
+        response.raise_for_status()
+        return response.content

opendart_fss/api/disclosure.py

@@ -0,0 +1,103 @@
+"""DS001 공시정보 API."""
+
+from opendart_fss.api.base import BaseAPI
+from opendart_fss.models.disclosure import (
+    Company,
+    CompanyResponse,
+    Disclosure,
+    DisclosureListResponse,
+)
+
+
+class DisclosureAPI(BaseAPI):
+    """공시정보 API (DS001)."""
+
+    async def search(
+        self,
+        *,
+        corp_code: str | None = None,
+        bgn_de: str | None = None,
+        end_de: str | None = None,
+        last_reprt_at: str | None = None,
+        pblntf_ty: str | None = None,
+        pblntf_detail_ty: str | None = None,
+        corp_cls: str | None = None,
+        sort: str | None = None,
+        sort_mth: str | None = None,
+        page_no: int | None = None,
+        page_count: int | None = None,
+    ) -> list[Disclosure]:
+        """공시검색.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+            bgn_de: 시작일 (YYYYMMDD)
+            end_de: 종료일 (YYYYMMDD)
+            last_reprt_at: 최종보고서만 검색여부 (Y/N)
+            pblntf_ty: 공시유형 (A~J)
+            pblntf_detail_ty: 공시상세유형
+            corp_cls: 법인구분 (Y/K/N/E)
+            sort: 정렬 기준 (date/crp/rpt)
+            sort_mth: 정렬 방법 (asc/desc)
+            page_no: 페이지 번호
+            page_count: 페이지당 건수 (최대 100)
+
+        Returns:
+            공시 목록
+        """
+        response = await self._get(
+            "/api/list.json",
+            DisclosureListResponse,
+            params={
+                "corp_code": corp_code,
+                "bgn_de": bgn_de,
+                "end_de": end_de,
+                "last_reprt_at": last_reprt_at,
+                "pblntf_ty": pblntf_ty,
+                "pblntf_detail_ty": pblntf_detail_ty,
+                "corp_cls": corp_cls,
+                "sort": sort,
+                "sort_mth": sort_mth,
+                "page_no": page_no,
+                "page_count": page_count,
+            },
+        )
+        return response.items
+
+    async def get_company(self, corp_code: str) -> Company:
+        """기업개황 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+
+        Returns:
+            기업 개황 정보
+        """
+        response = await self._get(
+            "/api/company.json",
+            CompanyResponse,
+            params={"corp_code": corp_code},
+        )
+        return response.to_company()
+
+    async def download_document(self, rcept_no: str) -> bytes:
+        """공시서류 원본 다운로드.
+
+        Args:
+            rcept_no: 접수번호 (14자리)
+
+        Returns:
+            ZIP 파일 바이트
+        """
+        return await self._download(
+            "/api/document.xml",
+            params={"rcept_no": rcept_no},
+        )
+
+    async def download_corp_codes(self) -> bytes:
+        """고유번호 전체 다운로드.
+
+        Returns:
+            ZIP 파일 바이트 (CORPCODE.xml 포함)
+        """
+        return await self._download("/api/corpCode.xml")

opendart_fss/api/financial.py

@@ -0,0 +1,206 @@
+"""DS003 정기보고서 재무정보 API."""
+
+from opendart_fss.api.base import BaseAPI
+from opendart_fss.models.financial import (
+    FinancialAccount,
+    FinancialAccountListResponse,
+    FinancialIndicator,
+    FinancialIndicatorListResponse,
+    XbrlTaxonomy,
+    XbrlTaxonomyListResponse,
+)
+
+
+class FinancialAPI(BaseAPI):
+    """정기보고서 재무정보 API (DS003)."""
+
+    async def get_single_account(
+        self,
+        corp_code: str,
+        bsns_year: str,
+        reprt_code: str,
+        fs_div: str = "CFS",
+    ) -> list[FinancialAccount]:
+        """단일회사 주요계정 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+            bsns_year: 사업연도 (YYYY)
+            reprt_code: 보고서 코드 (11011~11014)
+            fs_div: 개별/연결 구분 (CFS/OFS)
+
+        Returns:
+            주요계정 목록
+        """
+        response = await self._get(
+            "/api/fnlttSinglAcnt.json",
+            FinancialAccountListResponse,
+            params={
+                "corp_code": corp_code,
+                "bsns_year": bsns_year,
+                "reprt_code": reprt_code,
+                "fs_div": fs_div,
+            },
+        )
+        return response.items
+
+    async def get_multi_account(
+        self,
+        corp_code: str,
+        bsns_year: str,
+        reprt_code: str,
+        fs_div: str = "CFS",
+    ) -> list[FinancialAccount]:
+        """다중회사 주요계정 조회.
+
+        Args:
+            corp_code: 고유번호 (쉼표로 구분, 최대 100개)
+            bsns_year: 사업연도 (YYYY)
+            reprt_code: 보고서 코드 (11011~11014)
+            fs_div: 개별/연결 구분 (CFS/OFS)
+
+        Returns:
+            주요계정 목록
+        """
+        response = await self._get(
+            "/api/fnlttMultiAcnt.json",
+            FinancialAccountListResponse,
+            params={
+                "corp_code": corp_code,
+                "bsns_year": bsns_year,
+                "reprt_code": reprt_code,
+                "fs_div": fs_div,
+            },
+        )
+        return response.items
+
+    async def get_full_statements(
+        self,
+        corp_code: str,
+        bsns_year: str,
+        reprt_code: str,
+        fs_div: str = "CFS",
+    ) -> list[FinancialAccount]:
+        """단일회사 전체 재무제표 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+            bsns_year: 사업연도 (YYYY)
+            reprt_code: 보고서 코드 (11011~11014)
+            fs_div: 개별/연결 구분 (CFS/OFS)
+
+        Returns:
+            전체 재무제표 계정 목록
+        """
+        response = await self._get(
+            "/api/fnlttSinglAcntAll.json",
+            FinancialAccountListResponse,
+            params={
+                "corp_code": corp_code,
+                "bsns_year": bsns_year,
+                "reprt_code": reprt_code,
+                "fs_div": fs_div,
+            },
+        )
+        return response.items
+
+    async def download_xbrl(
+        self,
+        rcept_no: str,
+        reprt_code: str,
+    ) -> bytes:
+        """XBRL 원본파일 다운로드.
+
+        Args:
+            rcept_no: 접수번호 (14자리)
+            reprt_code: 보고서 코드 (11011~11014)
+
+        Returns:
+            ZIP 파일 바이트
+        """
+        return await self._download(
+            "/api/fnlttXbrl.xml",
+            params={
+                "rcept_no": rcept_no,
+                "reprt_code": reprt_code,
+            },
+        )
+
+    async def get_xbrl_taxonomy(
+        self,
+        sj_div: str,
+    ) -> list[XbrlTaxonomy]:
+        """XBRL 택사노미 조회.
+
+        Args:
+            sj_div: 재무제표구분 (BS/IS/CIS/CF/SCE)
+
+        Returns:
+            택사노미 목록
+        """
+        response = await self._get(
+            "/api/xbrlTaxonomy.json",
+            XbrlTaxonomyListResponse,
+            params={"sj_div": sj_div},
+        )
+        return response.items
+
+    async def get_indicators(
+        self,
+        corp_code: str,
+        bsns_year: str,
+        reprt_code: str,
+        idx_cl_code: str | None = None,
+    ) -> list[FinancialIndicator]:
+        """다중회사 재무지표 조회.
+
+        Args:
+            corp_code: 고유번호 (쉼표로 구분, 최대 100개)
+            bsns_year: 사업연도 (YYYY)
+            reprt_code: 보고서 코드 (11011~11014)
+            idx_cl_code: 지표분류코드 (선택)
+
+        Returns:
+            재무지표 목록
+        """
+        response = await self._get(
+            "/api/fnlttCmpnyIndx.json",
+            FinancialIndicatorListResponse,
+            params={
+                "corp_code": corp_code,
+                "bsns_year": bsns_year,
+                "reprt_code": reprt_code,
+                "idx_cl_code": idx_cl_code,
+            },
+        )
+        return response.items
+
+    async def get_single_indicators(
+        self,
+        corp_code: str,
+        bsns_year: str,
+        reprt_code: str,
+        idx_cl_code: str,
+    ) -> list[FinancialIndicator]:
+        """단일회사 주요 재무지표 조회.
+
+        Args:
+            corp_code: 고유번호 (8자리)
+            bsns_year: 사업연도 (YYYY, 2023년 3분기 이후)
+            reprt_code: 보고서 코드 (11011~11014)
+            idx_cl_code: 지표분류코드 (M210000~M240000)
+
+        Returns:
+            재무지표 목록
+        """
+        response = await self._get(
+            "/api/fnlttSinglIndx.json",
+            FinancialIndicatorListResponse,
+            params={
+                "corp_code": corp_code,
+                "bsns_year": bsns_year,
+                "reprt_code": reprt_code,
+                "idx_cl_code": idx_cl_code,
+            },
+        )
+        return response.items