echoss-common 2.2.0__tar.gz → 2.3.0__tar.gz

{echoss_common-2.2.0/echoss_common.egg-info → echoss_common-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 2.2.0
+Version: 2.3.0
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -9,6 +9,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyyaml>6.0.2
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
@@ -16,7 +17,7 @@ Dynamic: license-file
 # echoss-common
 
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
-로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
+로깅(Logger)과 config 파일 포맷 읽기/쓰기, 설정 파일의 비밀값 자리표시자 치환(`EnvConfig`) 기능을 제공합니다.
 
 ## 문서 지도
 
@@ -33,6 +34,11 @@ pip install echoss-common
 
 - Python >= 3.12
 - pyyaml > 6.0.2
+- python-dotenv >= 1.0.0 (2.3.0 부터)
+
+## 2.3.0 변경 사항
+
+- 비밀값을 설정 파일 밖에 두는 `EnvConfig` 를 추가했습니다(아래 「비밀값 자리표시자」). 이를 위해 `python-dotenv` 가 필수 의존으로 추가됩니다. 기존 `dict_load` · `dict_dump` 동작은 그대로입니다.
 
 ## 2.2.0 변경 사항
 
@@ -146,7 +152,7 @@ modify_loggers_by_prefix(
 
 - 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
 - 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
@@ -213,6 +219,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -263,6 +270,38 @@ dict_dump({'settings': {'@version': '1', 'port': '8080'}}, 'config/settings.xml'
 dict_dump(settings, 'config/settings.yaml', force_write=False)
 ```
 
+#### 비밀값 자리표시자 (`EnvConfig`, 2.3.0)
+
+API 키·비밀번호는 설정 파일에 `${이름}` 으로 적고, 실제 값은 `.env` 또는 운영체제 환경변수에 둡니다.
+
+```yaml
+# config.yaml (git 에 커밋)
+api:
+  key: ${OPENAI_API_KEY}
+db:
+  url: postgres://app:${PG_PASSWORD}@db.local/app
+```
+
+```
+# .env (git 에 넣지 않음 — .gitignore 에 추가하고, 변수 이름만 적은 .env.example 을 커밋)
+OPENAI_API_KEY=sk-...
+PG_PASSWORD=...
+```
+
+```python
+from echoss_common import EnvConfig
+
+cfg = EnvConfig.load('config.yaml')         # .env 는 작업 폴더부터 위로 찾음, env_path='...' 로 지정 가능
+cfg.data['api']['key']                      # 'sk-...'
+cfg.data['api']['timeout'] = 60
+cfg.dump('config.yaml')                     # ${OPENAI_API_KEY} 등 자리표시자는 그대로 저장
+```
+
+- 문자열 값 안의 `${이름}` 을 모두 바꿉니다 — 값 전체와 값 일부(`postgres://app:${PG_PASSWORD}@...`) 모두, 중첩 dict · list 포함. 이름은 영문자 · 숫자 · 밑줄이고 숫자로 시작하지 않습니다. `$HOME`, `pa$$word` 는 바꾸지 않습니다. 이스케이프는 없습니다 — 평문 값에 `${...}` 를 쓰면 치환 대상이 됩니다.
+- 값은 운영체제 환경변수에서 먼저 찾고, 없으면 `.env` 에서 찾습니다. `.env` 의 값은 프로세스 환경변수에도 들어갑니다(이미 있는 값은 바꾸지 않음). 어디에도 없으면 `ValueError` 입니다(어느 키 · 어느 변수인지 메시지에 표시).
+- `dump` 는 자리표시자가 있던 자리를 원본 자리표시자로 씁니다. 그 자리 값을 프로그램이 바꿨으면 바뀐 값은 설정 파일에 쓰지 않고 `UserWarning` 을 냅니다.
+- `dump` 는 기존 `.env` 를 덮어쓰지 않습니다. `.env` 가 없을 때만 자리표시자 변수로 새로 만들고, 값 전체가 자리표시자인 자리를 바꿨으면 바뀐 값을 씁니다. 새로 만든 `.env` 가 git 에 들어가지 않게 `.gitignore` 에 `.env` 를 넣어 둡니다.
+
 ---
 
 ## API 참조
@@ -321,6 +360,20 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `force_write` | bool | `True` | 기존 파일 덮어쓰기 여부 |
 | `xml_tag` | str | `None` | XML 루트 태그 (미지정 시 단일 최상위 키 사용) |
 
+### `EnvConfig.load(file_path, file_format, env_path, **kwargs)`
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|----------|------|--------|------|
+| `file_path` | str | — | 읽을 설정 파일 경로 (`dict_load` 와 같음) |
+| `file_format` | str | `None` | 포맷 강제 지정 |
+| `env_path` | str | `None` | `.env` 경로 (미지정 시 작업 폴더부터 위로 찾고, 없으면 작업 폴더의 `.env`) |
+
+반환값: `EnvConfig` — `data` 는 치환된 설정, `raw` 는 파일 그대로의 설정, `env_path` 는 쓴 `.env` 경로. 자리표시자 변수가 없으면 `ValueError`.
+
+### `EnvConfig.dump(file_path, file_format, force_write, xml_tag, **kwargs)`
+
+인자는 `dict_dump` 와 같습니다. `data` 를 저장하되 자리표시자가 있던 자리는 원본 자리표시자로 씁니다. `.env` 가 없을 때만 새로 만듭니다.
+
 ---
 
 ## 라이선스

{echoss_common-2.2.0 → echoss_common-2.3.0}/README.md

@@ -1,7 +1,7 @@
 # echoss-common
 
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
-로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
+로깅(Logger)과 config 파일 포맷 읽기/쓰기, 설정 파일의 비밀값 자리표시자 치환(`EnvConfig`) 기능을 제공합니다.
 
 ## 문서 지도
 
@@ -18,6 +18,11 @@ pip install echoss-common
 
 - Python >= 3.12
 - pyyaml > 6.0.2
+- python-dotenv >= 1.0.0 (2.3.0 부터)
+
+## 2.3.0 변경 사항
+
+- 비밀값을 설정 파일 밖에 두는 `EnvConfig` 를 추가했습니다(아래 「비밀값 자리표시자」). 이를 위해 `python-dotenv` 가 필수 의존으로 추가됩니다. 기존 `dict_load` · `dict_dump` 동작은 그대로입니다.
 
 ## 2.2.0 변경 사항
 
@@ -131,7 +136,7 @@ modify_loggers_by_prefix(
 
 - 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
 - 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
@@ -198,6 +203,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -248,6 +254,38 @@ dict_dump({'settings': {'@version': '1', 'port': '8080'}}, 'config/settings.xml'
 dict_dump(settings, 'config/settings.yaml', force_write=False)
 ```
 
+#### 비밀값 자리표시자 (`EnvConfig`, 2.3.0)
+
+API 키·비밀번호는 설정 파일에 `${이름}` 으로 적고, 실제 값은 `.env` 또는 운영체제 환경변수에 둡니다.
+
+```yaml
+# config.yaml (git 에 커밋)
+api:
+  key: ${OPENAI_API_KEY}
+db:
+  url: postgres://app:${PG_PASSWORD}@db.local/app
+```
+
+```
+# .env (git 에 넣지 않음 — .gitignore 에 추가하고, 변수 이름만 적은 .env.example 을 커밋)
+OPENAI_API_KEY=sk-...
+PG_PASSWORD=...
+```
+
+```python
+from echoss_common import EnvConfig
+
+cfg = EnvConfig.load('config.yaml')         # .env 는 작업 폴더부터 위로 찾음, env_path='...' 로 지정 가능
+cfg.data['api']['key']                      # 'sk-...'
+cfg.data['api']['timeout'] = 60
+cfg.dump('config.yaml')                     # ${OPENAI_API_KEY} 등 자리표시자는 그대로 저장
+```
+
+- 문자열 값 안의 `${이름}` 을 모두 바꿉니다 — 값 전체와 값 일부(`postgres://app:${PG_PASSWORD}@...`) 모두, 중첩 dict · list 포함. 이름은 영문자 · 숫자 · 밑줄이고 숫자로 시작하지 않습니다. `$HOME`, `pa$$word` 는 바꾸지 않습니다. 이스케이프는 없습니다 — 평문 값에 `${...}` 를 쓰면 치환 대상이 됩니다.
+- 값은 운영체제 환경변수에서 먼저 찾고, 없으면 `.env` 에서 찾습니다. `.env` 의 값은 프로세스 환경변수에도 들어갑니다(이미 있는 값은 바꾸지 않음). 어디에도 없으면 `ValueError` 입니다(어느 키 · 어느 변수인지 메시지에 표시).
+- `dump` 는 자리표시자가 있던 자리를 원본 자리표시자로 씁니다. 그 자리 값을 프로그램이 바꿨으면 바뀐 값은 설정 파일에 쓰지 않고 `UserWarning` 을 냅니다.
+- `dump` 는 기존 `.env` 를 덮어쓰지 않습니다. `.env` 가 없을 때만 자리표시자 변수로 새로 만들고, 값 전체가 자리표시자인 자리를 바꿨으면 바뀐 값을 씁니다. 새로 만든 `.env` 가 git 에 들어가지 않게 `.gitignore` 에 `.env` 를 넣어 둡니다.
+
 ---
 
 ## API 참조
@@ -306,6 +344,20 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `force_write` | bool | `True` | 기존 파일 덮어쓰기 여부 |
 | `xml_tag` | str | `None` | XML 루트 태그 (미지정 시 단일 최상위 키 사용) |
 
+### `EnvConfig.load(file_path, file_format, env_path, **kwargs)`
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|----------|------|--------|------|
+| `file_path` | str | — | 읽을 설정 파일 경로 (`dict_load` 와 같음) |
+| `file_format` | str | `None` | 포맷 강제 지정 |
+| `env_path` | str | `None` | `.env` 경로 (미지정 시 작업 폴더부터 위로 찾고, 없으면 작업 폴더의 `.env`) |
+
+반환값: `EnvConfig` — `data` 는 치환된 설정, `raw` 는 파일 그대로의 설정, `env_path` 는 쓴 `.env` 경로. 자리표시자 변수가 없으면 `ValueError`.
+
+### `EnvConfig.dump(file_path, file_format, force_write, xml_tag, **kwargs)`
+
+인자는 `dict_dump` 와 같습니다. `data` 를 저장하되 자리표시자가 있던 자리는 원본 자리표시자로 씁니다. `.env` 가 없을 때만 새로 만듭니다.
+
 ---
 
 ## 라이선스

{echoss_common-2.2.0 → echoss_common-2.3.0}/echoss_common/__init__.py

@@ -1,6 +1,7 @@
 # for v1.0
 from .echoss_logger import JsonLineFormatter, JsonLogDict, get_app_logger, get_logger, use_logger, LOG_FORMAT_DETAIL, set_logger_level, modify_loggers_by_prefix
 from .config_fileformat import dict_load, dict_dump
+from .env_config import EnvConfig
 
 __all__ = [
     "JsonLogDict",
@@ -12,5 +13,6 @@ __all__ = [
     "set_logger_level",
     "modify_loggers_by_prefix",
     "dict_load",
-    "dict_dump"
+    "dict_dump",
+    "EnvConfig"
 ]

echoss_common-2.3.0/echoss_common/env_config.py

@@ -0,0 +1,77 @@
+import copy
+import os
+import re
+import warnings
+
+from dotenv import find_dotenv, load_dotenv, set_key
+
+from .config_fileformat import dict_dump, dict_load
+
+PLACEHOLDER = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+# Replace every ${NAME} inside string values; path names the key in the error.
+def _substitute(value, path=""):
+    if isinstance(value, dict):
+        return {k: _substitute(v, f"{path}.{k}" if path else str(k)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_substitute(v, f"{path}[{i}]") for i, v in enumerate(value)]
+    if not isinstance(value, str):
+        return value
+
+    def lookup(m):
+        found = os.environ.get(m[1])
+        if found is None:
+            raise ValueError(f"[{path}] environment variable '{m[1]}' not found (.env / OS env)")
+        return found
+
+    return PLACEHOLDER.sub(lookup, value)
+
+
+# Write the placeholder back wherever the file had one; collect variables for a new .env.
+def _restore(current, raw, loaded, path, env_values, new_env):
+    if isinstance(current, dict) and isinstance(raw, dict) and isinstance(loaded, dict):
+        return {k: _restore(v, raw[k], loaded[k], f"{path}.{k}" if path else str(k), env_values, new_env)
+                if k in raw and k in loaded else v for k, v in current.items()}
+    if isinstance(current, list) and isinstance(raw, list) and isinstance(loaded, list):
+        return [_restore(v, raw[i], loaded[i], f"{path}[{i}]", env_values, new_env)
+                if i < len(raw) and i < len(loaded) else v for i, v in enumerate(current)]
+    names = PLACEHOLDER.findall(raw) if isinstance(raw, str) else []
+    if not names:
+        return current
+    for name in names:
+        env_values.setdefault(name, os.environ.get(name))
+    if current != loaded:
+        whole = PLACEHOLDER.fullmatch(raw)
+        if new_env and whole:
+            env_values[whole[1]] = str(current)
+        else:
+            warnings.warn(f"[{path}] changed value not saved; the placeholder {raw!r} is kept",
+                          UserWarning, stacklevel=3)
+    return raw
+
+
+# A config file whose ${NAME} placeholders come from the OS environment or .env.
+# data is the substituted config; dump() writes the placeholders back so secrets stay out of the file.
+class EnvConfig:
+    def __init__(self, raw, env_path):
+        self.raw = raw            # as read from the file, placeholders kept
+        self.env_path = env_path  # .env read at load, created at dump when missing
+        self.data = _substitute(raw)
+        self.loaded = copy.deepcopy(self.data)
+
+    @classmethod
+    def load(cls, file_path, file_format=None, env_path=None, **kwargs):
+        env_path = env_path or find_dotenv(usecwd=True) or os.path.join(os.getcwd(), ".env")
+        load_dotenv(env_path, override=False)  # OS environment values win over .env
+        return cls(dict_load(file_path, file_format, **kwargs), env_path)
+
+    def dump(self, file_path, file_format=None, force_write=True, xml_tag=None, **kwargs):
+        new_env = not os.path.exists(self.env_path)
+        env_values = {}
+        out = _restore(self.data, self.raw, self.loaded, "", env_values, new_env)
+        dict_dump(out, file_path, file_format, force_write=force_write, xml_tag=xml_tag, **kwargs)
+        if new_env and env_values:
+            open(self.env_path, "x").close()  # never overwrite an existing .env
+            for name, value in env_values.items():
+                set_key(self.env_path, name, value)

{echoss_common-2.2.0 → echoss_common-2.3.0/echoss_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 2.2.0
+Version: 2.3.0
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -9,6 +9,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyyaml>6.0.2
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
@@ -16,7 +17,7 @@ Dynamic: license-file
 # echoss-common
 
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
-로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
+로깅(Logger)과 config 파일 포맷 읽기/쓰기, 설정 파일의 비밀값 자리표시자 치환(`EnvConfig`) 기능을 제공합니다.
 
 ## 문서 지도
 
@@ -33,6 +34,11 @@ pip install echoss-common
 
 - Python >= 3.12
 - pyyaml > 6.0.2
+- python-dotenv >= 1.0.0 (2.3.0 부터)
+
+## 2.3.0 변경 사항
+
+- 비밀값을 설정 파일 밖에 두는 `EnvConfig` 를 추가했습니다(아래 「비밀값 자리표시자」). 이를 위해 `python-dotenv` 가 필수 의존으로 추가됩니다. 기존 `dict_load` · `dict_dump` 동작은 그대로입니다.
 
 ## 2.2.0 변경 사항
 
@@ -146,7 +152,7 @@ modify_loggers_by_prefix(
 
 - 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
 - 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
@@ -213,6 +219,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -263,6 +270,38 @@ dict_dump({'settings': {'@version': '1', 'port': '8080'}}, 'config/settings.xml'
 dict_dump(settings, 'config/settings.yaml', force_write=False)
 ```
 
+#### 비밀값 자리표시자 (`EnvConfig`, 2.3.0)
+
+API 키·비밀번호는 설정 파일에 `${이름}` 으로 적고, 실제 값은 `.env` 또는 운영체제 환경변수에 둡니다.
+
+```yaml
+# config.yaml (git 에 커밋)
+api:
+  key: ${OPENAI_API_KEY}
+db:
+  url: postgres://app:${PG_PASSWORD}@db.local/app
+```
+
+```
+# .env (git 에 넣지 않음 — .gitignore 에 추가하고, 변수 이름만 적은 .env.example 을 커밋)
+OPENAI_API_KEY=sk-...
+PG_PASSWORD=...
+```
+
+```python
+from echoss_common import EnvConfig
+
+cfg = EnvConfig.load('config.yaml')         # .env 는 작업 폴더부터 위로 찾음, env_path='...' 로 지정 가능
+cfg.data['api']['key']                      # 'sk-...'
+cfg.data['api']['timeout'] = 60
+cfg.dump('config.yaml')                     # ${OPENAI_API_KEY} 등 자리표시자는 그대로 저장
+```
+
+- 문자열 값 안의 `${이름}` 을 모두 바꿉니다 — 값 전체와 값 일부(`postgres://app:${PG_PASSWORD}@...`) 모두, 중첩 dict · list 포함. 이름은 영문자 · 숫자 · 밑줄이고 숫자로 시작하지 않습니다. `$HOME`, `pa$$word` 는 바꾸지 않습니다. 이스케이프는 없습니다 — 평문 값에 `${...}` 를 쓰면 치환 대상이 됩니다.
+- 값은 운영체제 환경변수에서 먼저 찾고, 없으면 `.env` 에서 찾습니다. `.env` 의 값은 프로세스 환경변수에도 들어갑니다(이미 있는 값은 바꾸지 않음). 어디에도 없으면 `ValueError` 입니다(어느 키 · 어느 변수인지 메시지에 표시).
+- `dump` 는 자리표시자가 있던 자리를 원본 자리표시자로 씁니다. 그 자리 값을 프로그램이 바꿨으면 바뀐 값은 설정 파일에 쓰지 않고 `UserWarning` 을 냅니다.
+- `dump` 는 기존 `.env` 를 덮어쓰지 않습니다. `.env` 가 없을 때만 자리표시자 변수로 새로 만들고, 값 전체가 자리표시자인 자리를 바꿨으면 바뀐 값을 씁니다. 새로 만든 `.env` 가 git 에 들어가지 않게 `.gitignore` 에 `.env` 를 넣어 둡니다.
+
 ---
 
 ## API 참조
@@ -321,6 +360,20 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `force_write` | bool | `True` | 기존 파일 덮어쓰기 여부 |
 | `xml_tag` | str | `None` | XML 루트 태그 (미지정 시 단일 최상위 키 사용) |
 
+### `EnvConfig.load(file_path, file_format, env_path, **kwargs)`
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|----------|------|--------|------|
+| `file_path` | str | — | 읽을 설정 파일 경로 (`dict_load` 와 같음) |
+| `file_format` | str | `None` | 포맷 강제 지정 |
+| `env_path` | str | `None` | `.env` 경로 (미지정 시 작업 폴더부터 위로 찾고, 없으면 작업 폴더의 `.env`) |
+
+반환값: `EnvConfig` — `data` 는 치환된 설정, `raw` 는 파일 그대로의 설정, `env_path` 는 쓴 `.env` 경로. 자리표시자 변수가 없으면 `ValueError`.
+
+### `EnvConfig.dump(file_path, file_format, force_write, xml_tag, **kwargs)`
+
+인자는 `dict_dump` 와 같습니다. `data` 를 저장하되 자리표시자가 있던 자리는 원본 자리표시자로 씁니다. `.env` 가 없을 때만 새로 만듭니다.
+
 ---
 
 ## 라이선스

{echoss_common-2.2.0 → echoss_common-2.3.0}/echoss_common.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 echoss_common/__init__.py
 echoss_common/config_fileformat.py
 echoss_common/echoss_logger.py
+echoss_common/env_config.py
 echoss_common.egg-info/PKG-INFO
 echoss_common.egg-info/SOURCES.txt
 echoss_common.egg-info/dependency_links.txt
@@ -17,6 +18,7 @@ tests/test_echoss_logger_2.py
 tests/test_echoss_logger_2x.py
 tests/test_echoss_logger_json.py
 tests/test_echoss_logger_rotation_modes.py
+tests/test_env_config.py
 tests/scripts/check_xml_samples.py
 tests/scripts/hold_file.py
 tests/scripts/spike_default_log_file.py

{echoss_common-2.2.0 → echoss_common-2.3.0}/echoss_common.egg-info/requires.txt

@@ -1,4 +1,5 @@
 pyyaml>6.0.2
+python-dotenv>=1.0.0
 
 [dev]
 pytest

{echoss_common-2.2.0 → echoss_common-2.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 # 패키지 메타데이터
 [project]
 name="echoss-common"
-version="2.2.0"
+version="2.3.0"
 description="echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)"
 readme = "README.md"
 license = "Apache-2.0"
@@ -22,7 +22,8 @@ requires-python='>=3.12'
 
 # 런타임 의존성: YAML 파싱을 위한 pyyaml
 dependencies=[
-        "pyyaml>6.0.2"
+        "pyyaml>6.0.2",
+        "python-dotenv>=1.0.0"
 ]
 
 # 개발 의존성: 테스트 실행을 위한 pytest

echoss_common-2.3.0/tests/test_env_config.py

@@ -0,0 +1,126 @@
+import json
+import os
+
+import pytest
+import yaml
+
+from echoss_common import EnvConfig
+
+NAMES = ("EC_API_KEY", "EC_PG_PW", "EC_ONLY_IN_ENV_FILE", "EC_MISSING")
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    # monkeypatch restores these names afterwards, including values load_dotenv puts in os.environ
+    for name in NAMES:
+        monkeypatch.delenv(name, raising=False)
+
+
+def _write_yaml(path, data):
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+
+CONFIG = {
+    "api": {"key": "${EC_API_KEY}", "timeout": 30},
+    "db": {"url": "postgres://u:${EC_PG_PW}@host/db", "hosts": ["a", "${EC_API_KEY}"]},
+    "plain": "pa$$word $HOME",
+}
+
+
+def _load(tmp_path, env_text=None):
+    cfg_file = tmp_path / "config.yaml"
+    _write_yaml(cfg_file, CONFIG)
+    env_file = tmp_path / ".env"
+    if env_text is not None:
+        env_file.write_text(env_text, encoding="utf-8")
+    return EnvConfig.load(str(cfg_file), env_path=str(env_file)), cfg_file, env_file
+
+
+# T-E1, T-E8
+def test_load_substitutes_whole_and_partial_placeholders_in_nested_values(tmp_path):
+    cfg, _, _ = _load(tmp_path, "EC_API_KEY=key-1\nEC_PG_PW=pw-1\n")
+
+    assert cfg.data == {
+        "api": {"key": "key-1", "timeout": 30},
+        "db": {"url": "postgres://u:pw-1@host/db", "hosts": ["a", "key-1"]},
+        "plain": "pa$$word $HOME",
+    }
+    assert cfg.raw == CONFIG
+
+
+# T-E2
+def test_os_environment_wins_over_env_file_and_env_file_values_reach_os_environ(tmp_path, monkeypatch):
+    monkeypatch.setenv("EC_API_KEY", "from-os")
+    cfg, _, _ = _load(tmp_path, "EC_API_KEY=from-file\nEC_PG_PW=pw-1\nEC_ONLY_IN_ENV_FILE=x\n")
+
+    assert cfg.data["api"]["key"] == "from-os"
+    assert os.environ["EC_API_KEY"] == "from-os"
+    assert os.environ["EC_ONLY_IN_ENV_FILE"] == "x"
+
+
+# T-E3
+def test_missing_variable_raises_with_key_path_and_name(tmp_path):
+    with pytest.raises(ValueError, match=r"\[db\.url\] environment variable 'EC_PG_PW' not found"):
+        _load(tmp_path, "EC_API_KEY=key-1\n")
+
+
+# T-E4
+def test_env_file_in_working_folder_is_used_without_env_path(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".env").write_text("EC_API_KEY=key-1\nEC_PG_PW=pw-1\n", encoding="utf-8")
+    cfg_file = tmp_path / "config.yaml"
+    _write_yaml(cfg_file, CONFIG)
+
+    cfg = EnvConfig.load(str(cfg_file))
+
+    assert cfg.data["api"]["key"] == "key-1"
+    assert cfg.env_path == str(tmp_path / ".env")
+
+
+# T-E5
+@pytest.mark.parametrize("ext", ["yaml", "json"])
+def test_dump_keeps_placeholders_and_writes_changed_plain_values(tmp_path, ext, recwarn):
+    cfg, _, env_file = _load(tmp_path, "EC_API_KEY=key-1\nEC_PG_PW=pw-1\n")
+    cfg.data["api"]["timeout"] = 60
+    cfg.data["new"] = "added"
+    out = tmp_path / f"out.{ext}"
+
+    cfg.dump(str(out))
+
+    text = out.read_text(encoding="utf-8")
+    assert "key-1" not in text and "pw-1" not in text
+    saved = yaml.safe_load(text) if ext == "yaml" else json.loads(text)
+    assert saved == {**CONFIG, "api": {"key": "${EC_API_KEY}", "timeout": 60}, "new": "added"}
+    assert not [w for w in recwarn if issubclass(w.category, UserWarning)]
+
+
+# T-E6
+def test_dump_with_existing_env_file_keeps_placeholder_and_warns_on_changed_secret(tmp_path):
+    env_text = "EC_API_KEY=key-1\nEC_PG_PW=pw-1\n"
+    cfg, _, env_file = _load(tmp_path, env_text)
+    cfg.data["api"]["key"] = "key-2"
+    out = tmp_path / "out.yaml"
+
+    with pytest.warns(UserWarning, match=r"\[api\.key\] changed value not saved"):
+        cfg.dump(str(out))
+
+    assert yaml.safe_load(out.read_text(encoding="utf-8"))["api"]["key"] == "${EC_API_KEY}"
+    assert env_file.read_text(encoding="utf-8") == env_text
+
+
+# T-E7
+def test_dump_without_env_file_creates_it_with_changed_whole_values(tmp_path, monkeypatch):
+    monkeypatch.setenv("EC_API_KEY", "key-1")
+    monkeypatch.setenv("EC_PG_PW", "pw-1")
+    cfg, _, env_file = _load(tmp_path)  # no .env
+    cfg.data["api"]["key"] = "key-2"
+    cfg.data["db"]["url"] = "postgres://u:pw-2@host/db"
+    out = tmp_path / "out.yaml"
+
+    with pytest.warns(UserWarning, match=r"\[db\.url\] changed value not saved") as caught:
+        cfg.dump(str(out))
+
+    assert len([w for w in caught if issubclass(w.category, UserWarning)]) == 1
+    assert yaml.safe_load(out.read_text(encoding="utf-8")) == CONFIG
+    from dotenv import dotenv_values
+    assert dotenv_values(env_file) == {"EC_API_KEY": "key-2", "EC_PG_PW": "pw-1"}