rainbow-rb-utils 0.0.9.dev5__tar.gz

rainbow_rb_utils-0.0.9.dev5/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: rainbow-rb-utils
+Version: 0.0.9.dev5
+Summary: Rainbow Python Utilities
+Author-email: Derek <dfd1123@rainbow-robotics.com>
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: psutil<8.0.0,>=7.0.0
+Requires-Dist: rainbow-rb-log==0.0.9.dev5
+
+# rb_utils
+
+`rb_utils`는 백엔드 전반에서 재사용하는 유틸리티 모음 패키지입니다.
+
+## 모듈/함수 상세
+
+## 1) `rb_utils.parser`
+
+- `snake_to_camel(s: str) -> str`: snake_case 문자열을 CamelCase 형태로 변환
+- `camel_to_snake(s: str) -> str`: CamelCase 문자열을 snake_case로 변환
+- `t_to_dict(obj: Any) -> Any`: 중첩 객체(FlatBuffer T, dict/list/tuple/set, bytes, numpy 배열)를 Python 기본 타입으로 재귀 변환
+- `_normalize_filter(filter_: Any) -> dict`: `None/dict/JSON 문자열`을 공통 dict로 정규화
+- `to_json(obj: Any) -> str`: `t_to_dict` 결과를 JSON 문자열로 직렬화
+- `to_iso(val: str | datetime) -> str`: datetime이면 ISO 문자열, 문자열이면 그대로 반환
+
+예시:
+
+```python
+from rb_utils.parser import t_to_dict, to_json
+
+payload_dict = t_to_dict(obj_payload)
+payload_json = to_json(obj_payload)
+```
+
+## 2) `rb_utils.flow_manager`
+
+- `safe_eval_expr(expr, variables=None, get_global_variable=None) -> Any`: 제한된 AST 규칙으로 안전 평가
+- `_pick_target_loop(func, provided) -> asyncio.AbstractEventLoop | None`: callable 실행 대상 loop 선택
+- `call_with_matching_args(func, **provided) -> Any`: 함수 시그니처에 맞춰 인자만 골라 호출 (sync/async 공통)
+- `eval_value(value, variables=None, get_global_variable=None) -> Any`: 문자열/리스트/튜플/딕셔너리를 재귀 평가
+- `make_builtins_allow_most() -> dict`: 위험 builtins 제외한 builtins dict 생성
+
+예시:
+
+```python
+from rb_utils.flow_manager import eval_value
+
+value = eval_value("a + 10", variables={"local": {"a": 5}, "global": {}})
+# value == 15
+```
+
+## 3) `rb_utils.asyncio_helper`
+
+- `spawn(coro, *, name=None, log_ex=True)`: 현재 loop에 task 생성 후 완료/예외 로깅
+- `_ensure_private_loop() -> asyncio.AbstractEventLoop`: 전용 백그라운드 loop 확보
+- `fire_and_log(coro, *, name=None, loop=None)`: 현재 loop/외부 loop/전용 loop에 안전하게 실행
+- `_attach_done_logging(fut_or_task, *, name=None)`: Future/Task 완료 시 예외 로깅 callback 연결
+
+예시:
+
+```python
+from rb_utils.asyncio_helper import fire_and_log
+
+fire_and_log(socket_client.emit("muscat/program/log", {"msg": "hello"}), name="program-log")
+```
+
+## 4) `rb_utils.service_exception`
+
+- `class ServiceException(Exception)`:
+  - 필드: `message: str`, `status_code: int | None`
+  - `__str__()`: `message (status=...)` 형태 출력
+  - `to_dict()`: `{message, status_code}` 반환
+
+예시:
+
+```python
+from rb_utils.service_exception import ServiceException
+
+raise ServiceException("invalid request", status_code=400)
+```
+
+## 5) `rb_utils.date`
+
+- `is_valid_date(d)`: `date/str/int(timestamp)` 유효성 검사
+- `timestamp_ms_to_seconds(timestamp, tz=UTC)`: ms/seconds timestamp를 seconds로 정규화
+- `is_has_time(s: str)`: 문자열에 시간 정보 포함 여부 판단
+- `parse_date_with_time(mode, d, tz=UTC)`: 날짜/문자열/타임스탬프를 timezone-aware datetime으로 변환
+- `ensure_datetime(dt, tz)`: `date | datetime`을 지정 tz의 datetime으로 보정
+- `_tz(tz_name)`: timezone 캐시 조회
+- `convert_dt(local, in_tz, out_tz)`: 입력 tz 기준 datetime/date를 출력 tz로 변환
+- `get_current_dt_yyyymmddhhmmss(tz)`: 현재 시각을 `YYYYMMDDHHMMSS` 문자열 반환
+
+예시:
+
+```python
+from rb_utils.date import parse_date_with_time
+from datetime import UTC
+
+dt = parse_date_with_time("start", "2026-02-25", tz=UTC)
+```
+
+## 6) `rb_utils.file`
+
+- `content_disposition_header(filename) -> str`: 다운로드용 `Content-Disposition` 헤더 생성
+- `sanitize_filename(name, default="export.csv", max_name_len=100) -> str`: OS 금지문자 제거/길이 제한
+- `get_env_path() -> Path | None`: 실행 위치 기준으로 `.env` 파일 탐색
+
+예시:
+
+```python
+from rb_utils.file import sanitize_filename
+
+safe_name = sanitize_filename("../../report?.csv")
+```
+
+## 7) `rb_utils.pagination`
+
+- `class PageInfo(TypedDict)`: 페이지 응답 메타 타입 (`mode/page/pages/limit/total/sort/order`)
+- `class LogsResponse(TypedDict)`: 로그 목록 응답 타입 (`items`, `pageInfo`)
+
+## 8) `rb_utils.helper`
+
+- `ManipulateZenohResHelper(obj)`: Zenoh 응답 객체 보정 유틸 의도 함수
+
+주의:
+- 현재 구현은 dict 처리가 아닌 `.hasAttr/.set` 접근과 즉시 `ValueError`를 포함하므로, 사용 전 동작 검증이 필요합니다.
+
+## 실무 사용 패턴
+
+- FlatBuffer/SDK 응답 평탄화: `t_to_dict`
+- Flow step 동적 인자 평가: `eval_value`, `safe_eval_expr`
+- 비동기 fire-and-forget + 예외 로깅: `fire_and_log`
+- 서비스 레이어 공통 예외: `ServiceException`
+- 파일 다운로드/이름 정리: `content_disposition_header`, `sanitize_filename`
+
+## 공통 주의사항
+
+- `flow_manager` 평가기는 허용된 연산/함수만 실행합니다.
+- timezone 변환 함수는 `Asia/Seoul` 같은 IANA tz 문자열을 명시해야 합니다.

