[Python] 파이썬으로 규칙기반에 의해 데스크톱 파일을 정리하는 프로그램 만들기 (1)

 

AI 서버, OCR, PDF 분석 없이
로컬 규칙 기반 MVP를 구현했다.
핵심 코드, 파일 설명 등
간단하게만 기록용으로 적어보겠다.

 

 

 

 

[ GitHub에 코드 설명이 잘 적혀있습니다 ]

 

- Python 파일

GitHub - hyeong-ing/DesktopCleanAI at cleanAI

 

 

- rules.txt

GitHub - hyeong-ing/DesktopCleanAI at deskpilot

 

 

 

 

1. 배경

• 테스트 데스크톱

진짜 데스크톱에 할 수가 없어서 이렇게 테스트 데스크톱을 만들었다. 

 

 

• 터미널에서 코드 실행

터미널에서 확인했다.

 

 

 

 

---

 

 

 

 

2. 파일 설명

• 주요 파일

폴더명	설명
config.py	프로젝트 설정값 관리, 여기서 test_desktop 설정함
scanner.py	파일과 폴더를 스캔함
rules.py	rules.txt 읽음
classifier.py	태그와 rules.txt 기준 분류함
planner.py	파일별 정리 계획 생성함
path_planner.py	실제 이동될 경로 계산함
mover.py	파일 이동을 실행함
log_store.py	move-log.json 저장하고 읽음
undo.py	되돌리기 기능
redo.py	앞으로가기 기능
selected_mover.py	선택한 파일만 이동함
doctor.py	프로젝트 상태 점검함
deskpilot.py	통합 실행 파일

 

 

• rules.txt

school: 정보처리기사, 서술형, 기사 
study: 스프링, 강의, 공부, 기본편 
project: project, api, test, lotto

이 파일은 테스트 폴더인 test_desktop에 만든다. 그냥 두면 안되고 .을 붙인 숨겨진 폴더를 만들어서 둬야한다. 그 부분은 아래 링크로 걸어두겠다. 숨김 폴더 이름은 .deskpilot이고 그 안에 rules.txt를 넣었다.

rules.txt는 말그대로 규칙을 적어둔다. 정보처리기사, 서술형, 기사라는 단어가 제목에 붙어있으면 school 폴더로 이동한다.

- 숨김 폴더

[macOS] Finder 숨김 파일 보기 & 숨김 설정 & 숨김 해제

 

 

 

---

 

 

 

3. 중요한 코드만

• config.py

TEST_DESKTOP_FOLDER_NAME = "test_desktop"
APP_FOLDER_NAME = ".deskpilot"
ARCHIVE_FOLDER_NAME = "archive"

MOVE_CONFIRM_TEXT = "정리하기"
UNDO_CONFIRM_TEXT = "되돌리기"
REDO_CONFIRM_TEXT = "앞으로가기"

EXCLUDED_FILENAMES = {
    ".DS_Store",
    "desktop.ini",
    "Thumbs.db",
    "rules.txt",
    "move-log.json",
}

EXCLUDED_FOLDER_NAMES = {
    APP_FOLDER_NAME,
    "deskpilot",
    "__pycache__",
}

나중에 테스트 폴더도 바꿔야하하고 제외 시킨 파일이 추가되거나 제거될 여러 가능성을 고려해서 한곳에 기능을 관리하도록 모았다. 이 파일에서 테스트 폴더 이름, 확인 문구(확인문구를 제대로 적어야 기능이 실행되도록 만들었음), 제외 파일 목록을 볼 수 있다.

 

 

• scanner.py

def get_desktop_path():
    return Path.home() / "Desktop" / TEST_DESKTOP_FOLDER_NAME

테스트용 가짜 Desktop 폴더 경로를 가져온다.

