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` 을 사용합니다.
