pyjallib 0.1.8__py3-none-any.whl → 0.1.9__py3-none-any.whl

pyjallib/perforce.py

@@ -1,735 +1,528 @@
+"""
+P4Python을 사용하는 Perforce 모듈.
+
+이 모듈은 P4Python을 사용하여 Perforce 서버와 상호작용하는 기능을 제공합니다.
+주요 기능:
+- 워크스페이스 연결
+- 체인지리스트 관리 (생성, 조회, 편집, 제출, 되돌리기)
+- 파일 작업 (체크아웃, 추가, 삭제)
+- 파일 동기화 및 업데이트 확인
+"""
+
+import logging
+from P4 import P4, P4Exception
 import os
-import subprocess
-import socket
+from pathlib import Path
 
-class Perforce:
-    """
-    Perforce 버전 관리 시스템과의 상호작용을 위한 클래스입니다.
-    
-    이 클래스는 Perforce 명령을 실행하고, 워크스페이스를 관리하며
-    Perforce 서버와의 연결을 제어하는 기능을 제공합니다.
-    """
-    
-    def __init__(self, server, user, workspace=None):
-        """
-        Perforce 클래스의 인스턴스를 초기화합니다.
-        
-        Parameters:
-            server (str, optional): Perforce 서버 주소. 기본값은 환경 변수 P4PORT 또는 "PC-BUILD:1666"
-            user (str, optional): Perforce 사용자 이름. 기본값은 환경 변수 P4USER 또는 "Dev"
-            workspace (str, optional): Perforce 워크스페이스 이름. 기본값은 환경 변수 P4CLIENT
-        """
-        self.server = server
-        self.user = user
-        self.workspace = workspace if workspace else os.environ.get('P4CLIENT')
-        self.workspaceRoot = None
-        self.localHostName = socket.gethostname()
-        
-        os.environ['P4USER'] = self.user
-        os.environ['P4PORT'] = self.server
-        if self.workspace:
-            os.environ['P4CLIENT'] = self.workspace
-        else:
-            # P4CLIENT가 None이면 환경 변수에서 제거 시도 (선택적)
-            if 'P4CLIENT' in os.environ:
-                del os.environ['P4CLIENT']
-        
-        # 초기화 시 연결 확인
-        self._initialize_connection()
-        
-    def _initialize_connection(self):
-        """
-        Perforce 서버와의 연결을 초기화합니다.
-        
-        서버 연결을 확인하고 워크스페이스 루트 경로를 설정합니다.
-        
-        Returns:
-            str: Perforce 서버 정보 문자열
-        
-        Raises:
-            Exception: Perforce 연결 초기화 실패 시 예외 처리
-        """
-        result = None
-        try:
-            # 서버 연결 확인 (info 명령은 가볍고 빠르게 실행됨)
-            result = subprocess.run(['p4', 'info'], 
-                                   capture_output=True, 
-                                   text=True, 
-                                   encoding="utf-8")
-            
-            workSpaceRootPathResult = subprocess.run(
-                ['p4', '-F', '%clientRoot%', '-ztag', 'info'],
-                capture_output=True, 
-                text=True, 
-                encoding="utf-8"
-            ).stdout.strip()
-            self.workspaceRoot = os.path.normpath(workSpaceRootPathResult)
-            
-            if result.returncode != 0:
-                print(f"Perforce 초기화 중 경고: {result.stderr}")
-        except Exception as e:
-            print(f"Perforce 초기화 실패: {e}")
-        
-        return result.stdout.strip()
-        
-    def _run_command(self, inCommands):
-        """
-        Perforce 명령을 실행하고 결과를 반환합니다.
-        
-        Parameters:
-            inCommands (list): 실행할 Perforce 명령어와 인수들의 리스트
-        
-        Returns:
-            str: 명령 실행 결과 문자열
-        """
-        self._initialize_connection()
-        
-        commands = ['p4'] + inCommands
-        result = subprocess.run(commands, capture_output=True, text=True, encoding="utf-8")
-                
-        return result.stdout.strip()
+# 로깅 설정
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+# 사용자 문서 폴더 내 로그 파일 저장
+log_path = os.path.join(Path.home() / "Documents", 'Perforce.log')
+file_handler = logging.FileHandler(log_path, encoding='utf-8')
+file_handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+logger.addHandler(file_handler)
 
-    def get_local_hostname(self):
-        """
-        현재 로컬 머신의 호스트 이름을 반환합니다.
-        
-        Returns:
-            str: 로컬 머신의 호스트 이름
-        """
-        # 현재 로컬 머신의 호스트 이름을 반환합니다.
-        return self.localHostName
 
-    def get_all_clients(self):
-        """
-        모든 Perforce 클라이언트 워크스페이스의 이름 목록을 반환합니다.
-        
-        Returns:
-            list: 클라이언트 워크스페이스 이름 리스트
-        """
-        # 모든 클라이언트 워크스페이스의 이름을 반환합니다.
-        result = self._run_command(['clients'])
-        clients = []
-        
-        if result is None:
-            return clients
-            
-        for line in result.splitlines():
-            if line.startswith('Client'):
-                parts = line.split()
-                if len(parts) >= 2:
-                    clients.append(parts[1])
-        return clients
-
-    def get_local_workspaces(self):
-        """
-        현재 로컬 머신에 있는 워크스페이스 목록을 반환합니다.
-        
-        현재 호스트 이름으로 시작하는 모든 클라이언트를 찾습니다.
-        
-        Returns:
-            list: 로컬 머신의 워크스페이스 이름 리스트
-        """
-        all_clients = self.get_all_clients()
-        local_clients = []
+class Perforce:
+    """P4Python을 사용하여 Perforce 작업을 수행하는 클래스."""
 
