rainbow-rb-utils 0.0.9.dev5__py3-none-any.whl

rainbow/rb_utils/parser.py

@@ -0,0 +1,165 @@
+"""
+[파서 유틸리티]
+"""
+
+import json
+from collections.abc import (
+    Mapping,
+)
+from datetime import datetime
+from typing import Any
+
+import numpy as np
+
+try:
+    import orjson
+except ImportError:
+    orjson = None
+
+
+def bytes_to_str(b: bytes, encoding: str = "utf-8", errors: str = "strict") -> str:
+    return b.decode(encoding, errors)
+
+
+def _orjson_default(obj: Any) -> Any:
+    if np is not None and isinstance(obj, np.generic):
+        return obj.item()
+    if isinstance(obj, bytes | bytearray | memoryview):
+        if isinstance(obj, memoryview):
+            obj = bytes(obj)
+        try:
+            return obj.decode("utf-8")
+        except UnicodeDecodeError:
+            return list(obj)
+    if isinstance(obj, set):
+        return list(obj)
+
+    to_list = getattr(obj, "tolist", None)
+    if callable(to_list):
+        return to_list()
+
+    obj_dict = getattr(obj, "__dict__", None)
+    if obj_dict is not None:
+        return obj_dict
+
+    slots = getattr(type(obj), "__slots__", None)
+    if slots:
+        return {key: getattr(obj, key, None) for key in slots}
+
+    raise TypeError(f"Object of type {type(obj)!r} is not JSON serializable")
+
+
+def _t_to_dict_via_orjson(obj: Any) -> Any:
+    if orjson is None:
+        raise TypeError("orjson unavailable")
+
+    return orjson.loads(
+        orjson.dumps(
+            obj,
+            default=_orjson_default,
+            option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY,
+        )
+    )
+
+
+def snake_to_camel(s: str) -> str:
+    """
+    - s: 스네이크 케이스 문자열
+    - 스네이크 케이스 문자열을 카멜 케이스 문자열로 변환
+    """
+    parts = s.split("_")
+    return "".join(p[:1].upper() + p[1:] for p in parts if p)
+
+
+def camel_to_snake(s: str) -> str:
+    """
+    - s: 카멜 케이스 문자열
+    - 카멜 케이스 문자열을 스네이크 케이스 문자열로 변환
+    """
+    return "".join("_" + word.lower() if word.isupper() else word for word in s).lstrip("_")
+
+
+def t_to_dict(obj: Any) -> Any:
+    """
+    - obj: 객체
+    - 객체를 딕셔너리로 변환
+    """
+    # numpy scalar (np.float32, np.int64 등) -> Python scalar
+    if np is not None and isinstance(obj, np.generic):
+        return obj.item()
+    # 원시형
+    if obj is None or isinstance(obj, bool | int | float | str):
+        return obj
+    # numpy 배열
+    if np is not None and isinstance(obj, np.ndarray):
+        return obj.tolist()
+    # bytes류 → string 디코딩
+    if isinstance(obj, bytes | bytearray | memoryview):
+        if isinstance(obj, memoryview):
+            obj = bytes(obj)
+        try:
+            return obj.decode("utf-8")
+        except UnicodeDecodeError:
+            return list(obj)
+    # dict류
+    if isinstance(obj, Mapping):
+        return {k: t_to_dict(v) for k, v in obj.items()}
+    # 시퀀스
+    if isinstance(obj, list | tuple | set):
+        return [t_to_dict(v) for v in obj]
+    # 큰 dict-backed/slotted 객체는 C serializer 경로를 우선 시도
+    if orjson is not None and (
+        getattr(obj, "__dict__", None) is not None or getattr(type(obj), "__slots__", None)
+    ):
+        try:
+            return _t_to_dict_via_orjson(obj)
+        except (TypeError, orjson.JSONEncodeError, orjson.JSONDecodeError):
+            pass
+    # 일반/T-object
+    if hasattr(obj, "__dict__"):
+        return {k: t_to_dict(v) for k, v in vars(obj).items()}
+    # 마지막 안전핀
+    return str(obj)
+
+
+def _normalize_filter(filter_: Any) -> dict:
+    """
+    filter_가 None, dict, JSON string 모두 OK.
+    빈 문자열/공백/'null'/'None'이면 {} 반환.
+    """
+    if filter_ is None:
+        return {}
+    if isinstance(filter_, Mapping):
+        return dict(filter_)
+    if isinstance(filter_, str):
+        s = filter_.strip()
+        print("s : ", s)
+        if s == "" or s.lower() in ("null", "none"):
+            return {}
+        try:
+            data = json.loads(s)
+        except Exception as e:
+            raise TypeError(f"filter_ JSON 파싱 실패: {e}") from e
+        if not isinstance(data, dict):
+            raise TypeError("filter_ 문자열은 JSON object여야 합니다.")
+        return data
+    raise TypeError(f"filter_ 타입이 잘못되었습니다: {type(filter_)}")
+
+
+def to_json(obj: Any) -> str:
+    """
+    - obj: 객체
+    - 객체를 JSON 문자열로 변환
+    """
+    return json.dumps(t_to_dict(obj), ensure_ascii=False)
+
+
+def to_iso(val: str | datetime):
+    """
+    - val: 문자열 또는 datetime
+    - 문자열 또는 datetime를 ISO 형식의 문자열로 변환
+    """
+    if isinstance(val, datetime):
+        return val.isoformat()
+
+    return val

