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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 2.0.1
+Version: 2.2.0
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -34,6 +34,19 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 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` … 로 회전합니다(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 변경 사항
 
 호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
@@ -88,9 +101,16 @@ logger = get_logger(
     file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
-    level='DEBUG'                      # 로그 레벨
+    level='DEBUG',                     # 로그 레벨
+    rotation='midnight'                # 회전 방식: 'midnight'(기본) | 'none' | '50m'
 )
 
+# 회전하지 않고 한 파일에 계속 쌓기
+event_logger = get_logger('events', file_path='logs/events.jsonl', rotation='none')
+
+# 50 MiB 마다 회전, 회전 파일 10개 보관
+big_logger = get_logger('big', file_path='logs/big.log', rotation='50m', backup_count=10)
+
 logger.info("애플리케이션 시작")
 logger.debug("디버그 메시지")
 logger.error("오류 발생")
@@ -116,11 +136,20 @@ modify_loggers_by_prefix(
 
 #### 로그 회전
 
-파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+`rotation` 인자로 고릅니다.
 
-- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+| `rotation` | 동작 | 회전 파일 | `backup_count` |
+|---|---|---|---|
+| `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
+| `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
+
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+- **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
 #### JsonLogDict 사용 예시
 
@@ -238,7 +267,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 
 ## API 참조
 
-### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |----------|------|--------|------|
@@ -248,8 +277,9 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
 
-### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 `get_logger()`와 동일한 파라미터를 받지만, `@cache` 데코레이터로 감싸져 있어 동일한 인자로 호출할 경우 항상 같은 로거 인스턴스를 반환합니다. 애플리케이션 전역에서 하나의 로거를 공유할 때 적합합니다.
 
@@ -261,6 +291,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 (`get_logger` 와 같음) |
 
 ### `JsonLogDict(data)`
 

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

@@ -19,6 +19,19 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 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` … 로 회전합니다(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 변경 사항
 
 호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
@@ -73,9 +86,16 @@ logger = get_logger(
     file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
-    level='DEBUG'                      # 로그 레벨
+    level='DEBUG',                     # 로그 레벨
+    rotation='midnight'                # 회전 방식: 'midnight'(기본) | 'none' | '50m'
 )
 
+# 회전하지 않고 한 파일에 계속 쌓기
+event_logger = get_logger('events', file_path='logs/events.jsonl', rotation='none')
+
+# 50 MiB 마다 회전, 회전 파일 10개 보관
+big_logger = get_logger('big', file_path='logs/big.log', rotation='50m', backup_count=10)
+
 logger.info("애플리케이션 시작")
 logger.debug("디버그 메시지")
 logger.error("오류 발생")
@@ -101,11 +121,20 @@ modify_loggers_by_prefix(
 
 #### 로그 회전
 
-파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+`rotation` 인자로 고릅니다.
 
-- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+| `rotation` | 동작 | 회전 파일 | `backup_count` |
+|---|---|---|---|
+| `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
+| `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
+
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+- **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
 #### JsonLogDict 사용 예시
 
@@ -223,7 +252,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 
 ## API 참조
 
-### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |----------|------|--------|------|
@@ -233,8 +262,9 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
 
-### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 `get_logger()`와 동일한 파라미터를 받지만, `@cache` 데코레이터로 감싸져 있어 동일한 인자로 호출할 경우 항상 같은 로거 인스턴스를 반환합니다. 애플리케이션 전역에서 하나의 로거를 공유할 때 적합합니다.
 
@@ -246,6 +276,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 (`get_logger` 와 같음) |
 
 ### `JsonLogDict(data)`
 

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

@@ -1,13 +1,15 @@
 import json
 import logging
 import os
+import re
 import shutil
 import sys
 import time
+import warnings
 from collections.abc import Mapping
 from functools import cache
 from logging import StreamHandler
-from logging.handlers import TimedRotatingFileHandler
+from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler
 from typing import Any
 
 LOG_FORMAT = "[%(asctime)s.%(msecs)03d] %(levelname)-7s %(name)s : %(message)s"
@@ -22,7 +24,7 @@ os.environ["PYTHONIOENCODING"] = "utf-8"
 # Created By echoss_logger.py logger dict
 _logger_cache: dict[str, logging.Logger] = {}
 _logger_console_handler_cache: dict[str, StreamHandler] = {}
-_logger_file_handler_cache: dict[str, TimedRotatingFileHandler] = {}
+_logger_file_handler_cache: dict[str, logging.FileHandler] = {}
 
 
 class JsonLogDict:
@@ -69,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):
@@ -96,12 +109,66 @@ 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)
 
 
+_SIZE_ROTATION = re.compile(r"[1-9][0-9]*m")  # MiB, lowercase m only
+
+
+# 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.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):
+    if rotation in ("midnight", "none"):
+        return
+    if not (isinstance(rotation, str) and _SIZE_ROTATION.fullmatch(rotation)):
+        raise ValueError(f"rotation must be 'midnight', 'none' or '<MB>m' like '50m': {rotation!r}")
+
+
 def _get_console_handler(formatter):
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setFormatter(formatter)
@@ -109,8 +176,14 @@ def _get_console_handler(formatter):
     return console_handler
 
 
