텍스트 파일의 인코딩을 자동으로 감지하고 UTF-8로 변환하는 고성능 Python 도구입니다.
- 🔍 자동 인코딩 감지:
chardet라이브러리로 정확한 인코딩 감지 - ⚡ 멀티프로세싱: CPU 멀티코어 활용으로 최대 15배 속도 향상
- 🎯 스마트 샘플링: 파일 크기별 최적화된 인코딩 감지 전략
- 🛡️ 안전한 변환: 자동 백업 생성 및 완전한 복구 시스템
- 📊 실시간 모니터링: 진행률, 성능 통계, 상세 로그 기록
- 🔄 완전한 백업 시스템: 모든 변환 파일 자동 백업
- 📋 백업 레지스트리: JSON 기반 백업 정보 관리
- 🎯 선택적 복구: 특정 파일/디렉토리/전체 복구 지원
- 🗑️ 백업 관리: 제거, 정리, 목록 보기 기능
- 🔍 시스템 정리: 미등록 .backup 파일 자동 발견 및 정리
- 📁 자동 로그 관리:
log/디렉토리에 날짜별 로그 저장 - 📊 상세 로깅: 모든 변환 과정, 성공/실패, 성능 메트릭 기록
- 👀 로그 뷰어: 내장 로그 파일 뷰어로 실시간 확인
- ⚙️ 성능 튜닝: 프로세스 수, 청크 크기 등 실시간 조정
| 인코딩 | 설명 | 주요 사용처 |
|---|---|---|
| UTF-8 | 유니코드 표준 | 웹, 현대 시스템 |
| CP949 | 한국어 확장 완성형 | Windows 한글 |
| EUC-KR | 한국어 완성형 | 레거시 시스템 |
| ASCII | 기본 문자셋 | 영어 텍스트 |
| Latin-1 | 서유럽 문자셋 | 유럽어 |
| UTF-16/32 | 유니코드 변형 | Windows, Java |
| GB2312, Big5 | 중국어 | 중국 시스템 |
| Shift_JIS | 일본어 | 일본 시스템 |
- Python: 3.8 이상 (권장: 3.9+)
- OS: Windows, macOS, Linux
- 하드웨어: 멀티코어 CPU 권장 (4코어 이상), 8GB+ RAM
# 필수 라이브러리 설치
pip install chardet
# 또는 requirements.txt 사용
pip install -r requirements.txtchardet>=5.0.0python encoding_converter.py=== 텍스트 파일 인코딩 변환기 ⚡ (고성능 버전) ===
🔄 변환 기능
1. 단일 파일 변환
2. 디렉토리 일괄 변환 (현재 디렉토리만)
3. 디렉토리 재귀 변환 (하위 디렉토리 포함)
📊 분석 기능
4. 인코딩만 확인
5. 디렉토리 통계 보기
⚙️ 시스템 설정
6. 성능 설정 변경
🔄 백업 관리
7. 백업 파일에서 복구
8. 백업 파일 목록 보기
9. 백업 파일 제거
10. 백업 파일 정리 (오래된 백업)
11. 전체 백업 파일 정리 (.backup 파일 검색)
📄 로그 관리
12. 로그 파일 보기
🚪 종료
13. 종료
from encoding_converter import EncodingConverter
# 최적화된 인스턴스 생성
converter = EncodingConverter(max_workers=8)
# 대용량 디렉토리 고속 처리
converter.batch_convert(
directory_path="/large/project",
file_extension=".txt",
recursive=True,
max_depth=5,
force_convert=True, # 신뢰도 무시
use_multiprocessing=True # 병렬 처리
)# 성능 테스트 실행
python encoding_converter.py --benchmark /test/directory
# 출력 예시:
# 🧪 성능 벤치마크 시작 (1000개 파일)
# 🔄 순차 처리: 120.5초
# ⚡ 병렬 처리: 8.2초
# 🚀 속도 향상: 14.7배# 변환 시 자동 백업 생성
converter.convert_to_utf8("important.txt")
# → important.txt.backup 자동 생성
# → log/backup_registry.json에 정보 저장
# 실수로 변환했을 때 복구
converter.restore_from_backup(target_file="important.txt")
# → 원본 인코딩으로 완전 복구# 백업 목록 확인
converter.list_backup_files("/project")
# 오래된 백업 정리
converter.cleanup_backup_files(older_than_days=30)
# 백업 완전 제거
converter.remove_backup_files(directory_path="/project")💻 시스템 정보: CPU 8코어, 사용할 프로세스: 6개
📁 로그 디렉토리: /project/log
🚀 강제 변환 모드 | ⚡ 멀티프로세싱 (6개 프로세스)
※ 인코딩 신뢰도와 상관없이 모든 파일을 변환합니다.
============================================================
변환 시작... (1,247개 파일)
============================================================
진행률: 1247/1247 (100.0%)
============================================================
🎉 일괄 변환 완료!
============================================================
✅ 성공: 1,241개
❌ 실패: 6개
📄 전체: 1,247개
⏱️ 총 소요시간: 15.23초
📊 처리 속도: 81.9개/초
💾 총 파일 크기: 456.78MB
🚀 처리량: 29.98MB/초
📋 복구 가능한 파일 목록:
============================================================
1. /project/src/main.py
백업시간: 2025-01-05T14:30:25
원본인코딩: cp949
백업파일: /project/src/main.py.backup
2. /project/docs/readme.txt
백업시간: 2025-01-05T14:30:28
원본인코딩: euc-kr
백업파일: /project/docs/readme.txt.backup
복구할 파일을 선택하세요:
a) 모든 파일 복구
q) 취소
숫자) 특정 파일 복구
선택: a
🔄 복구 시작...
✅ 복구 완료: /project/src/main.py
✅ 복구 완료: /project/docs/readme.txt
==================================================
🎉 복구 완료!
✅ 성공: 2개
❌ 실패: 0개
🔍 시스템 전체에서 .backup 파일 검색 중...
📊 백업 파일 검색 결과:
등록된 백업: 45개
미등록 백업: 12개
총 백업 파일: 57개
🚫 미등록 백업 파일들:
1. /old_project/test.txt.backup
크기: 2,048 bytes
수정일: 2024-12-15 09:30:15
미등록 백업 파일 처리:
1. 모든 미등록 백업 삭제
2. 미등록 백업을 레지스트리에 등록
3. 아무것도 하지 않음
선택: 1
⚠️ 모든 미등록 백업을 삭제하시겠습니까? (DELETE 입력): DELETE
✅ 12개 미등록 백업을 삭제했습니다.
import multiprocessing as mp
cpu_count = mp.cpu_count()
if cpu_count <= 2:
max_workers = 1 # 저사양
elif cpu_count <= 4:
max_workers = cpu_count - 1 # 중간사양
else:
max_workers = int(cpu_count * 0.75) # 고사양
converter = EncodingConverter(max_workers=max_workers)# 작은 파일이 많은 경우
converter.chunk_size = 4096
converter.large_file_threshold = 100 * 1024
# 큰 파일이 많은 경우
converter.chunk_size = 32768
converter.large_file_threshold = 10 * 1024 * 1024# 메모리 절약 모드
converter = EncodingConverter(max_workers=2)
converter.chunk_size = 2048
# 순차 처리로 안정성 확보
converter.batch_convert(
directory_path="/data",
use_multiprocessing=False
)def process_massive_dataset(base_path: str):
"""10만개+ 파일 처리 최적화"""
converter = EncodingConverter(max_workers=8)
# 1단계: 확장자별 분할 처리
extensions = ['.txt', '.log', '.csv', '.md', '.py']
for ext in extensions:
print(f"Processing {ext} files...")
# 2단계: 디렉토리별 세분화
for subdir in Path(base_path).iterdir():
if subdir.is_dir():
converter.batch_convert(
str(subdir),
ext,
recursive=True,
max_depth=3,
force_convert=True,
use_multiprocessing=True
)
# 3단계: 백업 정리 (메모리 절약)
converter.cleanup_backup_files(
str(subdir),
older_than_days=1
)class CustomEncodingConverter(EncodingConverter):
def __init__(self, max_workers=None):
super().__init__(max_workers)
# 추가 인코딩 지원
self.supported_encodings.extend([
'iso-8859-1', 'windows-1252', 'koi8-r',
'iso-8859-2', 'windows-1250' # 동유럽
])
def custom_detect_encoding(self, file_path: str):
"""특별한 감지 로직 추가"""
# BOM 확인, 특정 패턴 검사 등
pass# 오류: ModuleNotFoundError: No module named 'chardet'
pip install chardet
# Windows에서 권한 문제 시
pip install chardet --user# Linux/Mac 권한 오류
chmod 644 target_file.txt
sudo python encoding_converter.py
# Windows 관리자 권한 필요
# → 관리자 권한으로 명령 프롬프트 실행# Windows에서 BrokenProcessPool 오류
if __name__ == "__main__":
# 반드시 이 블록 안에서 실행
converter = EncodingConverter()
converter.batch_convert(...)# 대용량 파일 처리 시
converter = EncodingConverter(max_workers=2) # 프로세스 수 감소
converter.chunk_size = 2048 # 청크 크기 감소
converter.batch_convert(use_multiprocessing=False) # 순차 처리# 1. 멀티프로세싱 확인
print(f"CPU: {mp.cpu_count()}, 프로세스: {converter.max_workers}")
# 2. 청크 크기 최적화
converter.chunk_size = 16384 # 16KB로 증가
# 3. 강제 변환 모드 (신뢰도 확인 생략)
converter.batch_convert(force_convert=True)
# 4. SSD 사용 권장 (HDD 대비 10배 빠름)# 1. 프로세스 수 감소
converter = EncodingConverter(max_workers=2)
# 2. 청크 크기 감소
converter.chunk_size = 2048
# 3. 분할 처리
for subdir in large_directory.iterdir():
converter.batch_convert(str(subdir))# 로그 로테이션 (수동)
import shutil
from datetime import datetime
log_dir = Path("log")
archive_dir = log_dir / "archive"
archive_dir.mkdir(exist_ok=True)
# 30일 이전 로그 아카이브
cutoff_date = datetime.now() - timedelta(days=30)
for log_file in log_dir.glob("*.log"):
if datetime.fromtimestamp(log_file.stat().st_mtime) < cutoff_date:
shutil.move(str(log_file), str(archive_dir / log_file.name))# 정기적인 백업 정리 (예: 매주 실행)
python encoding_converter.py
# 11번 → 미등록 백업 정리
# 10번 → 7일 이전 백업 삭제@RestController
public class EncodingController {
@PostMapping("/convert")
public ResponseEntity<ConversionResult> convertFiles(
@RequestParam String directory,
@RequestParam(defaultValue = ".txt") String extension) {
try {
ProcessBuilder pb = new ProcessBuilder(
"python", "encoding_converter.py",
"--batch", directory,
"--extension", extension,
"--force", "true",
"--multiprocessing", "true"
);
Process process = pb.start();
int exitCode = process.waitFor();
if (exitCode == 0) {
// 로그 파일에서 결과 파싱
String logContent = readLatestLog();
ConversionResult result = parseConversionResult(logContent);
return ResponseEntity.ok(result);
} else {
return ResponseEntity.badRequest()
.body(new ConversionResult("변환 실패"));
}
} catch (Exception e) {
return ResponseEntity.internalServerError()
.body(new ConversionResult("오류: " + e.getMessage()));
}
}
}from fastapi import FastAPI, UploadFile, BackgroundTasks
from encoding_converter import EncodingConverter
import tempfile
import os
app = FastAPI()
converter = EncodingConverter()
@app.post("/convert-file/")
async def convert_file_encoding(
file: UploadFile,
background_tasks: BackgroundTasks
):
# 임시 파일로 저장
with tempfile.NamedTemporaryFile(delete=False) as temp_file:
content = await file.read()
temp_file.write(content)
temp_path = temp_file.name
try:
# 인코딩 변환
success = converter.convert_to_utf8(temp_path, force_convert=True)
if success:
# 변환된 파일 내용 읽기
with open(temp_path, 'r', encoding='utf-8') as f:
converted_content = f.read()
# 백그라운드에서 임시 파일 정리
background_tasks.add_task(os.unlink, temp_path)
return {
"success": True,
"content": converted_content,
"message": "변환 완료"
}
else:
return {"success": False, "message": "변환 실패"}
except Exception as e:
return {"success": False, "message": f"오류: {e}"}FROM python:3.9-slim
WORKDIR /app
# 시스템 패키지 설치
RUN apt-get update && apt-get install -y \
locales \
&& rm -rf /var/lib/apt/lists/*
# 한국어 로케일 설정
RUN sed -i '/ko_KR.UTF-8/s/^# //g' /etc/locale.gen && \
locale-gen
ENV LANG ko_KR.UTF-8
ENV LANGUAGE ko_KR:ko
ENV LC_ALL ko_KR.UTF-8
# Python 의존성 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 앱 코드 복사
COPY encoding_converter.py .
# 로그 디렉토리 생성
RUN mkdir -p /app/log
# 실행
CMD ["python", "encoding_converter.py"]apiVersion: apps/v1
kind: Deployment
metadata:
name: encoding-converter
spec:
replicas: 3
selector:
matchLabels:
app: encoding-converter
template:
metadata:
labels:
app: encoding-converter
spec:
containers:
- name: converter
image: encoding-converter:latest
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "2Gi"
cpu: "1000m"
volumeMounts:
- name: data-storage
mountPath: /data
- name: log-storage
mountPath: /app/log
volumes:
- name: data-storage
persistentVolumeClaim:
claimName: data-pvc
- name: log-storage
persistentVolumeClaim:
claimName: log-pvc- 이 저장소를 포크합니다
- 새로운 기능 브랜치를 생성합니다 (
git checkout -b feature/amazing-feature) - 변경사항을 커밋합니다 (
git commit -am 'Add amazing feature') - 브랜치에 푸시합니다 (
git push origin feature/amazing-feature) - Pull Request를 생성합니다
- 코드 스타일: PEP 8 준수
- 테스트: 새 기능에 대한 단위 테스트 작성
- 문서화: 새 기능에 대한 docstring 및 README 업데이트
- 로깅: 모든 주요 작업에 대한 로그 기록
이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
- GitHub Issues: 버그 리포트 및 기능 요청
- 이메일: zero2080@naver.com
프로그램에 내장된 벤치마크 도구로 실제 성능을 측정할 수 있습니다:
# 벤치마크 실행
python encoding_converter.py --benchmark /path/to/test/directory
# 또는 메뉴에서 실행
python encoding_converter.py
# 메뉴 선택 후 테스트 디렉토리에서 순차/병렬 처리 비교일반적인 멀티프로세싱 환경에서 기대할 수 있는 성능:
| CPU 코어 | 예상 속도 향상 | 최적 프로세스 수 |
|---|---|---|
| 2코어 | 1.5-1.8배 | 1-2개 |
| 4코어 | 2.5-3.5배 | 3개 |
| 6코어 | 4-6배 | 4-5개 |
| 8코어+ | 6-12배 | 6-8개 |
- SSD 사용 (HDD 대비 5-10배 빠름)
- 멀티코어 CPU (코어 수에 비례하여 향상)
- 충분한 RAM (8GB 이상 권장)
- 작은 파일 개수가 많은 경우 (병렬 처리 효과 극대화)
- HDD 사용 (I/O 병목 현상)
- 네트워크 드라이브 (네트워크 지연)
- 바이러스 스캐너 (실시간 검사)
- 단일 대용량 파일 (병렬 처리 효과 제한)
# test_generator.py - 테스트 파일 생성기
import os
from pathlib import Path
def create_test_files(base_dir: str, file_count: int = 100):
"""테스트용 파일들 생성"""
test_dir = Path(base_dir) / "encoding_test"
test_dir.mkdir(exist_ok=True)
# 다양한 인코딩으로 테스트 파일 생성
encodings = ['cp949', 'euc-kr', 'latin-1']
content = "안녕하세요. 이것은 테스트 파일입니다. " * 100
for i in range(file_count):
encoding = encodings[i % len(encodings)]
file_path = test_dir / f"test_{i:03d}.txt"
with open(file_path, 'w', encoding=encoding) as f:
f.write(f"File {i}: {content}")
print(f"✅ {file_count}개 테스트 파일 생성 완료: {test_dir}")
# 실행
create_test_files(".", 1000) # 1000개 파일 생성# 생성된 테스트 파일로 벤치마크
python encoding_converter.py --benchmark ./encoding_test
# 출력 예시:
# 🧪 성능 벤치마크 시작 (1000개 파일)
# ============================================================
# 🔄 순차 처리 테스트... 완료 (45.2초)
# ⚡ 병렬 처리 테스트... 완료 (8.7초)
# 📊 벤치마크 결과:
# 순차 처리: 45.20초
# 병렬 처리: 8.70초
# 🚀 속도 향상: 5.2배실제 테스트 후 여러분의 결과를 기록해보세요:
내 시스템 사양:
- CPU: ___________
- RAM: ___________
- Storage: _______
테스트 결과:
- 파일 수: ______개
- 순차 처리: ____초
- 병렬 처리: ____초
- 속도 향상: ____배
# 최적 프로세스 수 찾기
def find_optimal_workers(test_directory: str):
"""시스템에 최적인 프로세스 수 찾기"""
import time
results = {}
max_workers = mp.cpu_count()
for workers in range(1, max_workers + 1):
converter = EncodingConverter(max_workers=workers)
start_time = time.time()
# 소량 테스트 실행
converter.batch_convert(
test_directory,
recursive=False,
use_multiprocessing=(workers > 1)
)
end_time = time.time()
results[workers] = end_time - start_time
print(f"{workers}개 프로세스: {results[workers]:.2f}초")
# 최적 설정 찾기
optimal_workers = min(results, key=results.get)
print(f"🚀 최적 프로세스 수: {optimal_workers}개")
return optimal_workersimport psutil
import time
def monitor_memory_usage():
"""메모리 사용량 실시간 모니터링"""
process = psutil.Process()
print("메모리 사용량 모니터링 중...")
print("시간\t\t메모리(MB)\tCPU(%)")
print("-" * 40)
start_time = time.time()
while True:
memory_mb = process.memory_info().rss / 1024 / 1024
cpu_percent = process.cpu_percent()
elapsed = time.time() - start_time
print(f"{elapsed:6.1f}초\t{memory_mb:8.1f}MB\t{cpu_percent:6.1f}%")
time.sleep(1)실제 성능은 시스템 환경에 따라 크게 달라집니다! 위의 벤치마크 도구를 사용해서 여러분의 시스템에서 실제 성능을 측정해보시기 바랍니다. 💪
최종 개발 완료: 2025년 1월 | 버전: 2.0.0 (최종 완전판)
성능: 일반 모드 대비 최대 15배 속도 향상 | 완전한 백업 시스템 | 통합 로그 관리
적용 분야: 대용량 데이터 처리, 레거시 시스템 마이그레이션, 국제화 프로젝트