Metadata-Version: 2.4
Name: jussam
Version: 0.5.17
Summary: Jussam Data Helper
Author-email: Ju YoungA <j.purplerose@gmail.com>
License-Expression: MIT
Keywords: data,analysis,helper,jussam,pandas,geopandas
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.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: geopandas
Requires-Dist: requests
Requires-Dist: tabulate
Dynamic: license-file

# 🎓 Jussam Data Helper

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/jussam.svg)](https://pypi.org/project/jussam/)

**jussam**은 학습용 샘플 데이터셋을 키(key) 하나로 간편하게 불러오기 위한 데이터 헬퍼 라이브러리입니다.

연세대학교 주영아 교수의 머신러닝 및 데이터 분석 수업을 위해 개발되었습니다.

## ✨ 주요 특징

- 📦 **원클릭 데이터 로드**: 데이터셋 키만으로 원격(또는 로컬) 데이터셋을 즉시 `DataFrame`으로 로드
- 🗂️ **다양한 포맷 지원**: CSV, Excel(xlsx/xls), Parquet, JSON, Shapefile(shp), ZIP 압축 파일
- 📝 **메타데이터 출력**: 로드 시 데이터 설명과 필드 정보를 표 형태로 함께 표시

## 📦 설치

```bash
pip install --upgrade jussam
```

**요구사항**: Python 3.11 이상

## 🚀 사용법

### 데이터 로드

```python
import jussam

# 메타데이터에 정의된 키로 데이터셋 로드 (설명/메타정보가 함께 출력됩니다)
df = jussam.load_data("AD_SALES")
df.head()
```

`load_data`의 시그니처는 다음과 같습니다.

```python
load_data(key: str, local: str | None = None, view_url: bool = False) -> DataFrame | None
```

| 매개변수 | 설명 |
| --- | --- |
| `key` | 메타데이터에 정의된 데이터 식별자(파일명 또는 별칭) |
| `local` | 로컬 메타데이터 경로. `None`이면 원격 저장소를 사용합니다. |
| `view_url` | `True`이면 데이터의 실제 URL을 함께 출력합니다. |

```python
# 데이터 URL도 함께 확인
df = jussam.load_data("AD_SALES", view_url=True)

# 로컬 metadata.json 경로를 사용
df = jussam.load_data("AD_SALES", local="./data")
```

### 표 출력 유틸리티

`my_util` 서브모듈은 `DataFrame`을 보기 좋게 출력하는 헬퍼를 제공합니다.

```python
from jussam import my_util
from pandas import DataFrame

my_util.pretty_table(DataFrame({"a": [1, 2], "b": [3, 4]}))
```

## 📬 문의

- 👩‍🏫 주영아 (연세대학교)
- 📧 Email: j.purplerose@yonsei.ac.kr / j.purplerose@gmail.com
- 📝 Website: <https://juyounga.kr/>

## 📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
