rscc-common 0.2.0__tar.gz

rscc_common-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Java
+target/
+*.class
+.flattened-pom.xml
+
+# JS
+node_modules/
+dist/
+*.tgz
+*.tsbuildinfo
+coverage/
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.egg-info/
+build/
+*.whl
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+# 참고: python -m build 의 산출물(dist/)은 위 JS 절의 dist/ 패턴이
+# 경로 전체에 적용되므로 별도 항목 없이 함께 무시된다.
+
+# 로그 (rscc_common.logging 이 자정 롤링 gzip 로그 파일을 생성)
+logs/
+*.log
+
+# IDE / OS
+.idea/
+*.iml
+.vscode/
+.DS_Store
+
+# 환경 파일은 커밋 금지
+.env
+.env.*

rscc_common-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeonghyeon-Ryu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rscc_common-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: rscc-common
+Version: 0.2.0
+Summary: RSCC 공통 Python 라이브러리 — 로깅, X-Trace-Id 전파, CommonResponse, ResultCode, 텍스트 유틸
+Project-URL: Homepage, https://github.com/Jeonghyeon-Ryu/r-common
+Project-URL: Repository, https://github.com/Jeonghyeon-Ryu/r-common
+Project-URL: Changelog, https://github.com/Jeonghyeon-Ryu/r-common/releases
+Author: Jeonghyeon-Ryu
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: httpx>=0.27; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# rscc-common
+
+RSCC 공통 Python 라이브러리 — 공통 로깅, X-Trace-Id 분산 트레이스 전파, CommonResponse
+응답 봉투, ResultCode 에러 코드, 한글 초성 유틸. 기본 설치는 **의존성 0** (표준 라이브러리만) —
+FastAPI/pydantic 통합은 `[fastapi]` extra 로 opt-in 한다.
+
+Java(`com.rscc:rscc-common-*`)·JS(`@rscc/common-*`) 와 같은 저장소에서 **와이어 계약을
+공유하는 폴리글랏 라이브러리**다 — 응답 봉투/에러 코드/트레이스 헤더 규약의 단일 소스는
+[contracts/](https://github.com/Jeonghyeon-Ryu/r-common/tree/master/contracts).
+
+- 저장소: <https://github.com/Jeonghyeon-Ryu/r-common>
+- 변경 이력: [CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md)
+- 라이선스: MIT
+
+## 설치
+
+```bash
+pip install rscc-common               # 기본 — 의존성 0 (errors / logging / trace / text)
+pip install "rscc-common[fastapi]"    # + fastapi>=0.110, httpx>=0.27 (response 모듈 사용 가능)
+```
+
+PyPI 대신 git 태그로 직설치할 수도 있다 (pip 은 서브디렉토리 설치를 지원):
+
+```bash
+pip install "rscc-common[fastapi] @ git+https://github.com/Jeonghyeon-Ryu/r-common.git@py-v0.2.0#subdirectory=python/rscc-common"
+# extra 불필요 시: "rscc-common @ git+https://...#subdirectory=python/rscc-common"
+```
+
+(py-v0.2.0 릴리스 후 유효 — 최신 태그는
+[CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md) 참조.
+`py-v0.1.0` 은 이 문서의 API 일부(`reset_trace_id` 등)가 없는 릴리스 인프라 도입 이전 태그 —
+사용하지 말 것.)
+
+개발(저장소 체크아웃 안, editable — `--reload` 에 즉시 반영):
+`pip install -e "python/rscc-common[fastapi]"`
+
+Python **>= 3.11** (상한 없음). 타입 힌트 포함 (`py.typed` — 소비 측 mypy/pyright 가 읽음).
+
+## 모듈
+
+| 모듈 | 의존성 | 공개 API |
+|---|---|---|
+| `rscc_common` (최상위) | 없음 | `__version__` + 무의존 심볼 재노출 (`ResultCode`, `configure_logging`, `get_trace_id`, `set_trace_id`, `reset_trace_id`, `new_trace_id`, `install_trace_middleware`, `trace_request_hook`, `async_trace_request_hook`) |
+| `rscc_common.errors` | 없음 | `ResultCode` enum — 멤버별 `.code`(str, 와이어는 JSON 문자열) / `.http_status`(int) / `.message`(기본 한국어 메시지). [contracts/error-codes.yaml](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/error-codes.yaml) 과 정확히 동기 (테스트로 강제) |
+| `rscc_common.logging` | 없음 | `configure_logging(log_dir, level, app_name, *, noisy_loggers=..., quiet_uvicorn=...)` — 콘솔 + 자정 롤링 파일(전날분 gzip, 30일 보관). 명시 호출형 (임포트 부작용 없음), 재호출 시 기존 핸들러 close 후 교체 |
+| `rscc_common.trace` | 없음 (순수 ASGI/덕타이핑) | [contracts/trace.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/trace.md) 구현 — `install_trace_middleware(app)`, `get_trace_id()`, `set_trace_id(id) -> Token`, `reset_trace_id(token)`, `new_trace_id()`, httpx 발신 훅 `trace_request_hook` / `async_trace_request_hook`, 상수 `TRACE_HEADER` |
+| `rscc_common.response` | **[fastapi] extra 전용** (pydantic) | `CommonResponse` — 와이어 키 `success/code/message/data`, 팩토리 `ok(data)` / `fail(result_code, message=None)`, `to_wire()` 가 `data=None` 키 생략을 강제 ([contracts/common-response.schema.json](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/common-response.schema.json)) |
+| `rscc_common.text.chosung` | 없음 | `of(s)` — 한글 초성 변환 (예: `"검색 엔진"` → `"ㄱㅅㅇㅈ"`), `is_chosung_query(s)` — 초성 질의 여부. search-api `Chosung.java` / ai-core `chosung.py` 와 골든 벡터 파리티 |
+
+## 사용 예
+
+```python
+from fastapi import FastAPI
+import httpx
+
+from rscc_common import configure_logging, install_trace_middleware, trace_request_hook
+from rscc_common.errors import ResultCode
+from rscc_common.response import CommonResponse   # [fastapi] extra 필요
+
+configure_logging(log_dir="logs", app_name="ai-core",
+                  noisy_loggers=("httpx", "httpcore", "urllib3"), quiet_uvicorn=True)
+
+app = FastAPI()
+install_trace_middleware(app)   # X-Trace-Id 수신 재사용 → contextvar → 응답 에코
+
+# 다운스트림 전파 (trace.md 4단계)
+client = httpx.Client(event_hooks={"request": [trace_request_hook]})
+
+@app.get("/thing")
+def get_thing():
+    return CommonResponse.ok({"id": 1}).to_wire()          # data 포함
+
+@app.get("/missing")
+def missing():
+    return CommonResponse.fail(ResultCode.NOT_FOUND).to_wire()  # data 키 부재
+```
+
+요청 컨텍스트 밖(백그라운드 태스크 등)에서 traceId 를 수동 바인딩할 때:
+
+```python
+from rscc_common import new_trace_id, reset_trace_id, set_trace_id
+
+token = set_trace_id(new_trace_id())   # 또는 요청에서 캡처해 둔 traceId
+try:
+    do_background_work()               # 이 안의 로그·httpx 발신에 traceId 가 실린다
+finally:
+    reset_trace_id(token)              # 이전 값 복원 (권장) — 일회성 태스크는 set_trace_id(None) 도 가능
+```
+
+## 알려진 제약
+
+- **트레이스 미들웨어는 미처리 예외의 500 응답에 `X-Trace-Id` 를 에코하지 못한다** —
+  `app.add_middleware` 등록이 Starlette `ServerErrorMiddleware` 안쪽에서 실행되기 때문.
+  `HTTPException`·검증 오류 등 예외 핸들러가 처리하는 경로(4xx 등)는 정상 에코된다.
+  상세·우회책은 `rscc_common.trace.install_trace_middleware` docstring 참조.
+- `rscc_common.response` 는 **`[fastapi]` extra 설치 후에만 임포트 가능** —
+  기본 설치에서 임포트하면 `ModuleNotFoundError` (pydantic 부재). 나머지 모듈은 기본 설치로 동작.
+- FastAPI 핸들러에서 `CommonResponse` 모델을 **직접 반환하지 말고 반드시 `.to_wire()`** 를
+  반환할 것 — 직접 반환하면 `data: null` 이 와이어에 실려 "실패/무데이터 시 data 키 생략" 계약이 깨진다.
+- `configure_logging` 은 **단일 프로세스**(단일 uvicorn worker) 전제 — 멀티 worker 가 같은
+  로그 파일을 회전시키면 안전하지 않다. `level` 기본값은 `logging.DEBUG` — 프로덕션은
+  `logging.INFO` 권장.
+- `text.chosung.of()` 의 공백 스킵은 스페이스/탭만 (개행·전각 공백은 통과) —
+  Java `Chosung.java` 와의 파리티 제약.
+
+## 테스트 (저장소 체크아웃에서)
+
+```bash
+cd python/rscc-common
+python -m pytest -q    # pyproject 의 pythonpath=["src"] 덕에 설치 없이 바로 동작
+```
+
+테스트 의존성은 pyproject 의 `[dependency-groups] dev` (pytest, pyyaml, fastapi>=0.110,
+httpx>=0.27) — pip 25.1+ 는 `pip install --group dev`. `tests/test_errors.py` 는 저장소의
+`contracts/error-codes.yaml` 과 enum 정합을 비교하며, 파일이 없는 환경(sdist 등)에서는 자동 skip 된다.
+
+## 버전·릴리스
+
+- **버전 단일 소스**: `src/rscc_common/__init__.py` 의 `__version__` —
+  `pyproject.toml` 은 dynamic version 으로 이 값을 읽는다 (릴리스 시 pyproject 수정 불필요).
+- `py-vX.Y.Z` 태그가 push 되면 GitHub Actions
+  ([release-python.yml](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/.github/workflows/release-python.yml))
+  이 태그↔`__version__` 정합 검증 → `python -m build` → **PyPI Trusted Publishing (OIDC)**
+  업로드 → GitHub Release 생성.
+- 절차 상세(runbook)·릴리스 이력:
+  [루트 README](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/README.md) ·
+  [CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md)

rscc_common-0.2.0/README.md

@@ -0,0 +1,127 @@
+# rscc-common
+
+RSCC 공통 Python 라이브러리 — 공통 로깅, X-Trace-Id 분산 트레이스 전파, CommonResponse
+응답 봉투, ResultCode 에러 코드, 한글 초성 유틸. 기본 설치는 **의존성 0** (표준 라이브러리만) —
+FastAPI/pydantic 통합은 `[fastapi]` extra 로 opt-in 한다.
+
+Java(`com.rscc:rscc-common-*`)·JS(`@rscc/common-*`) 와 같은 저장소에서 **와이어 계약을
+공유하는 폴리글랏 라이브러리**다 — 응답 봉투/에러 코드/트레이스 헤더 규약의 단일 소스는
+[contracts/](https://github.com/Jeonghyeon-Ryu/r-common/tree/master/contracts).
+
+- 저장소: <https://github.com/Jeonghyeon-Ryu/r-common>
+- 변경 이력: [CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md)
+- 라이선스: MIT
+
+## 설치
+
+```bash
+pip install rscc-common               # 기본 — 의존성 0 (errors / logging / trace / text)
+pip install "rscc-common[fastapi]"    # + fastapi>=0.110, httpx>=0.27 (response 모듈 사용 가능)
+```
+
+PyPI 대신 git 태그로 직설치할 수도 있다 (pip 은 서브디렉토리 설치를 지원):
+
+```bash
+pip install "rscc-common[fastapi] @ git+https://github.com/Jeonghyeon-Ryu/r-common.git@py-v0.2.0#subdirectory=python/rscc-common"
+# extra 불필요 시: "rscc-common @ git+https://...#subdirectory=python/rscc-common"
+```
+
+(py-v0.2.0 릴리스 후 유효 — 최신 태그는
+[CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md) 참조.
+`py-v0.1.0` 은 이 문서의 API 일부(`reset_trace_id` 등)가 없는 릴리스 인프라 도입 이전 태그 —
+사용하지 말 것.)
+
+개발(저장소 체크아웃 안, editable — `--reload` 에 즉시 반영):
+`pip install -e "python/rscc-common[fastapi]"`
+
+Python **>= 3.11** (상한 없음). 타입 힌트 포함 (`py.typed` — 소비 측 mypy/pyright 가 읽음).
+
+## 모듈
+
+| 모듈 | 의존성 | 공개 API |
+|---|---|---|
+| `rscc_common` (최상위) | 없음 | `__version__` + 무의존 심볼 재노출 (`ResultCode`, `configure_logging`, `get_trace_id`, `set_trace_id`, `reset_trace_id`, `new_trace_id`, `install_trace_middleware`, `trace_request_hook`, `async_trace_request_hook`) |
+| `rscc_common.errors` | 없음 | `ResultCode` enum — 멤버별 `.code`(str, 와이어는 JSON 문자열) / `.http_status`(int) / `.message`(기본 한국어 메시지). [contracts/error-codes.yaml](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/error-codes.yaml) 과 정확히 동기 (테스트로 강제) |
+| `rscc_common.logging` | 없음 | `configure_logging(log_dir, level, app_name, *, noisy_loggers=..., quiet_uvicorn=...)` — 콘솔 + 자정 롤링 파일(전날분 gzip, 30일 보관). 명시 호출형 (임포트 부작용 없음), 재호출 시 기존 핸들러 close 후 교체 |
+| `rscc_common.trace` | 없음 (순수 ASGI/덕타이핑) | [contracts/trace.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/trace.md) 구현 — `install_trace_middleware(app)`, `get_trace_id()`, `set_trace_id(id) -> Token`, `reset_trace_id(token)`, `new_trace_id()`, httpx 발신 훅 `trace_request_hook` / `async_trace_request_hook`, 상수 `TRACE_HEADER` |
+| `rscc_common.response` | **[fastapi] extra 전용** (pydantic) | `CommonResponse` — 와이어 키 `success/code/message/data`, 팩토리 `ok(data)` / `fail(result_code, message=None)`, `to_wire()` 가 `data=None` 키 생략을 강제 ([contracts/common-response.schema.json](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/contracts/common-response.schema.json)) |
+| `rscc_common.text.chosung` | 없음 | `of(s)` — 한글 초성 변환 (예: `"검색 엔진"` → `"ㄱㅅㅇㅈ"`), `is_chosung_query(s)` — 초성 질의 여부. search-api `Chosung.java` / ai-core `chosung.py` 와 골든 벡터 파리티 |
+
+## 사용 예
+
+```python
+from fastapi import FastAPI
+import httpx
+
+from rscc_common import configure_logging, install_trace_middleware, trace_request_hook
+from rscc_common.errors import ResultCode
+from rscc_common.response import CommonResponse   # [fastapi] extra 필요
+
+configure_logging(log_dir="logs", app_name="ai-core",
+                  noisy_loggers=("httpx", "httpcore", "urllib3"), quiet_uvicorn=True)
+
+app = FastAPI()
+install_trace_middleware(app)   # X-Trace-Id 수신 재사용 → contextvar → 응답 에코
+
+# 다운스트림 전파 (trace.md 4단계)
+client = httpx.Client(event_hooks={"request": [trace_request_hook]})
+
+@app.get("/thing")
+def get_thing():
+    return CommonResponse.ok({"id": 1}).to_wire()          # data 포함
+
+@app.get("/missing")
+def missing():
+    return CommonResponse.fail(ResultCode.NOT_FOUND).to_wire()  # data 키 부재
+```
+
+요청 컨텍스트 밖(백그라운드 태스크 등)에서 traceId 를 수동 바인딩할 때:
+
+```python
+from rscc_common import new_trace_id, reset_trace_id, set_trace_id
+
+token = set_trace_id(new_trace_id())   # 또는 요청에서 캡처해 둔 traceId
+try:
+    do_background_work()               # 이 안의 로그·httpx 발신에 traceId 가 실린다
+finally:
+    reset_trace_id(token)              # 이전 값 복원 (권장) — 일회성 태스크는 set_trace_id(None) 도 가능
+```
+
+## 알려진 제약
+
+- **트레이스 미들웨어는 미처리 예외의 500 응답에 `X-Trace-Id` 를 에코하지 못한다** —
+  `app.add_middleware` 등록이 Starlette `ServerErrorMiddleware` 안쪽에서 실행되기 때문.
+  `HTTPException`·검증 오류 등 예외 핸들러가 처리하는 경로(4xx 등)는 정상 에코된다.
+  상세·우회책은 `rscc_common.trace.install_trace_middleware` docstring 참조.
+- `rscc_common.response` 는 **`[fastapi]` extra 설치 후에만 임포트 가능** —
+  기본 설치에서 임포트하면 `ModuleNotFoundError` (pydantic 부재). 나머지 모듈은 기본 설치로 동작.
+- FastAPI 핸들러에서 `CommonResponse` 모델을 **직접 반환하지 말고 반드시 `.to_wire()`** 를
+  반환할 것 — 직접 반환하면 `data: null` 이 와이어에 실려 "실패/무데이터 시 data 키 생략" 계약이 깨진다.
+- `configure_logging` 은 **단일 프로세스**(단일 uvicorn worker) 전제 — 멀티 worker 가 같은
+  로그 파일을 회전시키면 안전하지 않다. `level` 기본값은 `logging.DEBUG` — 프로덕션은
+  `logging.INFO` 권장.
+- `text.chosung.of()` 의 공백 스킵은 스페이스/탭만 (개행·전각 공백은 통과) —
+  Java `Chosung.java` 와의 파리티 제약.
+
+## 테스트 (저장소 체크아웃에서)
+
+```bash
+cd python/rscc-common
+python -m pytest -q    # pyproject 의 pythonpath=["src"] 덕에 설치 없이 바로 동작
+```
+
+테스트 의존성은 pyproject 의 `[dependency-groups] dev` (pytest, pyyaml, fastapi>=0.110,
+httpx>=0.27) — pip 25.1+ 는 `pip install --group dev`. `tests/test_errors.py` 는 저장소의
+`contracts/error-codes.yaml` 과 enum 정합을 비교하며, 파일이 없는 환경(sdist 등)에서는 자동 skip 된다.
+
+## 버전·릴리스
+
+- **버전 단일 소스**: `src/rscc_common/__init__.py` 의 `__version__` —
+  `pyproject.toml` 은 dynamic version 으로 이 값을 읽는다 (릴리스 시 pyproject 수정 불필요).
+- `py-vX.Y.Z` 태그가 push 되면 GitHub Actions
+  ([release-python.yml](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/.github/workflows/release-python.yml))
+  이 태그↔`__version__` 정합 검증 → `python -m build` → **PyPI Trusted Publishing (OIDC)**
+  업로드 → GitHub Release 생성.
+- 절차 상세(runbook)·릴리스 이력:
+  [루트 README](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/README.md) ·
+  [CHANGELOG.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/CHANGELOG.md)

rscc_common-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+# >=1.26 — 아래 PEP 639 표기(license SPDX 문자열 + license-files 평면 배열)를 지원하는 최소 버전.
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rscc-common"
+# version 은 여기 두지 않는다 — src/rscc_common/__init__.py 의 __version__ 이 단일 소스.
+# (두 곳에 적어 두면 릴리스 때 한쪽만 올리는 사고가 나기 쉬워 dynamic 으로 일원화)
+dynamic = ["version"]
+description = "RSCC 공통 Python 라이브러리 — 로깅, X-Trace-Id 전파, CommonResponse, ResultCode, 텍스트 유틸"
+readme = "README.md"
+# PEP 639 SPDX 라이선스 식별자 — 같은 디렉토리의 LICENSE 파일(MIT)과 쌍으로 배포된다.
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jeonghyeon-Ryu" }]
+# 상한을 두지 않는다 — 표준 라이브러리만 쓰는 코어라 새 파이썬(3.14+)에서
+# 설치가 차단될 이유가 없다. 하한 3.11 은 `str | None` 등 문법 사용 때문.
+requires-python = ">=3.11"
+# 기본 설치는 표준 라이브러리만 사용 (의존성 0).
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    # py.typed 마커 동봉 — 소비 측 mypy/pyright 가 타입 힌트를 읽는다
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Jeonghyeon-Ryu/r-common"
+Repository = "https://github.com/Jeonghyeon-Ryu/r-common"
+Changelog = "https://github.com/Jeonghyeon-Ryu/r-common/releases"
+
+[project.optional-dependencies]
+# FastAPI 통합(response.py 의 pydantic 포함)과 httpx 훅 실사용에 필요.
+fastapi = ["fastapi>=0.110", "httpx>=0.27"]
+
+# 개발/테스트 전용 의존성 (PEP 735) — 배포본 의존성 아님.
+# 설치: `pip install --group dev` (pip 25.1+) 또는 개별 pip install.
+[dependency-groups]
+dev = ["pytest", "pyyaml", "fastapi>=0.110", "httpx>=0.27"]
+
+# __version__ 을 빌드 시점에 읽어 패키지 버전으로 쓴다 (위 dynamic 과 쌍).
+[tool.hatch.version]
+path = "src/rscc_common/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rscc_common"]
+
+# src 레이아웃이라 설치 없이는 rscc_common 을 임포트할 수 없다 —
+# pythonpath 로 src 를 얹어 체크아웃 직후 `python -m pytest` 가 바로 돌게 한다.
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

rscc_common-0.2.0/src/rscc_common/__init__.py

@@ -0,0 +1,97 @@
+"""rscc-common — RSCC 공통 Python 라이브러리.
+
+기본 설치는 표준 라이브러리만 사용한다. 여기서 재노출하는 심볼은 모두 무의존 모듈의 것이다.
+`rscc_common.response` (pydantic 필요) 와 `rscc_common.handlers` (fastapi 필요) 는
+`rscc-common[fastapi]` extra 설치 후 서브모듈로 직접 임포트한다 — 패키지 임포트만으로
+pydantic/fastapi 를 요구하지 않기 위해 여기서 재노출하지 않는다.
+
+무의존 유틸 모듈(jwt/datetimes/masking/sse)은 서브모듈 네임스페이스로 재노출한다
+(`from rscc_common import jwt; jwt.decode_token(...)`). 함수가 많고 이름이 일반적이라
+플랫 재노출 대신 네임스페이스로 묶었다.
+"""
+
+from . import (
+    api_key,
+    bizno,
+    bulkhead,
+    cache,
+    circuit_breaker,
+    client_ip,
+    constant_time,
+    datetimes,
+    jwt,
+    log_sanitize,
+    masking,
+    metrics,
+    rate_limit,
+    retry,
+    sse,
+    validation,
+)
+from .access_log import install_access_log
+from .errors import CommonException, ResultCode
+from .logging import configure_logging
+from .rate_limit import install_rate_limit
+from .security_headers import install_security_headers
+from .trace import (
+    async_trace_request_hook,
+    get_trace_id,
+    install_trace_middleware,
+    new_trace_id,
+    reset_trace_id,
+    set_trace_id,
+    trace_request_hook,
+)
+from .user_context import (
+    UserContext,
+    async_user_context_request_hook,
+    get_user_context,
+    install_user_context_middleware,
+    reset_user_context,
+    set_user_context,
+    user_context_request_hook,
+)
+
+# 패키지 버전의 단일 소스 — pyproject.toml 은 dynamic version 으로 이 값을 읽는다.
+# 릴리스 절차: 이 값 수정 → py-vX.Y.Z 태그 push (pyproject 는 건드릴 것 없음).
+__version__ = "0.2.0"
+
+__all__ = [
+    "CommonException",
+    "ResultCode",
+    "UserContext",
+    "api_key",
+    "async_trace_request_hook",
+    "async_user_context_request_hook",
+    "bizno",
+    "bulkhead",
+    "cache",
+    "circuit_breaker",
+    "client_ip",
+    "configure_logging",
+    "constant_time",
+    "datetimes",
+    "get_trace_id",
+    "get_user_context",
+    "install_access_log",
+    "install_rate_limit",
+    "install_security_headers",
+    "install_trace_middleware",
+    "install_user_context_middleware",
+    "jwt",
+    "log_sanitize",
+    "masking",
+    "metrics",
+    "new_trace_id",
+    "rate_limit",
+    "reset_trace_id",
+    "reset_user_context",
+    "retry",
+    "set_trace_id",
+    "set_user_context",
+    "sse",
+    "trace_request_hook",
+    "user_context_request_hook",
+    "validation",
+    "__version__",
+]