def scan_desktop_files():
    desktop_path = get_desktop_path()
    validate_desktop_path(desktop_path)

    files = []

    for item in desktop_path.iterdir():
        if not item.is_file():
            continue

        if is_hidden_path(item):
            continue

        if is_excluded_file(item):
            continue

        files.append(item)

    return sorted(files, key=lambda path: path.name.lower())

test_desktop 바로 아래에 있는 파일만 가져오는 함수이다. 그런데 이때 폴더, 숨김 파일, 시스템 파일, rules.txt, move-log.json을 제외한다.

def scan_destination_folders():
    desktop_path = get_desktop_path()
    validate_desktop_path(desktop_path)

    folders = []

    for item in desktop_path.iterdir():
        if not item.is_dir():
            continue

        if is_hidden_path(item):
            continue

        if is_excluded_folder(item):
            continue

        folders.append(item)

    return sorted(folders, key=lambda path: path.name.lower())

test_desktop 바로 아래에 있는 폴더만 가져오는 함수이다. 이 폴더들은 나중에 파일을 이동할 목적지 후보가 된다. 파일, 숨김 폴더, 앱 내부 설정 폴더, 파이썬 캐시 폴더는 제외된다.

 

 

• rules.py

def get_rules_path():
    return get_desktop_path() / APP_FOLDER_NAME / "rules.txt"

rules.txt 파일 경로를 가져온다.

def read_rules():
    rules_path = get_rules_path()

    if not rules_path.exists():
        return {}

    rules = {}

    with open(rules_path, "r", encoding="utf-8") as file:
        for line in file:
            line = line.strip()

            if line == "" or line.startswith("#"):
                continue

            if ":" not in line:
                continue

            folder_name, keywords_text = line.split(":", 1)
            folder_name = folder_name.strip()

            keywords = []

            for keyword in keywords_text.split(","):
                keyword = keyword.strip()

                if keyword != "":
                    keywords.append(keyword)

            if folder_name != "" and keywords:
                rules[folder_name] = keywords

    return rules

rules.txt를 읽어서 파이썬 딕셔너리로 바꾸는 함수이다. 

이 txt를 읽어서

    rules.txt 예:
    school: 정보처리기사, 서술형, 기사
    study: 스프링, 강의, 공부​

 

이렇게 변환한다.

    {
        "school": ["정보처리기사", "서술형", "기사"],
        "study": ["스프링", "강의", "공부"]
    }​

 

 

• classifier.py

def classify_by_tag(file_path, destination_folder_names):
    filename = file_path.name
    tag_name = extract_front_tag(filename)

    if tag_name is None:
        return None

    if tag_name not in destination_folder_names:
        return None

    return {
        "filename": filename,
        "targetFolder": tag_name,
        "reason": "파일명 앞 태그와 같은 이름의 폴더를 찾았습니다.",
        "source": "FILENAME_TAG",
    }

파일명 앞의 [태그]를 보고 이동할 폴더를 추천하는 함수이다.

def classify_by_rules(file_path, rules, destination_folder_names):
    filename = file_path.name
    normalized_filename = normalize_text(filename)

    for folder_name, keywords in rules.items():
        if folder_name not in destination_folder_names:
            continue

        for keyword in keywords:
            normalized_keyword = normalize_text(keyword)

            if normalized_keyword in normalized_filename:
                return {
                    "filename": filename,
                    "targetFolder": folder_name,
                    "reason": f"파일명에 rules.txt 키워드 '{keyword}'가 포함되어 있습니다.",
                    "source": "RULES_TXT",
                }

    return None

rules.txt 규칙을 보고 이동할 폴더를 추천하는 함수이다. 조건은 파일명 안에 rules.txt의 키워드가 포함되어 있어야 하고 규칙의 폴더 이름이 실제 이동 목적지 폴더에 존재해야 한다.

 

 

• planner.py

