🏠 홈 📖 전체 문서 📋 치트시트 🌐 Colab 가이드 🧪 테스트 리포트

Jupyter 한글 환경 설정 모듈 v2.4.0

🏠 c0z0c 메인 페이지 🚀 간단 사용법: helper.setup() 한 번으로 모든 설정 완료!

Jupyter Notebook과 Google Colab에서 한글 폰트 설정, pandas 확장 기능, 데이터 캐시를 제공하는 모듈입니다.

📺 YouTube 튜토리얼

🆕 v2.4.0 주요 업데이트

🎯 빠른 사용법

from urllib.request import urlretrieve; urlretrieve("https://raw.githubusercontent.com/c0z0c/jupyter_hangul/master/helper_c0z0c_dev.py", "helper_c0z0c_dev.py")
import helper_c0z0c_dev as helper # 한번에 모든 설정 완료

🎉 출력 예시:

🚀 Jupyter/Colab 한글 환경 설정 중... (helper v2.4.0)
✅ 한글 폰트 및 pandas 확장 기능 설정 완료
🎉 사용 가능: 한글 폰트, CSV 읽기, DataFrame.head_att(), 캐시 기능

🧪 베타 버전 테스트 (최신 기능 미리 체험)

# 베타 버전 - 최신 기능 포함 (실험적 기능 포함)
from urllib.request import urlretrieve; urlretrieve("https://raw.githubusercontent.com/c0z0c/jupyter_hangul/refs/heads/beta/helper_c0z0c_dev.py", "helper_c0z0c_dev.py")
import helper_c0z0c_dev as helper

💾 캐시 기능 (완전체!)

import helper_c0z0c_dev as helper

# 다양한 객체 캐시 지원
key = helper.cache_key("model", "v1.0", alpha=0.1)  # 파라미터 기반 키 생성
helper.cache_save(key, trained_model)               # ML 모델 저장
helper.cache_save("processed_data", df)             # DataFrame 저장
helper.cache_save("features", numpy_array)          # numpy 배열 저장

# 캐시 로드 및 존재 확인
if helper.cache_exists(key):
    model = helper.cache_load(key)
    print("캐시에서 로드됨")
else:
    model = train_new_model()
    helper.cache_save(key, model)

# 완전한 캐시 관리
helper.cache_list()              # 저장된 캐시 목록
helper.cache_size()              # 캐시 전체 크기
helper.cache_cleanup(days=30)    # 30일 이상 된 캐시 정리
helper.cache_compress()          # 캐시 압축
helper.cache_clear()             # 전체 캐시 삭제

🌐 환경 지원

사용 가능한 기능:

주요 기능

빠른 시작

1. 모듈 다운로드 및 설치

# Jupyter Notebook 또는 Google Colab에서 실행
!wget https://raw.githubusercontent.com/c0z0c/jupyter_hangul/master/helper_c0z0c_dev.py > /dev/null 2>&1

🧪 베타 버전 사용 시

# 베타 버전 다운로드
from urllib.request import urlretrieve; urlretrieve("https://raw.githubusercontent.com/c0z0c/jupyter_hangul/refs/heads/beta/helper_c0z0c_dev.py", "helper_c0z0c_dev.py")

2. 모듈 import 및 설정

import helper_c0z0c_dev as helper # 한번에 모든 설정 완료!
# import helper_c0z0c_dev as helper setup() 자동 호출
# helper.setup()  # 한번에 모든 설정 완료!

사용 예제

# 마스터 버전 (권장)
from urllib.request import urlretrieve; urlretrieve("https://raw.githubusercontent.com/c0z0c/jupyter_hangul/master/helper_c0z0c_dev.py", "helper_c0z0c_dev.py")
import helper_c0z0c_dev as helper

# 베타 버전 (최신 기능 테스트용)
# from urllib.request import urlretrieve; urlretrieve("https://raw.githubusercontent.com/c0z0c/jupyter_hangul/refs/heads/beta/helper_c0z0c_dev.py", "helper_c0z0c_dev.py")
# import helper_c0z0c_dev as helper

한글 폰트 사용

import matplotlib.pyplot as plt

# 한글 폰트가 자동으로 적용됨
plt.figure(figsize=(10, 6))
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
plt.title('한글 제목')
plt.xlabel('X축 라벨')
plt.ylabel('Y축 라벨')
plt.show()

pandas 확장 기능

import pandas as pd

# 샘플 데이터 생성
df = pd.DataFrame({
    'id': [1, 2, 3],
    'name': ['홍길동', '김철수', '이영희'],
    'age': [25, 30, 35]
})

# 기본 컬럼 설명 설정
df.set_head_att({
    'id': 'ID',
    'name': '이름',
    'age': '나이'
})

# 다양한 설명 세트 관리 (NEW!)
df.set_head_ext('korean', {
    'id': 'ID',
    'name': '이름',
    'age': '나이'
})

