echoss-common 1.2.0__tar.gz → 2.0.1__tar.gz

{echoss_common-1.2.0/echoss_common.egg-info → echoss_common-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 1.2.0
+Version: 2.0.1
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -18,6 +18,11 @@ Dynamic: license-file
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
 로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
 
+## 문서 지도
+
+- [`prior-work.jsonl`](prior-work.jsonl) — 작업원장. 이전 작업의 결론·이미 해본 것·백로그 (조사 착수 전 조회)
+- [`docs/`](docs/) — PDCA 계획·설계·분석 문서
+
 ## 설치
 
 ```bash
@@ -29,6 +34,23 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 2.0.0 변경 사항
+
+호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
+
+| 바뀐 것 | 1.2.0 | 2.0.0 | 대응 |
+|---|---|---|---|
+| 기본 로그 파일 | `file_path` 를 주지 않으면 `logs/echoss.log` 에 기록 | 파일을 만들지 않고 콘솔만 | 파일 로그가 필요하면 `file_path` 를 지정 (`modify_loggers_by_prefix` 는 `new_path`) |
+| 없는 설정 파일 | `dict_load` 가 오류 로그를 남기고 빈 dict 반환 | `FileNotFoundError` | 경로를 확인하거나 예외를 처리 |
+| YAML 저장 키 순서 | 키를 정렬해 저장 | 넣은 순서대로 저장 | — |
+| 설정 파일 인코딩 | 운영체제 기본 인코딩(Windows 는 CP949 등) | 항상 UTF-8 로 읽고 씀 | UTF-8 이 아닌 설정 파일은 UTF-8 로 변환 |
+
+그 밖의 변경:
+
+- `import echoss_common` 이 더 이상 파일이나 폴더를 만들지 않습니다(1.2.0 은 import 만으로 `logs/echoss.log` 를 만들어, 쓰기 금지 폴더에서는 import 가 실패했습니다).
+- 로그 회전은 Windows 에서 다른 프로세스가 로그 파일을 열고 있어도 기록을 잃지 않습니다(아래 「로그 회전」).
+- 지원하지 않는 형식을 읽으면 호출마다 새 빈 dict 를 돌려줍니다(1.2.0 은 같은 dict 객체를 공유했습니다).
+
 ---
 
 ## 기능
@@ -63,7 +85,7 @@ from echoss_common import get_logger, get_app_logger, use_logger, set_logger_lev
 logger = get_logger(
     logger_name='myapp',
     logger_format=LOG_FORMAT_DETAIL,   # 상세 포맷 사용 (선택)
-    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: logs/echoss.log)
+    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
     level='DEBUG'                      # 로그 레벨
@@ -92,6 +114,14 @@ modify_loggers_by_prefix(
 )
 ```
 
+#### 로그 회전
+
+파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+
 #### JsonLogDict 사용 예시
 
 로그 메시지에 dict, list 등 복잡한 데이터를 JSON 형태로 출력할 때 사용합니다.
@@ -169,6 +199,11 @@ XML을 읽을 때는 문서의 루트 태그를 포함한 딕셔너리를 반환
 반복 요소는 리스트로 표현합니다. XML을 쓸 때는 `xml_tag`를 지정하거나 딕셔너리에 루트 키가
 하나 있어야 합니다.
 
+- 파일은 항상 UTF-8 로 읽고 씁니다(XML 은 문서 선언을 따릅니다).
+- 없는 파일을 읽으면 `FileNotFoundError` 가 납니다. 지원하지 않는 형식은 파일을 열지 않고 오류 로그와 함께 빈 dict 를 돌려줍니다.
+- JSON 파일의 최상위가 배열이면 `list` 를 반환합니다.
+- YAML 로 저장할 때 키 순서를 유지합니다.
+
 #### 사용 예시
 
 ```python
@@ -209,7 +244,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 (`None`이면 파일 미사용) |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -222,7 +257,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -243,6 +278,8 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `file_path` | str | — | 읽을 파일 경로 |
 | `file_format` | str | `None` | 포맷 강제 지정 (미지정 시 확장자 자동 인식) |
 
+반환은 `dict` 입니다(JSON 최상위가 배열이면 `list`). 파일이 없으면 `FileNotFoundError` 를 냅니다.
+
 ### `dict_dump(config, file_path, file_format, force_write, xml_tag, **kwargs)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |

{echoss_common-1.2.0 → echoss_common-2.0.1}/README.md

@@ -3,6 +3,11 @@
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
 로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
 
+## 문서 지도
+
+- [`prior-work.jsonl`](prior-work.jsonl) — 작업원장. 이전 작업의 결론·이미 해본 것·백로그 (조사 착수 전 조회)
+- [`docs/`](docs/) — PDCA 계획·설계·분석 문서
+
 ## 설치
 
 ```bash
@@ -14,6 +19,23 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 2.0.0 변경 사항
+
+호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
+
+| 바뀐 것 | 1.2.0 | 2.0.0 | 대응 |
+|---|---|---|---|
+| 기본 로그 파일 | `file_path` 를 주지 않으면 `logs/echoss.log` 에 기록 | 파일을 만들지 않고 콘솔만 | 파일 로그가 필요하면 `file_path` 를 지정 (`modify_loggers_by_prefix` 는 `new_path`) |
+| 없는 설정 파일 | `dict_load` 가 오류 로그를 남기고 빈 dict 반환 | `FileNotFoundError` | 경로를 확인하거나 예외를 처리 |
+| YAML 저장 키 순서 | 키를 정렬해 저장 | 넣은 순서대로 저장 | — |
+| 설정 파일 인코딩 | 운영체제 기본 인코딩(Windows 는 CP949 등) | 항상 UTF-8 로 읽고 씀 | UTF-8 이 아닌 설정 파일은 UTF-8 로 변환 |
+
+그 밖의 변경:
+
+- `import echoss_common` 이 더 이상 파일이나 폴더를 만들지 않습니다(1.2.0 은 import 만으로 `logs/echoss.log` 를 만들어, 쓰기 금지 폴더에서는 import 가 실패했습니다).
+- 로그 회전은 Windows 에서 다른 프로세스가 로그 파일을 열고 있어도 기록을 잃지 않습니다(아래 「로그 회전」).
+- 지원하지 않는 형식을 읽으면 호출마다 새 빈 dict 를 돌려줍니다(1.2.0 은 같은 dict 객체를 공유했습니다).
+
 ---
 
 ## 기능
@@ -48,7 +70,7 @@ from echoss_common import get_logger, get_app_logger, use_logger, set_logger_lev
 logger = get_logger(
     logger_name='myapp',
     logger_format=LOG_FORMAT_DETAIL,   # 상세 포맷 사용 (선택)
-    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: logs/echoss.log)
+    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
     level='DEBUG'                      # 로그 레벨
@@ -77,6 +99,14 @@ modify_loggers_by_prefix(
 )
 ```
 
+#### 로그 회전
+
+파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+
 #### JsonLogDict 사용 예시
 
 로그 메시지에 dict, list 등 복잡한 데이터를 JSON 형태로 출력할 때 사용합니다.
@@ -154,6 +184,11 @@ XML을 읽을 때는 문서의 루트 태그를 포함한 딕셔너리를 반환
 반복 요소는 리스트로 표현합니다. XML을 쓸 때는 `xml_tag`를 지정하거나 딕셔너리에 루트 키가
 하나 있어야 합니다.
 
+- 파일은 항상 UTF-8 로 읽고 씁니다(XML 은 문서 선언을 따릅니다).
+- 없는 파일을 읽으면 `FileNotFoundError` 가 납니다. 지원하지 않는 형식은 파일을 열지 않고 오류 로그와 함께 빈 dict 를 돌려줍니다.
+- JSON 파일의 최상위가 배열이면 `list` 를 반환합니다.
+- YAML 로 저장할 때 키 순서를 유지합니다.
+
 #### 사용 예시
 
 ```python
@@ -194,7 +229,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 (`None`이면 파일 미사용) |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -207,7 +242,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -228,6 +263,8 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `file_path` | str | — | 읽을 파일 경로 |
 | `file_format` | str | `None` | 포맷 강제 지정 (미지정 시 확장자 자동 인식) |
 
+반환은 `dict` 입니다(JSON 최상위가 배열이면 `list`). 파일이 없으면 `FileNotFoundError` 를 냅니다.
+
 ### `dict_dump(config, file_path, file_format, force_write, xml_tag, **kwargs)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |

{echoss_common-1.2.0 → echoss_common-2.0.1}/echoss_common/config_fileformat.py

@@ -4,14 +4,13 @@
 import configparser
 import io
 import json
+import logging
 import os
 import xml.etree.ElementTree as ET
 import yaml
 
-from echoss_common import get_logger
-
-logger = get_logger("echoss_fileformat")
-EMPTY_DICT = dict()
+# no handler here: importing must not create files (echoss-fileformat attaches handlers to this name)
+logger = logging.getLogger("echoss_fileformat")
 
 
 def _xml_element_to_dict(element: ET.Element) -> dict:
@@ -74,21 +73,20 @@ def dict_load(file_path: str, file_format: str | None = None, **kwargs) -> dict:
         file_format : file extension name to read
         kwargs : keyword arguments
     Return:
-        dict
+        dict (list if a json file's top level is an array)
+    Raises:
+        FileNotFoundError: if file_path does not exist (an unsupported format returns {} without opening the file)
     """
     if file_format is None:
         _, ext = os.path.splitext(file_path)
         file_format = ext[1:].lower() if ext else None
-    if not os.path.exists(file_path):
-        logger.error(f"load config file [{file_path}] is not exist")
-        return EMPTY_DICT
 
     if "yaml" == file_format or "yml" == file_format :
-        with open(file_path, 'r') as f:
+        with open(file_path, 'r', encoding='utf-8') as f:
             yaml_dict = yaml.safe_load(f)
             return yaml_dict
     elif "json" == file_format:
-        with open(file_path, 'r') as f:
+        with open(file_path, 'r', encoding='utf-8') as f:
             return json.load(f, **kwargs)
     elif "xml" == file_format:
         root = ET.parse(file_path).getroot()
@@ -96,7 +94,7 @@ def dict_load(file_path: str, file_format: str | None = None, **kwargs) -> dict:
     elif 'properties' == file_format:
         config = configparser.ConfigParser()
         properties_dict = {}
-        with open(file_path, 'r') as f:
+        with open(file_path, 'r', encoding='utf-8') as f:
             file_content = f.read()
             if not file_content.strip().startswith('['):
                 file_content = '[DEFAULT]\n' + file_content
@@ -111,7 +109,7 @@ def dict_load(file_path: str, file_format: str | None = None, **kwargs) -> dict:
         return properties_dict
     else:
         logger.error(f"Unsupported file format [{file_format}]")
-        return EMPTY_DICT
+        return {}
 
 def dict_dump(config: dict, file_path: str, file_format: str | None = None, force_write: bool = True, xml_tag: str | None = None, **kwargs):
     """config dict write to file
@@ -133,10 +131,10 @@ def dict_dump(config: dict, file_path: str, file_format: str | None = None, forc
         return
 
     if "yaml" == file_format or "yml" == file_format :
-        with open(file_path, 'w') as f:
-            yaml.dump(config, f, default_style=False, allow_unicode=True)
+        with open(file_path, 'w', encoding='utf-8') as f:
+            yaml.dump(config, f, default_style=False, allow_unicode=True, sort_keys=False)
     elif "json" == file_format:
-        with open(file_path, 'w') as f:
+        with open(file_path, 'w', encoding='utf-8') as f:
             indent = kwargs.pop('indent', 4)
             json.dump(config, f, indent=indent, **kwargs)
     elif "xml" == file_format:
@@ -165,7 +163,7 @@ def dict_dump(config: dict, file_path: str, file_format: str | None = None, forc
             # parser.add_section('DEFAULT')
             for k, v in config.items():
                 parser.set('DEFAULT', k, str(v))
-        with open(file_path, 'w') as f:
+        with open(file_path, 'w', encoding='utf-8') as f:
             if have_section:
                 parser.write(f)
             else:

{echoss_common-1.2.0 → echoss_common-2.0.1}/echoss_common/echoss_logger.py

@@ -1,7 +1,9 @@
 import json
 import logging
 import os
+import shutil
 import sys
+import time
 from collections.abc import Mapping
 from functools import cache
 from logging import StreamHandler
@@ -50,6 +52,56 @@ class JsonLineFormatter(logging.Formatter):
         return json.dumps(payload, ensure_ascii=False, default=str)
 
 
+# Windows cannot rename a file another handle keeps open, so a replaced stream only arises
+# there through copy-truncate, which keeps the inode. Keep the 2.0.0 behaviour on Windows.
+_STALE_STREAM_CHECK = os.name != "nt"
+
+
+# True when another handler already rotated the file this handler is still writing to.
+def _stream_replaced(handler) -> bool:
+    if not _STALE_STREAM_CHECK or handler.stream is None:
+        return False
+    try:
+        mine = os.fstat(handler.stream.fileno())
+        disk = os.stat(handler.baseFilename)
+    except OSError:
+        return False
+    return (mine.st_dev, mine.st_ino) != (disk.st_dev, disk.st_ino)
+
+
+# On Windows, renaming a log file that another handle keeps open fails with PermissionError (WinError 32).
+# Fall back to copy-then-truncate so no record is lost, and always move rolloverAt forward.
+class CopyTruncateRotatingHandler(TimedRotatingFileHandler):
+    def rotate(self, source, dest):
+        if not os.path.exists(source):
+            return
+        try:
+            os.rename(source, dest)
+            return
+        except PermissionError:
+            pass
+        try:
+            # "x": another process already rotated into dest - do not overwrite
+            with open(dest, "xb") as out, open(source, "rb") as src:
+                shutil.copyfileobj(src, out)
+        except FileExistsError:
+            return
+        with open(source, "r+b") as f:
+            f.truncate(0)
+
+    def doRollover(self):
+        if _stream_replaced(self):
+            self.stream.close()
+            self.stream = None  # a failed _open() must leave None so the next emit reopens, as the stdlib does
+            self.stream = self._open()
+            self.rolloverAt = self.computeRollover(int(time.time()))
+            return
+        super().doRollover()
+        now = int(time.time())
+        if self.rolloverAt <= now:
+            self.rolloverAt = self.computeRollover(now)
+
+
 def _get_console_handler(formatter):
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setFormatter(formatter)
@@ -58,7 +110,7 @@ def _get_console_handler(formatter):
 
 
 def _get_file_handler(formatter, file_path, backup_count):
-    file_handler = TimedRotatingFileHandler(file_path, when="midnight", backupCount=backup_count, encoding='utf-8')
+    file_handler = CopyTruncateRotatingHandler(file_path, when="midnight", backupCount=backup_count, encoding='utf-8')
     file_handler.setFormatter(formatter)
     return file_handler
 
@@ -124,12 +176,12 @@ def use_logger(logger_name='echoss'):
 
 
 @cache
-def get_app_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=LOG_FILE, backup_count=0,
+def get_app_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=None, backup_count=0,
                    use_console=True, level="DEBUG"):
     return get_logger(logger_name, logger_format, file_path, backup_count, use_console, level)
 
 
-def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=LOG_FILE, backup_count=0,
+def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=None, backup_count=0,
                use_console=True, level="DEBUG"):
     """
     create new echoss logger or replace old logger
@@ -159,9 +211,10 @@ def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=LOG_FIL
     logger.propagate = False
 
     # make file_path parent directory
-    parent_dir = os.path.dirname(file_path)
-    if parent_dir:
-        os.makedirs(parent_dir, exist_ok=True)
+    if file_path is not None:
+        parent_dir = os.path.dirname(file_path)
+        if parent_dir:
+            os.makedirs(parent_dir, exist_ok=True)
 
     # 콘솔 핸들러 get 또는 생성
     console_handler = None
@@ -178,7 +231,11 @@ def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=LOG_FIL
     file_handler = _get_app_file_handler(logger_name)
 
     # Check if the existing handler path matches the current file_path
-    if file_handler is not None and os.path.abspath(file_handler.baseFilename) == os.path.abspath(file_path):
+    if file_path is None:
+        # no file logging: the cached file handler (if any) is removed below as unknown
+        file_handler = None
+        _logger_file_handler_cache.pop(logger_name, None)
+    elif file_handler is not None and os.path.abspath(file_handler.baseFilename) == os.path.abspath(file_path):
         file_handler.setFormatter(formatter)
     else:
         file_handler = _get_file_handler(formatter, file_path, backup_count)
@@ -221,7 +278,7 @@ def set_logger_level(logger, level):
     logger.setLevel(numeric_level)
 
 
-def modify_loggers_by_prefix(prefix, new_format: str = LOG_FORMAT, new_path: str = LOG_FILE,
+def modify_loggers_by_prefix(prefix, new_format: str = LOG_FORMAT, new_path: str | None = None,
                              backup_count: int = 0, use_console=True, level="DEBUG"):
     """
     Modify loggers that logger name starting with a specific prefix.

{echoss_common-1.2.0 → echoss_common-2.0.1/echoss_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 1.2.0
+Version: 2.0.1
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -18,6 +18,11 @@ Dynamic: license-file
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
 로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
 
+## 문서 지도
+
+- [`prior-work.jsonl`](prior-work.jsonl) — 작업원장. 이전 작업의 결론·이미 해본 것·백로그 (조사 착수 전 조회)
+- [`docs/`](docs/) — PDCA 계획·설계·분석 문서
+
 ## 설치
 
 ```bash
@@ -29,6 +34,23 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 2.0.0 변경 사항
+
+호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
+
+| 바뀐 것 | 1.2.0 | 2.0.0 | 대응 |
+|---|---|---|---|
+| 기본 로그 파일 | `file_path` 를 주지 않으면 `logs/echoss.log` 에 기록 | 파일을 만들지 않고 콘솔만 | 파일 로그가 필요하면 `file_path` 를 지정 (`modify_loggers_by_prefix` 는 `new_path`) |
+| 없는 설정 파일 | `dict_load` 가 오류 로그를 남기고 빈 dict 반환 | `FileNotFoundError` | 경로를 확인하거나 예외를 처리 |
+| YAML 저장 키 순서 | 키를 정렬해 저장 | 넣은 순서대로 저장 | — |
+| 설정 파일 인코딩 | 운영체제 기본 인코딩(Windows 는 CP949 등) | 항상 UTF-8 로 읽고 씀 | UTF-8 이 아닌 설정 파일은 UTF-8 로 변환 |
+
+그 밖의 변경:
+
+- `import echoss_common` 이 더 이상 파일이나 폴더를 만들지 않습니다(1.2.0 은 import 만으로 `logs/echoss.log` 를 만들어, 쓰기 금지 폴더에서는 import 가 실패했습니다).
+- 로그 회전은 Windows 에서 다른 프로세스가 로그 파일을 열고 있어도 기록을 잃지 않습니다(아래 「로그 회전」).
+- 지원하지 않는 형식을 읽으면 호출마다 새 빈 dict 를 돌려줍니다(1.2.0 은 같은 dict 객체를 공유했습니다).
+
 ---
 
 ## 기능
@@ -63,7 +85,7 @@ from echoss_common import get_logger, get_app_logger, use_logger, set_logger_lev
 logger = get_logger(
     logger_name='myapp',
     logger_format=LOG_FORMAT_DETAIL,   # 상세 포맷 사용 (선택)
-    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: logs/echoss.log)
+    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
     level='DEBUG'                      # 로그 레벨
@@ -92,6 +114,14 @@ modify_loggers_by_prefix(
 )
 ```
 
+#### 로그 회전
+
+파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+
 #### JsonLogDict 사용 예시
 
 로그 메시지에 dict, list 등 복잡한 데이터를 JSON 형태로 출력할 때 사용합니다.
@@ -169,6 +199,11 @@ XML을 읽을 때는 문서의 루트 태그를 포함한 딕셔너리를 반환
 반복 요소는 리스트로 표현합니다. XML을 쓸 때는 `xml_tag`를 지정하거나 딕셔너리에 루트 키가
 하나 있어야 합니다.
 
+- 파일은 항상 UTF-8 로 읽고 씁니다(XML 은 문서 선언을 따릅니다).
+- 없는 파일을 읽으면 `FileNotFoundError` 가 납니다. 지원하지 않는 형식은 파일을 열지 않고 오류 로그와 함께 빈 dict 를 돌려줍니다.
+- JSON 파일의 최상위가 배열이면 `list` 를 반환합니다.
+- YAML 로 저장할 때 키 순서를 유지합니다.
+
 #### 사용 예시
 
 ```python
@@ -209,7 +244,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 (`None`이면 파일 미사용) |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -222,7 +257,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 |----------|------|--------|------|
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
-| `file_path` | str | `'logs/echoss.log'` | 로그 파일 경로 |
+| `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
@@ -243,6 +278,8 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `file_path` | str | — | 읽을 파일 경로 |
 | `file_format` | str | `None` | 포맷 강제 지정 (미지정 시 확장자 자동 인식) |
 
+반환은 `dict` 입니다(JSON 최상위가 배열이면 `list`). 파일이 없으면 `FileNotFoundError` 를 냅니다.
+
 ### `dict_dump(config, file_path, file_format, force_write, xml_tag, **kwargs)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |

{echoss_common-1.2.0 → echoss_common-2.0.1}/echoss_common.egg-info/SOURCES.txt

@@ -11,7 +11,12 @@ echoss_common.egg-info/dependency_links.txt
 echoss_common.egg-info/requires.txt
 echoss_common.egg-info/top_level.txt
 tests/test_config_fileformat.py
+tests/test_config_fileformat_2x.py
 tests/test_echoss_logger_1.py
 tests/test_echoss_logger_2.py
+tests/test_echoss_logger_2x.py
 tests/test_echoss_logger_json.py
+tests/scripts/check_xml_samples.py
+tests/scripts/hold_file.py
+tests/scripts/spike_default_log_file.py
 tests/scripts/verify_xml_edge_cases.py

{echoss_common-1.2.0 → echoss_common-2.0.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 # 패키지 메타데이터
 [project]
 name="echoss-common"
-version="1.2.0"
+version="2.0.1"
 description="echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)"
 readme = "README.md"
 license = "Apache-2.0"

echoss_common-2.0.1/tests/scripts/check_xml_samples.py

@@ -0,0 +1,38 @@
+#!/home/ubuntu/miniconda3/envs/index_rag/bin/python
+"""Load echoss-fileformat sample XML files with echoss_common.dict_load.
+
+Checks that no non-string key (e.g. a comment node function) appears in the result.
+Usage: check_xml_samples.py <xml file> [<xml file> ...]
+"""
+import sys
+
+from echoss_common import dict_load
+
+
+def non_str_keys(value, path="$"):
+    found = []
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if not isinstance(key, str):
+                found.append(f"{path}: {key!r}")
+            found.extend(non_str_keys(child, f"{path}.{key}"))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            found.extend(non_str_keys(item, f"{path}[{index}]"))
+    return found
+
+
+failed = False
+for file_path in sys.argv[1:]:
+    try:
+        result = dict_load(file_path)
+    except Exception as exc:
+        failed = True
+        print(f"FAIL {file_path}: {type(exc).__name__} {exc}")
+        continue
+    bad = non_str_keys(result)
+    root = next(iter(result)) if result else None
+    print(f"{'FAIL' if bad else 'OK  '} {file_path}: root={root!r} non_str_keys={bad}")
+    failed = failed or bool(bad)
+
+sys.exit(1 if failed else 0)

echoss_common-2.0.1/tests/scripts/hold_file.py

@@ -0,0 +1,11 @@
+#!/home/ubuntu/miniconda3/envs/index_rag/bin/python
+"""Keep a file open (read handle) until stdin is closed.
+
+Used by tests as the "second process" that holds a log file during rotation.
+Usage: hold_file.py <path>
+"""
+import sys
+
+with open(sys.argv[1], "rb"):
+    print("ready", flush=True)
+    sys.stdin.read()

echoss_common-2.0.1/tests/scripts/spike_default_log_file.py

@@ -0,0 +1,34 @@
+#!/home/ubuntu/miniconda3/envs/index_rag/bin/python
+"""Spike: does importing/declaring echoss logger create logs/echoss.log in the CWD?
+
+Run from an empty directory with PYTHONPATH pointing at the repo root.
+"""
+import os
+import sys
+
+
+def exists_default():
+    return os.path.exists(os.path.join("logs", "echoss.log"))
+
+
+print("cwd:", os.getcwd())
+print("1 before import, logs/echoss.log exists:", exists_default())
+
+import echoss_common  # noqa: E402
+
+print("2 after `import echoss_common`, exists:", exists_default())
+
+from echoss_common import get_logger  # noqa: E402
+
+logger = get_logger("myapp", file_path="custom/my.log")
+logger.info("hello")
+print("3 after get_logger(file_path='custom/my.log'), default exists:", exists_default(),
+      "| custom exists:", os.path.exists("custom/my.log"))
+
+try:
+    get_logger("nofile", file_path=None)
+    print("4 get_logger(file_path=None): OK")
+except Exception as exc:
+    print("4 get_logger(file_path=None) raised:", type(exc).__name__, exc)
+
+sys.exit(0)

echoss_common-2.0.1/tests/test_config_fileformat_2x.py

@@ -0,0 +1,56 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from echoss_common import dict_dump, dict_load
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+KOREAN = {"이름": "홍길동", "설명": {"지역": "서울"}}
+
+
+# T-10
+@pytest.mark.parametrize("file_name, text", [
+    ("ko.yaml", "이름: 홍길동\n설명:\n  지역: 서울\n"),
+    ("ko.json", json.dumps(KOREAN, ensure_ascii=False)),
+])
+def test_dict_load_reads_utf8_regardless_of_locale(tmp_path, file_name, text):
+    path = tmp_path / file_name
+    path.write_bytes(text.encode("utf-8"))
+    # non-UTF-8 default encoding: Windows ANSI code page, or the C locale without coercion on Linux
+    env = dict(os.environ, PYTHONPATH=str(REPO_ROOT), PYTHONUTF8="0", PYTHONCOERCECLOCALE="0", LC_ALL="C")
+    code = "import json, sys; from echoss_common import dict_load; print(json.dumps(dict_load(sys.argv[1])))"
+
+    result = subprocess.run([sys.executable, "-c", code, str(path)], env=env, capture_output=True, text=True)
+
+    assert result.returncode == 0, result.stderr
+    assert json.loads(result.stdout) == KOREAN
+
+
+# T-11
+def test_empty_result_is_a_new_dict_each_call(tmp_path):
+    first = dict_load(str(tmp_path / "a.unknown"))
+    first["x"] = 1
+
+    second = dict_load(str(tmp_path / "b.unknown"))
+
+    assert second == {}
+
+
+# T-12
+def test_dict_dump_yaml_keeps_key_order(tmp_path):
+    path = tmp_path / "order.yaml"
+
+    dict_dump({"이름": 1, "b": 2, "a": 3}, str(path))
+
+    assert list(dict_load(str(path))) == ["이름", "b", "a"]
+
+
+# T-13
+@pytest.mark.parametrize("ext", ["yaml", "json", "xml", "properties"])
+def test_dict_load_missing_file_raises(tmp_path, ext):
+    with pytest.raises(FileNotFoundError):
+        dict_load(str(tmp_path / f"missing.{ext}"))

echoss_common-2.0.1/tests/test_echoss_logger_2x.py

@@ -0,0 +1,238 @@
+import inspect
+import logging
+import os
+import subprocess
+import sys
+import time
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+
+import pytest
+
+import echoss_common
+import echoss_common.echoss_logger as echoss_logger
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+HOLD_FILE = REPO_ROOT / "tests" / "scripts" / "hold_file.py"
+
+
+@pytest.fixture(autouse=True)
+def reset_logging_state():
+    def clear():
+        for cache_name in (
+            "_logger_cache",
+            "_logger_console_handler_cache",
+            "_logger_file_handler_cache",
+        ):
+            getattr(echoss_logger, cache_name).clear()
+        for logger in logging.Logger.manager.loggerDict.values():
+            if isinstance(logger, logging.Logger):
+                for handler in list(logger.handlers):
+                    logger.removeHandler(handler)
+                    handler.close()
+
+    clear()
+    yield
+    clear()
+
+
+def _run_python(code, cwd):
+    env = dict(os.environ, PYTHONPATH=str(REPO_ROOT))
+    return subprocess.run([sys.executable, "-c", code], cwd=cwd, env=env, capture_output=True, text=True)
+
+
+def _file_handlers(logger):
+    return [h for h in logger.handlers if isinstance(h, TimedRotatingFileHandler)]
+
+
+# T-01
+def test_import_creates_nothing(tmp_path):
+    result = _run_python("import echoss_common", tmp_path)
+
+    assert result.returncode == 0, result.stderr
+    assert list(tmp_path.iterdir()) == []
+
+
+# T-02
+@pytest.mark.skipif(sys.platform == "win32", reason="chmod does not make a directory read-only on Windows")
+@pytest.mark.skipif(hasattr(os, "geteuid") and os.geteuid() == 0, reason="root ignores directory permissions")
+def test_import_and_log_in_read_only_directory(tmp_path):
+    read_only = tmp_path / "ro"
+    read_only.mkdir()
+    read_only.chmod(0o555)
+    try:
+        result = _run_python(
+            "from echoss_common import get_logger; get_logger('x').info('hello')", read_only
+        )
+    finally:
+        read_only.chmod(0o755)
+
+    assert result.returncode == 0, result.stderr
+    assert list(read_only.iterdir()) == []
+
+
+# T-03
+@pytest.mark.parametrize("kwargs", [{}, {"file_path": None}])
+def test_no_file_path_means_console_only(tmp_path, monkeypatch, kwargs):
+    monkeypatch.chdir(tmp_path)
+
+    logger = echoss_logger.get_logger("console-only", **kwargs)
+    logger.info("hello")
+
+    assert _file_handlers(logger) == []
+    assert len(logger.handlers) == 1
+    assert list(tmp_path.iterdir()) == []
+
+
+# T-04
+def test_file_path_none_removes_existing_file_handler(tmp_path):
+    logger = echoss_logger.get_logger("switch", file_path=str(tmp_path / "switch.log"))
+    old_handler = _file_handlers(logger)[0]
+
+    logger = echoss_logger.get_logger("switch", file_path=None)
+
+    assert _file_handlers(logger) == []
+    assert old_handler.stream is None
+
+
+# T-05
+def test_explicit_file_path_creates_only_that_file(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+
+    logger = echoss_logger.get_logger("explicit", file_path="my.log")
+    logger.info("hello")
+
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["my.log"]
+    assert isinstance(_file_handlers(logger)[0], echoss_logger.CopyTruncateRotatingHandler)
+
+
+# T-06
+def test_rotation_keeps_every_record_while_another_process_holds_the_file(tmp_path):
+    log_file = tmp_path / "held.log"
+    handler = echoss_logger.CopyTruncateRotatingHandler(str(log_file), when="S", interval=1, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger = logging.getLogger("held")
+    logger.propagate = False
+    logger.setLevel(logging.INFO)
+    logger.addHandler(handler)
+
+    holder = subprocess.Popen(
+        [sys.executable, str(HOLD_FILE), str(log_file)],
+        stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True,
+    )
+    try:
+        assert holder.stdout.readline().strip() == "ready"
+        written = 0
+        deadline = time.time() + 3
+        while time.time() < deadline:
+            logger.info(str(written))
+            written += 1
+            time.sleep(0.02)
+    finally:
+        logger.removeHandler(handler)
+        handler.close()
+        holder.stdin.close()
+        holder.wait(timeout=10)
+
+    rotated = sorted(tmp_path.glob("held.log.*"))
+    lines = []
+    for path in [log_file, *rotated]:
+        lines.extend(path.read_text(encoding="utf-8").splitlines())
+
+    assert len(rotated) >= 1
+    assert sorted(int(line) for line in lines) == list(range(written))
+
+
+# T-07
+def test_existing_dated_file_is_kept_and_rollover_moves_forward(tmp_path):
+    log_file = tmp_path / "pre.log"
+    handler = echoss_logger.CopyTruncateRotatingHandler(str(log_file), when="S", interval=1, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    handler.rolloverAt = int(time.time()) - 1
+    dated = Path(handler.rotation_filename(
+        handler.baseFilename + "." + time.strftime(handler.suffix, time.localtime(handler.rolloverAt - handler.interval))
+    ))
+    dated.write_text("pre-existing\n", encoding="utf-8")
+
+    try:
+        handler.emit(logging.makeLogRecord({"msg": "after"}))
+        now = int(time.time())
+    finally:
+        handler.close()
+
+    assert dated.read_text(encoding="utf-8") == "pre-existing\n"
+    assert handler.rolloverAt > now
+
+
+# Two loggers, one handler each, one file, rotating every second: writes A1 B1 | A2 B2 | A3 B3
+def _write_through_two_handlers(tmp_path):
+    log_file = tmp_path / "e.log"
+    loggers = []
+    for name in ("two_a", "two_b"):
+        handler = echoss_logger.CopyTruncateRotatingHandler(str(log_file), when="S", interval=1, encoding="utf-8")
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        logger = logging.getLogger(name)
+        logger.propagate = False
+        logger.setLevel(logging.INFO)
+        logger.addHandler(handler)
+        loggers.append(logger)
+    try:
+        for i in (1, 2, 3):
+            loggers[0].info("A%d", i)
+            loggers[1].info("B%d", i)
+            if i < 3:
+                time.sleep(1.2)
+    finally:
+        for logger in loggers:
+            for handler in list(logger.handlers):
+                logger.removeHandler(handler)
+                handler.close()
+    rotated = sorted(tmp_path.glob("e.log.*"))
+    return log_file.read_text(encoding="utf-8").split(), [p.read_text(encoding="utf-8").split() for p in rotated]
+
+
+# T-M1
+def test_two_handlers_on_one_file_write_current_file_after_rotation(tmp_path):
+    current, rotated = _write_through_two_handlers(tmp_path)
+
+    assert current == ["A3", "B3"]
+    assert rotated == [["A1", "B1"], ["A2", "B2"]]
+
+
+# T-M2
+def test_two_handlers_lose_and_duplicate_no_record(tmp_path):
+    current, rotated = _write_through_two_handlers(tmp_path)
+
+    assert sorted(current + [line for lines in rotated for line in lines]) == ["A1", "A2", "A3", "B1", "B2", "B3"]
+
+
+# T-M3
+def test_stale_stream_check_off_keeps_2_0_0_layout(tmp_path, monkeypatch):
+    monkeypatch.setattr(echoss_logger, "_STALE_STREAM_CHECK", False, raising=False)
+    current, rotated = _write_through_two_handlers(tmp_path)
+
+    assert current == ["A3"]
+    assert rotated == [["A1", "B1", "B2", "B3"], ["A2"]]
+
+
+# T-08
+@pytest.mark.parametrize("func, params", [
+    (echoss_common.get_app_logger,
+     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level"]),
+    (echoss_common.get_logger,
+     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level"]),
+    (echoss_common.use_logger, ["logger_name"]),
+    (echoss_common.set_logger_level, ["logger", "level"]),
+    (echoss_common.modify_loggers_by_prefix,
+     ["prefix", "new_format", "new_path", "backup_count", "use_console", "level"]),
+    (echoss_common.dict_load, ["file_path", "file_format", "kwargs"]),
+    (echoss_common.dict_dump, ["config", "file_path", "file_format", "force_write", "xml_tag", "kwargs"]),
+])
+def test_public_signatures_unchanged_from_1_2_0(func, params):
+    assert list(inspect.signature(func).parameters) == params
+
+
+def test_log_format_detail_unchanged_from_1_2_0():
+    assert echoss_common.LOG_FORMAT_DETAIL == (
+        "[%(asctime)s.%(msecs)03d] %(levelname)-7s %(module)s.%(funcName)s.%(lineno)d : %(message)s"
+    )