Metadata-Version: 2.4
Name: common-hj3415
Version: 0.2.3
Summary: Shared tools for hj3415 projects
Keywords: example,demo
Author-email: Hyungjin Kim <hj3415@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: contracts-hj3415

# common-hj3415 README

`common-hj3415`는 프로젝트 간 공통으로 사용하는 경량 유틸리티 라이브러리입니다.  
문자열 정리, 숫자 변환, 시간 정규화, 딕셔너리 일부 추출 같은 반복 로직을 한 곳에 모아 재사용할 수 있게 제공합니다.

`pyproject.toml` 기준 정보:
- 패키지명: `common-hj3415`
- 버전: `0.2.2`
- Python: `>=3.11`
- 빌드 백엔드: `flit_core`
- 의존성: `contracts-hj3415`

## 1. 프로젝트 기능 설명

이 프로젝트는 비즈니스 로직 패키지가 아니라 “공통 도구 모음” 역할을 합니다.

주요 기능:
- 문자열 정규화: `clean_text`
  - `None -> ""`
  - NBSP 제거
  - 연속 공백 축소
- 숫자 처리: `to_float`, `parse_number_token`, `nan_to_none`
- 시간 처리: `utcnow`, `to_utc`
- 디버깅/출력 보조: `head_dict`

이런 유틸을 공통 패키지로 분리하면, 여러 프로젝트에서 동일한 데이터 정리 규칙을 유지하기 쉽습니다.

## 2. 프로젝트 구조 설명

```text
common-hj3415/
├─ pyproject.toml
└─ src/common_hj3415/
   ├─ utils/
   │  ├─ strings.py   # clean_text
   │  ├─ numbers.py   # to_float, parse_number_token, nan_to_none
   │  ├─ time.py      # utcnow, to_utc
   │  └─ etc.py       # head_dict
   ├─ domain/         # 현재는 빈 스켈레톤(확장용)
   └─ py.typed
```

`utils`는 실제 사용 코드가 들어 있고, `domain`은 향후 공통 도메인 규칙 확장을 위한 자리입니다.

## 3. 다른 프로젝트에서 임포트해서 사용하는 예시

설치:

```bash
python -m pip install common-hj3415
```

문자열/숫자/시간 유틸 사용 예시:

```python
from datetime import datetime

from common_hj3415.utils.numbers import to_float
from common_hj3415.utils.strings import clean_text
from common_hj3415.utils.time import to_utc

name = clean_text("  삼성전자\xa0 ")
price = to_float("1,234.50")
asof = to_utc(datetime(2026, 3, 29, 12, 0, 0))

print(name)   # "삼성전자"
print(price)  # 1234.5
print(asof)   # 2026-03-29 12:00:00+00:00
```

딕셔너리 일부만 출력할 때:

```python
from common_hj3415.utils.etc import head_dict

d = {"a": 1, "b": 2, "c": 3, "d": 4}
print(head_dict(d, n=2))  # {"a": 1, "b": 2}
```

## 4. 참고 사항

- 이 패키지는 **CLI를 제공하지 않는 라이브러리**입니다.
- 현재 코드 기준으로 별도 환경변수 설정이 필요하지 않습니다.
- 단독 실행 서비스가 아니므로 Docker 실행 섹션은 포함하지 않았습니다.

