Skip to main content

echoss-common

echoss AI Bigdata Center 공통 유틸리티 라이브러리입니다. 로깅(Logger)과 config 파일 포맷 읽기/쓰기, 설정 파일의 비밀값 자리표시자 치환(EnvConfig) 기능을 제공합니다.

문서 지도

  • prior-work.jsonl — 작업원장. 이전 작업의 결론·이미 해본 것·백로그 (조사 착수 전 조회)
  • docs/ — PDCA 계획·설계·분석 문서

설치

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 … 로 회전합니다(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 과 같습니다. 아래 네 가지는 동작이 바뀌는 호환 단절입니다.

바뀐 것 1.2.0 2.0.0 대응
기본 로그 파일 file_path 를 주지 않으면 logs/echoss.log 에 기록 파일을 만들지 않고 콘솔만 파일 로그가 필요하면 file_path 를 지정 (modify_loggers_by_prefix 는 new_path)
없는 설정 파일 dict_load 가 오류 로그를 남기고 빈 dict 반환 FileNotFoundError 경로를 확인하거나 예외를 처리
YAML 저장 키 순서 키를 정렬해 저장 넣은 순서대로 저장 —
설정 파일 인코딩 운영체제 기본 인코딩(Windows 는 CP949 등) 항상 UTF-8 로 읽고 씀 UTF-8 이 아닌 설정 파일은 UTF-8 로 변환

그 밖의 변경:

  • import echoss_common 이 더 이상 파일이나 폴더를 만들지 않습니다(1.2.0 은 import 만으로 logs/echoss.log 를 만들어, 쓰기 금지 폴더에서는 import 가 실패했습니다).
  • 로그 회전은 Windows 에서 다른 프로세스가 로그 파일을 열고 있어도 기록을 잃지 않습니다(아래 「로그 회전」).
  • 지원하지 않는 형식을 읽으면 호출마다 새 빈 dict 를 돌려줍니다(1.2.0 은 같은 dict 객체를 공유했습니다).

기능

1. Logger (echoss_logger)

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

함수 및 클래스 목록

이름 종류 설명
get_logger() 함수 새 로거 생성 또는 기존 로거 갱신
get_app_logger() 함수 동일 인자로 항상 같은 로거를 반환하는 캐시 기반 로거
use_logger() 함수 이미 생성된 로거를 서브모듈에서 가져오기
set_logger_level() 함수 로거 레벨 변경
modify_loggers_by_prefix() 함수 이름 prefix로 여러 로거를 일괄 수정
JsonLogDict 클래스 임의 값을 JSON 문자열로 변환하여 로그 출력

상수

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

사용 예시

from echoss_common import get_logger, get_app_logger, use_logger, set_logger_level, modify_loggers_by_prefix, LOG_FORMAT_DETAIL, JsonLogDict

# 기본 로거 생성 (콘솔 + 파일 출력)
logger = get_logger(
    logger_name='myapp',
    logger_format=LOG_FORMAT_DETAIL,   # 상세 포맷 사용 (선택)
    file_path='logs/myapp.log',        # 로그 파일 경로 (기본: None — 파일 없이 콘솔만)
    backup_count=7,                    # 보관할 로그 파일 수 (0이면 전부 보관)
    use_console=True,                  # 콘솔 출력 여부
    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("오류 발생")

# 캐시 기반 싱글턴 로거 (동일 인자로 호출 시 항상 같은 인스턴스 반환)
app_logger = get_app_logger(logger_name='myapp', file_path='logs/myapp.log')

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

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

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

로그 회전

rotation 인자로 고릅니다.

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' 회전하지 않음 — 파일이 끝없이 커집니다 없음 쓰지 않음
  • 크기 회전의 일련번호 자리수는 크기 숫자의 자리수로 정합니다 — 1m9m 4 자리, 10m99m 3 자리, 100m~999m 2 자리, 1000m 이상 1 자리. 하루 약 10 GB 를 넘게 써서 자리수를 넘으면 번호가 그대로 길어집니다. 보관 순서는 숫자로 비교하므로 맞고, 리눅스 ls 화면 순서만 어긋납니다(ls -v 로 봅니다).
  • 같은 파일에 쓰는 로거는 로거 이름도 같게 합니다. 이름이 다르면 같은 파일을 핸들러 둘이 열게 됩니다. 외부 패키지 로거를 한 파일로 모을 때는 modify_loggers_by_prefix 를 씁니다 — 대상 로거들이 핸들러 하나를 공유합니다.
  • Windows 에서 다른 프로세스가 로그 파일을 열고 있어 이름 바꾸기가 막히면(PermissionError), 회전 파일에 내용을 복사한 뒤 원본을 비우고 계속 씁니다(자정 회전, 그리고 크기 회전에서 현재 파일을 회전 파일로 옮기는 단계). 날짜 파일이 이미 있으면(다른 프로세스가 먼저 회전) 덮어쓰지 않습니다.
  • 회전 파일 이름은 한 번 붙이면 바꾸지 않습니다. 회전할 때 backup_count 를 넘는 옛 회전 파일을 지우는데, 다른 프로그램이 그 파일을 열고 있어 막히면(Windows PermissionError) 지우기를 건너뛰고 다음 회전에서 다시 지웁니다. 기록은 잃지 않고, 핸들러마다 처음 한 번 RuntimeWarning 을 냅니다. 그동안 회전 파일이 backup_count 보다 많을 수 있습니다.
  • 알려진 한계: 복사와 비우기 사이에 다른 프로세스가 같은 파일에 쓴 줄은 사라질 수 있습니다. 이 틈은 회전 한 번(보통 자정)뿐입니다. 두 프로세스가 같은 파일에 동시에 쓰는 것 자체도 회전과 무관하게 줄을 잃을 수 있으므로 피합니다.
  • 정책: 프로세스가 다르면 같은 로그 파일을 쓰지 않습니다. 워커·컨테이너·인스턴스마다 파일 이름을 다르게 합니다(예: f"logs/app.{os.getpid()}.log"). 각 프로세스가 따로 회전하므로, 같은 파일을 쓰면 회전이 겹쳐 기록이 빠지거나 다른 날짜 파일에 들어가고, 드물게 날짜 파일 하나가 통째로 덮어써집니다. get_app_logger() 로 같은 로거를 받거나 fork 전에 만든 로거를 물려받아도 같습니다 — 공유는 한 프로세스 안에서만 됩니다. 구현으로 해결되면 이 정책을 풉니다.

JsonLogDict 사용 예시

로그 메시지에 dict, list 등 복잡한 데이터를 JSON 형태로 출력할 때 사용합니다. str() 또는 repr() 호출 시 JSON 문자열로 변환되며, JSON 직렬화가 불가능한 객체는 str()로 폴백합니다.

from echoss_common import get_logger, JsonLogDict

logger = get_logger('myapp')

# dict → JSON 문자열로 로그 출력
data = {"user": "kim", "age": 20, "active": True}
logger.info("사용자 정보: %s", JsonLogDict(data))
# 출력: 사용자 정보: {"user": "kim", "age": 20, "active": true}

# list, tuple 등도 지원
logger.debug("결과 목록: %s", JsonLogDict([1, 2, 3]))
# 출력: 결과 목록: [1, 2, 3]

# 중첩 구조도 지원
payload = {"tags": ["a", "b"], "meta": {"version": 1}}
logger.info("페이로드: %s", JsonLogDict(payload))

JSONL 구조화 로그

file_path의 확장자가 .jsonl이면 각 로그 레코드는 한 줄의 JSON 객체로 저장됩니다. 구조화된 데이터를 유지하려면 JsonLogDict를 메시지 자체로 전달해야 합니다.

from echoss_common import get_logger, JsonLogDict

logger = get_logger(
    "myapp",
    file_path="logs/myapp.jsonl",
    use_console=False,
)

logger.info(JsonLogDict({"user": "kim", "action": "login"}))
# {"timestamp": "...", "level": "INFO", "logger_name": "myapp",
#  "message": {"user": "kim", "action": "login"}}

다음 방식은 JSONL 행 자체는 유효하지만, JsonLogDict가 문자열 템플릿에 먼저 합쳐져 message가 문자열이 됩니다.

logger.info("payload: %s", JsonLogDict({"user": "kim"}))
# message 값은 'payload: {"user": "kim"}' 문자열이 됩니다.

2. config_fileformat (config_fileformat)

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

함수 목록

함수 설명
dict_load() 설정 파일을 dict로 읽기
dict_dump() dict를 설정 파일로 쓰기
EnvConfig.load() · .dump() ${이름} 자리표시자를 .env · 환경변수 값으로 바꿔 읽고, 자리표시자를 되살려 쓰기 (2.3.0, 아래 「비밀값 자리표시자」)

지원 포맷

확장자 포맷
.yaml, .yml YAML
.json JSON
.xml XML 설정
.properties Java Properties

XML을 읽을 때는 문서의 루트 태그를 포함한 딕셔너리를 반환합니다. XML 속성은 @name, 속성 또는 자식 요소와 함께 있는 직접 본문은 #text, 같은 이름의 반복 요소는 리스트로 표현합니다. XML을 쓸 때는 xml_tag를 지정하거나 딕셔너리에 루트 키가 하나 있어야 합니다.

  • 파일은 항상 UTF-8 로 읽고 씁니다(XML 은 문서 선언을 따릅니다).
  • 없는 파일을 읽으면 FileNotFoundError 가 납니다. 지원하지 않는 형식은 파일을 열지 않고 오류 로그와 함께 빈 dict 를 돌려줍니다.
  • JSON 파일의 최상위가 배열이면 list 를 반환합니다.
  • YAML 로 저장할 때 키 순서를 유지합니다.

사용 예시

from echoss_common import dict_load, dict_dump

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

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

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

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

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

# XML 파일 읽기와 쓰기
xml_config = dict_load('config/settings.xml')
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 또는 운영체제 환경변수에 둡니다.

# 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=...
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 참조

get_logger(logger_name, logger_format, file_path, backup_count, use_console, level, rotation)

파라미터 타입 기본값 설명
logger_name str 'echoss' 로거 이름
logger_format str LOG_FORMAT 로그 포맷 문자열
file_path str|None None 로그 파일 경로 (None이면 파일 미사용)
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, rotation)

get_logger()와 동일한 파라미터를 받지만, @cache 데코레이터로 감싸져 있어 동일한 인자로 호출할 경우 항상 같은 로거 인스턴스를 반환합니다. 애플리케이션 전역에서 하나의 로거를 공유할 때 적합합니다.

파라미터 타입 기본값 설명
logger_name str 'echoss' 로거 이름
logger_format str LOG_FORMAT 로그 포맷 문자열
file_path str|None None 로그 파일 경로 (None이면 파일 미사용)
backup_count int 0 보관할 로테이팅 파일 수
use_console bool True 콘솔 출력 여부
level str|int 'DEBUG' 로그 레벨
rotation str 'midnight' 회전 방식 (get_logger 와 같음)

JsonLogDict(data)

파라미터 타입 설명
data Any JSON으로 변환할 값 (dict, list, tuple, str, int, float, bool, None, Mapping 등)

str() 또는 repr() 호출 시 json.dumps()를 사용해 JSON 문자열을 반환합니다. Mapping 타입은 자동으로 dict로 변환되며, JSON 직렬화가 불가능한 객체는 str()로 폴백합니다.

dict_load(file_path, file_format, **kwargs)

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

반환은 dict 입니다(JSON 최상위가 배열이면 list). 파일이 없으면 FileNotFoundError 를 냅니다.

dict_dump(config, file_path, file_format, force_write, xml_tag, **kwargs)

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

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 가 없을 때만 새로 만듭니다.


라이선스

Apache License 2.0 (자세한 내용은 LICENSE 참고)

echoss AI Bigdata Center

참고(비공식 요청, 라이선스 조건 아님): 코드를 수정하여 재배포하실 경우 12cm에 사전 통보해 주시면 감사하겠습니다.

Metadata

Release files for echoss-common 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for echoss-common 2.3.0
File Size Uploaded Provenance Actions
echoss_common-2.3.0.tar.gz 41.1 kB Without provenance Details for echoss_common-2.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for echoss-common 2.3.0
File Interpreter ABI Platform Actions
echoss_common-2.3.0-py3-none-any.whl Python 3 none any Details for echoss_common-2.3.0-py3-none-any.whl

Total release size: 62.3 kB

Release files / echoss_common-2.3.0.tar.gz

Download URL echoss_common-2.3.0.tar.gz
Size 41.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5cf1e26af5f44685e6fbc4d68251f5e3966545397dc78377d76c85cb40a31774
BLAKE2b-256 checksum
How to use checksums
d527883710fff984f6662f3a7a018ca816349e76704997b8405650fc3cbf2944
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / echoss_common-2.3.0-py3-none-any.whl

Download URL echoss_common-2.3.0-py3-none-any.whl
Size 21.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea0c3b87b8d7bbe49c525954fc000f210c408f0d66c37bdc844cf92a8c3cdc0f
BLAKE2b-256 checksum
How to use checksums
50de49bdfea3e0cfd04a2b95b4af70a4be135f008521c556c55c1a1138dd9f96
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for echoss-common 2.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page