Source code for pyqqq.data.market

import datetime as dtm
from typing import Optional

import pandas as pd

import pyqqq.config as c
from pyqqq.utils.api_client import raise_for_status, send_request

LIQUIDITY_COLUMNS = [
    "investor_deposit",
    "forced_liquidation_amount",
    "forced_liquidation_ratio",
    "credit_loan_kospi",
    "credit_loan_kosdaq",
]




def get_market_liquidity(start_date: Optional[dtm.date] = None, end_date: Optional[dtm.date] = None) -> pd.DataFrame:
    """
    증시 주변자금 지표(투자자예탁금, 반대매매, 신용거래융자)를 조회합니다.

    금융투자협회 종합통계의 거래일 기준 일별 값이며, 종목별이 아닌 시장 전체 값입니다.

    - 통계 공표가 T+1 이후로 지연되므로 최근 1~2 거래일은 아직 조회되지 않을 수 있습니다.
    - 지표별로 공표 시점이 달라 일부 컬럼만 채워진 날이 있을 수 있으며, 없는 값은 NaN으로 반환됩니다.

    Args:
        start_date (dtm.date, optional): 조회 시작일. 기본값은 None이며, 이 경우 가장 최근 1건을 반환합니다.
        end_date (dtm.date, optional): 조회 종료일. 지정하지 않으면 오늘까지 조회됩니다. start_date 없이 지정할 수 없습니다.

    Returns:
        pd.DataFrame: 'date' 열이 인덱스로 설정된 날짜 오름차순 DataFrame. 조회된 데이터가 없으면 빈 DataFrame이 반환됩니다.
        결측값(NaN)을 표현하기 위해 모든 컬럼은 float 타입입니다.

        - date (datetime.date): 거래일 (인덱스)
        - investor_deposit (float): 투자자예탁금 (원, 장내파생상품 거래예수금 제외)
        - forced_liquidation_amount (float): 위탁매매 미수금 대비 실제 반대매매금액 (원)
        - forced_liquidation_ratio (float): 미수금 대비 반대매매비중 (%)
        - credit_loan_kospi (float): 신용거래융자 잔고 - 유가증권시장 (원)
        - credit_loan_kosdaq (float): 신용거래융자 잔고 - 코스닥시장 (원)

    Raises:
        requests.exceptions.RequestException: PYQQQ API로부터 데이터를 검색하는 과정에서 오류가 발생한 경우.

    Examples:
        >>> df = get_market_liquidity(dtm.date(2026, 8, 5), dtm.date(2026, 8, 7))
        >>> print(df)
                    investor_deposit  forced_liquidation_amount  forced_liquidation_ratio  credit_loan_kospi  credit_loan_kosdaq
        date
        2026-08-05      1.032125e+14               1.176826e+10                       1.0       2.252032e+13        5.897647e+12
        2026-08-06      1.040712e+14               1.069424e+10                       1.0       2.286851e+13        5.925503e+12
        2026-08-07      1.042064e+14               2.344273e+10                       2.2       2.309995e+13        6.130422e+12

        >>> df = get_market_liquidity()  # 가장 최근 1건
        >>> print(df)
                    investor_deposit  forced_liquidation_amount  forced_liquidation_ratio  credit_loan_kospi  credit_loan_kosdaq
        date
        2026-10-13      1.000983e+14               5.934961e+10                       5.6       2.672747e+13        7.525401e+12
    """
    assert start_date is None or type(start_date) is dtm.date, "start_date must be a datetime.date object"
    assert end_date is None or type(end_date) is dtm.date, "end_date must be a datetime.date object"
    assert start_date is not None or end_date is None, "start_date is required when end_date is given"
    if start_date and end_date:
        assert start_date <= end_date, "start_date must be same or before end_date"

    url = f"{c.PYQQQ_API_URL}/market/liquidity"
    params = {}
    if start_date:
        params["start"] = start_date
    if end_date:
        params["end"] = end_date

    r = send_request("GET", url, params=params)
    if r.status_code == 404:
        return pd.DataFrame()
    raise_for_status(r)

    # 기간 미지정 시 서버는 최근 1건을 객체로 반환한다
    body = r.json()
    rows = [body] if isinstance(body, dict) else body
    return _to_liquidity_frame(rows)



def _to_liquidity_frame(rows: list) -> pd.DataFrame:
    df = pd.DataFrame(rows)
    if df.empty:
        return df

    df["date"] = pd.to_datetime(df["date"], format="%Y%m%d").dt.date
    df = df.set_index("date").sort_index()
    return df.reindex(columns=LIQUIDITY_COLUMNS).astype(float)