rainbow_rb_utils-0.0.9.dev5/README.md

@@ -0,0 +1,129 @@
+# rb_utils
+
+`rb_utils`는 백엔드 전반에서 재사용하는 유틸리티 모음 패키지입니다.
+
+## 모듈/함수 상세
+
+## 1) `rb_utils.parser`
+
+- `snake_to_camel(s: str) -> str`: snake_case 문자열을 CamelCase 형태로 변환
+- `camel_to_snake(s: str) -> str`: CamelCase 문자열을 snake_case로 변환
+- `t_to_dict(obj: Any) -> Any`: 중첩 객체(FlatBuffer T, dict/list/tuple/set, bytes, numpy 배열)를 Python 기본 타입으로 재귀 변환
+- `_normalize_filter(filter_: Any) -> dict`: `None/dict/JSON 문자열`을 공통 dict로 정규화
+- `to_json(obj: Any) -> str`: `t_to_dict` 결과를 JSON 문자열로 직렬화
+- `to_iso(val: str | datetime) -> str`: datetime이면 ISO 문자열, 문자열이면 그대로 반환
+
+예시:
+
+```python
+from rb_utils.parser import t_to_dict, to_json
+
+payload_dict = t_to_dict(obj_payload)
+payload_json = to_json(obj_payload)
+```
+
+## 2) `rb_utils.flow_manager`
+
+- `safe_eval_expr(expr, variables=None, get_global_variable=None) -> Any`: 제한된 AST 규칙으로 안전 평가
+- `_pick_target_loop(func, provided) -> asyncio.AbstractEventLoop | None`: callable 실행 대상 loop 선택
+- `call_with_matching_args(func, **provided) -> Any`: 함수 시그니처에 맞춰 인자만 골라 호출 (sync/async 공통)
+- `eval_value(value, variables=None, get_global_variable=None) -> Any`: 문자열/리스트/튜플/딕셔너리를 재귀 평가
+- `make_builtins_allow_most() -> dict`: 위험 builtins 제외한 builtins dict 생성
+
+예시:
+
+```python
+from rb_utils.flow_manager import eval_value
+
+value = eval_value("a + 10", variables={"local": {"a": 5}, "global": {}})
+# value == 15
+```
+
+## 3) `rb_utils.asyncio_helper`
+
+- `spawn(coro, *, name=None, log_ex=True)`: 현재 loop에 task 생성 후 완료/예외 로깅
+- `_ensure_private_loop() -> asyncio.AbstractEventLoop`: 전용 백그라운드 loop 확보
+- `fire_and_log(coro, *, name=None, loop=None)`: 현재 loop/외부 loop/전용 loop에 안전하게 실행
+- `_attach_done_logging(fut_or_task, *, name=None)`: Future/Task 완료 시 예외 로깅 callback 연결
+
+예시:
+
+```python
+from rb_utils.asyncio_helper import fire_and_log
+
+fire_and_log(socket_client.emit("muscat/program/log", {"msg": "hello"}), name="program-log")
+```
+
+## 4) `rb_utils.service_exception`
+
+- `class ServiceException(Exception)`:
+  - 필드: `message: str`, `status_code: int | None`
+  - `__str__()`: `message (status=...)` 형태 출력
+  - `to_dict()`: `{message, status_code}` 반환
+
+예시:
+
+```python
+from rb_utils.service_exception import ServiceException
+
+raise ServiceException("invalid request", status_code=400)
+```
+
+## 5) `rb_utils.date`
+
+- `is_valid_date(d)`: `date/str/int(timestamp)` 유효성 검사
+- `timestamp_ms_to_seconds(timestamp, tz=UTC)`: ms/seconds timestamp를 seconds로 정규화
+- `is_has_time(s: str)`: 문자열에 시간 정보 포함 여부 판단
+- `parse_date_with_time(mode, d, tz=UTC)`: 날짜/문자열/타임스탬프를 timezone-aware datetime으로 변환
+- `ensure_datetime(dt, tz)`: `date | datetime`을 지정 tz의 datetime으로 보정
+- `_tz(tz_name)`: timezone 캐시 조회
+- `convert_dt(local, in_tz, out_tz)`: 입력 tz 기준 datetime/date를 출력 tz로 변환
+- `get_current_dt_yyyymmddhhmmss(tz)`: 현재 시각을 `YYYYMMDDHHMMSS` 문자열 반환
+
+예시:
+
+```python
+from rb_utils.date import parse_date_with_time
+from datetime import UTC
+
+dt = parse_date_with_time("start", "2026-02-25", tz=UTC)
+```
+
+## 6) `rb_utils.file`
+
+- `content_disposition_header(filename) -> str`: 다운로드용 `Content-Disposition` 헤더 생성
+- `sanitize_filename(name, default="export.csv", max_name_len=100) -> str`: OS 금지문자 제거/길이 제한
+- `get_env_path() -> Path | None`: 실행 위치 기준으로 `.env` 파일 탐색
+
+예시:
+
+```python
+from rb_utils.file import sanitize_filename
+
+safe_name = sanitize_filename("../../report?.csv")
+```
+
+## 7) `rb_utils.pagination`
+
+- `class PageInfo(TypedDict)`: 페이지 응답 메타 타입 (`mode/page/pages/limit/total/sort/order`)
+- `class LogsResponse(TypedDict)`: 로그 목록 응답 타입 (`items`, `pageInfo`)
+
+## 8) `rb_utils.helper`
+
+- `ManipulateZenohResHelper(obj)`: Zenoh 응답 객체 보정 유틸 의도 함수
+
+주의:
+- 현재 구현은 dict 처리가 아닌 `.hasAttr/.set` 접근과 즉시 `ValueError`를 포함하므로, 사용 전 동작 검증이 필요합니다.
+
+## 실무 사용 패턴
+
+- FlatBuffer/SDK 응답 평탄화: `t_to_dict`
+- Flow step 동적 인자 평가: `eval_value`, `safe_eval_expr`
+- 비동기 fire-and-forget + 예외 로깅: `fire_and_log`
+- 서비스 레이어 공통 예외: `ServiceException`
+- 파일 다운로드/이름 정리: `content_disposition_header`, `sanitize_filename`
+
+## 공통 주의사항
+
+- `flow_manager` 평가기는 허용된 연산/함수만 실행합니다.
+- timezone 변환 함수는 `Asia/Seoul` 같은 IANA tz 문자열을 명시해야 합니다.