-        for client in all_clients:
-            if client.startswith(self.localHostName):
-                local_clients.append(client)
+    def __init__(self):
+        """Perforce 인스턴스를 초기화합니다."""
+        self.p4 = P4()
+        self.connected = False
+        self.workspaceRoot = r""
+        logger.info("Perforce 인스턴스 생성됨")
+
+    def _is_connected(self) -> bool:
+        """Perforce 서버 연결 상태를 확인합니다.
 
-        return local_clients
-    
-    def set_workspace(self, inWorkspace):
-        """
-        주어진 워크스페이스로 현재 작업 환경을 전환합니다.
-        
-        Parameters:
-            inWorkspace (str): 전환할 워크스페이스 이름
-            
         Returns:
-            str: 워크스페이스 정보 문자열
-            
-        Raises:
-            ValueError: 지정된 워크스페이스가 로컬 워크스페이스 목록에 없을 경우
+            bool: 연결되어 있으면 True, 아니면 False
         """
-        # 주어진 워크스페이스로 전환합니다.
-        localWorkSpaces = self.get_local_workspaces()
-        if inWorkspace not in localWorkSpaces:
-            print(f"워크스페이스 '{inWorkspace}'는 로컬 워크스페이스 목록에 없습니다.")
+        if not self.connected:
+            logger.warning("Perforce 서버에 연결되지 않았습니다.")
             return False
-        
-        self.workspace = inWorkspace
-        os.environ['P4CLIENT'] = self.workspace
-        
         return True
-    
-    def sync(self, inWorkSpace=None, inPaths=None):
+
+    def _handle_p4_exception(self, e: P4Exception, context_msg: str = "") -> None:
+        """P4Exception을 처리하고 로깅합니다.
+
+        Args:
+            e (P4Exception): 발생한 예외
+            context_msg (str, optional): 예외가 발생한 컨텍스트 설명
         """
-        Perforce 워크스페이스를 최신 버전으로 동기화합니다.
-        
-        Parameters:
-            inWorkSpace (str, optional): 동기화할 워크스페이스 이름
-            inPaths (str or list, optional): 동기화할 특정 경로 또는 경로 목록
-            
+        logger.error(f"{context_msg} 중 P4Exception 발생: {e}")
+        for err in self.p4.errors:
+            logger.error(f"  P4 Error: {err}")
+        for warn in self.p4.warnings:
+            logger.warning(f"  P4 Warning: {warn}")
+
+    def connect(self, workspace_name: str) -> bool:
+        """지정된 워크스페이스에 연결합니다.
+
+        Args:
+            workspace_name (str): 연결할 워크스페이스 이름
+
         Returns:
-            bool: 동기화 성공 여부
+            bool: 연결 성공 시 True, 실패 시 False
         """
-        # 주어진 워크스페이스를 동기화합니다.
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-        
-        # 동기화 명령 실행
-        sync_command = ['sync']
-        
-        if inPaths:
-            # 문자열로 단일 경로가 주어진 경우 리스트로 변환
-            if isinstance(inPaths, str):
-                inPaths = [inPaths]
-                
-            valid_paths = []
-            for path in inPaths:
-                if os.path.exists(path):
-                    valid_paths.append(path)
-                else:
-                    print(f"경고: 지정된 경로 '{path}'가 로컬에 존재하지 않습니다.")
+        logger.info(f"'{workspace_name}' 워크스페이스에 연결 시도 중...")
+        try:
+            self.p4.client = workspace_name
+            self.p4.connect()
+            self.connected = True
             
-            if not valid_paths:
-                print("유효한 경로가 없어 동기화를 진행할 수 없습니다.")
-                return False
+            # 워크스페이스 루트 경로 가져오기
+            try:
+                client_info = self.p4.run_client("-o", workspace_name)[0]
+                root_path = client_info.get("Root", "")
                 
-            # 유효한 경로들을 모두 동기화 명령에 추가
-            sync_command.extend(valid_paths)
-    
-        self._run_command(sync_command)
-        return True
-        
-    def get_changelists(self, inWorkSpace=None):
-        """
-        특정 워크스페이스의 pending 상태 체인지 리스트를 가져옵니다.
-        
-        Parameters:
-            inWorkSpace (str, optional): 체인지 리스트를 가져올 워크스페이스 이름
-            
+                # Windows 경로 형식으로 변환 (슬래시를 백슬래시로)
+                root_path = os.path.normpath(root_path)
+                
+                self.workspaceRoot = root_path
+                logger.info(f"워크스페이스 루트 절대 경로: {self.workspaceRoot}")
+            except (IndexError, KeyError) as e:
+                logger.error(f"워크스페이스 루트 경로 가져오기 실패: {e}")
+                self.workspaceRoot = ""
+                
+            logger.info(f"'{workspace_name}' 워크스페이스에 성공적으로 연결됨 (User: {self.p4.user}, Port: {self.p4.port})")
+            return True
+        except P4Exception as e:
+            self.connected = False
+            self._handle_p4_exception(e, f"'{workspace_name}' 워크스페이스 연결")
+            return False
+
+    def get_pending_change_list(self) -> list:
+        """워크스페이스의 Pending된 체인지 리스트를 가져옵니다.
+
         Returns:
-            list: 체인지 리스트 정보 딕셔너리의 리스트
+            list: 체인지 리스트 정보 딕셔너리들의 리스트
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return []
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return []
-            
-        # 체인지 리스트 명령 실행
-        changes_command = ['changes']
-        
-        # 항상 pending 상태만 가져오도록 설정
-        changes_command.extend(['-s', 'pending'])
+        if not self._is_connected():
+            return []
+        logger.debug("Pending 체인지 리스트 조회 중...")
+        try:
+            pending_changes = self.p4.run_changes("-s", "pending", "-u", self.p4.user, "-c", self.p4.client)
+            change_numbers = [int(cl['change']) for cl in pending_changes]
             
-        if self.workspace:
-            changes_command.extend(['-c', self.workspace])
-            
-        result = self._run_command(changes_command)
-        changes = []
-        
-        for line in result.splitlines():
-            if line.startswith('Change'):
-                parts = line.split()
-                if len(parts) >= 5:
-                    change_id = parts[1]
-                    
-                    # 설명 부분 추출
-                    desc_start = line.find("'")
-                    desc_end = line.rfind("'")
-                    description = line[desc_start+1:desc_end] if desc_start != -1 and desc_end != -1 else ""
-                    
-                    changes.append({
-                        'id': change_id,
-                        'description': description
-                    })
-                    
-        return changes
-        
-    def create_new_changelist(self, inDescription="Created by pyjallib", inWorkSpace=None):
-        """
-        새로운 체인지 리스트를 생성합니다.
-        
-        Parameters:
-            inDescription (str): 체인지 리스트 설명
-            inWorkSpace (str, optional): 체인지 리스트를 생성할 워크스페이스 이름
+            # 각 체인지 리스트 번호에 대한 상세 정보 가져오기
+            change_list_info = []
+            for change_number in change_numbers:
+                cl_info = self.get_change_list_by_number(change_number)
+                if cl_info:
+                    change_list_info.append(cl_info)
             
