Gather KRX Flow (외국인/기관/개인)

공개 호출 방식

import dartlab

# 일별 외국인/기관/개인 net-buy
flow = dartlab.gather("flow", "005930")
if not flow.is_empty():
    print(flow.head(30))            # 최근 30 일
    # 누적
    import polars as pl
    cumulative = flow.with_columns([
        pl.col("foreignNet").cum_sum().alias("foreignCum"),
        pl.col("institutionNet").cum_sum().alias("institutionCum"),
    ])

# 백필/프록시 옵션은 공개 gather 엔진 경유:
dartlab.gather("flow", "005930", start="2010-01-04", sleepSec=1.0)
dartlab.gather("flow", "005930", all=True, proxy="http://user:pass@host:port")
dartlab.gather("flow", targets=["005930", "000660"], limit=30, parallel=2, proxy="http://user:pass@host:port")

호출 동작

• target = DART 종목코드 (KOSPI/KOSDAQ). KR 한정 — 외 시장 target 은 빈 DataFrame.
• 공개 호출계약은 dartlab.gather("flow", ...) 만 사용한다.
• NaverPay 증권 flow API 자동 호출. 백필/프록시 옵션은 dartlab.gather("flow", ...) 공개 계약에서만 사용.
• 여러 종목은 targets=[...] 로 넘기며, parallel 생략 시 min(종목수, 4) 로 자동 병렬 처리한다.
• proxy 는 gather HTTP client 공통 호출 범위에 적용된다. 병렬 수집도 같은 프록시 경로를 사용한다.
• 빈 결과 (KR 외 시장 · 신생 종목 · Naver API 부재) → 빈 DataFrame.
• 일별 EOD (T+1) freshness.

대표 반환 형태

pl.DataFrame:
  date : Date
  foreignNet : Int64        # 외국인 일별 순매수 (주)
  institutionNet : Int64    # 기관 일별 순매수 (주)
  individualNet : Int64     # 개인 일별 순매수 (주)
  (또는 시장 변경 시 추가 컬럼)

기본 검증

• 모든 수급 수치 claim 은 tableRef 또는 dateRef 의 sourceRef 에 묶는다.
• 일별 raw flow 전체 dump 금지 — 답변 본문 최근 5~30 일 + 누적 cumsum 또는 비중만 인용.
• 외국인 net-buy 단독 답변 금지 — 기관 동조/역행 context 동반 (둘 다 매수 = 강한 신호 · 외국인 매수+기관 매도 = 분리).
• KR 외 시장 target 호출 시 빈 결과 — 답변 본문에서 “시장 제한 (KR 한정)” 명시.
• 종목 펀더멘털 (실적 · 공시) context 없이 수급만 보고 매매 결론 금지.
• 백필/프록시/병렬 호출계약은 dartlab.gather("flow", ...) 로만 공개한다.