-def _get_file_handler(formatter, file_path, backup_count):
-    file_handler = CopyTruncateRotatingHandler(file_path, when="midnight", backupCount=backup_count, encoding='utf-8')
+def _get_file_handler(formatter, file_path, backup_count, rotation):
+    if rotation == "midnight":
+        file_handler = CopyTruncateRotatingHandler(file_path, when="midnight", backupCount=backup_count, encoding='utf-8')
+    elif rotation == "none":
+        file_handler = logging.FileHandler(file_path, encoding='utf-8')
+    else:
+        file_handler = SizeCopyTruncateRotatingHandler(file_path, rotation, backup_count)
+    file_handler.rotation = rotation  # compared when get_logger is called again with the same path
     file_handler.setFormatter(formatter)
     return file_handler
 
@@ -134,7 +207,7 @@ def _get_app_console_handler(logger_name: str) -> StreamHandler | None:
 
 
 # Retrieve a cached file handler if it exists and is still valid
-def _get_app_file_handler(logger_name: str) -> TimedRotatingFileHandler | None:
+def _get_app_file_handler(logger_name: str) -> logging.FileHandler | None:
     handler = _logger_file_handler_cache.get(logger_name)
     if handler is None or not _is_valid_file_handler(handler):
         return None
@@ -152,9 +225,9 @@ def _is_valid_stream_handler(handler: StreamHandler):
 
 
 # Validate that the cached file handler is still open and usable
-def _is_valid_file_handler(handler: TimedRotatingFileHandler):
+def _is_valid_file_handler(handler: logging.FileHandler):
     return (
-            isinstance(handler, TimedRotatingFileHandler)
+            isinstance(handler, logging.FileHandler)
             and getattr(handler, "stream", None) is not None
             and not getattr(handler.stream, "closed", False)
     )
@@ -177,24 +250,33 @@ def use_logger(logger_name='echoss'):
 
 @cache
 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)
+                   use_console=True, level="DEBUG", rotation="midnight"):
+    return get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)
 
 
 def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=None, backup_count=0,
-               use_console=True, level="DEBUG"):
+               use_console=True, level="DEBUG", rotation="midnight"):
     """
     create new echoss logger or replace old logger
     :param logger_name: logger name
     :param logger_format: logging format
     :param file_path: file path if File logging else None
-    :param backup_count: if 0 keep all timed rotating log files, else only keep backup count number of files
+    :param backup_count: midnight: 0 keeps all dated files, else only backup_count files.
+        size rotation: number of numbered files to keep; 0 means the file never rotates (stdlib behaviour)
     :param use_console: use console output or not
     :param level:  (str or int) set logging level
+    :param rotation: 'midnight' (default), 'none' (never rotate) or '<MB>m' like '50m' (rotate by size)
 
     :returns: generated logger
-    :raises None
+    :raises ValueError if rotation is not one of the forms above
     """
+    return _get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)
+
+
+# shared_file_handler: modify_loggers_by_prefix passes one file handler for all of its loggers
+def _get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation,
+                shared_file_handler=None):
+    _check_rotation(rotation)
     logger = _get_app_logger(logger_name)
     if logger is None:
         logger = logging.getLogger(logger_name)
