pxa-common 0.1.0__py3-none-any.whl

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/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/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/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/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}")

pxa_common/logging_conf.py

@@ -0,0 +1,45 @@
+"""로깅 설정.
+
+로그는 config 에 지정된 디렉토리에 파일로 저장되며 자정마다 회전한다.
+디렉토리 위치/레벨/보관일수는 config 파일에서 변경한다.
+"""
+from __future__ import annotations
+
+import logging
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+from typing import Optional
+
+from .config import LoggingConfig, get_logging_config
+
+_LOG_FORMAT = "%(asctime)s | %(levelname)-7s | %(name)s | %(message)s"
+
+
+def setup_logging(cfg: Optional[LoggingConfig] = None) -> logging.Logger:
+    """'pxa' 로거에 콘솔 + 파일(자정 회전) 핸들러를 구성한다."""
+    cfg = cfg or get_logging_config()
+    log_dir = Path(cfg.dir)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    logger = logging.getLogger("pxa")
+    logger.setLevel(cfg.level.upper())
+    logger.handlers.clear()
+    logger.propagate = False
+
+    formatter = logging.Formatter(_LOG_FORMAT)
+
+    file_handler = TimedRotatingFileHandler(
+        filename=str(log_dir / cfg.filename),
+        when=cfg.rotate_when,
+        backupCount=cfg.backup_count,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    logger.info("로깅 초기화 완료: dir=%s level=%s", cfg.dir, cfg.level)
+    return logger

pxa_common/messages/__init__.py

@@ -0,0 +1,9 @@
+"""메시지 패키지 공개 API."""
+from .catalog import (
+    get_message,
+    load_message_files,
+    msg,
+    register_messages,
+)
+
+__all__ = ["msg", "get_message", "register_messages", "load_message_files"]

pxa_common/messages/catalog.py

@@ -0,0 +1,85 @@
+"""메시지 카탈로그 (메시지 중앙관리).
+
+- 사용자 노출 메시지는 코드에 하드코딩하지 않고 key 로 관리한다.
+- 프레임워크 기본 메시지는 ``default.yaml`` 에 동봉된다.
+- 애플리케이션은 config(messages.files)의 YAML 을 추가하거나
+  ``register_messages()`` 로 직접 추가/재정의할 수 있다.
+- ``{name}`` 형태의 포맷 파라미터를 지원한다.
+
+    from pxa_common.messages import msg
+    msg("item.created", name="사과")
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Iterable, Mapping, Optional
+
+import yaml
+
+logger = logging.getLogger("pxa")
+
+_DEFAULT_FILE = Path(__file__).parent / "default.yaml"
+
+_catalog: dict[str, str] = {}
+
+
+def _flatten(data: Mapping, prefix: str = "") -> dict[str, str]:
+    """중첩 dict 를 'a.b.c' 형태의 평탄한 key 로 변환한다."""
+    flat: dict[str, str] = {}
+    for key, value in data.items():
+        full = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            flat.update(_flatten(value, f"{full}."))
+        else:
+            flat[full] = str(value)
+    return flat
+
+
+def register_messages(mapping: Mapping[str, object]) -> None:
+    """메시지를 추가/재정의한다. 중첩 dict 는 'a.b' key 로 평탄화된다."""
+    _catalog.update(_flatten(mapping))
+
+
+def load_message_files(paths: Iterable[str]) -> None:
+    """YAML 메시지 파일들을 로드한다 (config: messages.files)."""
+    for p in paths:
+        path = Path(p)
+        if not path.is_file():
+            logger.warning("메시지 파일을 찾을 수 없습니다: %s", p)
+            continue
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        register_messages(data)
+        logger.info("메시지 파일 로드: %s", p)
+
+
+def get_message(
+    key: str,
+    default: Optional[str] = None,
+    **params: object,
+) -> str:
+    """key 로 메시지를 조회한다.
+
+    카탈로그에 없으면 default, default 도 없으면 key 자체를 반환한다.
+    포맷 파라미터가 부족해도 예외 없이 원문 템플릿을 반환한다.
+    """
+    template = _catalog.get(key, default if default is not None else key)
+    if params:
+        try:
+            return template.format(**params)
+        except (KeyError, IndexError):
+            logger.warning("메시지 포맷 파라미터 불일치: key=%s", key)
+    return template
+
+
+# 짧은 별칭 — 주니어 개발자용
+msg = get_message
+
+
+def _load_defaults() -> None:
+    if _DEFAULT_FILE.is_file():
+        data = yaml.safe_load(_DEFAULT_FILE.read_text(encoding="utf-8")) or {}
+        register_messages(data)
+
+
+_load_defaults()

pxa_common/messages/default.yaml

@@ -0,0 +1,22 @@
+# =====================================================================
+# pxa-common 기본 메시지 카탈로그
+# 애플리케이션은 config(messages.files)의 자체 YAML 로 재정의/추가할 수 있다.
+# key 는 애플리케이션 코드(pxa-xxxxx) 또는 도메인 key(a.b.c) 를 사용한다.
+# =====================================================================
+
+# ---- 애플리케이션 코드 메시지 (codes.py 와 1:1) ----
+pxa-10000: "정상 처리되었습니다."
+pxa-20000: "알 수 없는 오류가 발생했습니다."
+pxa-20001: "요청 데이터 검증에 실패했습니다."
+pxa-20002: "필수 데이터가 누락되었습니다."
+pxa-20003: "인증이 필요합니다."
+pxa-20004: "데이터를 찾을 수 없습니다."
+pxa-20005: "권한이 없습니다."
+pxa-20006: "데이터베이스 처리 중 오류가 발생했습니다."
+pxa-20007: "이미 존재하는 데이터입니다."
+
+# ---- 공통 도메인 메시지 ----
+auth:
+  login_ok: "로그인 되었습니다."
+  logout_ok: "로그아웃 되었습니다."
+  login_failed: "아이디 또는 비밀번호가 올바르지 않습니다."

pxa_common/middleware.py

@@ -0,0 +1,39 @@
+"""요청/응답 로깅 미들웨어.
+
+모든 요청에 request-id 를 부여하고 처리시간과 함께 로깅한다.
+주니어 개발자는 별도 설정 없이 접근 로그를 얻는다.
+"""
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+logger = logging.getLogger("pxa")
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        request_id = uuid.uuid4().hex[:12]
+        request.state.request_id = request_id
+        start = time.perf_counter()
+        try:
+            response = await call_next(request)
+        except Exception:
+            elapsed = (time.perf_counter() - start) * 1000
+            logger.exception(
+                "[%s] %s %s -> EXC (%.1fms)",
+                request_id, request.method, request.url.path, elapsed,
+            )
+            raise
+        elapsed = (time.perf_counter() - start) * 1000
+        logger.info(
+            "[%s] %s %s -> %s (%.1fms)",
+            request_id, request.method, request.url.path,
+            response.status_code, elapsed,
+        )
+        response.headers["X-Request-Id"] = request_id
+        return response

pxa_common/response.py

@@ -0,0 +1,64 @@
+"""표준 request/response 포맷.
+
+모든 API 응답은 동일한 JSON 구조로 내려간다::
+
+    {
+        "success": true,
+        "code": "pxa-10000",
+        "message": "정상 처리되었습니다.",
+        "result": { ... }
+    }
+
+주니어 개발자는 ``ApiResponse.ok(result, message)`` 처럼 결과값과 메시지만
+넣으면 된다. HTTP 상태코드는 항상 200 이며, 정상/비정상은 code 로 구분한다.
+메시지를 생략하면 메시지 카탈로그에서 코드 메시지를 조회한다.
+"""
+from __future__ import annotations
+
+from typing import Any, Generic, Optional, TypeVar
+
+from .codes import AppCode
+from .fastapi import BaseModel
+from .messages.catalog import get_message
+
+T = TypeVar("T")
+
+
+class ApiResponse(BaseModel, Generic[T]):
+    """표준 응답 봉투(envelope). 라우터는 이 객체를 그대로 return 한다."""
+
+    success: bool
+    code: str
+    message: str
+    result: Optional[T] = None
+
+    @classmethod
+    def ok(
+        cls,
+        result: Any = None,
+        message: Optional[str] = None,
+    ) -> "ApiResponse":
+        """성공 응답. 개발자는 result 와 (선택적으로) message 만 채운다."""
+        return cls(
+            success=True,
+            code=AppCode.SUCCESS.code,
+            message=message or get_message(
+                AppCode.SUCCESS.code, default=AppCode.SUCCESS.message
+            ),
+            result=result,
+        )
+
+    @classmethod
+    def fail(
+        cls,
+        code: AppCode = AppCode.UNKNOWN_ERROR,
+        message: Optional[str] = None,
+        result: Any = None,
+    ) -> "ApiResponse":
+        """실패 응답. 코드는 AppCode Enum 에서 선택한다."""
+        return cls(
+            success=False,
+            code=code.code,
+            message=message or get_message(code.code, default=code.message),
+            result=result,
+        )

pxa_common-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,15 @@
+pxa_common/__init__.py,sha256=2u7NLelVK5EIWTW4SAYXsJbPRD11JSuGdVtcoj0qB-U,1645
+pxa_common/codes.py,sha256=XlyGusYeOYTEAJw1G0p-MiB9OqehPzBcdUoDYCHeFNc,1591
+pxa_common/config.py,sha256=-EfTaxk6XedAPEp6NbmOgYoROAA-0EV5eQn0VPfQKNA,3471
+pxa_common/exceptions.py,sha256=Y-rKXx8XRsFDqeFbH_sdsQrqDtlyGI4qRKxA_EY2yfg,3879
+pxa_common/fastapi.py,sha256=MEZt5FMkcws1Sc7DxVHJMLZsnxhzz6Ow7DULaVjXgRc,2021
+pxa_common/logging_conf.py,sha256=FEzjc6DifeeFjtfMZDuMjbGo9nVp5v-oHR_1OySJbCY,1436
+pxa_common/middleware.py,sha256=HoB0oR3v97YM25YS5o4eGApsPpVSajfP1vNmotkZ358,1273
+pxa_common/response.py,sha256=tJ_q01in-BtOMqmBlH0v5CnjpnlDQJ0qhNMF6f6b4Og,1878
+pxa_common/messages/__init__.py,sha256=1zyuSVAAQ2HeWcar9KjR2uuGW86eQVugmHskWsunwDY,213
+pxa_common/messages/catalog.py,sha256=nQh4hAbOecsrF2hHw1ODrV8bux9ndX2977UCjqeYTEg,2697
+pxa_common/messages/default.yaml,sha256=1VZwzeHvcyntKjkCZaoASqwQOMtRSotMN6EQjgr6VsI,1127
+pxa_common-0.1.0.dist-info/METADATA,sha256=Qwu7zEHehzl4LkWshetvjWCQNSn__-US4a41xqyPaOo,4084
+pxa_common-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pxa_common-0.1.0.dist-info/top_level.txt,sha256=NWDuN6XH5lg33gFD6XMtNsDzZV3piJHhibDuKLw6r_8,11
+pxa_common-0.1.0.dist-info/RECORD,,

pxa_common-0.1.0.dist-info/WHEEL

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

pxa_common-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pxa_common