+            logger.info(f"Pending 체인지 리스트 {len(change_list_info)}개 조회 완료")
+            return change_list_info
+        except P4Exception as e:
+            self._handle_p4_exception(e, "Pending 체인지 리스트 조회")
+            return []
+
+    def create_change_list(self, description: str) -> dict:
+        """새로운 체인지 리스트를 생성합니다.
+
+        Args:
+            description (str): 체인지 리스트 설명
+
         Returns:
-            dict: 생성된 체인지 리스트 정보 {'id': str, 'description': str} 또는 실패 시 None
+            dict: 생성된 체인지 리스트 정보. 실패 시 빈 딕셔너리
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return None
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return None
-            
-        # 체인지 리스트 생성 명령 실행
-        change_command = ['change', '-o']
-        result = self._run_command(change_command)
-        
-        # 체인지 스펙 수정
-        modified_spec = []
-        for line in result.splitlines():
-            if line.startswith('Description:'):
-                modified_spec.append(line)
-                # Add the new description, handling potential multi-line descriptions correctly
-                for desc_line in inDescription.splitlines():
-                    modified_spec.append(f"\t{desc_line}")
-                # Skip the default empty tab line if present
-                # This assumes the default spec has an empty line after Description:
-                # If not, this logic might need adjustment based on actual 'p4 change -o' output
-                # We'll rely on the loop structure to handle subsequent lines correctly.
-                continue # Move to the next line in the original spec
-            # Only append lines that are not part of the old description placeholder
-            # This logic assumes the default description is just a placeholder like '<enter description here>'
-            # or similar, often on a single line after 'Description:'.
-            # A more robust approach might be needed if the default spec is complex.
-            if not (line.startswith('\t') and 'Description:' in modified_spec[-1]):
-                 modified_spec.append(line)
-
-        # 수정된 체인지 스펙으로 체인지 리스트 생성
-        create_result = subprocess.run(['p4', 'change', '-i'],
-                                     input='\n'.join(modified_spec),
-                                     capture_output=True,
-                                     text=True,
-                                     encoding="utf-8")
-
-        # 결과에서 체인지 리스트 ID 추출
-        if create_result.returncode == 0 and create_result.stdout:
-            output = create_result.stdout.strip()
-            # 예: "Change 12345 created."
-            if 'Change' in output and 'created' in output:
-                parts = output.split()
-                if len(parts) >= 2:
-                    change_id = parts[1]
-                    return {'id': change_id, 'description': inDescription} # Return dictionary
-
-        print(f"Failed to create changelist. Error: {create_result.stderr}") # Log error if creation failed
-        return None
-
-    def checkout_files(self, inFiles, inChangelist=None, inWorkSpace=None):
-        """
-        지정한 파일들을 체크아웃하고 특정 체인지 리스트에 추가합니다.
-        
-        Parameters:
-            inFiles (list): 체크아웃할 파일 경로 리스트
-            inChangelist (str, optional): 파일을 추가할 체인지 리스트 ID
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
-            
+        if not self._is_connected():
+            return {}
+        logger.info(f"새 체인지 리스트 생성 시도: '{description}'")
+        try:
+            change_spec = self.p4.fetch_change()
+            change_spec["Description"] = description
+            result = self.p4.save_change(change_spec)
+            created_change_number = int(result[0].split()[1])
+            logger.info(f"체인지 리스트 {created_change_number} 생성 완료: '{description}'")
+            return self.get_change_list_by_number(created_change_number)
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 생성 ('{description}')")
+            return {}
+        except (IndexError, ValueError) as e:
+            logger.error(f"체인지 리스트 번호 파싱 오류: {e}")
+            return {}
+
+    def get_change_list_by_number(self, change_list_number: int) -> dict:
+        """체인지 리스트 번호로 체인지 리스트를 가져옵니다.
+
+        Args:
+            change_list_number (int): 체인지 리스트 번호
+
         Returns:
-            bool: 성공 여부
+            dict: 체인지 리스트 정보. 실패 시 빈 딕셔너리
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-            
-        if not inFiles:
-            return False
-            
-        # 체크아웃 명령 실행
-        edit_command = ['edit']
-        
-        target_changelist = inChangelist
-        if not target_changelist:
-            new_changelist_info = self.create_new_changelist(inDescription=f"Auto-checkout for {len(inFiles)} files")
-            if not new_changelist_info:
-                print("Failed to create a new changelist for checkout.")
-                return False
-            target_changelist = new_changelist_info['id']
+        if not self._is_connected():
+            return {}
+        logger.debug(f"체인지 리스트 {change_list_number} 정보 조회 중...")
+        try:
+            cl_info = self.p4.fetch_change(change_list_number)
+            if cl_info:
+                logger.info(f"체인지 리스트 {change_list_number} 정보 조회 완료.")
+                return cl_info
+            else:
+                logger.warning(f"체인지 리스트 {change_list_number}를 찾을 수 없습니다.")
+                return {}
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number} 정보 조회")
+            return {}
+
+    def get_change_list_by_description(self, description: str) -> dict:
+        """체인지 리스트 설명으로 체인지 리스트를 가져옵니다.
+
+        Args:
+            description (str): 체인지 리스트 설명
 
