"""
file:    log_utils.py
date:    2026/02/15
brief:   공통 로깅(logger) 설정 유틸리티

본 모듈은 프로젝트 전반에서 사용되는 표준 logger를 생성하고 설정한다.
콘솔 출력(StreamHandler)과 파일 출력(FileHandler)을 동시에 지원하며,
중복 핸들러 등록을 방지하도록 설계되어 있다.

특징:
- logger 이름은 고정("region_growing")으로 사용
- 로그 레벨은 INFO로 설정
- 기존 핸들러가 있을 경우 모두 제거 후 재설정
- log_file이 지정된 경우에만 파일 로깅 활성화

----------------------------------------------------------------------
Version     Date        Comment
---------   ----------  ----------------------------------------------

"""


import logging
import os


def setup_logger(log_file: str | None):
    """
    표준 logger 객체를 생성하고 콘솔/파일 핸들러를 설정한다.

    동작 요약:
    - 이름이 "region_growing"인 logger를 가져오거나 생성
    - 로그 레벨을 INFO로 설정
    - propagate를 False로 설정하여 상위 logger로의 중복 출력 방지
    - 기존 핸들러가 존재할 경우 모두 제거
    - 콘솔(StreamHandler)은 항상 추가
    - log_file이 지정된 경우 파일(FileHandler) 로깅 추가

    Parameters
    ----------
    log_file : str | None
        로그 파일 경로.
        - None이면 콘솔 출력만 수행
        - 문자열이면 해당 경로에 UTF-8 인코딩으로 로그 파일 생성

    Returns
    -------
    logging.Logger
        설정이 완료된 logger 객체
    """
    logger = logging.getLogger("region_growing")
    logger.setLevel(logging.INFO)
    logger.propagate = False

    # 기존 핸들러가 있을 경우 제거 (중복 로그 방지)
    if logger.handlers:
        for h in list(logger.handlers):
            logger.removeHandler(h)

    # 로그 출력 포맷 정의
    fmt = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")

    # 콘솔 출력용 핸들러
    sh = logging.StreamHandler()
    sh.setFormatter(fmt)
    logger.addHandler(sh)

    # 파일 출력용 핸들러 (log_file이 지정된 경우만)
    if log_file:
        os.makedirs(os.path.dirname(log_file), exist_ok=True)
        fh = logging.FileHandler(log_file, encoding="utf-8")
        fh.setFormatter(fmt)
        logger.addHandler(fh)

    return logger