rainbow-rb-utils 0.0.9.dev43__tar.gz → 0.0.9.dev44__tar.gz

{rainbow_rb_utils-0.0.9.dev43 → rainbow_rb_utils-0.0.9.dev44}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: rainbow-rb-utils
-Version: 0.0.9.dev43
+Version: 0.0.9.dev44
 Summary: Rainbow Python Utilities
 Author-email: Derek <dfd1123@rainbow-robotics.com>
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: psutil<8.0.0,>=7.0.0
-Requires-Dist: rainbow-rb-log==0.0.9.dev43
+Requires-Dist: rainbow-rb-log==0.0.9.dev44
 
 # rb_utils
 
@@ -113,12 +113,60 @@ from rb_utils.file import sanitize_filename
 safe_name = sanitize_filename("../../report?.csv")
 ```
 
-## 7) `rb_utils.pagination`
+## 7) `rb_utils.env`
+
+- `env_get(key, default=None, start=None)`: `os.environ` 우선, 이후 가까운 `.env.development` → `.env` 순서로 값 조회
+- `load_env(start=None, override=False)`: 가까운 env 파일들을 `os.environ`에 로드
+- `iter_env_paths(start=None)`: 실제 읽을 env 파일 목록을 우선순위 순서로 반환
+- `parse_env_file(path)`: env 파일을 dict로 파싱
+
+예시:
+
+새 코드에서 값 하나를 바로 읽을 때는 `load_env()`가 필요 없습니다.
+
+```python
+from rb_utils.env import env_get
+
+username = env_get("MONGO_USERNAME")
+password = env_get("MONGO_PASSWORD")
+host = env_get("MONGO_HOST", "127.0.0.1")
+```
+
+기존 코드가 `os.getenv(...)`를 많이 쓰고 있으면 프로세스 시작 시 한 번만 로드합니다.
+
+```python
+import os
+
+from rb_utils.env import load_env
+
+load_env()
+
+username = os.getenv("MONGO_USERNAME")
+password = os.getenv("MONGO_PASSWORD")
+```
+
+기본 우선순위:
+
+1. 현재 위치에서 가장 가까운 `.env.development`
+2. 같은 디렉토리의 `.env`
+3. 부모 디렉토리의 `.env.development`
+4. 부모 디렉토리의 `.env`
+
+즉 개발 환경에서는 `.env.development`가 `.env` 값을 덮어씁니다.
+운영 빌드에는 `.env.development`를 copy하지 않으므로 `.env`만 적용됩니다.
+
+다른 suffix가 필요하면 명시적으로 지정:
+
+```python
+env_get("KEY", env_files=(".env.local", ".env.development", ".env"))
+```
+
+## 8) `rb_utils.pagination`
 
 - `class PageInfo(TypedDict)`: 페이지 응답 메타 타입 (`mode/page/pages/limit/total/sort/order`)
 - `class LogsResponse(TypedDict)`: 로그 목록 응답 타입 (`items`, `pageInfo`)
 
-## 8) `rb_utils.helper`
+## 9) `rb_utils.helper`
 
 - `ManipulateZenohResHelper(obj)`: Zenoh 응답 객체 보정 유틸 의도 함수
 

{rainbow_rb_utils-0.0.9.dev43 → rainbow_rb_utils-0.0.9.dev44}/README.md

@@ -103,12 +103,60 @@ from rb_utils.file import sanitize_filename
 safe_name = sanitize_filename("../../report?.csv")
 ```
 
-## 7) `rb_utils.pagination`
+## 7) `rb_utils.env`
+
+- `env_get(key, default=None, start=None)`: `os.environ` 우선, 이후 가까운 `.env.development` → `.env` 순서로 값 조회
+- `load_env(start=None, override=False)`: 가까운 env 파일들을 `os.environ`에 로드
+- `iter_env_paths(start=None)`: 실제 읽을 env 파일 목록을 우선순위 순서로 반환
+- `parse_env_file(path)`: env 파일을 dict로 파싱
+
+예시:
+
+새 코드에서 값 하나를 바로 읽을 때는 `load_env()`가 필요 없습니다.
+
+```python
+from rb_utils.env import env_get
+
+username = env_get("MONGO_USERNAME")
+password = env_get("MONGO_PASSWORD")
+host = env_get("MONGO_HOST", "127.0.0.1")
+```
+
+기존 코드가 `os.getenv(...)`를 많이 쓰고 있으면 프로세스 시작 시 한 번만 로드합니다.
+
+```python
+import os
+
+from rb_utils.env import load_env
+
+load_env()
+
+username = os.getenv("MONGO_USERNAME")
+password = os.getenv("MONGO_PASSWORD")
+```
+
+기본 우선순위:
+
+1. 현재 위치에서 가장 가까운 `.env.development`
+2. 같은 디렉토리의 `.env`
+3. 부모 디렉토리의 `.env.development`
+4. 부모 디렉토리의 `.env`
+
+즉 개발 환경에서는 `.env.development`가 `.env` 값을 덮어씁니다.
+운영 빌드에는 `.env.development`를 copy하지 않으므로 `.env`만 적용됩니다.
+
+다른 suffix가 필요하면 명시적으로 지정:
+
+```python
+env_get("KEY", env_files=(".env.local", ".env.development", ".env"))
+```
+
+## 8) `rb_utils.pagination`
 
 - `class PageInfo(TypedDict)`: 페이지 응답 메타 타입 (`mode/page/pages/limit/total/sort/order`)
 - `class LogsResponse(TypedDict)`: 로그 목록 응답 타입 (`items`, `pageInfo`)
 