-        edit_command.extend(['-c', target_changelist])
-        edit_command.extend(inFiles)
-        
-        result = self._run_command(edit_command)
-        
-        if len(self.get_changelist_files(target_changelist)) == 0:
-            self.delete_changelist(target_changelist)
-        
-        return True
-        
-    def add_files(self, inFiles, inChangelist=None, inWorkSpace=None):
-        """
-        지정한 파일들을 Perforce에 추가합니다.
-        
-        Parameters:
-            inFiles (list): 추가할 파일 경로 리스트
-            inChangelist (str, optional): 파일을 추가할 체인지 리스트 ID
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
-            
         Returns:
-            bool: 성공 여부
+            dict: 체인지 리스트 정보 (일치하는 첫 번째 체인지 리스트)
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-            
-        if not inFiles:
-            return False
-            
-        # 파일 추가 명령 실행
-        add_command = ['add']
-        
-        target_changelist = inChangelist
-        if not target_changelist:
-            new_changelist_info = self.create_new_changelist(inDescription=f"Auto-add for {len(inFiles)} files")
-            if not new_changelist_info:
-                print("Failed to create a new changelist for add.")
-                return False
-            target_changelist = new_changelist_info['id']
+        if not self._is_connected():
+            return {}
+        logger.debug(f"설명으로 체인지 리스트 조회 중: '{description}'")
+        try:
+            pending_changes = self.p4.run_changes("-l", "-s", "pending", "-u", self.p4.user, "-c", self.p4.client)
+            for cl in pending_changes:
+                cl_desc = cl.get('Description', b'').decode('utf-8', 'replace').strip()
+                if cl_desc == description.strip():
+                    logger.info(f"설명 '{description}'에 해당하는 체인지 리스트 {cl['change']} 조회 완료.")
+                    return self.get_change_list_by_number(int(cl['change']))
+            logger.info(f"설명 '{description}'에 해당하는 Pending 체인지 리스트를 찾을 수 없습니다.")
+            return {}
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"설명으로 체인지 리스트 조회 ('{description}')")
+            return {}
+
+    def edit_change_list(self, change_list_number: int, description: str = None, add_file_paths: list = None, remove_file_paths: list = None) -> dict:
+        """체인지 리스트를 편집합니다.
+
+        Args:
+            change_list_number (int): 체인지 리스트 번호
+            description (str, optional): 변경할 설명
+            add_file_paths (list, optional): 추가할 파일 경로 리스트
+            remove_file_paths (list, optional): 제거할 파일 경로 리스트
 
