자모가 분리된 한글 파일명 조합

fix_hangul_filename.py

import os
import sys
import unicodedata

def fix_hangul_in_filenames(directory: str, recursive: bool = False):
    """
    주어진 디렉토리 내에서 한글 자모가 분리되어 있는 파일명을 찾아
    정상적인 한글 형태(NFC 형태)로 변환하는 함수입니다.

    매개변수:
        directory (str): 검사할 디렉토리의 경로
        recursive (bool): 하위 디렉토리까지 포함할지 여부 (기본값: False)
    """

    # 1. 지정된 경로가 실제로 존재하는 디렉토리인지 확인
    if not os.path.isdir(directory):
        print(f"❌ 지정한 경로가 디렉토리가 아닙니다: {directory}")
        return

    # 2. os.walk()를 사용하여 디렉토리 내의 파일 목록을 순회
    #    recursive=False이면 하위 폴더는 탐색하지 않음
    for root, dirs, files in os.walk(directory):
        for name in files:
            # 3. 파일명을 유니코드 정규화(NFC)하여 한글 자모를 조합
            normalized_name = unicodedata.normalize('NFC', name)

            # 4. 원래 이름과 정규화된 이름이 다를 경우에만 수정 수행
            if name != normalized_name:
                old_path = os.path.join(root, name)
                new_path = os.path.join(root, normalized_name)

                try:
                    # 5. 파일 이름 변경 (rename)
                    os.rename(old_path, new_path)
                    print(f"✅ 파일명 수정 완료: '{name}' → '{normalized_name}'")

                except Exception as e:
                    # 6. 권한 문제나 중복 파일명 등으로 실패할 경우 예외 처리
                    print(f"⚠️ 파일명 변경 실패: '{name}' → '{normalized_name}' ({e})")

        # recursive=False이면 현재 디렉토리까지만 수행
        if not recursive:
            break


if __name__ == "__main__":
    """
    명령행에서 실행할 때의 진입점.
    사용자가 인수로 디렉토리 경로를 지정해야 함.
    예:
        python fix_hangul_filename.py "C:\\Videos"
        python fix_hangul_filename.py "/Users/junseok/Downloads" --recursive
    """

    # 인자가 충분히 주어지지 않았을 경우 안내 메시지 출력
    if len(sys.argv) < 2:
        print("사용법: python fix_hangul_filename.py <디렉토리경로> [--recursive]")
        sys.exit(1)

    # 첫 번째 인자는 디렉토리 경로
    target_dir = sys.argv[1]

    # '--recursive' 옵션이 포함되어 있으면 하위 폴더까지 처리
    recursive = "--recursive" in sys.argv

    print(f"🔍 디렉토리 검사 시작: {target_dir}")
    if recursive:
        print("↳ 하위 디렉토리까지 포함하여 검사합니다.")
    else:
        print("↳ 현재 디렉토리만 검사합니다.")

    # 파일명 복원 실행
    fix_hangul_in_filenames(target_dir, recursive)

    print("✅ 모든 파일 검사 완료.")