krx-news-client

한국 주식시장의 뉴스·공시를 모아 하나의 스키마로 내주는 Python 클라이언트 라이브러리 — DART, 토스증권.

매체마다 HTML 구조도 갱신 주기도 제각각이라, 뉴스를 쓰려는 쪽이 매번 크롤러를 다시 짜게 된다. 그 일을 한 번만 하려고 만들었다. kiwoom-client와 같은 성격의 라이브러리다 — 서버를 띄우지 않고, 호출한 프로세스 안에서 그때그때 매체에 직접 요청해 정규화된 결과를 돌려준다.

설치

Python 3.11 이상.

pip install krx-news-client

빠른 시작

import asyncio
from krx_news_client import TossScraper

async def main():
    scraper = TossScraper()
    try:
        articles = await scraper.scrape_news()
        for article in articles[:5]:
            print(article.title, article.published_at)
    finally:
        await scraper.close()

asyncio.run(main())

실행하면 이런 식으로 출력된다:

코스피, 외국인 순매수에 2%대 상승 마감 2025-06-10 15:30:00+09:00
삼성전자, 3분기 실적 시장 예상 상회 2025-06-10 14:05:00+09:00
...

DART 공시는 API 키가 필요하다:

from krx_news_client import DartScraper

scraper = DartScraper(api_key="...")
disclosures = await scraper.scrape_disclosures()

더 많은 예제는 examples/ 참고.

수집 소스

수집한 기사는 매체와 무관하게 NewsArticle, 공시는 Disclosure 한 벌로 정규화한다. 소스가 늘어도 호출 코드는 그대로다.

응답 필드

NewsArticle

Disclosure는 id·source·title·url·published_at·collected_at은 같고, category·content·summary·tickers·author는 없는 대신 company·ticker·disclosure_type(공시 유형)이 있다.

구조

flowchart LR
    Caller["호출 프로세스\n(예: quant-airflow)"]

    subgraph Client["krx-news-client"]
        direction TB
        Toss["TossScraper\n.scrape_news()"]
        Dart["DartScraper\n.scrape_disclosures()"]
        Base["BaseScraper\nUA 순환 · 간격 조절(throttle)\n재시도 · 429 백오프"]
        Schema["schemas.py\nNewsArticle · Disclosure"]

        Toss --> Base
        Dart --> Base
        Toss -->|_make_article| Schema
        Dart -->|_make_disclosure| Schema
    end

    TossAPI[("토스증권\nwts-info-api\n(비공식 내부 API)")]
    DartAPI[("DART\nopendart.fss.or.kr\n(공식 Open API)")]

    Caller -->|await scraper.scrape_news()\n / scrape_disclosures()| Client
    Base -->|POST 대시보드 피드| TossAPI
    Base -->|GET list.json| DartAPI
    Client -->|list[NewsArticle]\n / list[Disclosure]| Caller

BaseScraper가 재시도·429 백오프 등 공통 처리를 맡고, 각 스크레이퍼는 매체 응답을 파싱해 정규화된 스키마로 변환하는 일만 한다. DART는 일한도(status=020) 소진 시 DartQuotaExceededError를 던져 "공시 없음"과 "한도 초과"를 구분할 수 있게 한다.

저장이 필요하면 호출하는 쪽에서 알아서 한다 (예: quant-airflow가 이 라이브러리로 수집해 TimescaleDB에 적재).

라이선스

Apache License 2.0 — 전문은 LICENSE 참조.

⭐ 도움이 되셨다면

이 프로젝트가 유용했다면 우측 상단 ⭐ Star 를 눌러주세요. 검색·추천 노출이 올라가 더 많은 분들이 찾을 수 있습니다.

• 🐛 버그·질문 → Issues
• 📈 업데이트 소식 → 팔로우 @younghwan91

관련 프로젝트 — 오픈소스 퀀트 스택

한국·미국 주식과 암호화폐를 아우르는 오픈소스 스택입니다. 각 저장소는 독립적으로 쓸 수 있습니다.

만든 사람

채영환 (Younghwan Chae) · GitHub @younghwan91 · LinkedIn

전체 오픈소스 퀀트 스택은 프로필에서 한눈에 볼 수 있습니다.