-        add_command.extend(['-c', target_changelist])
-        add_command.extend(inFiles)
-        
-        result = self._run_command(add_command)
-        
-        if len(self.get_changelist_files(target_changelist)) == 0:
-            self.delete_changelist(target_changelist)
-        
-        return True
-        
-    def delete_files(self, inFiles, inChangelist=None, inWorkSpace=None):
+        Returns:
+            dict: 업데이트된 체인지 리스트 정보
         """
-        지정한 파일들을 Perforce에서 삭제합니다.
-
-        Parameters:
-            inFiles (list): 삭제할 파일 경로 리스트
-            inChangelist (str, optional): 파일 삭제를 추가할 체인지 리스트 ID
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
+        if not self._is_connected():
+            return {}
+        logger.info(f"체인지 리스트 {change_list_number} 편집 시도...")
+        try:
+            if description is not None:
+                change_spec = self.p4.fetch_change(change_list_number)
+                current_description = change_spec.get('Description', '').strip()
+                if current_description != description.strip():
+                    change_spec['Description'] = description
+                    self.p4.save_change(change_spec)
+                    logger.info(f"체인지 리스트 {change_list_number} 설명 변경 완료: '{description}'")
+
+            if add_file_paths:
+                for file_path in add_file_paths:
+                    try:
+                        self.p4.run_reopen("-c", change_list_number, file_path)
+                        logger.info(f"파일 '{file_path}'를 체인지 리스트 {change_list_number}로 이동 완료.")
+                    except P4Exception as e_reopen:
+                        self._handle_p4_exception(e_reopen, f"파일 '{file_path}'을 CL {change_list_number}로 이동")
+
+            if remove_file_paths:
+                for file_path in remove_file_paths:
+                    try:
+                        self.p4.run_revert("-c", change_list_number, file_path)
+                        logger.info(f"파일 '{file_path}'를 체인지 리스트 {change_list_number}에서 제거(revert) 완료.")
+                    except P4Exception as e_revert:
+                        self._handle_p4_exception(e_revert, f"파일 '{file_path}'을 CL {change_list_number}에서 제거(revert)")
+
+            return self.get_change_list_by_number(change_list_number)
+
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number} 편집")
+            return self.get_change_list_by_number(change_list_number)
+
+    def _file_op(self, command: str, file_path: str, change_list_number: int, op_name: str) -> bool:
+        """파일 작업을 수행하는 내부 헬퍼 함수입니다.
+
+        Args:
+            command (str): 실행할 명령어 (edit/add/delete)
+            file_path (str): 대상 파일 경로
+            change_list_number (int): 체인지 리스트 번호
+            op_name (str): 작업 이름 (로깅용)
 
         Returns:
-            bool: 성공 여부
+            bool: 작업 성공 시 True, 실패 시 False
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
+        if not self._is_connected():
+            return False
+        logger.info(f"파일 '{file_path}'에 대한 '{op_name}' 작업 시도 (CL: {change_list_number})...")
+        try:
+            if command == "edit":
+                self.p4.run_edit("-c", change_list_number, file_path)
+            elif command == "add":
+                self.p4.run_add("-c", change_list_number, file_path)
+            elif command == "delete":
+                self.p4.run_delete("-c", change_list_number, file_path)
+            else:
+                logger.error(f"지원되지 않는 파일 작업: {command}")
                 return False
-
-        if not inFiles:
+            logger.info(f"파일 '{file_path}'에 대한 '{op_name}' 작업 성공 (CL: {change_list_number}).")
+            return True
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"파일 '{file_path}' {op_name} (CL: {change_list_number})")
             return False
 
-        # 파일 삭제 명령 실행
-        delete_command = ['delete']
-
-        target_changelist = inChangelist
-        if not target_changelist:
-            # If no changelist is specified, create a new one
-            new_changelist_info = self.create_new_changelist(inDescription=f"Auto-delete for {len(inFiles)} files")
-            if not new_changelist_info:
-                print("Failed to create a new changelist for delete.")
-                return False
-            target_changelist = new_changelist_info['id']
+    def checkout_file(self, file_path: str, change_list_number: int) -> bool:
+        """파일을 체크아웃합니다.
 
-        delete_command.extend(['-c', target_changelist])
-        delete_command.extend(inFiles)
+        Args:
+            file_path (str): 체크아웃할 파일 경로
+            change_list_number (int): 체인지 리스트 번호
 
-        result = self._run_command(delete_command)
-        
-        if len(self.get_changelist_files(target_changelist)) == 0:
-            self.delete_changelist(target_changelist)
-            
-        return True
-
-    def revert_changelist(self, inChangelist, inWorkSpace=None):
+        Returns:
+            bool: 체크아웃 성공 시 True, 실패 시 False
         """
-        특정 체인지 리스트의 모든 변경 사항을 되돌립니다 (revert).
+        return self._file_op("edit", file_path, change_list_number, "체크아웃")
 
-        Parameters:
-            inChangelist (str): 되돌릴 체인지 리스트 ID
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
+    def add_file(self, file_path: str, change_list_number: int) -> bool:
+        """파일을 추가합니다.
+
+        Args:
+            file_path (str): 추가할 파일 경로
+            change_list_number (int): 체인지 리스트 번호
 
         Returns:
-            bool: 성공 여부
+            bool: 추가 성공 시 True, 실패 시 False
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-
-        if not inChangelist:
-            print("Error: Changelist ID must be provided for revert operation.")
-            return False
+        return self._file_op("add", file_path, change_list_number, "추가")
 
-        # Revert 명령 실행
-        revert_command = ['revert', '-c', inChangelist, '//...'] # Revert all files in the changelist
+    def delete_file(self, file_path: str, change_list_number: int) -> bool:
+        """파일을 삭제합니다.
 
-        result = self._run_command(revert_command)
-        # p4 revert might not return an error code even if nothing was reverted.
-        # We'll assume success if the command ran. More robust checking might involve parsing 'result'.
-        print(f"Revert result for CL {inChangelist}:\n{result}")
-        self._run_command(['change', '-d', inChangelist])
-        return True
+        Args:
+            file_path (str): 삭제할 파일 경로
+            change_list_number (int): 체인지 리스트 번호
 