def create_plan_for_file(file_path, destination_folder_names, rules):
    result = classify_by_tag(file_path, destination_folder_names)

    if result is not None:
        result["action"] = "MOVE"
        result["confidence"] = 1.0
        return result

    result = classify_by_rules(file_path, rules, destination_folder_names)

    if result is not None:
        result["action"] = "MOVE"
        result["confidence"] = 0.8
        return result

    if ARCHIVE_FOLDER_NAME in destination_folder_names:
        return {
            "filename": file_path.name,
            "targetFolder": ARCHIVE_FOLDER_NAME,
            "reason": "태그와 rules.txt로 분류되지 않아 archive 폴더로 추천합니다.",
            "source": "FALLBACK_ARCHIVE",
            "action": "MOVE",
            "confidence": 0.3,
        }

    return {
        "filename": file_path.name,
        "targetFolder": None,
        "reason": "분류되지 않았고 archive 폴더가 없어 Desktop에 남깁니다.",
        "source": "UNCLASSIFIED",
        "action": "KEEP",
        "confidence": 0.0,
    }

모든 파일에 대해 최종 정리 계획을 만든다. 태그 → rules.txt → archive → Desktop 유지 순서로 만든다.

 

 

• path_planner.py

def remove_front_tag(filename):
    cleaned_name = re.sub(r"^\[[^\]]+\]\s*", "", filename)

    if cleaned_name.strip() == "":
        return filename

    return cleaned_name.strip()

파일명 맨 앞의 [태그]를 제거한다. 예시로 [school]정보처리기사 정리본.pdf가  정보처리기사 정리본.pdf로 변경된다.

def make_unique_target_path(target_path, reserved_target_paths):
    candidate_path = target_path

    parent = target_path.parent
    stem = target_path.stem
    suffix = target_path.suffix

    number = 1

    while candidate_path.exists() or candidate_path in reserved_target_paths:
        candidate_filename = f"{stem}({number}){suffix}"
        candidate_path = parent / candidate_filename
        number += 1

    return candidate_path

이동하려는 폴더 안에 같은 이름의 파일이 있으면 파일명 뒤에 숫자를 붙여서 중복을 피한다. 예시로 school/정리본.pdf 가 이미 있으면 school/정리본(1).pdf 로 변경한다.

 

 

• mover.py

def is_inside_base_path(path, base_path):
    try:
        path.resolve().relative_to(base_path.resolve())
        return True
    except ValueError:
        return False

주어진 path가 base_path 내부에 있는지 확인하는 함수이다. test_desktop 밖의 파일을 실수로 이동하지 않기 위해 사용한다.

if dry_run:
    results.append(
        create_result(
            item,
            "DRY_RUN",
            "실제 이동 없이 이동 예정만 확인했습니다.",
        )
    )
    continue

기본은 dry-run이고, 실제 이동은 --apply와 확인 문구를 통과해야 실행되도록 했다. 나중에 사용자가 선택한 파일만 이동하도록 할 것이다.

 

 

• log_store.py

def save_move_session(results):
    successful_moves = []

    for result in results:
        if result.get("status") != "SUCCESS":
            continue

        successful_moves.append(
            {
                "filename": result.get("filename"),
                "originalPath": result.get("originalPath"),
                "movedPath": result.get("targetPath"),
                "source": result.get("source"),
                "status": result.get("status"),
            }
        )

    if not successful_moves:
        return None

    log_data = load_log()

    session = {
        "sessionId": create_session_id(),
        "executedAt": datetime.now().isoformat(timespec="seconds"),
        "basePath": str(get_desktop_path()),
        "moves": successful_moves,
    }

    log_data["undoStack"].append(session)
    log_data["redoStack"] = []

    save_log(log_data)

    return session

실제 이동에 성공한 파일만 로그에 저장해서 undo/redo의 기준으로 사용한다.

 

 

• undo.py

def create_undo_plan(session):
    moves = session.get("moves", [])

    undo_plan = []

    for move in reversed(moves):
        undo_plan.append(
            {
                "filename": move.get("filename"),
                "fromPath": move.get("movedPath"),
                "toPath": move.get("originalPath"),
                "source": move.get("source"),
            }
        )

    return undo_plan

