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

{echoss_common-2.1.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.1.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,12 +34,23 @@ 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 변경 사항
+
+- **크기 회전 파일 이름이 바뀌었습니다.** `myapp.log.50m.1`(가장 최근) … 처럼 회전마다 번호를 미는 대신, `myapp.log.50m.2026-11-01.001` 처럼 회전한 날짜와 그날의 일련번호를 붙이고 다시 바꾸지 않습니다. 2.1.0 이 남긴 `myapp.log.50m.1` 같은 파일은 세지도 지우지도 않으니 직접 정리합니다.
+- 크기 회전의 `backup_count=0` 은 자정 회전과 같이 「회전하고 전부 보관」입니다(2.1.0 은 회전하지 않았습니다).
+- 회전 중 지울 옛 로그 파일을 다른 프로그램이 열고 있으면(Windows `PermissionError`) 지우기를 건너뛰고 계속 씁니다. 2.1.0 은 크기 회전에서 이후 기록을 잃고, 자정 회전에서 회전당 한 줄을 잃었습니다(아래 「로그 회전」).
 
 ## 2.1.0 변경 사항
 
 - `get_logger` · `get_app_logger` · `modify_loggers_by_prefix` 에 회전 방식 인자 `rotation` 이 맨 끝에 추가됐습니다. 기본값 `'midnight'` 은 2.0.x 와 같습니다(아래 「로그 회전」).
   - `'none'` — 회전하지 않고 한 파일에 계속 씁니다.
-  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다. 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
+  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다(2.2.0 에서 이름 규칙 변경). 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
 - **`modify_loggers_by_prefix` 동작 변경**: 대상 로거들이 파일 핸들러 **하나를 공유**합니다(2.0.x 는 로거마다 핸들러를 따로 붙였습니다). 기록은 전처럼 한 파일에 시간 순서대로 쌓이고, 회전도 한 번만 일어납니다. 2.0.x 에서 첫 로거 다음부터 `backup_count` 를 0 으로 바꾸던 처리는 없어졌습니다 — 준 `backup_count` 가 그대로 적용됩니다.
 
 ## 2.0.0 변경 사항
@@ -135,13 +147,13 @@ modify_loggers_by_prefix(
 | `rotation` | 동작 | 회전 파일 | `backup_count` |
 |---|---|---|---|
 | `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
-| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.1`(가장 최근) … `myapp.log.50m.N` | **1 이상을 주어야 회전합니다.** 0 이면 회전하지 않습니다(Python 표준 크기 회전과 같음) |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
 | `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
 
-- 회전 없이 쌓으려면 `'none'` 을 씁니다(`'50m'` 에 `backup_count=0` 으로 쓰지 않습니다).
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
-- 알려진 한계(크기 회전, Windows 확인 전): 회전할 때 `.50m.1` → `.50m.2` 처럼 번호 파일도 이름을 바꾸거나 지웁니다. 다른 프로그램이 그 번호 파일을 열고 있을 때 Windows 에서 어떻게 되는지는 2.1.0 배포 뒤 확인하고, 문제가 있으면 2.1.1 에서 고칩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
@@ -207,6 +219,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -257,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 참조
@@ -268,7 +313,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
 | `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
-| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (자정 회전은 0이면 전부 보관, 크기 회전은 1 이상이어야 회전) |
+| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
 | `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
@@ -315,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.1.0 → echoss_common-2.3.0}/README.md

@@ -1,7 +1,7 @@
 # echoss-common
 
 echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다.
-로깅(Logger)과 config 파일 포맷 읽기/쓰기 기능을 제공합니다.
+로깅(Logger)과 config 파일 포맷 읽기/쓰기, 설정 파일의 비밀값 자리표시자 치환(`EnvConfig`) 기능을 제공합니다.
 
 ## 문서 지도
 
@@ -18,12 +18,23 @@ 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 변경 사항
+
+- **크기 회전 파일 이름이 바뀌었습니다.** `myapp.log.50m.1`(가장 최근) … 처럼 회전마다 번호를 미는 대신, `myapp.log.50m.2026-11-01.001` 처럼 회전한 날짜와 그날의 일련번호를 붙이고 다시 바꾸지 않습니다. 2.1.0 이 남긴 `myapp.log.50m.1` 같은 파일은 세지도 지우지도 않으니 직접 정리합니다.
+- 크기 회전의 `backup_count=0` 은 자정 회전과 같이 「회전하고 전부 보관」입니다(2.1.0 은 회전하지 않았습니다).
+- 회전 중 지울 옛 로그 파일을 다른 프로그램이 열고 있으면(Windows `PermissionError`) 지우기를 건너뛰고 계속 씁니다. 2.1.0 은 크기 회전에서 이후 기록을 잃고, 자정 회전에서 회전당 한 줄을 잃었습니다(아래 「로그 회전」).
 
 ## 2.1.0 변경 사항
 
 - `get_logger` · `get_app_logger` · `modify_loggers_by_prefix` 에 회전 방식 인자 `rotation` 이 맨 끝에 추가됐습니다. 기본값 `'midnight'` 은 2.0.x 와 같습니다(아래 「로그 회전」).
   - `'none'` — 회전하지 않고 한 파일에 계속 씁니다.
-  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다. 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
+  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다(2.2.0 에서 이름 규칙 변경). 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
 - **`modify_loggers_by_prefix` 동작 변경**: 대상 로거들이 파일 핸들러 **하나를 공유**합니다(2.0.x 는 로거마다 핸들러를 따로 붙였습니다). 기록은 전처럼 한 파일에 시간 순서대로 쌓이고, 회전도 한 번만 일어납니다. 2.0.x 에서 첫 로거 다음부터 `backup_count` 를 0 으로 바꾸던 처리는 없어졌습니다 — 준 `backup_count` 가 그대로 적용됩니다.
 
 ## 2.0.0 변경 사항
@@ -120,13 +131,13 @@ modify_loggers_by_prefix(
 | `rotation` | 동작 | 회전 파일 | `backup_count` |
 |---|---|---|---|
 | `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
-| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.1`(가장 최근) … `myapp.log.50m.N` | **1 이상을 주어야 회전합니다.** 0 이면 회전하지 않습니다(Python 표준 크기 회전과 같음) |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
 | `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
 
-- 회전 없이 쌓으려면 `'none'` 을 씁니다(`'50m'` 에 `backup_count=0` 으로 쓰지 않습니다).
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
-- 알려진 한계(크기 회전, Windows 확인 전): 회전할 때 `.50m.1` → `.50m.2` 처럼 번호 파일도 이름을 바꾸거나 지웁니다. 다른 프로그램이 그 번호 파일을 열고 있을 때 Windows 에서 어떻게 되는지는 2.1.0 배포 뒤 확인하고, 문제가 있으면 2.1.1 에서 고칩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
@@ -192,6 +203,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -242,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 참조
@@ -253,7 +297,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
 | `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
-| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (자정 회전은 0이면 전부 보관, 크기 회전은 1 이상이어야 회전) |
+| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
 | `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
@@ -300,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.1.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.1.0 → echoss_common-2.3.0}/echoss_common/echoss_logger.py

@@ -5,6 +5,7 @@ import re
 import shutil
 import sys
 import time
+import warnings
 from collections.abc import Mapping
 from functools import cache
 from logging import StreamHandler
@@ -70,6 +71,17 @@ def _stream_replaced(handler) -> bool:
     return (mine.st_dev, mine.st_ino) != (disk.st_dev, disk.st_ino)
 
 
+# A rotation step hit a file another process keeps open (Windows: PermissionError).
+# Keep every record in the current file; warn once per handler.
+def _keep_writing_after_held_file(handler, exc):
+    if not getattr(handler, "_held_warned", False):
+        handler._held_warned = True
+        warnings.warn(f"log rotation step skipped, a file is held open by another process: {exc}",
+                      RuntimeWarning, stacklevel=2)
+    if handler.stream is None:
+        handler.stream = handler._open()
+
+
 # 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):
@@ -97,7 +109,10 @@ class CopyTruncateRotatingHandler(TimedRotatingFileHandler):
             self.stream = self._open()
             self.rolloverAt = self.computeRollover(int(time.time()))
             return
-        super().doRollover()
+        try:
+            super().doRollover()
+        except PermissionError as exc:  # an old dated file to delete is held open
+            _keep_writing_after_held_file(self, exc)
         now = int(time.time())
         if self.rolloverAt <= now:
             self.rolloverAt = self.computeRollover(now)
@@ -106,15 +121,45 @@ class CopyTruncateRotatingHandler(TimedRotatingFileHandler):
 _SIZE_ROTATION = re.compile(r"[1-9][0-9]*m")  # MiB, lowercase m only
 
 
-# Size rotation with rotated files named a.log.50m.1 (newest) .. a.log.50m.N.
-# The current file -> .1 step reuses the copy-truncate fallback of the midnight handler.
+# Size rotation into names that never change: a.log.50m.2026-11-01.001 (the day's largest number + 1).
+# Windows blocks renaming or deleting a file another process holds; with no renaming chain,
+# only deleting an old file can be blocked, as in midnight rotation.
 class SizeCopyTruncateRotatingHandler(RotatingFileHandler):
     rotate = CopyTruncateRotatingHandler.rotate
 
     def __init__(self, filename, size, backup_count):
         super().__init__(filename, maxBytes=int(size[:-1]) * 1024 * 1024,
                          backupCount=backup_count, encoding="utf-8")
-        self.namer = lambda name: f"{self.baseFilename}.{size}{name[len(self.baseFilename):]}"
+        self.size = size
+        self.width = max(1, 5 - len(size[:-1]))  # 1-9m: 4 digits, 10-99m: 3, 100-999m: 2, 1000m+: 1
+        self.pattern = re.compile(re.escape(os.path.basename(self.baseFilename))
+                                  + rf"\.{size}\.(\d{{4}}-\d{{2}}-\d{{2}})\.(\d+)")
+
+    # (date, number, path) of this handler's rotated files, oldest first
+    def rotated_files(self):
+        folder = os.path.dirname(self.baseFilename)
+        found = []
+        for name in os.listdir(folder):
+            m = self.pattern.fullmatch(name)
+            if m:
+                found.append((m[1], int(m[2]), os.path.join(folder, name)))
+        return sorted(found)
+
+    def doRollover(self):
+        if self.stream:
+            self.stream.close()
+            self.stream = None
+        files = self.rotated_files()
+        today = time.strftime("%Y-%m-%d")
+        number = max((n for day, n, _ in files if day == today), default=0) + 1
+        self.rotate(self.baseFilename, f"{self.baseFilename}.{self.size}.{today}.{number:0{self.width}d}")
+        self.stream = self._open()
+        if self.backupCount > 0:  # 0 keeps every rotated file, as in midnight rotation
+            try:
+                for *_, path in files[:len(files) + 1 - self.backupCount]:
+                    os.remove(path)
+            except PermissionError as exc:  # an old rotated file is held open
+                _keep_writing_after_held_file(self, exc)
 
 
 def _check_rotation(rotation):

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.1.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.1.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,12 +34,23 @@ 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 변경 사항
+
+- **크기 회전 파일 이름이 바뀌었습니다.** `myapp.log.50m.1`(가장 최근) … 처럼 회전마다 번호를 미는 대신, `myapp.log.50m.2026-11-01.001` 처럼 회전한 날짜와 그날의 일련번호를 붙이고 다시 바꾸지 않습니다. 2.1.0 이 남긴 `myapp.log.50m.1` 같은 파일은 세지도 지우지도 않으니 직접 정리합니다.
+- 크기 회전의 `backup_count=0` 은 자정 회전과 같이 「회전하고 전부 보관」입니다(2.1.0 은 회전하지 않았습니다).
+- 회전 중 지울 옛 로그 파일을 다른 프로그램이 열고 있으면(Windows `PermissionError`) 지우기를 건너뛰고 계속 씁니다. 2.1.0 은 크기 회전에서 이후 기록을 잃고, 자정 회전에서 회전당 한 줄을 잃었습니다(아래 「로그 회전」).
 
 ## 2.1.0 변경 사항
 
 - `get_logger` · `get_app_logger` · `modify_loggers_by_prefix` 에 회전 방식 인자 `rotation` 이 맨 끝에 추가됐습니다. 기본값 `'midnight'` 은 2.0.x 와 같습니다(아래 「로그 회전」).
   - `'none'` — 회전하지 않고 한 파일에 계속 씁니다.
-  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다. 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
+  - `'50m'` — 파일이 50 MiB 를 넘기 전에 `myapp.log.50m.1`(가장 최근), `.50m.2` … 로 회전합니다(2.2.0 에서 이름 규칙 변경). 크기는 `'{숫자}m'`(MiB) 형태만 받고 `'1g'`, `'500k'`, `'50'` 등은 `ValueError` 입니다.
 - **`modify_loggers_by_prefix` 동작 변경**: 대상 로거들이 파일 핸들러 **하나를 공유**합니다(2.0.x 는 로거마다 핸들러를 따로 붙였습니다). 기록은 전처럼 한 파일에 시간 순서대로 쌓이고, 회전도 한 번만 일어납니다. 2.0.x 에서 첫 로거 다음부터 `backup_count` 를 0 으로 바꾸던 처리는 없어졌습니다 — 준 `backup_count` 가 그대로 적용됩니다.
 
 ## 2.0.0 변경 사항
@@ -135,13 +147,13 @@ modify_loggers_by_prefix(
 | `rotation` | 동작 | 회전 파일 | `backup_count` |
 |---|---|---|---|
 | `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
-| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.1`(가장 최근) … `myapp.log.50m.N` | **1 이상을 주어야 회전합니다.** 0 이면 회전하지 않습니다(Python 표준 크기 회전과 같음) |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
 | `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
 
-- 회전 없이 쌓으려면 `'none'` 을 씁니다(`'50m'` 에 `backup_count=0` 으로 쓰지 않습니다).
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
 - 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
-- 알려진 한계(크기 회전, Windows 확인 전): 회전할 때 `.50m.1` → `.50m.2` 처럼 번호 파일도 이름을 바꾸거나 지웁니다. 다른 프로그램이 그 번호 파일을 열고 있을 때 Windows 에서 어떻게 되는지는 2.1.0 배포 뒤 확인하고, 문제가 있으면 2.1.1 에서 고칩니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
 - **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
@@ -207,6 +219,7 @@ logger.info("payload: %s", JsonLogDict({"user": "kim"}))
 |------|------|
 | `dict_load()` | 설정 파일을 `dict`로 읽기 |
 | `dict_dump()` | `dict`를 설정 파일로 쓰기 |
+| `EnvConfig.load()` · `.dump()` | `${이름}` 자리표시자를 `.env` · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」) |
 
 #### 지원 포맷
 
@@ -257,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 참조
@@ -268,7 +313,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `logger_name` | str | `'echoss'` | 로거 이름 |
 | `logger_format` | str | `LOG_FORMAT` | 로그 포맷 문자열 |
 | `file_path` | str\|None | `None` | 로그 파일 경로 (`None`이면 파일 미사용) |
-| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (자정 회전은 0이면 전부 보관, 크기 회전은 1 이상이어야 회전) |
+| `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
 | `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
@@ -315,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.1.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.1.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.1.0 → echoss_common-2.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 # 패키지 메타데이터
 [project]
 name="echoss-common"
-version="2.1.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.1.0 → echoss_common-2.3.0}/tests/test_echoss_logger_2x.py

@@ -207,6 +207,8 @@ def test_two_handlers_lose_and_duplicate_no_record(tmp_path):
 
 
 # T-M3
+@pytest.mark.skipif(sys.platform == "win32", reason="Windows blocks the rename while the second handler keeps "
+                    "the file open, so copy-truncate keeps A3 and B3 in the current file (T-M1/T-M2 cover no loss)")
 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)

{echoss_common-2.1.0 → echoss_common-2.3.0}/tests/test_echoss_logger_rotation_modes.py

@@ -3,6 +3,8 @@ import logging
 import os
 import subprocess
 import sys
+import time
+import warnings
 from contextlib import contextmanager
 from pathlib import Path
 
@@ -46,6 +48,11 @@ def _numbers(paths):
     return found
 
 
+def _rotated(name, *numbers):
+    today = time.strftime("%Y-%m-%d")
+    return [f"{name}.1m.{today}.{n:04d}" for n in numbers]
+
+
 def _write(logger, count, start=0):
     for n in range(start, start + count):
         logger.info(f"{n} {LINE}")
@@ -69,7 +76,7 @@ def test_size_rotation_names_limit_and_backup_count(tmp_path):
     _write(logger, written)
 
     files = sorted(tmp_path.iterdir())
-    assert [f.name for f in files] == ["s.log", "s.log.1m.1", "s.log.1m.2"]
+    assert [f.name for f in files] == ["s.log"] + _rotated("s.log", 2, 3)  # 3 rotations, the 2 newest kept
     assert all(f.stat().st_size <= MIB for f in files)
     kept = sorted(_numbers(files))
     assert kept == list(range(written - len(kept), written))  # newest records, no gap
@@ -120,7 +127,7 @@ def test_size_rotation_falls_back_to_copy_truncate_when_rename_is_blocked(tmp_pa
     _write(logger, written)
 
     files = sorted(tmp_path.iterdir())
-    assert "blk.log.1m.1" in [f.name for f in files]
+    assert _rotated("blk.log", 1)[0] in [f.name for f in files]
     assert sorted(_numbers(files)) == list(range(written))
 
 
@@ -179,7 +186,7 @@ def test_modify_loggers_by_prefix_shares_one_file_handler(tmp_path, rotation):
     files = sorted(tmp_path.iterdir())
     kept = sorted(_numbers(files))
     if rotation == "1m":
-        assert [f.name for f in files] == ["shared.log", "shared.log.1m.1", "shared.log.1m.2"]
+        assert [f.name for f in files] == ["shared.log"] + _rotated("shared.log", 2, 3)
         assert all(f.stat().st_size <= MIB for f in files)
         assert kept == list(range(count - len(kept), count))  # newest records of all three loggers, no gap
     else:
@@ -260,16 +267,17 @@ def test_size_rotation_keeps_every_record_while_another_process_holds_the_curren
 # T-R9
 def test_size_rotation_keeps_every_record_while_another_process_holds_a_numbered_file(tmp_path):
     log_file = tmp_path / "h9.log"
-    logger = _size_logger("rm-h9", log_file, 10)
-    first = 1200  # one rotation, so h9.log.1m.1 exists
+    logger = _size_logger("rm-h9", log_file, 1)
+    first = 1200  # one rotation, so the first rotated file exists
     _write(logger, first)
-    numbered = tmp_path / "h9.log.1m.1"
+    numbered = tmp_path / _rotated("h9.log", 1)[0]
     assert numbered.exists()
-    more = 2400  # two more rotations shift .1m.1 while it is held
+    more = 2400  # two more rotations try to delete it while it is held
     with _held(numbered):
         _write(logger, more, start=first)
 
-    assert sorted(_numbers(sorted(tmp_path.iterdir()))) == list(range(first + more))
+    kept = sorted(_numbers(sorted(tmp_path.iterdir())))  # Linux deletes, Windows keeps the held file
+    assert kept == list(range(first + more - len(kept), first + more))  # newest records, no gap
 
 
 # T-R10
@@ -281,3 +289,113 @@ def test_none_rotation_keeps_every_record_while_another_process_holds_the_file(t
         _write(logger, 500)
 
     assert _numbers([log_file]) == list(range(500))
+
+
+# T-W1 ~ T-W4: a file to shift or delete is held open (Linux stand-in: PermissionError raised by a patched os call)
+def _held_warnings(caught):
+    return [w for w in caught if issubclass(w.category, RuntimeWarning) and "held open" in str(w.message)]
+
+
+# T-W1
+def test_size_rotation_keeps_rotating_while_an_old_rotated_file_cannot_be_deleted(tmp_path, monkeypatch):
+    log_file = tmp_path / "w1.log"
+    logger = _size_logger("rm-w1", log_file, 1)
+    first = 1200  # one rotation, so the first rotated file exists
+    _write(logger, first)
+
+    def blocked_remove(path):
+        raise PermissionError("simulated: another handle keeps the file open")
+
+    monkeypatch.setattr(os, "remove", blocked_remove)
+    more = 2400  # two more rotations, each trying to delete the oldest rotated file
+    with pytest.warns(RuntimeWarning) as caught:
+        _write(logger, more, start=first)
+
+    files = sorted(tmp_path.iterdir())
+    assert len(_held_warnings(caught)) == 1
+    assert [f.name for f in files] == ["w1.log"] + _rotated("w1.log", 1, 2, 3)  # kept past backup_count
+    assert all(f.stat().st_size <= MIB for f in files)
+    assert sorted(_numbers(files)) == list(range(first + more))
+
+
+# T-W3
+def test_midnight_rotation_keeps_every_record_while_an_old_dated_file_cannot_be_deleted(tmp_path, monkeypatch):
+    log_file = tmp_path / "w3.log"
+    logger = echoss_logger.get_logger("rm-w3", logger_format="%(message)s", file_path=str(log_file),
+                                      backup_count=1, use_console=False, level="INFO")
+    [handler] = _file_handlers(logger)
+    for day in ("2020-01-01", "2020-01-02"):  # old dated files the rotation will try to delete
+        (tmp_path / f"w3.log.{day}").write_text("", encoding="utf-8")
+
+    def blocked_remove(path):
+        raise PermissionError("simulated: another handle keeps the file open")
+
+    monkeypatch.setattr(os, "remove", blocked_remove)
+    _write(logger, 10)
+    handler.rolloverAt = int(time.time()) - 1  # one rotation; a second one the same day finds its dated name taken
+    with pytest.warns(RuntimeWarning) as caught:
+        _write(logger, 10, start=10)
+
+    assert len(_held_warnings(caught)) == 1
+    assert sorted(_numbers(sorted(tmp_path.iterdir()))) == list(range(20))
+
+
+# T-W5 (Windows: on Linux nothing is blocked)
+def test_midnight_rotation_keeps_every_record_while_another_process_holds_an_old_dated_file(tmp_path):
+    log_file = tmp_path / "w5.log"
+    logger = echoss_logger.get_logger("rm-w5", logger_format="%(message)s", file_path=str(log_file),
+                                      backup_count=1, use_console=False, level="INFO")
+    [handler] = _file_handlers(logger)
+    old = tmp_path / "w5.log.2020-01-01"
+    old.write_text("", encoding="utf-8")
+    _write(logger, 10)
+    with _held(old):
+        handler.rolloverAt = int(time.time()) - 1
+        _write(logger, 10, start=10)
+
+    assert sorted(_numbers(sorted(tmp_path.iterdir()))) == list(range(20))
+
+
+# T-W4
+def test_size_rotation_backup_count_zero_keeps_every_rotated_file(tmp_path):
+    log_file = tmp_path / "w4.log"
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        logger = _size_logger("rm-w4", log_file, 0)
+        _write(logger, 3500)
+
+    files = sorted(tmp_path.iterdir())
+    assert [f.name for f in files] == ["w4.log"] + _rotated("w4.log", 1, 2, 3)
+    assert sorted(_numbers(files)) == list(range(3500))
+
+
+# T-W6
+@pytest.mark.parametrize("size, width", [("1m", 4), ("9m", 4), ("10m", 3), ("100m", 2), ("1000m", 1), ("2048m", 1)])
+def test_size_rotation_number_width_follows_size_digits(tmp_path, size, width):
+    handler = echoss_logger.SizeCopyTruncateRotatingHandler(str(tmp_path / "x.log"), size, 5)
+    try:
+        handler.emit(logging.makeLogRecord({"msg": "0 a"}))
+        handler.doRollover()
+    finally:
+        handler.close()
+
+    assert [f.name for f in tmp_path.iterdir() if f.name != "x.log"] == \
+        [f"x.log.{size}.{time.strftime('%Y-%m-%d')}.{1:0{width}d}"]
+
+
+# T-W6
+def test_size_rotation_takes_the_days_largest_number_plus_one(tmp_path):
+    today = time.strftime("%Y-%m-%d")
+    for name in (f"x.log.1m.{today}.0009", f"x.log.1m.{today}.12345", "x.log.1m.2020-01-01.0500",
+                 "x.log.1m.7", "x.log.50m.2020-01-01.001"):  # gap, overflow, another day, 2.1.0 name, other size
+        (tmp_path / name).write_text("", encoding="utf-8")
+    handler = echoss_logger.SizeCopyTruncateRotatingHandler(str(tmp_path / "x.log"), "1m", 10)
+    try:
+        handler.emit(logging.makeLogRecord({"msg": "0 a"}))
+        handler.doRollover()
+        rotated = [os.path.basename(path) for *_, path in handler.rotated_files()]
+    finally:
+        handler.close()
+
+    assert rotated == ["x.log.1m.2020-01-01.0500", f"x.log.1m.{today}.0009", f"x.log.1m.{today}.12345",
+                       f"x.log.1m.{today}.12346"]

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"}