-    def submit_changelist(self, inChangelist, inDescription=None, inWorkSpace=None):
+        Returns:
+            bool: 삭제 성공 시 True, 실패 시 False
         """
-        특정 체인지 리스트를 서버에 제출합니다.
+        return self._file_op("delete", file_path, change_list_number, "삭제")
+
+    def submit_change_list(self, change_list_number: int) -> bool:
+        """체인지 리스트를 제출합니다.
 
-        Parameters:
-            inChangelist (str): 제출할 체인지 리스트 ID
-            inDescription (str, optional): 제출 설명 (없으면 체인지 리스트의 기존 설명 사용)
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
+        Args:
+            change_list_number (int): 제출할 체인지 리스트 번호
 
         Returns:
-            bool: 성공 여부
+            bool: 제출 성공 시 True, 실패 시 False
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-
-        if not inChangelist:
+        if not self._is_connected():
+            return False
+        logger.info(f"체인지 리스트 {change_list_number} 제출 시도...")
+        try:
+            self.p4.run_submit("-c", change_list_number)
+            logger.info(f"체인지 리스트 {change_list_number} 제출 성공.")
+            return True
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number} 제출")
+            if any("nothing to submit" in err.lower() for err in self.p4.errors):
+                logger.warning(f"체인지 리스트 {change_list_number}에 제출할 파일이 없습니다.")
             return False
 
-        if inDescription:
-            # 체인지 리스트 스펙 가져오기
-            change_spec = self._run_command(['change', '-o', inChangelist])
-
-            # 설명 수정
-            modified_spec = []
-            description_lines_skipped = False
-            for line in change_spec.splitlines():
-                if line.startswith('Description:'):
-                    modified_spec.append(line)
-                    # Add the new description, handling potential multi-line descriptions correctly
-                    for desc_line in inDescription.splitlines():
-                        modified_spec.append(f"\t{desc_line}")
-                    description_lines_skipped = True # Start skipping old description lines
-                    continue
-
-                # Skip old description lines (indented lines after Description:)
-                if description_lines_skipped:
-                    if line.startswith('\t') or line.strip() == '':
-                        continue # Skip indented lines or empty lines within the old description
-                    else:
-                        description_lines_skipped = False # Reached the next field
-
-                if not description_lines_skipped:
-                    modified_spec.append(line)
-            
-            print(modified_spec)
+    def revert_change_list(self, change_list_number: int) -> bool:
+        """체인지 리스트를 되돌리고 삭제합니다.
 
-            # 수정된 스펙 적용
-            spec_update = subprocess.run(['p4', 'change', '-i'],
-                                       input='\n'.join(modified_spec),
-                                       capture_output=True,
-                                       text=True,
-                                       encoding="utf-8")
+        체인지 리스트 내 모든 파일을 되돌린 후 빈 체인지 리스트를 삭제합니다.
 
-            if spec_update.returncode != 0:
-                print(f"Error updating changelist spec for {inChangelist}: {spec_update.stderr}")
-                return False
+        Args:
+            change_list_number (int): 되돌릴 체인지 리스트 번호
 
-        self._run_command(['submit', '-c', inChangelist])
-        self.delete_empty_changelists()
-        return True
-
-    def get_changelist_files(self, inChangelist, inWorkSpace=None):
-        """
-        체인지 리스트에 포함된 파일 목록을 가져옵니다.
-        
-        Parameters:
-            inChangelist (str): 체인지 리스트 ID
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
-            
         Returns:
-            list: 파일 정보 딕셔너리의 리스트
+            bool: 되돌리기 및 삭제 성공 시 True, 실패 시 False
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return []
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return []
+        if not self._is_connected():
+            return False
+        logger.info(f"체인지 리스트 {change_list_number} 전체 되돌리기 및 삭제 시도...")
+        try:
+            # 체인지 리스트의 모든 파일 되돌리기
+            self.p4.run_revert("-c", change_list_number, "//...")
+            logger.info(f"체인지 리스트 {change_list_number} 전체 되돌리기 성공.")
             
-        opened_result = self._run_command(['opened', '-c', inChangelist])
-        files = []
-        
-        for line in opened_result.splitlines():
-            if '#' in line:
-                file_path = line.split('#')[0].strip()
-                action = line.split('for ')[1].split(' ')[0] if 'for ' in line else ''
-                
-                files.append(file_path)
+            # 빈 체인지 리스트 삭제
+            try:
+                self.p4.run_change("-d", change_list_number)
+                logger.info(f"체인지 리스트 {change_list_number} 삭제 완료.")
+            except P4Exception as e_delete:
+                self._handle_p4_exception(e_delete, f"체인지 리스트 {change_list_number} 삭제")
+                logger.warning(f"파일 되돌리기는 성공했으나 체인지 리스트 {change_list_number} 삭제에 실패했습니다.")
+                return False
                 
-        return files
+            return True
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number} 전체 되돌리기")
+            return False
     
-    def delete_changelist(self, inChangelist, inWorkSpace=None):
+    def delete_empty_change_list(self, change_list_number: int) -> bool:
+        """빈 체인지 리스트를 삭제합니다.
+
+        Args:
+            change_list_number (int): 삭제할 체인지 리스트 번호
+
+        Returns:
+            bool: 삭제 성공 시 True, 실패 시 False
         """