@@ -235,10 +317,17 @@ def get_logger(logger_name='echoss', logger_format=LOG_FORMAT, file_path=None, b
         # 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):
+    elif shared_file_handler is not None:
+        file_handler = shared_file_handler
+        if file_handler not in logger.handlers:
+            logger.addHandler(file_handler)
+        _logger_file_handler_cache[logger_name] = file_handler
+    elif (file_handler is not None
+          and os.path.abspath(file_handler.baseFilename) == os.path.abspath(file_path)
+          and getattr(file_handler, "rotation", "midnight") == rotation):
         file_handler.setFormatter(formatter)
     else:
-        file_handler = _get_file_handler(formatter, file_path, backup_count)
+        file_handler = _get_file_handler(formatter, file_path, backup_count, rotation)
         logger.addHandler(file_handler)
         _logger_file_handler_cache[logger_name] = file_handler
 
@@ -279,31 +368,36 @@ def set_logger_level(logger, level):
 
 
 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"):
+                             backup_count: int = 0, use_console=True, level="DEBUG", rotation="midnight"):
     """
     Modify loggers that logger name starting with a specific prefix.
     :param prefix: prefix of lgger name
     :param new_format: new logging format
     :param new_path: new file path if File logging else None
-    :param backup_count: if 0 keep all timed rotating log files, else only keep backup count number of files
+    :param backup_count: same as get_logger
     :param use_console: use console output or not
     :param level: set logging level by level name or level number
+    :param rotation: same as get_logger
     :return: first logger
-    :raises None
+    :raises ValueError if rotation is invalid
+
+    All matched loggers share one file handler, so they write to one file in time order and rotate once.
     """
 
+    _check_rotation(rotation)  # also when no logger matches the prefix
+
     # Iterate over all loggers in the logging manager
     is_first = True
     first_logger = None
+    shared_file_handler = None
     for logger_name in logging.Logger.manager.loggerDict.keys():
         if logger_name.startswith(prefix):
-            current_logger = get_logger(logger_name, logger_format=new_format, file_path=new_path,
-                                        backup_count=backup_count, use_console=use_console, level=level)
+            current_logger = _get_logger(logger_name, new_format, new_path, backup_count, use_console, level,
+                                         rotation, shared_file_handler)
 
             if is_first:
                 is_first = False
                 first_logger = current_logger
-            if backup_count != 0:
-                backup_count = 0
+                shared_file_handler = _logger_file_handler_cache.get(logger_name)
 
     return first_logger

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-common
-Version: 2.0.1
+Version: 2.2.0
 Summary: echoss AI Bigdata Center 공통 유틸리티 라이브러리 (Logger, JsonLogDict, config_fileformat)
 License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
@@ -34,6 +34,19 @@ pip install echoss-common
 - Python >= 3.12
 - pyyaml > 6.0.2
 
+## 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` … 로 회전합니다(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 변경 사항
 
 호출 방식(함수 이름·인자 이름·인자 순서)은 1.2.0 과 같습니다. 아래 네 가지는 **동작이 바뀌는 호환 단절**입니다.
@@ -88,9 +101,16 @@ logger = get_logger(
     file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
     backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
     use_console=True,                  # 콘솔 출력 여부
-    level='DEBUG'                      # 로그 레벨
+    level='DEBUG',                     # 로그 레벨
+    rotation='midnight'                # 회전 방식: 'midnight'(기본) | 'none' | '50m'
 )
 
+# 회전하지 않고 한 파일에 계속 쌓기
+event_logger = get_logger('events', file_path='logs/events.jsonl', rotation='none')
+
+# 50 MiB 마다 회전, 회전 파일 10개 보관
+big_logger = get_logger('big', file_path='logs/big.log', rotation='50m', backup_count=10)
+
 logger.info("애플리케이션 시작")
 logger.debug("디버그 메시지")
 logger.error("오류 발생")
@@ -116,11 +136,20 @@ modify_loggers_by_prefix(
 
 #### 로그 회전
 
-파일 로그는 매일 자정에 날짜를 붙인 파일(`myapp.log.2026-10-10`)로 회전합니다.
+`rotation` 인자로 고릅니다.
 
-- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다.
-- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 날짜 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다. 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+| `rotation` | 동작 | 회전 파일 | `backup_count` |
+|---|---|---|---|
+| `'midnight'` (기본) | 매일 자정에 회전 | `myapp.log.2026-10-10` | 0 이면 전부 보관, N 이면 N 개 |
+| `'50m'` (`'{숫자}m'`, MiB) | 파일이 그 크기를 넘기 전에 회전 | `myapp.log.50m.2026-11-01.001`, `.002` … (회전한 날짜와 그날의 일련번호) | 0 이면 전부 보관, N 이면 가장 새 N 개 |
+| `'none'` | 회전하지 않음 — 파일이 끝없이 커집니다 | 없음 | 쓰지 않음 |
+
+- 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — `1m`~`9m` 4 자리, `10m`~`99m` 3 자리, `100m`~`999m` 2 자리, `1000m` 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 `ls` 화면 순서만 어긋납니다(`ls -v` 로 봅니다).
+- 같은 파일에 쓰는 로거는 **로거 이름도 같게** 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 `modify_loggers_by_prefix` 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
+- Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(`PermissionError`), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 `.1` 로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
+- 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 `backup_count` 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows `PermissionError`) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 `RuntimeWarning` 을 냅니다. 그동안 회전 파일이 `backup_count` 보다 많을 수 있습니다.
 - 알려진 한계: 복사와 비우기 사이에 **다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다.** 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