최근 이동 세션을 바탕으로 되돌리기 계획을 만든다. movedPath -> originalPath 방향으로 되돌린다.

def update_log_after_undo(log_data):
    session = log_data["undoStack"].pop()
    log_data["redoStack"].append(session)

    save_log(log_data)

    return session

되돌리기 성공 후 로그를 업데이트한다. undoStack의 가장 최근 세션을 꺼내 redoStack으로 옮긴다.

 

 

• redo.py

def create_redo_plan(session):
    moves = session.get("moves", [])

    redo_plan = []

    for move in moves:
        redo_plan.append(
            {
                "filename": move.get("filename"),
                "fromPath": move.get("originalPath"),
                "toPath": move.get("movedPath"),
                "source": move.get("source"),
            }
        )

    return redo_plan

redoStack의 세션을 바탕으로 앞으로가기 계획을 만든다. originalPath -> movedPath 방향으로 다시 이동한다.

def update_log_after_redo(log_data):
    session = log_data["redoStack"].pop()
    log_data["undoStack"].append(session)

    save_log(log_data)

    return session

앞으로가기 성공 후 로그를 업데이트하는 함수이다. redoStack의 가장 최근 세션을 꺼내 undoStack으로 옮긴다.

 

 

• selected_mover.py

def parse_selection(selection_text, max_number):
    selection_text = selection_text.strip().lower()

    if selection_text == "all":
        return set(range(1, max_number + 1))

    if selection_text == "none" or selection_text == "":
        return set()

    selected_numbers = set()

    parts = selection_text.split(",")

    for part in parts:
        part = part.strip()

        if "-" in part:
            start_text, end_text = part.split("-", 1)

            start = int(start_text.strip())
            end = int(end_text.strip())

            for number in range(start, end + 1):
                selected_numbers.add(number)

        else:
            number = int(part)
            selected_numbers.add(number)

    return selected_numbers

전체 이동이 아니라 사용자가 선택한 파일만 이동할 수 있게 한다.

 

 

• deskpilot.py

if args.command == "preview":
    run_preview()

elif args.command == "move":
    run_move(apply=args.apply)

elif args.command == "undo":
    run_undo(apply=args.apply)

elif args.command == "redo":
    run_redo(apply=args.apply)

elif args.command == "log":
    run_log()

elif args.command == "doctor":
    checks = run_checks()
    print_checks(checks)

모든 기능을 하나의 명령어로 실행할 수 있게 묶었다. preview, move, undo, redo, log, doctor 기능을 deskpilot.py 하나로 실행할 수 있다.

 

 

• doctor.py

def check_move_log_json():
    log_path = get_log_path()

    if not log_path.exists():
        return create_check_result(
            "WARN",
            "move-log.json 파일이 아직 없습니다. 실제 이동을 하면 생성됩니다.",
        )

    try:
        with open(log_path, "r", encoding="utf-8") as file:
            log_data = json.load(file)

    except json.JSONDecodeError:
        return create_check_result(
            "ERROR",
            "move-log.json 파일의 JSON 형식이 깨져 있습니다.",
        )

    if "undoStack" not in log_data:
        return create_check_result(
            "ERROR",
            "move-log.json에 undoStack이 없습니다.",
        )

    if "redoStack" not in log_data:
        return create_check_result(
            "ERROR",
            "move-log.json에 redoStack이 없습니다.",
        )

    return create_check_result(
        "OK",
        "move-log.json 파일이 정상입니다.",
    )

프로젝트 상태를 검사한다. 실행 전 폴더, rules.txt, archive, move-log.json 상태를 점검해서 문제를 미리 찾는다.

 

 

 

---

 

 

 

4. 실행화면

• doctor 실행

 

 

• 선택해서 파일 옮기기

 

 

• 되돌리기

 

 

• 앞으로 되돌리기