-        빈 체인지 리스트를 삭제합니다.
+        if not self._is_connected():
+            return False
         
-        Parameters:
-            inChangelist (str): 삭제할 체인지 리스트 ID
-            inWorkspace (str, optional): 작업할 워크스페이스 이름
+        logger.info(f"체인지 리스트 {change_list_number} 삭제 시도 중...")
+        try:
+            # 체인지 리스트 정보 가져오기
+            change_spec = self.p4.fetch_change(change_list_number)
             
-        Returns:
-            bool: 성공 여부
-        """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
+            # 파일이 있는지 확인
+            if change_spec and change_spec.get('Files') and len(change_spec['Files']) > 0:
+                logger.warning(f"체인지 리스트 {change_list_number}에 파일이 {len(change_spec['Files'])}개 있어 삭제할 수 없습니다.")
                 return False
             
-        if not inChangelist:
-            print("Error: Changelist ID must be provided for delete operation.")
+            # 빈 체인지 리스트 삭제
+            self.p4.run_change("-d", change_list_number)
+            logger.info(f"빈 체인지 리스트 {change_list_number} 삭제 완료.")
+            return True
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number} 삭제")
             return False
-        
-        # 체인지 리스트의 파일 목록을 확인합니다
-        files = self.get_changelist_files(inChangelist)
-        if files:
-            print(f"Error: Changelist {inChangelist} is not empty. It contains {len(files)} files.")
+
+    def revert_files(self, change_list_number: int, file_paths: list) -> bool:
+        """체인지 리스트 내의 특정 파일들을 되돌립니다.
+
+        Args:
+            change_list_number (int): 체인지 리스트 번호
+            file_paths (list): 되돌릴 파일 경로 리스트
+
+        Returns:
+            bool: 되돌리기 성공 시 True, 실패 시 False
+        """
+        if not self._is_connected():
             return False
+        if not file_paths:
+            logger.warning("되돌릴 파일 목록이 비어있습니다.")
+            return True
             
-        # 빈 체인지 리스트를 삭제합니다
-        delete_result = self._run_command(['change', '-d', inChangelist])
-        
-        if 'deleted' in delete_result:
+        logger.info(f"체인지 리스트 {change_list_number}에서 {len(file_paths)}개 파일 되돌리기 시도...")
+        try:
+            for file_path in file_paths:
+                self.p4.run_revert("-c", change_list_number, file_path)
+                logger.info(f"파일 '{file_path}'를 체인지 리스트 {change_list_number}에서 되돌리기 성공.")
             return True
-        else:
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"체인지 리스트 {change_list_number}에서 파일 되돌리기")
             return False
 
-    def delete_empty_changelists(self, inWorkSpace=None):
-        """
-        빈 체인지 리스트를 삭제합니다.
-        
-        Parameters:
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
-            
-        Returns:
-            bool: 성공 여부
-        """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-        
-        # 모든 체인지 리스트 가져오기
-        changes = self.get_changelists()
-        
-        for change in changes:
-            if len(self.get_changelist_files(change['id'])) == 0:
-                self.delete_changelist(change['id'])
-        
-        return True
+    def check_update_required(self, file_paths: list) -> bool:
+        """파일이나 폴더의 업데이트 필요 여부를 확인합니다.
+
+        Args:
+            file_paths (list): 확인할 파일 또는 폴더 경로 리스트. 
+                              폴더 경로는 자동으로 재귀적으로 처리됩니다.
 
-    def upload_files(self, inFiles, inDescription=None, inWorkSpace=None):
-        """
-        지정한 파일들을 Perforce에 Submit 합니다.
-        
-        만약 파일들이 Depot에 존재하지 않으면 Add, 존재하면 Chekcout을 수행합니다.
-        
-        Parameters:
-            inFiles (list): 업로드할 파일 경로 리스트
-            inWorkSpace (str, optional): 작업할 워크스페이스 이름
-        
         Returns:
-            bool: 성공 여부
+            bool: 업데이트가 필요한 파일이 있으면 True, 없으면 False
         """
-        if inWorkSpace == None:
-            if self.workspace == None:
-                print(f"워크스페이스가 없습니다.")
-                return False
-        else:
-            if not self.set_workspace(inWorkSpace):
-                print(f"워크스페이스 '{inWorkSpace}'는 로컬 워크스페이스 목록에 없습니다.")
-                return False
-        
-        if not inFiles:
-            print("업로드할 파일이 지정되지 않았습니다.")
+        if not self._is_connected():
             return False
-        
-        # 문자열로 단일 경로가 주어진 경우 리스트로 변환
-        if isinstance(inFiles, str):
-            inFiles = [inFiles]
-            
-        # 새 체인지리스트 생성
-        description = inDescription if inDescription else f"Auto-upload for {len(inFiles)} files"
-        new_changelist_info = self.create_new_changelist(inDescription=description)
-        if not new_changelist_info:
-            print("Failed to create a new changelist for file upload.")
+        if not file_paths:
+            logger.debug("업데이트 필요 여부 확인할 파일/폴더 목록이 비어있습니다.")
             return False
-            
-        target_changelist = new_changelist_info['id']
         
