pxa-common 0.1.0__tar.gz

pxa_common-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: pxa-common
+Version: 0.1.0
+Summary: PXA 공통 기반 (로깅/예외·에러코드/설정관리/표준 응답포맷/메시지)
+Author: Platform Team
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi==0.128.*
+Requires-Dist: pydantic>=2.7
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+
+# pxa-common
+
+PXA 공통 기반 패키지. **로깅 · 예외처리/에러코드 · 설정파일 관리 · 표준 request/response 포맷 · 메시지 카탈로그** 를 제공합니다.
+
+> **단독 사용 가능** — 네 패키지(`pxa-common`, `pxa-auth`, `pxa-db-connector`, `pxa-extend`)는 서로 의존하지 않습니다. 필요한 것만 골라 설치하세요.
+> 함께 쓰려면 각 패키지의 `integrations.pxa_common` 어댑터를 한 줄 호출하면 됩니다.
+
+PEP 네이밍 점검은 **`pxa-extend`** 로 분리되어 있습니다.
+
+---
+
+## 설치
+
+```bash
+pip install pxa-common --index-url https://nexus.example.com/repository/pypi-internal/simple/
+```
+
+## 1. 표준 응답 포맷
+
+모든 응답의 HTTP status 는 **항상 200**이고, 정상/비정상은 애플리케이션 코드로 구분합니다.
+
+```json
+{ "success": true, "code": "pxa-10000", "message": "정상 처리되었습니다.", "result": {} }
+```
+
+```python
+from pxa_common import ApiResponse
+
+return ApiResponse.ok(result=item, message="조회 성공")   # pxa-10000
+```
+
+- `pxa-10000` 정상 / `pxa-2xxxx` 비정상 (`20001` 검증, `20002` 필수값 누락, `20003` 미인증, `20004` 없음, `20005` 권한, `20006` DB, `20007` 중복)
+- 메시지를 생략하면 메시지 카탈로그에서 코드 메시지를 조회합니다.
+- 에러코드 추가는 `pxa_common/codes.py` 의 `AppCode` 에 한 줄 추가하면 됩니다.
+
+## 2. 예외 처리
+
+```python
+from pxa_common import NotFoundError, register_exception_handlers
+
+register_exception_handlers(app)      # 앱 생성 시 1회
+raise NotFoundError("주문 없음")       # -> HTTP 200 + pxa-20004 표준 응답
+```
+
+`AppError` 계열(`NotFoundError`, `ValidationError`, `RequiredFieldError`, `UnauthorizedError`, `ForbiddenError`, `DbError`, `DuplicatedError`)과 요청 검증 실패, 예상치 못한 예외까지 모두 표준 포맷으로 자동 변환됩니다.
+
+## 3. 설정파일 관리
+
+우선순위: **환경변수(`PXA_*`) > config.yaml > 기본값**. 파일 경로는 `PXA_CONFIG` 로 지정합니다.
+
+```yaml
+app:     { name: "my-service", debug: false }
+logging: { dir: "./logs", level: "INFO" }
+db:      { host: "localhost" }        # 각 패키지가 자기 섹션을 읽어간다
+```
+
+```python
+from pxa_common import load_section
+from pydantic import BaseModel
+
+class DbConfig(BaseModel):
+    host: str = "localhost"
+
+db = load_section("db", DbConfig)     # 공통 모듈은 db 구조를 몰라도 된다
+```
+
+환경변수 override 는 `PXA_DB__HOST=db.internal` 형식입니다.
+
+## 4. 로깅
+
+```python
+from pxa_common import setup_logging
+setup_logging()      # config 의 logging 섹션을 사용
+```
+
+지정 디렉토리에 파일로 저장되며 자정마다 회전합니다(보관일수 설정 가능). 요청 로그는 `RequestLoggingMiddleware` 를 추가하면 request-id 와 처리시간까지 자동 기록됩니다.
+
+## 5. 메시지 카탈로그
+
+```python
+from pxa_common import msg, register_messages
+
+register_messages({"order": {"created": "주문 '{no}' 생성됨"}})
+msg("order.created", no="A-1")        # -> "주문 'A-1' 생성됨"
+```
+
+기본 메시지는 `messages/default.yaml` 에서 자동 로드되고, `config(messages.files)` 로 애플리케이션 YAML 을 추가할 수 있습니다.
+
+## 6. 테스트 & 배포
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+python -m build && twine upload -r nexus dist/*
+```
+
+PEP 네이밍 점검은 `pxa-extend` 의 `pxa-lint` / `pxa-naming` 을 사용합니다.

pxa_common-0.1.0/README.md

@@ -0,0 +1,98 @@
+# pxa-common
+
+PXA 공통 기반 패키지. **로깅 · 예외처리/에러코드 · 설정파일 관리 · 표준 request/response 포맷 · 메시지 카탈로그** 를 제공합니다.
+
+> **단독 사용 가능** — 네 패키지(`pxa-common`, `pxa-auth`, `pxa-db-connector`, `pxa-extend`)는 서로 의존하지 않습니다. 필요한 것만 골라 설치하세요.
+> 함께 쓰려면 각 패키지의 `integrations.pxa_common` 어댑터를 한 줄 호출하면 됩니다.
+
+PEP 네이밍 점검은 **`pxa-extend`** 로 분리되어 있습니다.
+
+---
+
+## 설치
+
+```bash
+pip install pxa-common --index-url https://nexus.example.com/repository/pypi-internal/simple/
+```
+
+## 1. 표준 응답 포맷
+
+모든 응답의 HTTP status 는 **항상 200**이고, 정상/비정상은 애플리케이션 코드로 구분합니다.
+
+```json
+{ "success": true, "code": "pxa-10000", "message": "정상 처리되었습니다.", "result": {} }
+```
+
+```python
+from pxa_common import ApiResponse
+
+return ApiResponse.ok(result=item, message="조회 성공")   # pxa-10000
+```
+
+- `pxa-10000` 정상 / `pxa-2xxxx` 비정상 (`20001` 검증, `20002` 필수값 누락, `20003` 미인증, `20004` 없음, `20005` 권한, `20006` DB, `20007` 중복)
+- 메시지를 생략하면 메시지 카탈로그에서 코드 메시지를 조회합니다.
+- 에러코드 추가는 `pxa_common/codes.py` 의 `AppCode` 에 한 줄 추가하면 됩니다.
+
+## 2. 예외 처리
+
+```python
+from pxa_common import NotFoundError, register_exception_handlers
+
+register_exception_handlers(app)      # 앱 생성 시 1회
+raise NotFoundError("주문 없음")       # -> HTTP 200 + pxa-20004 표준 응답
+```
+
+`AppError` 계열(`NotFoundError`, `ValidationError`, `RequiredFieldError`, `UnauthorizedError`, `ForbiddenError`, `DbError`, `DuplicatedError`)과 요청 검증 실패, 예상치 못한 예외까지 모두 표준 포맷으로 자동 변환됩니다.
+
+## 3. 설정파일 관리
+
+우선순위: **환경변수(`PXA_*`) > config.yaml > 기본값**. 파일 경로는 `PXA_CONFIG` 로 지정합니다.
+
+```yaml
+app:     { name: "my-service", debug: false }
+logging: { dir: "./logs", level: "INFO" }
+db:      { host: "localhost" }        # 각 패키지가 자기 섹션을 읽어간다
+```
+
+```python
+from pxa_common import load_section
+from pydantic import BaseModel
+
+class DbConfig(BaseModel):
+    host: str = "localhost"
+
+db = load_section("db", DbConfig)     # 공통 모듈은 db 구조를 몰라도 된다
+```
+
+환경변수 override 는 `PXA_DB__HOST=db.internal` 형식입니다.
+
+## 4. 로깅
+
+```python
+from pxa_common import setup_logging
+setup_logging()      # config 의 logging 섹션을 사용
+```
+
+지정 디렉토리에 파일로 저장되며 자정마다 회전합니다(보관일수 설정 가능). 요청 로그는 `RequestLoggingMiddleware` 를 추가하면 request-id 와 처리시간까지 자동 기록됩니다.
+
+## 5. 메시지 카탈로그
+
+```python
+from pxa_common import msg, register_messages
+
+register_messages({"order": {"created": "주문 '{no}' 생성됨"}})
+msg("order.created", no="A-1")        # -> "주문 'A-1' 생성됨"
+```
+
+기본 메시지는 `messages/default.yaml` 에서 자동 로드되고, `config(messages.files)` 로 애플리케이션 YAML 을 추가할 수 있습니다.
+
+## 6. 테스트 & 배포
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+python -m build && twine upload -r nexus dist/*
+```
+
+PEP 네이밍 점검은 `pxa-extend` 의 `pxa-lint` / `pxa-naming` 을 사용합니다.

pxa_common-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pxa-common"
+version = "0.1.0"
+description = "PXA 공통 기반 (로깅/예외·에러코드/설정관리/표준 응답포맷/메시지)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Platform Team" }]
+dependencies = [
+    "fastapi==0.128.*",
+    "pydantic>=2.7",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+# PEP 네이밍 점검은 pxa-extend 로 분리되어 있다.
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pxa_common = ["messages/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

pxa_common-0.1.0/setup.cfg

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

pxa_common-0.1.0/src/pxa_common/__init__.py

@@ -0,0 +1,67 @@
+"""pxa-common — PXA 공통 기반 패키지.
+
+로깅 / 예외·에러코드 / 설정파일 관리 / 표준 request·response 포맷 /
+메시지 카탈로그를 제공한다. PEP 네이밍 점검은 pxa-extend 에 있다.
+
+다른 pxa 패키지(pxa-db-connector, pxa-auth)와는 서로 의존하지 않는다.
+함께 쓰려면 각 패키지의 ``integrations.pxa_common`` 어댑터를 호출한다.
+"""
+from .codes import AppCode
+from .config import (
+    AppConfig,
+    LoggingConfig,
+    MessagesConfig,
+    get_app_config,
+    get_logging_config,
+    get_messages_config,
+    get_raw,
+    load_raw,
+    load_section,
+    reload_config,
+)
+from .exceptions import (
+    AppError,
+    DbError,
+    DuplicatedError,
+    ForbiddenError,
+    NotFoundError,
+    RequiredFieldError,
+    UnauthorizedError,
+    ValidationError,
+    register_exception_handlers,
+)
+from .logging_conf import setup_logging
+from .messages import load_message_files, msg, register_messages
+from .middleware import RequestLoggingMiddleware
+from .response import ApiResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApiResponse",
+    "AppCode",
+    "AppConfig",
+    "LoggingConfig",
+    "MessagesConfig",
+    "load_raw",
+    "get_raw",
+    "reload_config",
+    "load_section",
+    "get_app_config",
+    "get_logging_config",
+    "get_messages_config",
+    "setup_logging",
+    "RequestLoggingMiddleware",
+    "register_exception_handlers",
+    "AppError",
+    "NotFoundError",
+    "ValidationError",
+    "RequiredFieldError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "DbError",
+    "DuplicatedError",
+    "msg",
+    "register_messages",
+    "load_message_files",
+]

pxa_common-0.1.0/src/pxa_common/codes.py

@@ -0,0 +1,41 @@
+"""애플리케이션 코드 중앙 관리.
+
+모든 HTTP 응답은 200 으로 내려가며, 정상/비정상은 애플리케이션 코드로 구분한다.
+
+  - pxa-10000 : 정상
+  - pxa-2xxxx : 비정상(에러)
+
+새로운 에러코드가 필요하면 이 Enum 에만 추가한다.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AppCode(str, Enum):
+    """애플리케이션 코드. (코드, 기본 메시지, HTTP 상태) 를 함께 보유한다."""
+
+    # ---- 정상 ----
+    SUCCESS = ("pxa-10000", "정상 처리되었습니다.", 200)
+
+    # ---- 비정상 (공통) ----
+    UNKNOWN_ERROR = ("pxa-20000", "알 수 없는 오류가 발생했습니다.", 200)
+    VALIDATION_ERROR = ("pxa-20001", "요청 데이터 검증에 실패했습니다.", 200)
+    REQUIRED_FIELD_MISSING = ("pxa-20002", "필수 데이터가 누락되었습니다.", 200)
+    UNAUTHORIZED = ("pxa-20003", "인증이 필요합니다.", 200)
+    NOT_FOUND = ("pxa-20004", "데이터를 찾을 수 없습니다.", 200)
+    FORBIDDEN = ("pxa-20005", "권한이 없습니다.", 200)
+    DB_ERROR = ("pxa-20006", "데이터베이스 처리 중 오류가 발생했습니다.", 200)
+    DUPLICATED = ("pxa-20007", "이미 존재하는 데이터입니다.", 200)
+
+    def __new__(cls, code: str, message: str, http_status: int):
+        obj = str.__new__(cls, code)
+        obj._value_ = code
+        obj.code = code
+        obj.message = message
+        obj.http_status = http_status
+        return obj
+
+    @property
+    def is_success(self) -> bool:
+        return self.code.startswith("pxa-1")

pxa_common-0.1.0/src/pxa_common/config.py

@@ -0,0 +1,113 @@
+"""설정 파일 관리 (코드와 환경값 분리).
+
+- YAML config 파일 + 환경변수에서 설정을 읽는다.
+- 우선순위: 환경변수(PXA_*) > config.yaml > 기본값
+- config 파일 경로는 환경변수 ``PXA_CONFIG`` 로 지정한다.
+
+각 패키지(db-connector, auth)는 자신의 설정 모델을 정의하고
+``load_section("db", DbConfig)`` 처럼 자기 섹션만 읽어간다.
+따라서 공통 모듈이 DB/인증 설정을 알 필요가 없다(느슨한 결합).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Type, TypeVar
+
+import yaml
+
+from .fastapi import BaseModel, Field
+
+DEFAULT_CONFIG_PATH = "config/config.yaml"
+
+M = TypeVar("M", bound=BaseModel)
+
+_raw_cache: Optional[dict] = None
+
+
+class AppConfig(BaseModel):
+    name: str = "pxa-app"
+    debug: bool = False
+
+
+class LoggingConfig(BaseModel):
+    dir: str = "./logs"
+    level: str = "INFO"
+    filename: str = "app.log"
+    rotate_when: str = "midnight"
+    backup_count: int = 14
+
+
+class MessagesConfig(BaseModel):
+    files: list[str] = Field(default_factory=list)
+
+
+def _apply_env_overrides(data: dict) -> dict:
+    """PXA_SECTION__KEY 형태의 환경변수로 설정을 덮어쓴다.
+
+    예) PXA_DB__HOST=db.internal  ->  data['db']['host'] = 'db.internal'
+    """
+    prefix = "PXA_"
+    for env_key, env_val in os.environ.items():
+        if not env_key.startswith(prefix) or env_key == "PXA_CONFIG":
+            continue
+        path = env_key[len(prefix):].lower().split("__")
+        cursor = data
+        for part in path[:-1]:
+            # 같은 자리에 스칼라가 있으면 dict 로 바꾼다(설정 병합 중 타입 충돌 방지)
+            if not isinstance(cursor.get(part), dict):
+                cursor[part] = {}
+            cursor = cursor[part]
+        cursor[path[-1]] = env_val
+    return data
+
+
+def load_raw(config_path: Optional[str] = None) -> dict:
+    """config 파일 + 환경변수를 병합한 원본 dict 를 만든다."""
+    path = config_path or os.environ.get("PXA_CONFIG", DEFAULT_CONFIG_PATH)
+    raw: dict = {}
+    cfg_file = Path(path)
+    if cfg_file.is_file():
+        raw = yaml.safe_load(cfg_file.read_text(encoding="utf-8")) or {}
+    return _apply_env_overrides(raw)
+
+
+def get_raw() -> dict:
+    """프로세스 전역에서 한 번만 읽는 설정 원본(캐시)."""
+    global _raw_cache
+    if _raw_cache is None:
+        _raw_cache = load_raw()
+    return _raw_cache
+
+
+def reload_config(config_path: Optional[str] = None) -> dict:
+    """설정을 다시 읽는다(테스트/설정 변경 시)."""
+    global _raw_cache
+    _raw_cache = load_raw(config_path)
+    return _raw_cache
+
+
+def load_section(name: str, model: Type[M], raw: Optional[dict] = None) -> M:
+    """설정의 한 섹션을 타입이 보장된 모델로 만든다.
+
+    섹션이 없으면 모델 기본값으로 생성된다.
+    """
+    data = (raw if raw is not None else get_raw()).get(name) or {}
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"설정의 '{name}' 섹션은 key: value 형태여야 합니다 "
+            f"(현재 {type(data).__name__})."
+        )
+    return model(**data)
+
+
+def get_app_config() -> AppConfig:
+    return load_section("app", AppConfig)
+
+
+def get_logging_config() -> LoggingConfig:
+    return load_section("logging", LoggingConfig)
+
+
+def get_messages_config() -> MessagesConfig:
+    return load_section("messages", MessagesConfig)

pxa_common-0.1.0/src/pxa_common/exceptions.py

@@ -0,0 +1,120 @@
+"""공통 예외 및 예외 핸들러.
+
+프레임워크 전역 예외를 하나의 ``AppError`` 계열로 관리하고,
+표준 응답 포맷(ApiResponse)으로 자동 변환한다.
+주니어 개발자는 ``raise NotFoundError("...")`` 처럼 의미만 표현하면 된다.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from .codes import AppCode
+from .fastapi import (
+    FastAPI,
+    JSONResponse,
+    Request,
+    RequestValidationError,
+)
+from .response import ApiResponse
+
+logger = logging.getLogger("pxa")
+
+
+class AppError(Exception):
+    """공통 예외 베이스. 항상 AppCode 를 가진다."""
+
+    def __init__(
+        self,
+        code: AppCode = AppCode.UNKNOWN_ERROR,
+        message: Optional[str] = None,
+        result: Any = None,
+    ):
+        self.code = code
+        self.message = message or code.message
+        self.result = result
+        super().__init__(self.message)
+
+
+class NotFoundError(AppError):
+    """없는 데이터를 조회/변경할 때 (pxa-20004)."""
+
+    def __init__(self, message: Optional[str] = None, result: Any = None):
+        super().__init__(AppCode.NOT_FOUND, message, result)
+
+
+class ValidationError(AppError):
+    """데이터 정합성 검증 실패 (pxa-20001)."""
+
+    def __init__(self, message: Optional[str] = None, result: Any = None):
+        super().__init__(AppCode.VALIDATION_ERROR, message, result)
+
+
+class RequiredFieldError(AppError):
+    """필수 데이터 누락 (pxa-20002)."""
+
+    def __init__(self, missing: list[str] | str, result: Any = None):
+        fields = missing if isinstance(missing, str) else ", ".join(missing)
+        message = f"필수 데이터가 누락되었습니다: {fields}"
+        super().__init__(AppCode.REQUIRED_FIELD_MISSING, message, result)
+
+
+class UnauthorizedError(AppError):
+    """인증 실패 (pxa-20003)."""
+
+    def __init__(self, message: Optional[str] = None):
+        super().__init__(AppCode.UNAUTHORIZED, message)
+
+
+class ForbiddenError(AppError):
+    """권한 없음 (pxa-20005)."""
+
+    def __init__(self, message: Optional[str] = None):
+        super().__init__(AppCode.FORBIDDEN, message)
+
+
+class DbError(AppError):
+    """DB 처리 오류 (pxa-20006)."""
+
+    def __init__(self, message: Optional[str] = None):
+        super().__init__(AppCode.DB_ERROR, message)
+
+
+class DuplicatedError(AppError):
+    """중복 데이터 (pxa-20007)."""
+
+    def __init__(self, message: Optional[str] = None):
+        super().__init__(AppCode.DUPLICATED, message)
+
+
+def _json(payload: ApiResponse) -> JSONResponse:
+    # 모든 응답의 HTTP status 는 200 으로 고정한다.
+    return JSONResponse(status_code=200, content=payload.model_dump())
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """FastAPI 앱에 공통 예외 핸들러를 등록한다."""
+
+    @app.exception_handler(AppError)
+    async def _handle_app_error(request: Request, exc: AppError) -> JSONResponse:
+        logger.warning(
+            "AppError code=%s path=%s msg=%s",
+            exc.code.code, request.url.path, exc.message,
+        )
+        return _json(ApiResponse.fail(exc.code, exc.message, exc.result))
+
+    @app.exception_handler(RequestValidationError)
+    async def _handle_request_validation(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        details = [
+            {"field": ".".join(str(p) for p in e["loc"]), "msg": e["msg"]}
+            for e in exc.errors()
+        ]
+        logger.info("RequestValidationError path=%s", request.url.path)
+        return _json(ApiResponse.fail(AppCode.VALIDATION_ERROR, result=details))
+
+    @app.exception_handler(Exception)
+    async def _handle_unexpected(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("Unhandled error path=%s", request.url.path)
+        return _json(ApiResponse.fail(AppCode.UNKNOWN_ERROR))

pxa_common-0.1.0/src/pxa_common/fastapi.py

@@ -0,0 +1,67 @@
+"""FastAPI 파사드 (FastAPI/pydantic 직접 노출 금지).
+
+주니어 개발자는 ``fastapi`` / ``pydantic`` 을 직접 import 하지 않고
+``pxa_common.fastapi`` 만 사용한다. 내부 구현(FastAPI 0.128)이 바뀌어도
+사용자 코드는 그대로 둘 수 있다.
+
+    from pxa_common.fastapi import APIRouter, Depends, BaseModel
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# 절대 import 이므로 site-packages 의 실제 fastapi 를 가리킨다.
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Cookie,
+    Depends,
+    FastAPI,
+    File,
+    Form,
+    Header,
+    HTTPException,
+    Path,
+    Query,
+    Request,
+    Response,
+    UploadFile,
+    WebSocket,
+    status,
+)
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import (
+    FileResponse,
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+)
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+if TYPE_CHECKING:      # 런타임에는 import 하지 않는다 (아래 __getattr__ 참고)
+    from fastapi.testclient import TestClient
+
+__all__ = [
+    "APIRouter", "Depends", "FastAPI", "Request", "Response",
+    "BackgroundTasks", "WebSocket", "HTTPException",
+    "RequestValidationError", "status",
+    "Body", "Cookie", "File", "Form", "Header", "Path", "Query", "UploadFile",
+    "JSONResponse", "HTMLResponse", "PlainTextResponse", "RedirectResponse",
+    "StreamingResponse", "FileResponse",
+    "BaseModel", "Field", "field_validator", "model_validator",
+    "TestClient",
+]
+
+
+def __getattr__(name: str):
+    """TestClient 는 테스트에서만 쓰고 httpx 를 요구하므로 지연 import 한다.
+
+    이렇게 해야 ``import pxa_common`` 이 운영 환경에서 httpx 없이도 된다.
+    """
+    if name == "TestClient":
+        from fastapi.testclient import TestClient
+        return TestClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")