hossam 0.2.1__tar.gz → 0.3.19__tar.gz

hossam-0.3.19/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+global-exclude __pycache__
+recursive-include hossam *.ttf
+recursive-include hossam *.png

hossam-0.3.19/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: hossam
+Version: 0.3.19
+Summary: Hossam Data Helper
+Author-email: Lee Kwang-Ho <leekh4232@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/leekh4232/hossam-py
+Project-URL: Repository, https://github.com/leekh4232/hossam-py
+Keywords: data,analysis,helper,hossam,tensorflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tqdm
+Requires-Dist: tabulate
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: requests
+Requires-Dist: openpyxl
+Requires-Dist: xlrd
+Requires-Dist: statsmodels
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: pingouin
+Requires-Dist: statannotations
+Requires-Dist: joblib
+Requires-Dist: geopandas
+Requires-Dist: kmodes
+Requires-Dist: pmdarima
+Requires-Dist: prophet
+Requires-Dist: plotly
+Requires-Dist: jenkspy
+Dynamic: license-file
+
+---
+title: 🎓 Hossam Data Helper
+---
+
+# 🎓 Hossam Data Helper
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-0.3.19-green.svg)](https://pypi.org/project/hossam/)
+[![Documentation](https://img.shields.io/badge/docs-py.hossam.kr-blue.svg)](https://py.hossam.kr)
+
+**Hossam**은 데이터 분석, 시각화, 통계 처리를 위한 종합 헬퍼 라이브러리입니다.
+
+아이티윌(ITWILL)에서 진행 중인 머신러닝 및 데이터 분석 수업을 위해 개발되었으며, 이광호 강사의 강의에서 활용됩니다.
+
+## ✨ 주요 특징
+
+- 📊 **풍부한 시각화**: 25+ 시각화 함수 (Seaborn/Matplotlib 기반)
+- 🎯 **통계 분석**: 회귀, 분류, 시계열 분석 도구
+- 📦 **샘플 데이터**: 학습용 데이터셋 즉시 로드
+- 🔧 **데이터 전처리**: 결측치 처리, 이상치 탐지, 스케일링
+- 🤖 **MCP 서버**: VSCode/Copilot과 통합 가능한 Model Context Protocol 지원
+- 📈 **교육용 최적화**: 데이터 분석 교육에 특화된 설계
+
+---
+
+## 📦 설치
+
+```bash
+pip install hossam
+```
+
+**요구사항**: Python 3.8 이상
+
+---
+
+## 🚀 빠른 시작
+
+### 샘플 데이터 로드
+
+```python
+from hossam import load_data, load_info
+
+# 사용 가능한 데이터셋 확인
+datasets = load_info()
+
+# 데이터 로드
+df = load_data('AD_SALES')
+```
+
+### 간단한 시각화
+
+```python
+from hossam import hs_plot
+import pandas as pd
+import numpy as np
+
+df = pd.DataFrame({
+    'x': np.random.randn(100),
+    'y': np.random.randn(100),
+    'category': np.random.choice(['A', 'B', 'C'], 100)
+})
+
+# 산점도
+hs_plot.scatterplot(df=df, xname='x', yname='y', hue='category')
+
+# 박스플롯
+hs_plot.boxplot(df=df, xname='category', yname='x')
+```
+
+---
+
+## 🤖 MCP Server
+
+Hossam은 **Model Context Protocol(MCP)** 기반 서버로도 작동하며, VSCode Copilot/Cline과 통합하여 데이터 분석 코드를 자동 생성할 수 있습니다.
+
+### 빠른 시작
+
+```bash
+# 서버 시작
+hossam-mcp
+```
+
+### VSCode + Copilot 연동
+
+VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이 필요합니다.
+
+**Copilot Chat에서 사용:**
+```
+@hossam 이 DataFrame의 결측치를 분석하고 처리하는 코드 작성해줘
+```
+
+**설정 가이드:**
+- [`.vscode/settings.json` 완성형 샘플](https://py.hossam.kr/guides/vscode-settings-sample/) ⭐
+- [VSCode + Copilot 연동 상세](https://py.hossam.kr/guides/vscode-copilot-integration/)
+- [MCP 서버 사용법](https://py.hossam.kr/guides/mcp/)
+- [Copilot Chat 프롬프트 예시](https://py.hossam.kr/guides/copilot-prompts/)
+
+---
+
+## 📚 전체 문서
+
+**완전한 API 문서와 가이드는 [py.hossam.kr](https://py.hossam.kr)에서 확인하세요.**
+
+### 주요 모듈
+
+- **hs_plot**: 25+ 시각화 함수 (선 그래프, 산점도, 히스토그램, 박스플롯, 히트맵 등)
+- **hs_stats**: 회귀/분류 분석, 교차검증, 정규성 검정, 상관분석 등
+- **hs_prep**: 결측치 처리, 이상치 탐지, 스케일링, 인코딩
+- **hs_gis**: GIS 데이터 로드 및 시각화 (대한민국 지도 지원)
+- **hs_classroom**: 학습용 이진분류, 다중분류, 회귀 데이터 생성
+- **hs_util**: 예쁜 테이블 출력, 그리드 서치 등
+
+자세한 사용법은 [API 문서](https://py.hossam.kr/api/hossam/)를 참고하세요.
+
+---
+
+## 🎓 예제
+
+### 결측치 분석
+
+```python
+from hossam import hs_prep
+
+# 결측치 정보 확인
+hs_prep.hs_missing_values(df)
+
+# 결측치 시각화
+hs_prep.hs_missing_values_barplot(df)
+```
+
+### 회귀 분석
+
+```python
+from hossam import hs_stats
+
+# 단순 선형 회귀
+result = hs_stats.hs_simple_regression(df, xname='x', yname='y', plot=True)
+```
+
+### 상관분석 히트맵
+
+```python
+from hossam import hs_plot
+
+hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
+```
+
+더 많은 예제는 [문서 사이트](https://py.hossam.kr)를 참고하세요.
+
+---
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
+
+---
+
+## 🔗 링크
+
+- **문서**: [py.hossam.kr](https://py.hossam.kr)
+- **PyPI**: [pypi.org/project/hossam](https://pypi.org/project/hossam/)
+- **강사**: 이광호 (ITWILL 머신러닝 및 데이터 분석)
+
+---
+
+**Made with ❤️ for Data Science Education**

hossam-0.3.19/README.md

@@ -0,0 +1,167 @@
+---
+title: 🎓 Hossam Data Helper
+---
+
+# 🎓 Hossam Data Helper
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-0.3.19-green.svg)](https://pypi.org/project/hossam/)
+[![Documentation](https://img.shields.io/badge/docs-py.hossam.kr-blue.svg)](https://py.hossam.kr)
+
+**Hossam**은 데이터 분석, 시각화, 통계 처리를 위한 종합 헬퍼 라이브러리입니다.
+
+아이티윌(ITWILL)에서 진행 중인 머신러닝 및 데이터 분석 수업을 위해 개발되었으며, 이광호 강사의 강의에서 활용됩니다.
+
+## ✨ 주요 특징
+
+- 📊 **풍부한 시각화**: 25+ 시각화 함수 (Seaborn/Matplotlib 기반)
+- 🎯 **통계 분석**: 회귀, 분류, 시계열 분석 도구
+- 📦 **샘플 데이터**: 학습용 데이터셋 즉시 로드
+- 🔧 **데이터 전처리**: 결측치 처리, 이상치 탐지, 스케일링
+- 🤖 **MCP 서버**: VSCode/Copilot과 통합 가능한 Model Context Protocol 지원
+- 📈 **교육용 최적화**: 데이터 분석 교육에 특화된 설계
+
+---
+
+## 📦 설치
+
+```bash
+pip install hossam
+```
+
+**요구사항**: Python 3.8 이상
+
+---
+
+## 🚀 빠른 시작
+
+### 샘플 데이터 로드
+
+```python
+from hossam import load_data, load_info
+
+# 사용 가능한 데이터셋 확인
+datasets = load_info()
+
+# 데이터 로드
+df = load_data('AD_SALES')
+```
+
+### 간단한 시각화
+
+```python
+from hossam import hs_plot
+import pandas as pd
+import numpy as np
+
+df = pd.DataFrame({
+    'x': np.random.randn(100),
+    'y': np.random.randn(100),
+    'category': np.random.choice(['A', 'B', 'C'], 100)
+})
+
+# 산점도
+hs_plot.scatterplot(df=df, xname='x', yname='y', hue='category')
+
+# 박스플롯
+hs_plot.boxplot(df=df, xname='category', yname='x')
+```
+
+---
+
+## 🤖 MCP Server
+
+Hossam은 **Model Context Protocol(MCP)** 기반 서버로도 작동하며, VSCode Copilot/Cline과 통합하여 데이터 분석 코드를 자동 생성할 수 있습니다.
+
+### 빠른 시작
+
+```bash
+# 서버 시작
+hossam-mcp
+```
+
+### VSCode + Copilot 연동
+
+VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이 필요합니다.
+
+**Copilot Chat에서 사용:**
+```
+@hossam 이 DataFrame의 결측치를 분석하고 처리하는 코드 작성해줘
+```
+
+**설정 가이드:**
+- [`.vscode/settings.json` 완성형 샘플](https://py.hossam.kr/guides/vscode-settings-sample/) ⭐
+- [VSCode + Copilot 연동 상세](https://py.hossam.kr/guides/vscode-copilot-integration/)
+- [MCP 서버 사용법](https://py.hossam.kr/guides/mcp/)
+- [Copilot Chat 프롬프트 예시](https://py.hossam.kr/guides/copilot-prompts/)
+
+---
+
+## 📚 전체 문서
+
+**완전한 API 문서와 가이드는 [py.hossam.kr](https://py.hossam.kr)에서 확인하세요.**
+
+### 주요 모듈
+
+- **hs_plot**: 25+ 시각화 함수 (선 그래프, 산점도, 히스토그램, 박스플롯, 히트맵 등)
+- **hs_stats**: 회귀/분류 분석, 교차검증, 정규성 검정, 상관분석 등
+- **hs_prep**: 결측치 처리, 이상치 탐지, 스케일링, 인코딩
+- **hs_gis**: GIS 데이터 로드 및 시각화 (대한민국 지도 지원)
+- **hs_classroom**: 학습용 이진분류, 다중분류, 회귀 데이터 생성
+- **hs_util**: 예쁜 테이블 출력, 그리드 서치 등
+
+자세한 사용법은 [API 문서](https://py.hossam.kr/api/hossam/)를 참고하세요.
+
+---
+
+## 🎓 예제
+
+### 결측치 분석
+
+```python
+from hossam import hs_prep
+
+# 결측치 정보 확인
+hs_prep.hs_missing_values(df)
+
+# 결측치 시각화
+hs_prep.hs_missing_values_barplot(df)
+```
+
+### 회귀 분석
+
+```python
+from hossam import hs_stats
+
+# 단순 선형 회귀
+result = hs_stats.hs_simple_regression(df, xname='x', yname='y', plot=True)
+```
+
+### 상관분석 히트맵
+
+```python
+from hossam import hs_plot
+
+hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
+```
+
+더 많은 예제는 [문서 사이트](https://py.hossam.kr)를 참고하세요.
+
+---
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
+
+---
+
+## 🔗 링크
+
+- **문서**: [py.hossam.kr](https://py.hossam.kr)
+- **PyPI**: [pypi.org/project/hossam](https://pypi.org/project/hossam/)
+- **강사**: 이광호 (ITWILL 머신러닝 및 데이터 분석)
+
+---
+
+**Made with ❤️ for Data Science Education**

hossam-0.3.19/hossam/__init__.py

@@ -0,0 +1,89 @@
+from .data_loader import load_data, load_info
+from .hs_stats import oneway_anova
+from matplotlib import pyplot as plt
+from matplotlib import font_manager as fm
+from importlib.resources import files, as_file
+from importlib.metadata import version
+from types import SimpleNamespace
+import sys
+import warnings
+
+try:
+    __version__ = version("hossam")
+except Exception:
+    __version__ = "develop"
+
+
+hs_fig = SimpleNamespace(
+    dpi=200,
+    width=800,
+    height=450,
+    font_size=9.5,
+    font_weight="normal",
+    frame_width=0.7,
+    line_width=1.5,
+    grid_alpha=0.3,
+    grid_width=0.5,
+    fill_alpha=0.3
+)
+
+__all__ = ["load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util", "hs_fig"]
+
+
+def _init_korean_font():
+    """
+    패키지에 포함된 한글 폰트를 기본 폰트로 설정합니다.
+    """
+    font_file = "NotoSansKR-Regular.ttf"
+    try:
+        # 패키지 리소스에서 폰트 파일 경로 확보
+        with as_file(files("hossam") / font_file) as font_path:
+            fm.fontManager.addfont(str(font_path))
+            fprop = fm.FontProperties(fname=str(font_path))
+            fname = fprop.get_name()
+
+            plt.rcParams.update({
+                "font.family": fname,
+                "font.size": hs_fig.font_size,
+                "font.weight": hs_fig.font_weight,
+                "axes.unicode_minus": False,
+                "text.antialiased": True,
+                "lines.antialiased": True,
+                "patch.antialiased": True,
+                "figure.dpi": hs_fig.dpi,
+                "savefig.dpi": hs_fig.dpi * 2,
+                "text.hinting": "auto",
+                "text.hinting_factor": 8,
+                "pdf.fonttype": 42,
+                "ps.fonttype": 42,
+            })
+            if sys.stdout.isatty():
+                print(
+                    "\n✅ 시각화를 위한 한글 글꼴(NotoSansKR-Regular)이 자동 적용되었습니다."
+                )
+            return
+    except Exception as e:
+        warnings.warn(f"\n한글 폰트 초기화: 패키지 폰트 사용 실패 ({e}).")
+
+
+def _init():
+
+    # 안내 메시지 (블릿 리스트)
+    messages = [
+        "📦 아이티윌 이광호 강사가 제작한 라이브러리를 사용중입니다.",
+        "📚 자세한 사용 방법은 https://py.hossam.kr 을 참고하세요.",
+        "📧 Email: leekh4232@gmail.com",
+        "🎬 Youtube: https://www.youtube.com/@hossam-codingclub",
+        "📝 Blog: https://blog.hossam.kr/",
+        f"🔖 Version: {__version__}",
+    ]
+
+    # MCP/stdio 환경에서는 배너를 출력하지 않음 (stdout TTY일 때만 출력)
+    if sys.stdout.isatty():
+        for msg in messages:
+            print(f"{msg}")
+
+    _init_korean_font()
+
+
+_init()

{hossam-0.2.1 → hossam-0.3.19}/hossam/data_loader.py

@@ -1,15 +1,18 @@
+# -*- coding: utf-8 -*-
+# -------------------------------------------------------------
+
 import requests
 import json
 from os.path import join, exists
 from io import BytesIO
 from pandas import DataFrame, read_csv, read_excel
-
-from .util import my_pretty_table
+from typing import Optional
+from typing import Optional
 
 BASE_URL = "https://data.hossam.kr"
 
-
-def get_df(path: str, index_col=None) -> DataFrame:
+# -------------------------------------------------------------
+def __get_df(path: str, index_col=None) -> DataFrame:
     p = path.rfind(".")
     exec = path[p+1:].lower()
 
@@ -32,7 +35,8 @@ def get_df(path: str, index_col=None) -> DataFrame:
                 info = read_excel(BytesIO(data_bytes), sheet_name='metadata', index_col=0)
                 #print("\033[94m[metadata]\033[0m")
                 print()
-                my_pretty_table(info)
+                from .util import hs_pretty_table
+                hs_pretty_table(info)
                 print()
             except Exception:
                 print(f"\033[91m[!] Cannot read metadata\033[0m")
@@ -43,7 +47,8 @@ def get_df(path: str, index_col=None) -> DataFrame:
                 info = read_excel(path, sheet_name='metadata', index_col=0)
                 #print("\033[94m[metadata]\033[0m")
                 print()
-                my_pretty_table(info)
+                from .util import hs_pretty_table
+                hs_pretty_table(info)
                 print()
             except:
                 print(f"\033[91m[!] Cannot read metadata\033[0m")
@@ -52,7 +57,8 @@ def get_df(path: str, index_col=None) -> DataFrame:
 
     return df
 
-def get_data_url(key: str, local: str = None) -> str:
+# -------------------------------------------------------------
+def __get_data_url(key: str, local: str = None) -> str:
     global BASE_URL
 
     path = None
@@ -87,8 +93,23 @@ def get_data_url(key: str, local: str = None) -> str:
 
     return path, info.get('desc'), info.get('index')
 
+# -------------------------------------------------------------
+def load_info(search: str = None, local: str = None) -> DataFrame:
+    """메타데이터에서 사용 가능한 데이터셋 정보를 로드한다.
+
+    Args:
+        search (str, optional): 이름 필터 문자열. 포함하는 항목만 반환.
+        local (str, optional): 로컬 메타데이터 경로. None이면 원격(BASE_URL) 사용.
+
+    Returns:
+        DataFrame: name, chapter, desc, url 컬럼을 갖는 테이블
 
-def load_info(search: str = None, local: str = None):
+    Examples:
+        >>> from hossam.data_loader import load_info
+        >>> info = load_info()
+        >>> list(info.columns)
+        ['name', 'chapter', 'desc', 'url']
+    """
     global BASE_URL
 
     path = None
@@ -135,11 +156,24 @@ def load_info(search: str = None, local: str = None):
 
     return my_df2
 
+# -------------------------------------------------------------
+def load_data(key: str, local: str = None) -> Optional[DataFrame]:
+    """키로 지정된 데이터셋을 로드한다.
 
-def load_data(key: str, local: str = None):
+    Args:
+        key (str): 메타데이터에 정의된 데이터 식별자(파일명 또는 별칭)
+        local (str, optional): 로컬 메타데이터 경로. None이면 원격(BASE_URL) 사용.
+
+    Returns:
+        DataFrame | None: 성공 시 데이터프레임, 실패 시 None
+
+    Examples:
+        >>> from hossam.data_loader import load_data
+        >>> df = load_data('AD_SALES')  # 메타데이터에 해당 키가 있어야 함
+    """
     index = None
     try:
-        url, desc, index = get_data_url(key, local=local)
+        url, desc, index = __get_data_url(key, local=local)
     except Exception as e:
         try:
             print(f"\033[91m{str(e)}\033[0m")
@@ -153,7 +187,7 @@ def load_data(key: str, local: str = None):
     df = None
 
     try:
-        df = get_df(url, index_col=index)
+        df = __get_df(url, index_col=index)
     except Exception as e:
         try:
             print(f"\033[91m{str(e)}\033[0m")
@@ -162,9 +196,4 @@ def load_data(key: str, local: str = None):
         return
 
 
-    return df
-
-if __name__ == "__main__":
-    print(load_info())
-    df = load_data("boston")
-    my_pretty_table(df)
+    return df