-        # 파일들이 이미 디포에 있는지 확인
-        files_to_add = []
-        files_to_edit = []
+        # 폴더 경로에 재귀적 와일드카드 패턴을 추가
+        processed_paths = []
+        for path in file_paths:
+            if os.path.isdir(path):
+                # 폴더 경로에 '...'(재귀) 패턴을 추가
+                processed_paths.append(os.path.join(path, '...'))
+                logger.debug(f"폴더 경로를 재귀 패턴으로 변환: {path} -> {os.path.join(path, '...')}")
+            else:
+                processed_paths.append(path)
         
-        for file_path in inFiles:
-            # 파일 상태 확인 (디포에 있는지 여부)
-            fstat_result = self._run_command(['fstat', file_path])
+        logger.debug(f"파일/폴더 업데이트 필요 여부 확인 중 (항목 {len(processed_paths)}개): {processed_paths}")
+        try:
+            sync_preview_results = self.p4.run_sync("-n", processed_paths)
+            needs_update = False
+            for result in sync_preview_results:
+                if isinstance(result, dict):
+                    if 'up-to-date' not in result.get('how', '') and \
+                       'no such file(s)' not in result.get('depotFile', ''):
+                        if result.get('how') and 'syncing' in result.get('how'):
+                            needs_update = True
+                            logger.info(f"파일 '{result.get('clientFile', result.get('depotFile'))}' 업데이트 필요: {result.get('how')}")
+                            break
+                        elif result.get('action') and result.get('action') not in ['checked', 'exists']:
+                            needs_update = True
+                            logger.info(f"파일 '{result.get('clientFile', result.get('depotFile'))}' 업데이트 필요 (action: {result.get('action')})")
+                            break
+                elif isinstance(result, str):
+                    if "up-to-date" not in result and "no such file(s)" not in result:
+                        needs_update = True
+                        logger.info(f"파일 업데이트 필요 (문자열 결과): {result}")
+                        break
             
-            if 'no such file' in fstat_result.lower() or not fstat_result:
-                # 디포에 없는 파일 - 추가 대상
-                files_to_add.append(file_path)
+            if needs_update:
+                logger.info(f"지정된 파일/폴더 중 업데이트가 필요한 파일이 있습니다.")
             else:
-                # 디포에 있는 파일 - 체크아웃 대상
-                files_to_edit.append(file_path)
-        
-        # 파일 추가 (있는 경우)
-        if files_to_add:
-            add_command = ['add', '-c', target_changelist]
-            add_command.extend(files_to_add)
-            self._run_command(add_command)
-        
-        # 파일 체크아웃 (있는 경우)
-        if files_to_edit:
-            edit_command = ['edit', '-c', target_changelist]
-            edit_command.extend(files_to_edit)
-            self._run_command(edit_command)
+                logger.info(f"지정된 모든 파일/폴더가 최신 상태입니다.")
+            return needs_update
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"파일/폴더 업데이트 필요 여부 확인 ({processed_paths})")
+            return False
+
+    def sync_files(self, file_paths: list) -> bool:
+        """파일이나 폴더를 동기화합니다.
+
+        Args:
+            file_paths (list): 동기화할 파일 또는 폴더 경로 리스트.
+                             폴더 경로는 자동으로 재귀적으로 처리됩니다.
+
+        Returns:
+            bool: 동기화 성공 시 True, 실패 시 False
+        """
+        if not self._is_connected():
+            return False
+        if not file_paths:
+            logger.debug("싱크할 파일/폴더 목록이 비어있습니다.")
+            return True
         
-        # 체인지리스트에 파일이 제대로 추가되었는지 확인
-        files_in_changelist = self.get_changelist_files(target_changelist)
+        # 폴더 경로에 재귀적 와일드카드 패턴을 추가
+        processed_paths = []
+        for path in file_paths:
+            if os.path.isdir(path):
+                # 폴더 경로에 '...'(재귀) 패턴을 추가
+                processed_paths.append(os.path.join(path, '...'))
+                logger.debug(f"폴더 경로를 재귀 패턴으로 변환: {path} -> {os.path.join(path, '...')}")
+            else:
+                processed_paths.append(path)
         
-        if not files_in_changelist:
-            # 파일 추가에 실패한 경우 빈 체인지리스트 삭제
-            self.delete_changelist(target_changelist)
-            print("파일을 체인지리스트에 추가하는 데 실패했습니다.")
+        logger.info(f"파일/폴더 싱크 시도 (항목 {len(processed_paths)}개): {processed_paths}")
+        try:
+            self.p4.run_sync(processed_paths)
+            logger.info(f"파일/폴더 싱크 완료: {processed_paths}")
+            return True
+        except P4Exception as e:
+            self._handle_p4_exception(e, f"파일/폴더 싱크 ({processed_paths})")
             return False
-            
-        print(f"파일 {len(files_in_changelist)}개가 체인지리스트 {target_changelist}에 추가되었습니다.")
-        return True
+
+    def disconnect(self):
+        """Perforce 서버와의 연결을 해제합니다."""
+        if self.connected:
+            try:
+                self.p4.disconnect()
+                self.connected = False
+                logger.info("Perforce 서버 연결 해제 완료.")
+            except P4Exception as e:
+                self._handle_p4_exception(e, "Perforce 서버 연결 해제")
+        else:
+            logger.debug("Perforce 서버에 이미 연결되지 않은 상태입니다.")
+
+    def __del__(self):
+        """객체가 소멸될 때 자동으로 연결을 해제합니다."""
+        self.disconnect()