+- **정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다.** 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: `f"logs/app.{os.getpid()}.log"`). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. `get_app_logger()` 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.
 
 #### JsonLogDict 사용 예시
 
@@ -238,7 +267,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 
 ## API 참조
 
-### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |----------|------|--------|------|
@@ -248,8 +277,9 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 (0이면 전부 보관) |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 — `'midnight'` · `'none'` · `'{숫자}m'`(MiB, 예 `'50m'`). 그 밖은 `ValueError` |
 
-### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level)`
+### `get_app_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)`
 
 `get_logger()`와 동일한 파라미터를 받지만, `@cache` 데코레이터로 감싸져 있어 동일한 인자로 호출할 경우 항상 같은 로거 인스턴스를 반환합니다. 애플리케이션 전역에서 하나의 로거를 공유할 때 적합합니다.
 
@@ -261,6 +291,7 @@ dict_dump(settings, 'config/settings.yaml', force_write=False)
 | `backup_count` | int | `0` | 보관할 로테이팅 파일 수 |
 | `use_console` | bool | `True` | 콘솔 출력 여부 |
 | `level` | str\|int | `'DEBUG'` | 로그 레벨 |
+| `rotation` | str | `'midnight'` | 회전 방식 (`get_logger` 와 같음) |
 
 ### `JsonLogDict(data)`
 

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

@@ -16,6 +16,7 @@ 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/test_echoss_logger_rotation_modes.py
 tests/scripts/check_xml_samples.py
 tests/scripts/hold_file.py
 tests/scripts/spike_default_log_file.py

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

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