-## 8) `rb_utils.helper`
+## 9) `rb_utils.helper`
 
 - `ManipulateZenohResHelper(obj)`: Zenoh 응답 객체 보정 유틸 의도 함수
 

{rainbow_rb_utils-0.0.9.dev43 → rainbow_rb_utils-0.0.9.dev44}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rainbow-rb-utils"
-version = "0.0.9.dev43"
+version = "0.0.9.dev44"
 requires-python = ">=3.11"
 description = "Rainbow Python Utilities"
 authors = [
@@ -14,7 +14,7 @@ readme = "README.md"
 
 dependencies = [
     "psutil>=7.0.0,<8.0.0",
-    "rainbow-rb-log==0.0.9.dev43",
+    "rainbow-rb-log==0.0.9.dev44",
 ]
 
 [tool.setuptools]

rainbow_rb_utils-0.0.9.dev44/src/rainbow/rb_utils/env.py

@@ -0,0 +1,131 @@
+"""Environment file lookup helpers.
+
+The default lookup order is intentionally local-first:
+
+1. nearest ``.env.development``
+2. nearest ``.env``
+3. parent ``.env.development``
+4. parent ``.env``
+5. ...
+
+Existing process environment values always win unless ``override=True`` is
+explicitly requested.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+DEFAULT_ENV_FILES = (".env.development", ".env")
+_ASSIGNMENT_RE = re.compile(r"^(?:export\s+)?(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?P<value>.*)$")
+
+
+def _start_path(start: str | os.PathLike[str] | None) -> Path:
+    if start is not None:
+        path = Path(start).expanduser()
+        return path if path.is_dir() else path.parent
+
+    meipass = getattr(sys, "_MEIPASS", None)
+    if meipass:
+        return Path(meipass)
+
+    return Path.cwd()
+
+
+def iter_env_paths(
+    start: str | os.PathLike[str] | None = None,
+    *,
+    env_files: Iterable[str] = DEFAULT_ENV_FILES,
+) -> list[Path]:
+    """Return existing env files in lookup precedence order.
+
+    The nearest directory wins over parents, and within each directory the
+    order of ``env_files`` is preserved.
+    """
+    base = _start_path(start).resolve()
+    names = tuple(env_files)
+    paths: list[Path] = []
+
+    for directory in (base, *base.parents):
+        for name in names:
+            candidate = directory / name
+            if candidate.is_file():
+                paths.append(candidate)
+
+    return paths
+
+
+def parse_env_file(path: str | os.PathLike[str]) -> dict[str, str]:
+    """Parse a simple dotenv-style file without mutating ``os.environ``."""
+    values: dict[str, str] = {}
+    env_path = Path(path)
+
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        match = _ASSIGNMENT_RE.match(line)
+        if match is None:
+            continue
+
+        key = match.group("key")
+        raw_value = match.group("value").strip()
+        try:
+            parsed = shlex.split(raw_value, comments=True, posix=True)
+        except ValueError:
+            parsed = [raw_value]
+        values[key] = parsed[0] if parsed else ""
+
+    return values
+
+
+def load_env(
+    start: str | os.PathLike[str] | None = None,
+    *,
+    env_files: Iterable[str] = DEFAULT_ENV_FILES,
+    override: bool = False,
+) -> list[Path]:
+    """Load nearest env files into ``os.environ``.
+
+    Returns the files that were read, in precedence order. With the default
+    ``override=False``, earlier files win because later files only fill missing
+    keys.
+    """
+    loaded = iter_env_paths(start, env_files=env_files)
+
+    for path in loaded:
+        for key, value in parse_env_file(path).items():
+            if override or key not in os.environ:
+                os.environ[key] = value
+
+    return loaded
+
+
+def env_get(
+    key: str,
+    default: object = None,
+    *,
+    start: str | os.PathLike[str] | None = None,
+    env_files: Iterable[str] = DEFAULT_ENV_FILES,
+) -> str | object:
+    """Read an environment value with local ``.env`` fallback.
+
+    ``os.environ`` has first priority, then nearest env files in this order:
+    ``.env.development``, ``.env``, parent ``.env.development``, parent
+    ``.env``, and so on.
+    """
+    if key in os.environ:
+        return os.environ[key]
+
+    for path in iter_env_paths(start, env_files=env_files):
+        values = parse_env_file(path)
+        if key in values:
+            return values[key]
+
+    return default

{rainbow_rb_utils-0.0.9.dev43 → rainbow_rb_utils-0.0.9.dev44}/src/rainbow_rb_utils.egg-info/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: rainbow-rb-utils
-Version: 0.0.9.dev43
+Version: 0.0.9.dev44
 Summary: Rainbow Python Utilities
 Author-email: Derek <dfd1123@rainbow-robotics.com>
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: psutil<8.0.0,>=7.0.0
-Requires-Dist: rainbow-rb-log==0.0.9.dev43
+Requires-Dist: rainbow-rb-log==0.0.9.dev44
 
 # rb_utils
 
@@ -113,12 +113,60 @@ from rb_utils.file import sanitize_filename
 safe_name = sanitize_filename("../../report?.csv")
 ```
 
-## 7) `rb_utils.pagination`
+## 7) `rb_utils.env`
+
+- `env_get(key, default=None, start=None)`: `os.environ` 우선, 이후 가까운 `.env.development` → `.env` 순서로 값 조회
+- `load_env(start=None, override=False)`: 가까운 env 파일들을 `os.environ`에 로드
+- `iter_env_paths(start=None)`: 실제 읽을 env 파일 목록을 우선순위 순서로 반환
+- `parse_env_file(path)`: env 파일을 dict로 파싱
+
+예시:
+
+새 코드에서 값 하나를 바로 읽을 때는 `load_env()`가 필요 없습니다.
+
+```python
+from rb_utils.env import env_get
+
+username = env_get("MONGO_USERNAME")
+password = env_get("MONGO_PASSWORD")
+host = env_get("MONGO_HOST", "127.0.0.1")
+```
+
+기존 코드가 `os.getenv(...)`를 많이 쓰고 있으면 프로세스 시작 시 한 번만 로드합니다.
+
+```python
+import os
+
+from rb_utils.env import load_env
+
+load_env()
+
+username = os.getenv("MONGO_USERNAME")
+password = os.getenv("MONGO_PASSWORD")
+```
+
+기본 우선순위:
+
+1. 현재 위치에서 가장 가까운 `.env.development`
+2. 같은 디렉토리의 `.env`
+3. 부모 디렉토리의 `.env.development`
+4. 부모 디렉토리의 `.env`
+
+즉 개발 환경에서는 `.env.development`가 `.env` 값을 덮어씁니다.
+운영 빌드에는 `.env.development`를 copy하지 않으므로 `.env`만 적용됩니다.
+
+다른 suffix가 필요하면 명시적으로 지정:
+
+```python
+env_get("KEY", env_files=(".env.local", ".env.development", ".env"))
+```
+
+## 8) `rb_utils.pagination`
 
 - `class PageInfo(TypedDict)`: 페이지 응답 메타 타입 (`mode/page/pages/limit/total/sort/order`)
 - `class LogsResponse(TypedDict)`: 로그 목록 응답 타입 (`items`, `pageInfo`)
 
-## 8) `rb_utils.helper`
+## 9) `rb_utils.helper`
 
 - `ManipulateZenohResHelper(obj)`: Zenoh 응답 객체 보정 유틸 의도 함수
 

{rainbow_rb_utils-0.0.9.dev43 → rainbow_rb_utils-0.0.9.dev44}/src/rainbow_rb_utils.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 src/rainbow/rb_utils/__init__.py
 src/rainbow/rb_utils/asyncio_helper.py
 src/rainbow/rb_utils/date.py
+src/rainbow/rb_utils/env.py
 src/rainbow/rb_utils/file.py
 src/rainbow/rb_utils/flow_manager.py
 src/rainbow/rb_utils/helper.py

rainbow_rb_utils-0.0.9.dev44/src/rainbow_rb_utils.egg-info/requires.txt

@@ -0,0 +1,2 @@
+psutil<8.0.0,>=7.0.0
+rainbow-rb-log==0.0.9.dev44

rainbow_rb_utils-0.0.9.dev43/src/rainbow_rb_utils.egg-info/requires.txt

@@ -1,2 +0,0 @@
-psutil<8.0.0,>=7.0.0
-rainbow-rb-log==0.0.9.dev43