rainbow/rb_utils/service_exception.py

@@ -0,0 +1,37 @@
+"""
+[서비스 예외 클래스]
+"""
+from __future__ import (
+    annotations,
+)
+
+from dataclasses import (
+    dataclass,
+)
+from typing import Any
+
+
+@dataclass(slots=True)
+class ServiceException(Exception):
+    """
+    - message: 예외 메시지
+    - status_code: HTTP 상태 코드 (기본: None)
+    """
+    message: str
+    status_code: int | None = None   # HTTP 등
+
+    def __str__(self) -> str:
+        base = self.message
+        if self.status_code is not None:
+            base += f" (status={self.status_code})"
+        return base
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        - message: 예외 메시지
+        - status_code: HTTP 상태 코드
+        """
+        return {
+            "message": self.message,
+            "status_code": self.status_code,
+        }

rainbow_rb_utils-0.0.9.dev5.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+rainbow/rb_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rainbow/rb_utils/asyncio_helper.py,sha256=NhKx63RDOf5Q-fjrKuxYa901eLo1jtaaOL1DWYd-Mzw,4866
+rainbow/rb_utils/date.py,sha256=jw9LyTbNmvWerKK5APqhJi7ScElBla_V0Ez7Sk-eh7M,6396
+rainbow/rb_utils/file.py,sha256=rrQbfRFqemC3fNAT1th4bd75_HSJ6CHhQ2BuJYz_ZAU,1369
+rainbow/rb_utils/flow_manager.py,sha256=Gk67dCQ8_4CvO5qdW7JwtuNh4TKV2eERaPHLwB-Ptpc,13834
+rainbow/rb_utils/helper.py,sha256=0ZfbhbrdA44qak5yNckBuYEbi575Gti0O_ZD1GyBloY,751
+rainbow/rb_utils/manipulate.py,sha256=hnYGa7GhFhku1tfCE0EQKtpFNQkMnunmY9t9QY3_bAM,8254
+rainbow/rb_utils/pagination.py,sha256=5x8JVRj48bqrYVernpBlAfDxMpAkDg5GyqfHESIZMK4,1077
+rainbow/rb_utils/parser.py,sha256=CADqHJkeTU_i3UczUt9e5jv6zzPNc_8mPBMc9uezbeg,4664
+rainbow/rb_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rainbow/rb_utils/service_exception.py,sha256=kXVzY_6eFUm8vEcWALGvOGeekcVK4hCqMFVk4MVrbHM,799
+rainbow_rb_utils-0.0.9.dev5.dist-info/METADATA,sha256=9_WkB1OKKNbSSyc93G4x-bsOUhM9k5KOSh6CAYYzQiY,5228
+rainbow_rb_utils-0.0.9.dev5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rainbow_rb_utils-0.0.9.dev5.dist-info/top_level.txt,sha256=sFePQxnQ07jm2rW5WMQ-MhaAdxyvnPKeXldV_kQjJ_A,8
+rainbow_rb_utils-0.0.9.dev5.dist-info/RECORD,,

rainbow_rb_utils-0.0.9.dev5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rainbow_rb_utils-0.0.9.dev5.dist-info/top_level.txt

@@ -0,0 +1 @@
+rainbow