{echoss_common-2.0.1 → echoss_common-2.2.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)
@@ -218,13 +220,13 @@ def test_stale_stream_check_off_keeps_2_0_0_layout(tmp_path, monkeypatch):
 # T-08
 @pytest.mark.parametrize("func, params", [
     (echoss_common.get_app_logger,
-     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level"]),
+     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level", "rotation"]),
     (echoss_common.get_logger,
-     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level"]),
+     ["logger_name", "logger_format", "file_path", "backup_count", "use_console", "level", "rotation"]),
     (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"]),
+     ["prefix", "new_format", "new_path", "backup_count", "use_console", "level", "rotation"]),
     (echoss_common.dict_load, ["file_path", "file_format", "kwargs"]),
     (echoss_common.dict_dump, ["config", "file_path", "file_format", "force_write", "xml_tag", "kwargs"]),
 ])

echoss_common-2.2.0/tests/test_echoss_logger_rotation_modes.py

@@ -0,0 +1,401 @@
+import json
+import logging
+import os
+import subprocess
+import sys
+import time
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+
+import pytest
+
+import echoss_common.echoss_logger as echoss_logger
+
+MIB = 1024 * 1024
+LINE = "x" * 1000
+
+
+@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 _file_handlers(logger):
+    return [h for h in logger.handlers if isinstance(h, logging.FileHandler)]
+
+
+def _numbers(paths):
+    found = []
+    for path in paths:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            found.append(int(line.split(" ", 1)[0]))
+    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}")
+
+
+# T-R1
+def test_default_rotation_is_midnight(tmp_path):
+    logger = echoss_logger.get_logger("rm-default", file_path=str(tmp_path / "d.log"), use_console=False)
+
+    [handler] = _file_handlers(logger)
+    assert type(handler) is echoss_logger.CopyTruncateRotatingHandler
+    assert handler.when == "MIDNIGHT"
+
+
+# T-R2
+def test_size_rotation_names_limit_and_backup_count(tmp_path):
+    log_file = tmp_path / "s.log"
+    logger = echoss_logger.get_logger("rm-size", logger_format="%(message)s", file_path=str(log_file),
+                                      backup_count=2, use_console=False, rotation="1m", level="INFO")
+    written = 3500  # about 3.4 MiB: enough for more rotations than backup_count
+    _write(logger, written)
+
+    files = sorted(tmp_path.iterdir())
+    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
+
+
+# T-R3
+@pytest.mark.parametrize("rotation", ["1g", "1k", "50", 50, "1M", "0m", "01m", "50mb", " 50m", "size"])
+def test_invalid_rotation_raises(tmp_path, rotation):
+    with pytest.raises(ValueError):
+        echoss_logger.get_logger("rm-bad", file_path=str(tmp_path / "b.log"), use_console=False, rotation=rotation)
+
+
+@pytest.mark.parametrize("rotation", ["1m", "50m", "2048m", "midnight", "none"])
+def test_valid_rotation_accepted(tmp_path, rotation):
+    logger = echoss_logger.get_logger("rm-ok", file_path=str(tmp_path / "ok.log"), use_console=False,
+                                      rotation=rotation)
+    assert len(_file_handlers(logger)) == 1
+
+
+# T-R4
+def test_none_rotation_keeps_one_file(tmp_path):
+    log_file = tmp_path / "n.log"
+    logger = echoss_logger.get_logger("rm-none", logger_format="%(message)s", file_path=str(log_file),
+                                      use_console=False, rotation="none", level="INFO")
+    [handler] = _file_handlers(logger)
+    assert type(handler) is logging.FileHandler
+
+    _write(logger, 1200)
+
+    assert [f.name for f in tmp_path.iterdir()] == ["n.log"]
+    assert _numbers([log_file]) == list(range(1200))
+
+
+# T-R5 (Linux stand-in for Windows: the real blocked path is judged by the Windows run)
+def test_size_rotation_falls_back_to_copy_truncate_when_rename_is_blocked(tmp_path, monkeypatch):
+    log_file = tmp_path / "blk.log"
+    real_rename = os.rename
+
+    def blocked_rename(src, dst):
+        if os.path.abspath(src) == str(log_file):
+            raise PermissionError("simulated: another handle keeps the file open")
+        return real_rename(src, dst)
+
+    monkeypatch.setattr(os, "rename", blocked_rename)
+    logger = echoss_logger.get_logger("rm-blk", logger_format="%(message)s", file_path=str(log_file),
+                                      backup_count=10, use_console=False, rotation="1m", level="INFO")
+    written = 2500
+    _write(logger, written)
+
+    files = sorted(tmp_path.iterdir())
+    assert _rotated("blk.log", 1)[0] in [f.name for f in files]
+    assert sorted(_numbers(files)) == list(range(written))
+
+
+# T-R6
+@pytest.mark.parametrize("rotation", ["midnight", "1m", "none"])
+def test_jsonl_path_writes_json_lines_in_every_mode(tmp_path, rotation):
+    log_file = tmp_path / "j.jsonl"
+    logger = echoss_logger.get_logger("rm-jsonl", file_path=str(log_file), use_console=False,
+                                      rotation=rotation, level="INFO")
+    logger.info("hello")
+    logger.info({"k": 1})
+
+    lines = log_file.read_text(encoding="utf-8").splitlines()
+    assert len(lines) == 2
+    assert all(isinstance(json.loads(line), dict) for line in lines)
+
+
+# T-R7
+def test_changing_rotation_on_same_path_replaces_handler(tmp_path):
+    log_file = str(tmp_path / "c.log")
+    logger = echoss_logger.get_logger("rm-change", file_path=log_file, use_console=False)
+    [old] = _file_handlers(logger)
+
+    logger = echoss_logger.get_logger("rm-change", file_path=log_file, use_console=False, rotation="none")
+
+    [new] = _file_handlers(logger)
+    assert new is not old
+    assert type(new) is logging.FileHandler
+    assert old.stream is None  # closed
+
+
+def _third_party_loggers(prefix):
+    loggers = [logging.getLogger(f"{prefix}{name}") for name in ("a", "b", "c")]
+    for logger in loggers:
+        logger.addHandler(logging.StreamHandler())  # each package's own handler, to be replaced
+    return loggers
+
+
+# T-R11
+@pytest.mark.parametrize("rotation", ["midnight", "1m", "none"])
+def test_modify_loggers_by_prefix_shares_one_file_handler(tmp_path, rotation):
+    log_file = tmp_path / "shared.log"
+    loggers = _third_party_loggers(f"rm11{rotation}.")
+
+    echoss_logger.modify_loggers_by_prefix(f"rm11{rotation}.", new_format="%(message)s", new_path=str(log_file),
+                                           backup_count=2, use_console=False, level="INFO", rotation=rotation)
+
+    handlers = [_file_handlers(logger) for logger in loggers]
+    assert all(len(h) == 1 for h in handlers)
+    assert handlers[0][0] is handlers[1][0] is handlers[2][0]
+    assert all(len(logger.handlers) == 1 for logger in loggers)  # package handlers removed
+
+    count = 3500 if rotation == "1m" else 30  # 1m: more rotations than backup_count=2
+    for n in range(count):
+        loggers[n % 3].info(f"{n} {LINE}")
+    files = sorted(tmp_path.iterdir())
+    kept = sorted(_numbers(files))
+    if rotation == "1m":
+        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:
+        assert [f.name for f in files] == ["shared.log"]
+        assert kept == list(range(count))
+
+
+# T-R3 (modify_loggers_by_prefix checks rotation even when no logger matches)
+def test_modify_loggers_by_prefix_rejects_invalid_rotation_without_match():
+    with pytest.raises(ValueError):
+        echoss_logger.modify_loggers_by_prefix("rm-no-such-prefix.", rotation="1g")
+
+
+# T-R12
+def test_reconfiguring_one_shared_logger_keeps_the_others_writing(tmp_path):
+    log_file = tmp_path / "shared.log"
+    a, b, c = _third_party_loggers("rm12.")
+    echoss_logger.modify_loggers_by_prefix("rm12.", new_format="%(message)s", new_path=str(log_file),
+                                           use_console=False, level="INFO")
+
+    echoss_logger.get_logger("rm12.a", logger_format="%(message)s", file_path=str(tmp_path / "other.log"),
+                             use_console=False, level="INFO")
+    b.info("1 b")
+    c.info("2 c")
+    a.info("3 a")
+
+    assert _numbers([log_file]) == [1, 2]
+    assert _numbers([tmp_path / "other.log"]) == [3]
+
+
+# T-R13
+def test_modify_loggers_by_prefix_twice_does_not_duplicate_handlers(tmp_path):
+    log_file = str(tmp_path / "shared.log")
+    loggers = _third_party_loggers("rm13.")
+    for _ in range(2):
+        echoss_logger.modify_loggers_by_prefix("rm13.", new_path=log_file, backup_count=1, use_console=False)
+
+    handlers = [_file_handlers(logger) for logger in loggers]
+    assert all(len(h) == 1 for h in handlers)
+    assert handlers[0][0] is handlers[1][0] is handlers[2][0]
+
+
+# T-R8 ~ T-R10: another process holds a file. On Linux nothing is blocked, so only the Windows run judges them.
+REPO_ROOT = Path(__file__).resolve().parents[1]
+HOLD_FILE = REPO_ROOT / "tests" / "scripts" / "hold_file.py"
+
+
+@contextmanager
+def _held(path):
+    holder = subprocess.Popen([sys.executable, str(HOLD_FILE), str(path)],
+                              stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+    try:
+        assert holder.stdout.readline().strip() == "ready"
+        yield
+    finally:
+        holder.stdin.close()
+        holder.wait(timeout=10)
+
+
+def _size_logger(name, log_file, backup_count):
+    return echoss_logger.get_logger(name, logger_format="%(message)s", file_path=str(log_file),
+                                    backup_count=backup_count, use_console=False, rotation="1m", level="INFO")
+
+
+# T-R8
+def test_size_rotation_keeps_every_record_while_another_process_holds_the_current_file(tmp_path):
+    log_file = tmp_path / "h8.log"
+    logger = _size_logger("rm-h8", log_file, 10)
+    written = 3500
+    with _held(log_file):
+        _write(logger, written)
+
+    files = sorted(tmp_path.iterdir())
+    assert any(f.name.startswith("h8.log.1m.") for f in files)
+    assert sorted(_numbers(files)) == list(range(written))
+
+
+# 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, 1)
+    first = 1200  # one rotation, so the first rotated file exists
+    _write(logger, first)
+    numbered = tmp_path / _rotated("h9.log", 1)[0]
+    assert numbered.exists()
+    more = 2400  # two more rotations try to delete it while it is held
+    with _held(numbered):
+        _write(logger, more, start=first)
+
+    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
+def test_none_rotation_keeps_every_record_while_another_process_holds_the_file(tmp_path):
+    log_file = tmp_path / "h10.log"
+    logger = echoss_logger.get_logger("rm-h10", logger_format="%(message)s", file_path=str(log_file),
+                                      use_console=False, rotation="none", level="INFO")
+    with _held(log_file):
+        _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"]