rainbow_rb_utils-0.0.9.dev5/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rainbow-rb-utils"
+version = "0.0.9.dev5"
+requires-python = ">=3.12,<3.13"
+description = "Rainbow Python Utilities"
+authors = [
+    { name = "Derek", email = "dfd1123@rainbow-robotics.com" },
+]
+readme = "README.md"
+
+dependencies = [
+    "psutil>=7.0.0,<8.0.0",
+    "rainbow-rb-log==0.0.9.dev5",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["rainbow.rb_utils*"]
+
+[tool.setuptools.package-data]
+"*" = ["py.typed"]

rainbow_rb_utils-0.0.9.dev5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rainbow_rb_utils-0.0.9.dev5/src/rainbow/rb_utils/asyncio_helper.py

@@ -0,0 +1,167 @@
+import asyncio
+import inspect
+import threading
+import time
+from collections.abc import (
+    Awaitable,
+    Coroutine,
+)
+from concurrent.futures import Future
+from typing import Any
+
+from rainbow.rb_log.log import (
+    rb_log,
+)
+
+_running: set[asyncio.Task] = set()
+
+_priv_loop = None
+_priv_thread = None
+_default_loop: asyncio.AbstractEventLoop | None = None
+_error_log_mtx = threading.Lock()
+_last_error_log_ts: dict[str, float] = {}
+
+
+def spawn(coro, *, name=None, log_ex=True):
+    t = asyncio.create_task(coro, name=name)
+    _running.add(t)
+
+    def _done(task: asyncio.Task):
+        _running.discard(task)
+        if log_ex:
+            try:
+                task.result()
+            except Exception as e:
+                rb_log.error(f"[task:{task.get_name() or id(task)}] error: {e}")
+
+    t.add_done_callback(_done)
+    return t
+
+
+async def cancel_all_tasks():
+    for t in list(_running):
+        t.cancel()
+    await asyncio.gather(*_running, return_exceptions=True)
+
+
+def _ensure_private_loop() -> asyncio.AbstractEventLoop:
+    global _priv_loop, _priv_thread
+    if _priv_loop and _priv_loop.is_running():
+        return _priv_loop
+    loop = asyncio.new_event_loop()
+    _priv_loop = loop
+
+    import threading
+
+    def _runner():
+        asyncio.set_event_loop(loop)
+        loop.run_forever()
+
+    _priv_thread = threading.Thread(target=_runner, name="fire-and-log-loop", daemon=True)
+    _priv_thread.start()
+    return loop
+
+
+def set_default_loop(loop: asyncio.AbstractEventLoop | None) -> None:
+    global _default_loop
+    _default_loop = loop
+
+
+def get_default_loop() -> asyncio.AbstractEventLoop | None:
+    return _default_loop
+
+
+async def _await_to_coroutine(awaitable: Awaitable[Any]) -> Any:
+    """Awaitable을 await하여 결과를 반환하는 coroutine으로 변환"""
+    return await awaitable
+
+
+def fire_and_log(
+    coro: Awaitable[Any],
+    *,
+    name: str | None = None,
+    loop: asyncio.AbstractEventLoop | None = None,
+    log_exceptions: bool = True,
+    sample_error_interval_sec: float | None = None,
+):
+    try:
+        running = asyncio.get_running_loop()
+
+        if loop is not None and loop is not running:
+            # run_coroutine_threadsafe는 Coroutine만 받을 수 있으므로 변환
+            coroutine: Coroutine[Any, Any, Any] = (
+                coro if inspect.iscoroutine(coro) else _await_to_coroutine(coro)
+            )
+            fut: Future[Any] = asyncio.run_coroutine_threadsafe(coroutine, loop)
+            _attach_done_logging(
+                fut,
+                name=name,
+                log_exceptions=log_exceptions,
+                sample_error_interval_sec=sample_error_interval_sec,
+            )
+            return fut
+
+        task: asyncio.Task = running.create_task(coro, name=name)  # type: ignore
+        _attach_done_logging(
+            task,
+            name=name,
+            log_exceptions=log_exceptions,
+            sample_error_interval_sec=sample_error_interval_sec,
+        )
+        return task
+    except RuntimeError:
+        target_loop = loop
+        if target_loop is None:
+            target_loop = get_default_loop()
+        if target_loop is None or not target_loop.is_running():
+            target_loop = _ensure_private_loop()
+
+        # run_coroutine_threadsafe는 Coroutine만 받을 수 있으므로 변환
+        coroutine = coro if inspect.iscoroutine(coro) else _await_to_coroutine(coro)
+        fut = asyncio.run_coroutine_threadsafe(coroutine, target_loop)
+        _attach_done_logging(
+            fut,
+            name=name,
+            log_exceptions=log_exceptions,
+            sample_error_interval_sec=sample_error_interval_sec,
+        )
+        return fut
+
+
+def _should_log_sampled(*, key: str, interval_sec: float | None) -> bool:
+    if interval_sec is None or interval_sec <= 0:
+        return True
+
+    now = time.monotonic()
+    with _error_log_mtx:
+        prev = _last_error_log_ts.get(key)
+        if prev is not None and (now - prev) < interval_sec:
+            return False
+        _last_error_log_ts[key] = now
+    return True
+
+
+def _attach_done_logging(
+    fut_or_task,
+    *,
+    name: str | None,
+    log_exceptions: bool,
+    sample_error_interval_sec: float | None,
+):
+    def _done(f):
+        try:
+            _ = f.result()
+        except asyncio.CancelledError:
+            if log_exceptions:
+                rb_log.info(
+                    f"[task:{name or getattr(f, 'get_name', lambda: '')() or id(f)}] cancelled"
+                )
+        except Exception as e:
+            if not log_exceptions:
+                return
+
+            task_name = name or getattr(f, "get_name", lambda: "")() or str(id(f))
+            if _should_log_sampled(key=str(task_name), interval_sec=sample_error_interval_sec):
+                rb_log.error(f"[task:{task_name}] crashed, {e}")
+
+    fut_or_task.add_done_callback(_done)

rainbow_rb_utils-0.0.9.dev5/src/rainbow/rb_utils/date.py

@@ -0,0 +1,221 @@
+"""
+[날짜 유틸리티]
+"""
+from datetime import (
+    UTC,
+    date,
+    datetime,
+    timezone,
+)
+from functools import (
+    lru_cache,
+)
+from typing import Literal
+from zoneinfo import ZoneInfo
+
+_STRPTIME_FORMATS = (
+    "%Y-%m-%dT%H:%M:%S%z",
+    "%Y-%m-%d %H:%M:%S%z",
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%d %H:%M:%S",
+    "%Y/%m/%d %H:%M:%S",
+    "%Y-%m-%dT%H:%M",
+    "%Y-%m-%d %H:%M",
+    "%Y/%m/%d %H:%M",
+    "%Y-%m-%d",
+    "%Y/%m/%d",
+    "%Y%m%d",
+    "%Y%m%d%H%M%S",
+    "%Y%m%d%H%M",
+)
+
+
+def is_valid_date(d: date | str | int):
+    """
+    - d: 날짜 문자열 또는 정수 또는 date
+    - 날짜 형식 검증
+    """
+    if isinstance(d, int):
+        try:
+            sec = timestamp_ms_to_seconds(int(d))
+            if sec <= 0:
+                return False
+            datetime.fromtimestamp(sec, tz=UTC)
+            return True
+        except (ValueError, OverflowError, OSError):
+            return False
+
+    if isinstance(d, str):
+        s = d.strip()
+        if not s:
+            return False
+
+        try:
+            s2 = s[:-1] + "+00:00" if s.endswith("Z") else s
+            datetime.fromisoformat(s2)
+            return True
+        except (ValueError, OverflowError, OSError):
+            pass
+
+        for fmt in _STRPTIME_FORMATS:
+            try:
+                datetime.strptime(s, fmt)
+                return True
+            except (ValueError, OverflowError, OSError):
+                continue
+        return False
+
+    return bool(isinstance(d, date))
+
+def timestamp_ms_to_seconds(timestamp: int, *, tz: timezone = UTC):
+    """
+    - timestamp: 밀리초 단위 타임스탬프
+    - tz: 타임존 (기본: UTC)
+    - 밀리초 단위 타임스탬프를 초 단위 타임스탬프로 변환
+    """
+    if timestamp > 10**12:
+        return datetime.fromtimestamp(timestamp / 1000.0, tz=tz).timestamp()
+    return datetime.fromtimestamp(timestamp, tz=tz).timestamp()
+
+def is_has_time(s: str) -> bool:
+    """
+    - s: 날짜 문자열
+    - 날짜 문자열에 시간이 포함되어 있는지 확인
+    """
+    s = s.strip()
+    if ":" in s or "T" in s:
+        return True
+
+    digits = "".join(ch for ch in s if ch.isdigit())
+    return len(digits) > 8
+
+def parse_date_with_time(
+    mode: Literal["start", "end"], d: str | int | datetime, *, tz: timezone = UTC
+):
+    """
+    - mode: 날짜 타입
+    - d: 날짜 문자열 또는 정수 또는 datetime
+    - tz: 타임존 (기본: UTC)
+    - 날짜 문자열 또는 정수 또는 datetime를 datetime 객체로 변환
+    """
+    if not is_valid_date(d):
+        raise ValueError("Invalid date")
+
+    if isinstance(d, datetime):
+        dt = d
+
+        dt = dt.replace(tzinfo=tz) if dt.tzinfo is None else dt.astimezone(tz)
+
+        has_time = not (dt.hour == 0 and dt.minute == 0 and dt.second == 0 and dt.microsecond == 0)
+    elif isinstance(d, int):
+        sec = timestamp_ms_to_seconds(int(d))
+        dt = datetime.fromtimestamp(sec, tz=tz)
+        has_time = True
+    else:
+        s = d.strip()
+        parsed = None
+
+        try:
+            s2 = s[:-1] + "+00:00" if s.endswith("Z") else s
+            parsed = datetime.fromisoformat(s2)
+        except (ValueError, OverflowError, OSError):
+            parsed = None
+
+        if parsed is None:
+            for fmt in _STRPTIME_FORMATS:
+                try:
+                    parsed = datetime.strptime(s, fmt)
+                    break
+                except (ValueError, OverflowError, OSError):
+                    parsed = None
+
+        if parsed is None:
+            raise ValueError("Unparseable date string")
+
+        parsed = parsed.replace(tzinfo=tz) if parsed.tzinfo is None else parsed.astimezone(tz)
+        dt = parsed
+
+        if is_has_time(s):
+            has_time = True
+        else:
+            has_time = not (
+                dt.hour == 0 and dt.minute == 0 and dt.second == 0 and dt.microsecond == 0
+            )
+
+    if not has_time:
+        if mode == "start":
+            dt = datetime(dt.year, dt.month, dt.day, 0, 0, 0, 0, tzinfo=tz)
+        else:
+            dt = datetime(dt.year, dt.month, dt.day, 23, 59, 59, 999999, tzinfo=tz)
+
+    return dt
+
+# === Yujin Added ===
+
+
+# DateTime으로 변환 (날짜만 들어오면 그날 00:00:00 timezone 시간으로 간주)
+def ensure_datetime(dt: date | datetime, tz:str) -> datetime:
+    """
+    - dt: 날짜 또는 datetime
+    - tz: 타임존
+    - 날짜 또는 datetime를 datetime 객체로 변환
+    """
+    if not tz or not isinstance(tz, str):
+        raise TypeError("timezone must be provided")
+    tz = ZoneInfo(tz)
+
+    if isinstance(dt, datetime):
+        return dt.replace(tzinfo=tz) if dt.tzinfo is None else dt.astimezone(tz)
+
+    if isinstance(dt, date):
+        return dt.combine(dt, datetime.min.time()).replace(tzinfo=tz)
+
+    raise TypeError("dt must be date or datetime")
+
+@lru_cache(maxsize=128)
+def _tz(tz_name: str) -> ZoneInfo:
+    if not tz_name or not isinstance(tz_name, str):
+        raise TypeError("timezone must be a non-empty string (e.g., 'Asia/Seoul').")
+    try:
+        return ZoneInfo(tz_name)
+    except Exception as e:
+        raise ValueError(f"Unknown timezone: {tz_name}") from e
+
+
+# 날짜를 timezone 변환하여 datetime으로 반환
+def convert_dt(
+    local: date | datetime,
+    in_tz: str,
+    out_tz: str,
+) -> datetime:
+    """
+    - local: 날짜 또는 datetime
+    - in_tz: 입력 타임존
+    - out_tz: 출력 타임존
+    - 날짜 또는 datetime를 타임존 변환
+    """
+    tz_in = _tz(in_tz)
+    tz_out = _tz(out_tz)
+    print(f"[convert_dt] tz_in: {tz_in}, tz_out: {tz_out}")
+
+    # datetime 들어온 경우
+    if isinstance(local, datetime):
+        dt_in = local.replace(tzinfo=tz_in) if local.tzinfo is None else local.astimezone(tz_in)
+        dt_out = dt_in.astimezone(tz_out)
+        return dt_out
+
+    # date 들어온 경우 (날짜만 있을 때)
+    if isinstance(local, date):
+        # 그 날짜의 00:00:00 in_tz 로 만든 후 out_tz 로 변환
+        dt_in = datetime.combine(local, datetime.min.time()).replace(tzinfo=tz_in)
+        dt_out = dt_in.astimezone(tz_out)
+        return dt_out
+    raise TypeError("local must be date or datetime")
+
+
+def get_current_dt_yyyymmddhhmmss(tz: str) -> str:
+    """
+    - tz: 타임존
+    - 현재 날짜+시간을 YYYYMMDDHHMMSS로 변환하여 반환
+    """
+    return datetime.now(ZoneInfo(tz)).strftime("%Y%m%d%H%M%s")