df.set_head_ext('detailed', {
    'id': '고유 식별자',
    'name': '사용자 성명',
    'age': '만 나이'
})

# 한글 설명이 포함된 DataFrame 출력 (다양한 형식 지원)
df.head_att()                    # 기본 print 형식
df.head_att(out='html')          # HTML 형식 (Jupyter/Colab에서 예쁘게 표시)
df.head_att(out='str')           # 문자열 형식

# 설명 세트 전환
df.change_set('detailed')        # 상세 설명으로 변경
df.head_att()

# 설명 세트 관리
df.list_sets()                   # 저장된 세트 목록
df.remove_set('detailed')        # 특정 세트 삭제

# Series도 완벽 지원
series = df['name']
series.head_att()

문제 해결

# 문제 발생 시 helper.setup() 다시 실행하면 대부분 해결됨
helper.setup()

편의 함수들

# 파일 읽기 (Colab/로컬 자동 인식, pandas.read_csv의 모든 옵션 지원)
df = helper.pd_read_csv('data.csv')
df = helper.pd_read_csv('data.csv', encoding='utf-8', sep=';')

# 다양한 입력 타입 지원
df = helper.pd_read_csv('data.csv')                    # 로컬 파일 경로 (자동 변환)
df = helper.pd_read_csv('https://example.com/data.csv') # URL (그대로 전달)
df = helper.pd_read_csv(file_object)                   # 파일 객체
from io import StringIO
df = helper.pd_read_csv(StringIO(csv_string))          # StringIO 객체

# 라이브러리 도움말 검색
helper.dir_start(pd.DataFrame, 'head')  # 'head'로 시작하는 메서드 검색

캐시 기능

# 캐시 키 생성 (딕셔너리 형태의 파라미터 기반)
params = {'alpha': 0.1, 'beta': 0.2, 'model': 'RF'}
cache_key = helper.cache_key(params)

# 데이터 캐시 저장/로드
if helper.cache_exists(cache_key):
    model = helper.cache_load(cache_key)
    print("캐시에서 모델 로드")
else:
    # 새로운 모델 훈련
    model = train_model(params)
    helper.cache_save(cache_key, model)
    print("모델 훈련 완료 및 캐시 저장")

# 캐시 관리
helper.cache_list()    # 저장된 캐시 목록
helper.cache_clear()   # 캐시 전체 삭제
helper.cache_info()    # 캐시 저장 위치 정보

DataFrame 커밋 기능 (NEW!)

# DataFrame을 git처럼 버전 관리
df.commit("데이터 전처리 완료")
df.commit("결측치 제거 후")
df.commit("피처 엔지니어링 적용")

# 커밋 히스토리 조회
df.commit_list()

# 커밋 관리
df.commit_rm(0)               # 인덱스로 삭제
df.commit_has("hash123")      # 커밋 존재 확인

# 심플 소스
df = helper.pd_checkout('원본')
if df.empty:
    df= helper.pd_read_csv('test.csv')
    helper.pd_commit(df, '원본')
    print('원본 reading from source')
else:
    print('원본 reading from cache')

📚 API 참조

주요 함수

파일 읽기

유틸리티

캐시 함수

DataFrame 커밋 함수

pandas 확장 메서드

Series도 동일한 메서드 완벽 지원

환경 지원

캐시 저장 위치

Google Colab

Jupyter Notebook (로컬)

설치 요구사항

모듈은 다음 라이브러리들을 사용합니다:

환경별 특징

Google Colab

Jupyter Notebook (로컬)

문제 해결

일반적인 문제

대부분의 문제는 helper.setup()을 다시 실행하면 해결됩니다.

helper.setup()  # 문제 해결

특정 문제별 해결방법

  1. 한글 폰트가 깨져 보일 때 
    helper.reset_matplotlib()  # matplotlib 완전 리셋 (v2.4.0 NEW!)
# 또는
helper.load_font()         # 폰트만 다시 로딩
  2. pandas 확장 기능이 작동하지 않을 때 
    helper.set_pandas_extension()  # pandas 확장만 다시 설정
  3. matplotlib이 Jupyter에서 작동하지 않을 때 (v2.4.0 NEW!) 
    helper.reset_matplotlib()  # IPython 글로벌 등록 포함
  4. Google Drive 연결 문제 (Colab) 
    helper.setup()  # 전체 재설정

감사 인사

기능 테스트에 도움을 주신 조하나 강사님 감사드립니다.

업데이트 내역

v2.4.0 (2025.08.29)

v2.3.0 (2025.08.03)

v2.2.0 (2025.07.25)

v2.1 (2025.07.13)

v2.0 (2025.07.12)

개발자 리뷰

주요 기능별 설계 의도:

개발 철학: Jupyter 환경에서 한국어 사용자의 데이터 분석 워크플로우를 최적화하고, 반복 작업을 줄여 분석에 집중할 수 있도록 돕는 것이 목표입니다.