hossam 0.4.2__tar.gz

hossam-0.4.2/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 Lee Kwang-Ho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hossam-0.4.2/MANIFEST.in

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

hossam-0.4.2/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: hossam
+Version: 0.4.2
+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
+Requires-Dist: flask
+Requires-Dist: xgboost
+Requires-Dist: lightgbm
+Requires-Dist: catboost
+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 이상
+
+## 📚 전체 문서
+
+**완전한 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/)를 참고하세요.
+
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
+
+## 🔗 링크
+
+- **문서**: [py.hossam.kr](https://py.hossam.kr)
+- **PyPI**: [pypi.org/project/hossam](https://pypi.org/project/hossam/)
+- **강사**: 이광호 (ITWILL 머신러닝 및 데이터 분석)
+
+---
+
+{% include 'HOSSAM_API.md' %}

hossam-0.4.2/README.md

@@ -0,0 +1,62 @@
+---
+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 이상
+
+## 📚 전체 문서
+
+**완전한 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/)를 참고하세요.
+
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
+
+## 🔗 링크
+
+- **문서**: [py.hossam.kr](https://py.hossam.kr)
+- **PyPI**: [pypi.org/project/hossam](https://pypi.org/project/hossam/)
+- **강사**: 이광호 (ITWILL 머신러닝 및 데이터 분석)
+
+---
+
+{% include 'HOSSAM_API.md' %}

hossam-0.4.2/hossam/__init__.py

@@ -0,0 +1,84 @@
+# submodules
+from . import hs_classroom
+from . import hs_gis
+from . import hs_plot
+from . import hs_prep
+from . import hs_stats
+from . import hs_timeserise
+from . import hs_util
+from .data_loader import load_data, load_info
+
+# py-modules
+import sys
+import warnings
+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
+
+try:
+    __version__ = version("hossam")
+except Exception:
+    __version__ = "develop"
+
+__all__ = ["load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util"]
+
+# 내부 모듈에서 hs_fig를 사용할 때는 아래와 같이 import 하세요.
+# from hossam import 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_plot.config.font_size,
+                "font.weight": hs_plot.config.font_weight,
+                "axes.unicode_minus": False,
+                "text.antialiased": True,
+                "lines.antialiased": True,
+                "patch.antialiased": True,
+                "figure.dpi": hs_plot.config.dpi,
+                "savefig.dpi": hs_plot.config.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__}",
+    ]
+
+    for msg in messages:
+        print(f"{msg}")
+
+    _init_korean_font()
+
+
+_init()

hossam-0.4.2/hossam/data_loader.py

@@ -0,0 +1,205 @@
+# -*- 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 typing import Optional
+from typing import Optional
+
+BASE_URL = "https://data.hossam.kr"
+
+# -------------------------------------------------------------
+def __get_df(path: str, index_col=None) -> DataFrame:
+    p = path.rfind(".")
+    exec = path[p+1:].lower()
+
+    if exec == 'xlsx':
+        # If path is a remote URL, fetch the file once and reuse the bytes
+        if path.lower().startswith(('http://', 'https://')):
+            path = path.replace("\\", "/")
+            with requests.Session() as session:
+                r = session.get(path)
+
+                if r.status_code != 200:
+                    raise Exception(f"HTTP {r.status_code} Error - {r.reason} > {path}")
+
+                data_bytes = r.content
+
+            # Use separate BytesIO objects for each read to avoid pointer/stream issues
+            df = read_excel(BytesIO(data_bytes), index_col=index_col)
+
+            try:
+                info = read_excel(BytesIO(data_bytes), sheet_name='metadata', index_col=0)
+                #print("\033[94m[metadata]\033[0m")
+                print()
+                from .util import hs_pretty_table
+                hs_pretty_table(info)
+                print()
+            except Exception:
+                #print(f"\033[91m[!] Cannot read metadata\033[0m")
+                pass
+        else:
+            df = read_excel(path, index_col=index_col)
+
+            try:
+                info = read_excel(path, sheet_name='metadata', index_col=0)
+                #print("\033[94m[metadata]\033[0m")
+                print()
+                from .util import hs_pretty_table
+                hs_pretty_table(info)
+                print()
+            except:
+                #print(f"\033[91m[!] Cannot read metadata\033[0m")
+                pass
+    else:
+        df = read_csv(path, index_col=index_col)
+
+    return df
+
+# -------------------------------------------------------------
+def __get_data_url(key: str, local: str = None) -> str:
+    global BASE_URL
+
+    path = None
+
+    if not local:
+        data_path = join(BASE_URL, "metadata.json").replace("\\", "/")
+
+        with requests.Session() as session:
+            r = session.get(data_path)
+
+            if r.status_code != 200:
+                raise Exception("[%d Error] %s" % (r.status_code, r.reason))
+
+        my_dict = r.json()
+        info = my_dict.get(key.lower())
+
+        if not info:
+            raise FileNotFoundError("%s는 존재하지 않는 데이터에 대한 요청입니다." % key)
+
+        path = join(BASE_URL, info['url'])
+    else:
+        data_path = join(local, "metadata.json")
+
+        if not exists(data_path):
+            raise FileNotFoundError("존재하지 않는 데이터에 대한 요청입니다.")
+
+        with open(data_path, "r", encoding="utf-8") as f:
+            my_dict = json.loads(f.read())
+
+        info = my_dict.get(key.lower())
+        path = join(local, info['url'])
+
+    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 컬럼을 갖는 테이블
+
+    Examples:
+        ```python
+        from hossam import *
+        info = load_info()
+        list(info.columns) #['name', 'chapter', 'desc', 'url']
+        ```
+    """
+    global BASE_URL
+
+    path = None
+
+    if not local:
+        data_path = join(BASE_URL, "metadata.json").replace("\\", "/")
+
+        with requests.Session() as session:
+            r = session.get(data_path)
+
+            if r.status_code != 200:
+                raise Exception("[%d Error] %s ::: %s" % (r.status_code, r.reason, data_path))
+
+        my_dict = r.json()
+    else:
+        data_path = join(local, "metadata.json")
+
+        if not exists(data_path):
+            raise FileNotFoundError("존재하지 않는 데이터에 대한 요청입니다.")
+
+        with open(data_path, "r", encoding="utf-8") as f:
+            my_dict = json.loads(f.read())
+
+    my_data = []
+    for key in my_dict:
+        if 'index' in my_dict[key]:
+            del my_dict[key]['index']
+
+        my_dict[key]['url'] = "%s/%s" % (BASE_URL, my_dict[key]['url'])
+        my_dict[key]['name'] = key
+
+        if 'chapter' in my_dict[key]:
+            my_dict[key]['chapter'] = ", ".join(my_dict[key]['chapter'])
+        else:
+            my_dict[key]['chapter'] = '공통'
+
+        my_data.append(my_dict[key])
+
+    my_df = DataFrame(my_data)
+    my_df2 = my_df.reindex(columns=['name', 'chapter', 'desc', 'url'])
+
+    if search:
+        my_df2 = my_df2[my_df2['name'].str.contains(search.lower())]
+
+    return my_df2
+
+# -------------------------------------------------------------
+def load_data(key: str, local: str = None) -> Optional[DataFrame]:
+    """키로 지정된 데이터셋을 로드한다.
+
+    Args:
+        key (str): 메타데이터에 정의된 데이터 식별자(파일명 또는 별칭)
+        local (str, optional): 로컬 메타데이터 경로. None이면 원격(BASE_URL) 사용.
+
+    Returns:
+        DataFrame | None: 성공 시 데이터프레임, 실패 시 None
+
+    Examples:
+        ```python
+        from hossam import *
+        df = load_data('AD_SALES')  # 메타데이터에 해당 키가 있어야 함
+        ```
+    """
+    index = None
+    try:
+        url, desc, index = __get_data_url(key, local=local)
+    except Exception as e:
+        try:
+            print(f"\033[91m{str(e)}\033[0m")
+        except Exception:
+            print(e)
+        return
+
+    #print("\033[94m[data]\033[0m", url.replace("\\", "/"))
+    #print("\033[94m[desc]\033[0m", desc)
+    print(f"\033[94m{desc}\033[0m")
+
+    df = None
+
+    try:
+        df = __get_df(url, index_col=index)
+    except Exception as e:
+        try:
+            print(f"\033[91m{str(e)}\033[0m")
+        except Exception:
+            print(e)
+        return
+
+
+    return df