Metadata-Version: 2.4
Name: echoss-common
Version: 1.0.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>6.0.2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# echoss-common

echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
로깅(Logger)과 파일 포맷(FileUtil) 기능을 제공합니다.

## 설치

```bash
pip install echoss-common
```

## 요구사항

- Python >= 3.12
- pyyaml > 6.0.2

---

## 기능

### 1. Logger (`echoss_logger`)

타임드 로테이팅 파일 핸들러와 콘솔 핸들러를 지원하는 로거 유틸리티입니다.

#### 함수 목록

| 함수 | 설명 |
|------|------|
| `get_logger()` | 새 로거 생성 또는 기존 로거 갱신 |
| `use_logger()` | 이미 생성된 로거를 서브모듈에서 가져오기 |
| `set_logger_level()` | 로거 레벨 변경 |
| `modify_loggers_by_prefix()` | 이름 prefix로 여러 로거를 일괄 수정 |

#### 상수

| 상수 | 값 |
|------|----|
| `LOG_FORMAT_DETAIL` | `[날짜시간] 레벨 모듈.함수.라인 : 메시지` 형식 |

#### 사용 예시

```python
from echoss_common import get_logger, use_logger, set_logger_level, modify_loggers_by_prefix, LOG_FORMAT_DETAIL

# 기본 로거 생성 (콘솔 + 파일 출력)
logger = get_logger(
    logger_name='myapp',
    logger_format=LOG_FORMAT_DETAIL,   # 상세 포맷 사용 (선택)
    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: logs/echoss.log)
    backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
    use_console=True,                  # 콘솔 출력 여부
    level='DEBUG'                      # 로그 레벨
)

logger.info("애플리케이션 시작")
logger.debug("디버그 메시지")
logger.error("오류 발생")

# 서브모듈에서 기존 로거 재사용
logger = use_logger('myapp')
logger.info("서브모듈에서 로거 사용")

# 로거 레벨만 변경
set_logger_level(logger, 'WARNING')

# prefix로 시작하는 모든 로거 일괄 수정
modify_loggers_by_prefix(
    prefix='myapp',
    new_format=LOG_FORMAT_DETAIL,
    new_path='logs/myapp.log',
    level='INFO'
)
```

---

### 2. FileUtil (`fileformat`)

설정 파일(YAML, JSON, XML, Properties)을 딕셔너리로 읽고 쓰는 유틸리티 클래스입니다.

#### 메서드 목록

| 메서드 | 설명 |
|--------|------|
| `FileUtil.dict_load()` | 설정 파일을 `dict`로 읽기 |
| `FileUtil.dict_dump()` | `dict`를 설정 파일로 쓰기 |

#### 지원 포맷

| 확장자 | 포맷 |
|--------|------|
| `.yaml`, `.yml` | YAML |
| `.json` | JSON |
| `.xml` | XML |
| `.properties` | Java Properties |

#### 사용 예시

```python
from echoss_common.fileformat import FileUtil

# YAML 파일 읽기
config = FileUtil.dict_load('config/settings.yaml')
print(config)

# JSON 파일 읽기
data = FileUtil.dict_load('config/params.json')

# Properties 파일 읽기
props = FileUtil.dict_load('config/app.properties')

# dict를 YAML 파일로 저장
settings = {'host': 'localhost', 'port': 8080, 'debug': True}
FileUtil.dict_dump(settings, 'config/settings.yaml')

# dict를 JSON 파일로 저장 (들여쓰기 지정 가능)
FileUtil.dict_dump(settings, 'config/settings.json', indent=2)

# 파일이 이미 존재할 때 덮어쓰기 방지
FileUtil.dict_dump(settings, 'config/settings.yaml', force_write=False)
```

---

## API 참조

### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`

| 파라미터 | 타입 | 기본값 | 설명 |
|----------|------|--------|------|
| `logger_name` | str | `'echoss'` | 로거 이름 |
| `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 (`None`이면 파일 미사용) |
| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
| `use_console` | bool | `True` | 콘솔 출력 여부 |
| `level` | str\|int | `'DEBUG'` | 로그 레벨 |

### `FileUtil.dict_load(file_path, file_format, **kwargs)`

| 파라미터 | 타입 | 기본값 | 설명 |
|----------|------|--------|------|
| `file_path` | str | — | 읽을 파일 경로 |
| `file_format` | str | `None` | 포맷 강제 지정 (미지정 시 확장자 자동 인식) |

### `FileUtil.dict_dump(config, file_path, file_format, force_write, xml_tag, **kwargs)`

| 파라미터 | 타입 | 기본값 | 설명 |
|----------|------|--------|------|
| `config` | dict | — | 저장할 딕셔너리 |
| `file_path` | str | — | 저장할 파일 경로 |
| `file_format` | str | `None` | 포맷 강제 지정 (미지정 시 확장자 자동 인식) |
| `force_write` | bool | `True` | 기존 파일 덮어쓰기 여부 |
| `xml_tag` | str | `None` | XML 저장 시 루트 태그 이름 |

---

## 라이선스

echoss AI Bigdata Center
